[Feature] RubyUI 2.0 — Phase 2.1: the hard components first

[cirdes]

What

The first components on the 2.0 layer — Dialog (8 classes), Toggle and ToggleGroup (3), Select (8), Data Table (14 + 3 adapters untouched) and ThemeToggle (1) — each a plain Ruby class inheriting RubyUI::Component beside an .html.erb sidecar. Their 22 golden scenarios are byte-identical to the frozen 1.6 snapshots in both the canonical and the strict form, through the ERB fixtures Phase 2.0b wrote; the scenarios' Phlex blocks are gone (the Kit methods they called no longer exist). No snapshot, fixture or Stimulus controller changed.

Before any of that, docs/ is pinned to the gem at main's commit 92f2619 (a git source with glob:), so the site keeps building unchanged while the gem migrates (Phase 3.3 points it back). Not RubyGems 1.6.0, which is 21 files behind main (decision 15).

Three layer changes the first sidecars needed, each measured before it was written (plan §"What this plan measured"): mixed_attrs, the nested hash a component forwards to a neighbour (decision 11); render_in drops the sidecar file's final newline, which was reaching the page as a text node inside every parent — the check is read once per compiled Template, not per render (decision 12); a class without a sidecar renders its nearest ancestor's, so a host's MyButton < RubyUI::Button keeps working, and a class directly under a component root finds its own (decision 13). Plus ComponentTest#erb, an inline template compiled through Herb for unit tests, and #descriptor.

Every unit test of the five families is ported to the ERB helper, none deleted; the enumerated arguments (DialogContent#size, Toggle/ToggleGroup variant and size, ToggleGroup type and orientation) accept their String form and refuse unknown values, with tests; SelectValue keeps whitespace-only content as Phlex did; DataTableSortHead's href keeps Phlex's javascript: guard; every caller-supplied attribute value goes through Attributes.flat, so nil omits it and a Symbol dasherizes as in 1.6.

Decisions 11–15 recorded; spec §4.3, §6 Phase 2.0, §6.2.1, §6.2.2, §9.2 amended; follow-up 1's Herb note corrected; follow-up 12 (the MCP registry's description fallback now reads a sidecar) filed for 2.2. The plan was reviewed by Codex before execution (ten findings, verified and folded in — plan Appendix B), executed task by task with a review after each, and given a whole-branch review whose two findings are the last three commits.

Stacked on #554 (Phase 2.0b), which is stacked on #548 (2.0a) and #536 (the ruler).

Why

Spec §6 Phase 2.1: the hard components first, so a design error in the layer surfaces now rather than at component 55. It did surface three (decisions 11–13), each a one-place fix, and the review found a fourth (the per-render source read), fixed the same way.

Test steps

From gem/: bundle exec rake → 779 runs, 0 failures, 0 skips; bundle exec rake golden → 388 runs (166 Phlex-lane, 188 ERB-lane, 7 coverage, 27 of the ruler's own); bundle exec standardrb → 427 files, no offenses. git diff --stat v2/fixtures -- gem/test/golden/snapshots gem/test/golden/strict gem/test/golden/views 'gem/lib/ruby_ui/**/*.js' → empty. cd mcp && bundle exec exe/ruby-ui-mcp-build && git diff --exit-code data/registry.json → clean. The CI Docs job builds docs/ against the gem at main's 92f2619.

Read first: the four composite sidecars — dialog_content.html.erb, data_table_column_toggle.html.erb, data_table_sort_head.html.erb, data_table_pagination.html.erb — they are decision 12's readability test.

Plan: design/plans/2026-09-20-phase-2-1-hard-components-implementation.md.

🤖 Generated with Claude Code

---

Summary by cubic

Migrates Dialog, Toggle/ToggleGroup, Select, DataTable, and ThemeToggle from Phlex to the RubyUI 2.0 layer: each is now a plain Ruby class inheriting RubyUI::Component with an .html.erb sidecar, rendering byte-identical to the frozen 1.6 snapshots in all 22 golden scenarios.

Layer changes

• Adds mixed_attrs, the nested Symbol-keyed hash a component forwards to a neighbor component, so data-action concatenates as it did in 1.6 instead of producing two attributes.
• render_in now drops the sidecar file's final newline, read once per compiled template rather than per render.
• A class without a sidecar renders its nearest ancestor's, so host subclasses like MyButton < RubyUI::Button keep working.
• Adds ComponentTest#erb, an inline template compiled through Herb for unit tests, and #descriptor for Stimulus matching.

Behavior details

• Enumerated arguments (DialogContent#size, Toggle/ToggleGroup variant and size, ToggleGroup type and orientation) accept String form and raise on unknown values instead of silently falling back to defaults.
• SelectValue keeps whitespace-only content; DataTableSortHead keeps Phlex's javascript: href guard; nil attributes are omitted and Symbol keys dasherize through Attributes.flat.
• docs/ is pinned to the gem at main's commit since RubyGems 1.6.0 is behind main; it points back at path: in Phase 3.3.
• No snapshots, fixtures, or Stimulus controllers changed; all unit tests are ported to the ERB helper, none deleted.

^{Written for commit 345c689. Summary will update on new commits.}

[cubic-dev-ai]

7 issues found across 106 files

Not reviewed (too large): design/plans/2026-09-20-phase-2-1-hard-components-implementation.md (~4,033 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="gem/lib/ruby_ui/data_table/data_table_row_checkbox.rb">

<violation number="1" location="gem/lib/ruby_ui/data_table/data_table_row_checkbox.rb:4">
P1: In an installed host application, rendering this class now raises because `Component#template` requires `RubyUI.component_roots`, but the generated RubyUI initializer leaves that list empty. Register the host component directory (for example, `Rails.root.join("app/components/ruby_ui")`) when installing the 2.0 layer, or otherwise make the root discovery automatic.</violation>
</file>

<file name="gem/lib/ruby_ui/dialog/dialog_footer.rb">

<violation number="1" location="gem/lib/ruby_ui/dialog/dialog_footer.rb:4">
P0: When a consumer generates the Dialog components, this new superclass is unavailable and its required sidecar is not copied: the generated class fails at load time, or at render time if `Component` was loaded manually. Update the installer/generator to load the 2.0 layer and copy each component's `.html.erb` sidecar.</violation>
</file>

<file name="gem/lib/ruby_ui/dialog/dialog_content.html.erb">

<violation number="1" location="gem/lib/ruby_ui/dialog/dialog_content.html.erb:8">
P3: The close-button `<svg>` uses `viewbox=` while the frozen 1.6 snapshot and the data_table sidecars added in this same PR use `viewBox`. Golden parity only holds because Nokogiri::HTML5 case-adjusts SVG attribute names during canonicalization; the raw ERB output the gem emits keeps literal `viewbox`, which is not a valid SVG attribute in XML/XHTML consumption contexts (case-sensitive there) and fails strict SVG validation. Change `viewbox` to `viewBox` to match the baseline and the sibling sidecars.</violation>
</file>

<file name="docs/Gemfile">

<violation number="1" location="docs/Gemfile:79">
P2: For the entire migration window this pin runs the docs app and its test suite against the external 1.6 gem snapshot (commit 92f2619), not the 2.0 gem code in this repo. Two consequences follow from the changed line: (1) the docs app's own render tests no longer exercise any 2.0 rendering code, so the migration's "byte-identical output" claim for doc-rendered components is validated only by the gem's golden suite, not by docs; (2) when the 2.0 line fixes the known 1.6 defects scheduled for correction (issues #540/#541), the published docs site will continue demonstrating the old, defective output the shipped gem no longer produces, until Phase 3.3 reverts. The decoupling is intentional and documented, but the Phase 3.3 revert is the only termination condition — nothing enforces it. Consider tracking the revert explicitly (a CI check or TODO keyed on the 2.0 version bump is enough) so the pin cannot silently survive the migration and permanently freeze docs to stale gem output.</violation>
</file>

<file name="gem/lib/ruby_ui/theme_toggle/theme_toggle.html.erb">

<violation number="1" location="gem/lib/ruby_ui/theme_toggle/theme_toggle.html.erb:1">
P3: Caller-supplied `variant`, `size`, `aria`, and `wrapper` on `RubyUI::ThemeToggle` are accepted without error but silently discarded: the explicit keywords in this sidecar always win over the same keys in `**component.mixed_attrs` (Ruby's explicit-keyword-over-splat precedence), while `class:`, `data:`, and other kwargs do pass through. Merge the fixed defaults into `mixed_attrs` instead, so caller overrides apply, or drop the keys you intend to hardwire and raise on them so the failure is loud.</violation>
</file>

<file name="design/v2/follow-up-issues.md">

<violation number="1" location="design/v2/follow-up-issues.md:161">
P3: Issue 12's diagnosis of `data_table` is incomplete: its directory does contain a `Docs::Header` (in `data_table_docs.rb`, `Docs::Header.new(title: ..., description: "A Hotwire-first data table. Every interaction (sort, search, pagination) ...")`), so the "with no `Docs::Header`" framing does not apply to it. The description is really lost because `extract_description`'s regex `Docs::Header\.new\(([^)]*)\)` stops at the first `)`, truncating the args at the parenthesis inside "(sort, search, pagination)", so `extract_kwarg` never finds the closing quote and the branch falls through to the fallback. The proposed fix (skip non-`.rb` files and the `frozen_string_literal` comment in the fallback) would therefore still not restore `data_table`'s intended description — it would just yield `""`. Correct the note to also fix the `Docs::Header` extraction (match balanced parentheses or tolerate parens inside the quoted description), or the "Before 2.2" fix will not actually fix `data_table`.</violation>
</file>

<file name="gem/test/ruby_ui/component_test.rb">

<violation number="1" location="gem/test/ruby_ui/component_test.rb:186">
P3: `test_the_sidecar_source_is_read_once_per_template_not_per_render` permanently replaces `source` on the process-wide cached Div template via `define_singleton_method` and never restores it. The template object comes from the shared lookup cache (`RubyUI::Probes::Div.template` → `lookup.find`), so every later test in the process that touches this template sees the overridden method returning the captured snapshot instead of the real file-backed `Template#source`, and the only cleanup is the test ending. Add an `ensure` that removes the singleton method from `template.singleton_class` after the assertion, or build the counter without mutating the shared object (e.g. a fresh template).</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P0: When a consumer generates the Dialog components, this new superclass is unavailable and its required sidecar is not copied: the generated class fails at load time, or at render time if Component was loaded manually. Update the installer/generator to load the 2.0 layer and copy each component's .html.erb sidecar.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At gem/lib/ruby_ui/dialog/dialog_footer.rb, line 4:

<comment>When a consumer generates the Dialog components, this new superclass is unavailable and its required sidecar is not copied: the generated class fails at load time, or at render time if `Component` was loaded manually. Update the installer/generator to load the 2.0 layer and copy each component's `.html.erb` sidecar.</comment>

<file context>
@@ -1,11 +1,7 @@
-      div(**attrs, &)
-    end
-
+  class DialogFooter < Component
     private
 
</file context>

[cubic-dev-ai]

P1: In an installed host application, rendering this class now raises because Component#template requires RubyUI.component_roots, but the generated RubyUI initializer leaves that list empty. Register the host component directory (for example, Rails.root.join("app/components/ruby_ui")) when installing the 2.0 layer, or otherwise make the root discovery automatic.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At gem/lib/ruby_ui/data_table/data_table_row_checkbox.rb, line 4:

<comment>In an installed host application, rendering this class now raises because `Component#template` requires `RubyUI.component_roots`, but the generated RubyUI initializer leaves that list empty. Register the host component directory (for example, `Rails.root.join("app/components/ruby_ui")`) when installing the 2.0 layer, or otherwise make the root discovery automatic.</comment>

<file context>
@@ -1,18 +1,14 @@
 
 module RubyUI
-  class DataTableRowCheckbox < Base
+  class DataTableRowCheckbox < Component
     def initialize(value:, name: "ids[]", label: nil, **attrs)
       @value = value
</file context>

[cubic-dev-ai]

P2: For the entire migration window this pin runs the docs app and its test suite against the external 1.6 gem snapshot (commit 92f2619), not the 2.0 gem code in this repo. Two consequences follow from the changed line: (1) the docs app's own render tests no longer exercise any 2.0 rendering code, so the migration's "byte-identical output" claim for doc-rendered components is validated only by the gem's golden suite, not by docs; (2) when the 2.0 line fixes the known 1.6 defects scheduled for correction (issues #540/#541), the published docs site will continue demonstrating the old, defective output the shipped gem no longer produces, until Phase 3.3 reverts. The decoupling is intentional and documented, but the Phase 3.3 revert is the only termination condition — nothing enforces it. Consider tracking the revert explicitly (a CI check or TODO keyed on the 2.0 version bump is enough) so the pin cannot silently survive the migration and permanently freeze docs to stale gem output.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/Gemfile, line 79:

<comment>For the entire migration window this pin runs the docs app and its test suite against the external 1.6 gem snapshot (commit 92f2619), not the 2.0 gem code in this repo. Two consequences follow from the changed line: (1) the docs app's own render tests no longer exercise any 2.0 rendering code, so the migration's "byte-identical output" claim for doc-rendered components is validated only by the gem's golden suite, not by docs; (2) when the 2.0 line fixes the known 1.6 defects scheduled for correction (issues #540/#541), the published docs site will continue demonstrating the old, defective output the shipped gem no longer produces, until Phase 3.3 reverts. The decoupling is intentional and documented, but the Phase 3.3 revert is the only termination condition — nothing enforces it. Consider tracking the revert explicitly (a CI check or TODO keyed on the 2.0 version bump is enough) so the pin cannot silently survive the migration and permanently freeze docs to stale gem output.</comment>

<file context>
@@ -73,7 +73,10 @@ end
+# Pinned to main's commit while ../gem migrates to 2.0 (spec §6 Phase 2.0,
+# last bullet; decision 15 — RubyGems 1.6.0 is behind main). Phase 3.3 points
+# it back at path: "../gem".
+gem "ruby_ui", github: "ruby-ui/ruby_ui", ref: "92f261931eb78bcc4682f4afb72b139553aba957", glob: "gem/*.gemspec", require: false
 
 gem "pry", "0.16.0"
</file context>

[cubic-dev-ai]

P3: The close-button <svg> uses viewbox= while the frozen 1.6 snapshot and the data_table sidecars added in this same PR use viewBox. Golden parity only holds because Nokogiri::HTML5 case-adjusts SVG attribute names during canonicalization; the raw ERB output the gem emits keeps literal viewbox, which is not a valid SVG attribute in XML/XHTML consumption contexts (case-sensitive there) and fails strict SVG validation. Change viewbox to viewBox to match the baseline and the sibling sidecars.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At gem/lib/ruby_ui/dialog/dialog_content.html.erb, line 8:

<comment>The close-button `<svg>` uses `viewbox=` while the frozen 1.6 snapshot and the data_table sidecars added in this same PR use `viewBox`. Golden parity only holds because Nokogiri::HTML5 case-adjusts SVG attribute names during canonicalization; the raw ERB output the gem emits keeps literal `viewbox`, which is not a valid SVG attribute in XML/XHTML consumption contexts (case-sensitive there) and fails strict SVG validation. Change `viewbox` to `viewBox` to match the baseline and the sibling sidecars.</comment>

<file context>
@@ -0,0 +1,17 @@
+><svg
+  width="15"
+  height="15"
+  viewbox="0 0 15 15"
+  fill="none"
+  xmlns="http://www.w3.org/2000/svg"
</file context>

Suggested change

	viewbox="0 0 15 15"
	viewBox="0 0 15 15"

[cubic-dev-ai]

P3: Caller-supplied variant, size, aria, and wrapper on RubyUI::ThemeToggle are accepted without error but silently discarded: the explicit keywords in this sidecar always win over the same keys in **component.mixed_attrs (Ruby's explicit-keyword-over-splat precedence), while class:, data:, and other kwargs do pass through. Merge the fixed defaults into mixed_attrs instead, so caller overrides apply, or drop the keys you intend to hardwire and raise on them so the failure is loud.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At gem/lib/ruby_ui/theme_toggle/theme_toggle.html.erb, line 1:

<comment>Caller-supplied `variant`, `size`, `aria`, and `wrapper` on `RubyUI::ThemeToggle` are accepted without error but silently discarded: the explicit keywords in this sidecar always win over the same keys in `**component.mixed_attrs` (Ruby's explicit-keyword-over-splat precedence), while `class:`, `data:`, and other kwargs do pass through. Merge the fixed defaults into `mixed_attrs` instead, so caller overrides apply, or drop the keys you intend to hardwire and raise on them so the failure is loud.</comment>

<file context>
@@ -0,0 +1 @@
+<%= render RubyUI::Toggle.new(variant: :default, size: :default, aria: {label: "Toggle theme"}, wrapper: {data: {controller: "ruby-ui--theme-toggle", action: "ruby-ui--toggle:change->ruby-ui--theme-toggle#apply"}}, **component.mixed_attrs) do %><%= component.content %><% end %>
</file context>

Suggested change

	<%= render RubyUI::Toggle.new(variant: :default, size: :default, aria: {label: "Toggle theme"}, wrapper: {data: {controller: "ruby-ui--theme-toggle", action: "ruby-ui--toggle:change->ruby-ui--theme-toggle#apply"}}, **component.mixed_attrs) do %><%= component.content %><% end %>
	<%= render RubyUI::Toggle.new(**RubyUI::Attributes.mix({variant: :default, size: :default, aria: {label: "Toggle theme"}, wrapper: {data: {controller: "ruby-ui--theme-toggle", action: "ruby-ui--toggle:change->ruby-ui--theme-toggle#apply"}}}, component.mixed_attrs)) do %><%= component.content %><% end %>

[cubic-dev-ai]

P3: Issue 12's diagnosis of data_table is incomplete: its directory does contain a Docs::Header (in data_table_docs.rb, Docs::Header.new(title: ..., description: "A Hotwire-first data table. Every interaction (sort, search, pagination) ...")), so the "with no Docs::Header" framing does not apply to it. The description is really lost because extract_description's regex Docs::Header\.new\(([^)]*)\) stops at the first ), truncating the args at the parenthesis inside "(sort, search, pagination)", so extract_kwarg never finds the closing quote and the branch falls through to the fallback. The proposed fix (skip non-.rb files and the frozen_string_literal comment in the fallback) would therefore still not restore data_table's intended description — it would just yield "". Correct the note to also fix the Docs::Header extraction (match balanced parentheses or tolerate parens inside the quoted description), or the "Before 2.2" fix will not actually fix data_table.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At design/v2/follow-up-issues.md, line 161:

<comment>Issue 12's diagnosis of `data_table` is incomplete: its directory does contain a `Docs::Header` (in `data_table_docs.rb`, `Docs::Header.new(title: ..., description: "A Hotwire-first data table. Every interaction (sort, search, pagination) ...")`), so the "with no `Docs::Header`" framing does not apply to it. The description is really lost because `extract_description`'s regex `Docs::Header\.new\(([^)]*)\)` stops at the first `)`, truncating the args at the parenthesis inside "(sort, search, pagination)", so `extract_kwarg` never finds the closing quote and the branch falls through to the fallback. The proposed fix (skip non-`.rb` files and the `frozen_string_literal` comment in the fallback) would therefore still not restore `data_table`'s intended description — it would just yield `""`. Correct the note to also fix the `Docs::Header` extraction (match balanced parentheses or tolerate parens inside the quoted description), or the "Before 2.2" fix will not actually fix `data_table`.</comment>

<file context>
@@ -154,6 +155,19 @@ Ordered by user impact.
+## 12. `RegistryBuilder` reads a component's description from its first file — now a sidecar
+
+- **Where:** `mcp/lib/ruby_ui/mcp/builders/registry_builder.rb`,
+  `extract_description`: with no `Docs::Header` and no markdown heading it
+  takes the first comment line of `files.first`. Files are sorted, so
+  `x.html.erb` now precedes `x.rb` and the fallback finds no `#` line;
</file context>

[cubic-dev-ai]

P3: test_the_sidecar_source_is_read_once_per_template_not_per_render permanently replaces source on the process-wide cached Div template via define_singleton_method and never restores it. The template object comes from the shared lookup cache (RubyUI::Probes::Div.template → lookup.find), so every later test in the process that touches this template sees the overridden method returning the captured snapshot instead of the real file-backed Template#source, and the only cleanup is the test ending. Add an ensure that removes the singleton method from template.singleton_class after the assertion, or build the counter without mutating the shared object (e.g. a fresh template).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At gem/test/ruby_ui/component_test.rb, line 186:

<comment>`test_the_sidecar_source_is_read_once_per_template_not_per_render` permanently replaces `source` on the process-wide cached Div template via `define_singleton_method` and never restores it. The template object comes from the shared lookup cache (`RubyUI::Probes::Div.template` → `lookup.find`), so every later test in the process that touches this template sees the overridden method returning the captured snapshot instead of the real file-backed `Template#source`, and the only cleanup is the test ending. Add an `ensure` that removes the singleton method from `template.singleton_class` after the assertion, or build the counter without mutating the shared object (e.g. a fresh template).</comment>

<file context>
@@ -121,4 +121,84 @@ def test_a_class_outside_every_component_root_is_refused
+    template = RubyUI::Probes::Div.template
+    reads = 0
+    source = template.source
+    template.define_singleton_method(:source) do
+      reads += 1
+      source
</file context>