poetry-ui 0.0.2

data/app/components/poetry/ui/table/component.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Semantic data tables composed from part helpers.
+    module Table
+      # A semantic <table> wrapped in a horizontally scrolling container.
+      # Compose the sections with the part helpers (poetry_table_header /
+      # _body / _row / _head / _cell / _footer / _caption), which render
+      # real thead/tbody/tr/th/td elements carrying the family's styling.
+      # Static and JS-free by itself - DataTable adds sorting, filtering,
+      # and selection on top.
+      #
+      # sticky_header: true pins the <thead> while the container scrolls.
+      # It only takes effect once container_class: caps the height (e.g.
+      # "max-h-96"), and it requires scroll_label: - the container becomes
+      # a focusable scroll region, which needs an accessible name.
+      #
+      # @example
+      #   render Poetry::Ui::Table::Component.new do
+      #     safe_join([
+      #       poetry_table_header { poetry_table_row { poetry_table_head { "Invoice" } } },
+      #       poetry_table_body { poetry_table_row { poetry_table_cell { "INV001" } } }
+      #     ])
+      #   end
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Compose the table with the part helpers (poetry_table_header/_body/_row/_head/_cell) - " \
+          "they carry the data-slot + classes onto real thead/tbody/tr/th/td.",
+          "A column header is poetry_table_head (a <th>); a data cell is poetry_table_cell (a <td>).",
+          "Mark a selected row with data-selected on poetry_table_row - never a bespoke highlight class.",
+          "sticky_header: true pins the thead while the container scrolls - it only scrolls once " \
+          "container_class: caps the height (\"max-h-96\"); without a cap nothing sticks.",
+          "sticky_header requires scroll_label: - the container becomes a focusable scroll region " \
+          "(tabindex=0 + role=region) and a keyboard-reachable region needs a name (the ScrollArea rule)."
+        ].freeze
+
+        option :sticky_header, :boolean, default: false,
+                                         doc: "Pins the <thead> while the container scrolls; needs a height cap " \
+                                              "(container_class:) to take effect, and requires scroll_label:."
+        option :container_class, :string,
+               doc: "Extra classes for the scroll container - e.g. \"max-h-96\" to cap its height."
+        option :scroll_label, :string,
+               doc: "The scroll region's accessible name, required with sticky_header: a scrollable region a " \
+                    "keyboard can't reach fails WCAG (axe scrollable-region-focusable), and a focusable region needs " \
+                    "a name."
+
+        part "table", "The semantic <table> element itself - the root the part helpers compose into"
+        part "table-caption", "The <caption> (poetry_table_caption) - the table's accessible purpose"
+        part "table-header", "The <thead> (poetry_table_header) holding the column-header row"
+        part "table-body", "The <tbody> (poetry_table_body) holding the data rows"
+        part "table-footer", "The <tfoot> (poetry_table_footer) - totals/summary rows"
+        part "table-row", "A <tr> (poetry_table_row) in any section",
+             states: {
+               "data-selected" => "the row is marked selected (presence attribute, no value) - " \
+                                  "the theme tints it"
+             }
+        part "table-head", "A column header <th> (poetry_table_head)"
+        part "table-cell", "A data <td> (poetry_table_cell)"
+
+        # No content = an empty <table> in a scroll container.
+        requires_content "the table sections (poetry_table_* helpers)"
+
+        # @api private
+        def before_render
+          ensure_content!
+          return unless sticky_header && scroll_label.blank?
+
+          raise ArgumentError,
+                "Table sticky_header: requires scroll_label: (the scroll region's accessible name)"
+        end
+
+        # @api private
+        def container_attributes
+          extra = [(css(:container_sticky) if sticky_header), container_class].compact.join(" ")
+          attrs = { "data-slot" => "table-container", "class" => css(:container, class: extra.presence) }
+          attrs.merge!("tabindex" => "0", "role" => "region", "aria-label" => scroll_label) if sticky_header
+          attrs
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "table" }.merge(component_data_attributes)
+          )
+        end
+
+        private :container_attributes, :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/table/preview.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Table
+      # The Table preview: the ported table-demo (recent invoices) with a
+      # caption, a footer total, and a selected row. Built with the same
+      # data-slot + Style parts the poetry_table_* helpers stamp (the
+      # helpers themselves are covered by the components-helper drift test).
+      class Preview < Poetry::Core::Preview::Base
+        ROWS = [
+          ["INV001", "Paid", "$250.00", true],
+          ["INV002", "Pending", "$150.00", false],
+          ["INV003", "Unpaid", "$350.00", false],
+          ["INV004", "Paid", "$500.00", false]
+        ].freeze
+
+        STATUSES = %w[Paid Pending Unpaid].freeze
+
+        def default
+          render_component do
+            safe_join([caption, header, body, footer])
+          end
+        end
+
+        # sticky_header pins the thead while the capped container scrolls
+        # - enough rows to overflow the max-h-56 cap.
+        def sticky
+          render_component(sticky_header: true, container_class: "max-h-56",
+                           scroll_label: "Recent invoices") do
+            safe_join([header, long_body])
+          end
+        end
+
+        private
+
+        def caption
+          part(:caption, :caption, "table-caption") { "A list of your recent invoices." }
+        end
+
+        def header
+          part(:thead, :header, "table-header") do
+            row do
+              safe_join([head { "Invoice" }, head { "Status" }, head(class: "text-right") { "Amount" }])
+            end
+          end
+        end
+
+        def body
+          part(:tbody, :body, "table-body") do
+            safe_join(ROWS.map do |invoice, status, amount, selected|
+              row(data: selected ? { slot: "table-row", selected: "" } : { slot: "table-row" }) do
+                safe_join([
+                            cell(class: "font-medium") { invoice },
+                            cell { status },
+                            cell(class: "text-right") { amount }
+                          ])
+              end
+            end)
+          end
+        end
+
+        def footer
+          part(:tfoot, :footer, "table-footer") do
+            row { safe_join([cell(colspan: 2) { "Total" }, cell(class: "text-right") { "$1,250.00" }]) }
+          end
+        end
+
+        def long_body
+          part(:tbody, :body, "table-body") do
+            safe_join((1..12).map do |i|
+              row do
+                safe_join([
+                            cell(class: "font-medium") { format("INV%03d", i) },
+                            cell { STATUSES[i % 3] },
+                            cell(class: "text-right") { format("$%d50.00", i) }
+                          ])
+              end
+            end)
+          end
+        end
+
+        # tag.<el> with the Style class + data-slot - what the helper emits.
+        def part(tag_name, element, slot, **attrs, &)
+          classes = [Style.css(element), attrs.delete(:class)].compact.join(" ")
+          data = attrs.delete(:data) || { slot: slot }
+          content_tag(tag_name, capture(&), **attrs, class: classes, data: data)
+        end
+
+        def row(**attrs, &) = part(:tr, :row, "table-row", **attrs, &)
+        def head(**attrs, &) = part(:th, :head, "table-head", **attrs, &)
+        def cell(**attrs, &) = part(:td, :cell, "table-cell", **attrs, &)
+      end
+    end
+  end
+end

data/app/components/poetry/ui/table/style.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Table
+      # Re-expressed through the cn-* theme layer. Zero JS - the row's
+      # selected state travels as data-selected, its tint in the theme
+      # with every other row tint. The scroll container carries its own
+      # themed hook (cn-table-container).
+      class Style < Poetry::Core::Style
+        base "cn-table"
+
+        element :container, "cn-table-container"
+        element :container_sticky,
+                "overflow-y-auto [&_thead]:sticky [&_thead]:top-0 [&_thead]:z-10 [&_thead]:bg-background"
+        element :header, "cn-table-header"
+        element :body, "cn-table-body"
+        element :footer, "cn-table-footer"
+        element :row, "cn-table-row transition-colors has-aria-expanded:bg-muted/50"
+        element :head, "cn-table-head"
+        element :cell, "cn-table-cell"
+        element :caption, "cn-table-caption"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/tabs/component.html.erb

@@ -0,0 +1,10 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:div, list_attributes) do %>
+    <% tab_defs.each do |tab| %>
+      <%= content_tag(:button, tab.title, trigger_attributes(tab)) %>
+    <% end %>
+  <% end %>
+  <% tab_defs.reject(&:panel_less).each do |tab| %>
+    <%= content_tag(:div, panel_body(tab), panel_attributes(tab)) %>
+  <% end %>
+<% end %>

data/app/components/poetry/ui/tabs/component.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Tabbed views switched by a tablist.
+    module Tabs
+      # A tablist of triggers that switches between panels. Declare each
+      # tab with with_tab (title plus a panel block) and the component
+      # wires the tab/tablist/tabpanel roles, their ids, and the keyboard:
+      # arrow keys move focus along the tablist and activate the focused
+      # tab. The active panel is server-rendered visible, so the initial
+      # view needs no JS.
+      #
+      # default: picks the active tab by value (otherwise the first
+      # enabled tab wins); label: names the tablist for assistive tech -
+      # recommended when a page has several tab sets.
+      #
+      # @example
+      #   <%= poetry_tabs(default: "account", label: "Account settings") do |tabs| %>
+      #     <% tabs.with_tab("Account", value: "account") do %>...panel...<% end %>
+      #     <% tabs.with_tab("Password", value: "password") do %>...panel...<% end %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the orientation axis.
+        ORIENTATIONS = %i[horizontal vertical].freeze
+        # The closed vocabulary for the list-variant axis.
+        VARIANTS = %i[default line].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Declare tabs with with_tab(title, value:) + the panel block (or defer: for a " \
+          "lazy turbo-frame panel) - never hand-wire role=tab/tabpanel ids.",
+          "panel: false declares a list-only tab (no tabpanel renders, the trigger drops " \
+          "aria-controls) - for demos/pattern shells; real tab sets carry panels.",
+          "default: picks the server-rendered active tab (the first enabled tab otherwise) - the " \
+          "panel is visible without JS.",
+          "label: names the tablist (aria-label) - recommended whenever the page has several tab sets.",
+          "Tabs switch VIEWS of one context; use navigation (links) when the URL should change."
+        ].freeze
+
+        # The same facts the before_render raise enforces, stated
+        # statically: poetry check flags the omission without rendering.
+        REQUIRED_SLOTS = { tab: "at least one tab" }.freeze
+
+        renders_many :tabs,
+                     doc: "Declares one tab: the title, its value:, and the panel as the block (defer: swaps in a " \
+                          "lazy turbo-frame panel; panel: false declares a list-only tab). Omitting all three " \
+                          "raises.",
+                     renders: lambda { |title, value:, disabled: false, defer: nil, panel: true, &block|
+                       unless block || defer || panel == false
+                         raise ArgumentError,
+                               "Tabs tab #{title.inspect} requires a panel block, defer:, or panel: false"
+                       end
+
+                       tab_defs << Tab.new(title: title, value: value.to_s, disabled: disabled, panel: block,
+                                           defer: defer, panel_less: panel == false)
+                       nil
+                     }
+
+        use_stimulus do
+          on :root do
+            controller(:tabs) { register }
+          end
+          # Both controllers declare on one element: roving-focus registers
+          # and owns the keyboard; the tabs controller is NOT registered on
+          # the list - its focus_activate action routes up to the root
+          # instance.
+          on :list do
+            controller :roving_focus do
+              register
+              value :orientation
+              value :loop, true
+              action :keydown, on: :keydown
+            end
+            controller :tabs do
+              action :focus_activate, on: event(:roving_focus, :entry)
+            end
+          end
+          on :trigger do
+            controller(:tabs) { action :activate, on: :click }
+          end
+        end
+
+        # The operate surface: activate a tab by its value (registered per
+        # instance, opt-in - see poetry-agent).
+        tool :set_value,
+             description: "Activate the tab whose value matches and show its panel.",
+             params: { value: { type: "string", required: true, description: "The tab's value." } },
+             executes: %i[tabs set_value],
+             mutating: true
+
+        # The rendered instance knows its tab values: the payload's schema
+        # carries them as the enum, so an agent can only ask for a tab that
+        # exists (the class-level projection stays a plain string).
+        def webmcp_tool_definition(definition)
+          return definition unless definition["name"] == "set_value"
+
+          values = tab_defs.map(&:value)
+          return definition if values.empty?
+
+          schema = definition.fetch("inputSchema")
+          value = schema.fetch("properties").fetch("value").merge("enum" => values)
+          definition.merge("inputSchema" => schema.merge("properties" => schema["properties"].merge("value" => value)))
+        end
+
+        option :default, :string,
+               doc: "The value of the server-rendered active tab; defaults to the first enabled tab. Raises when it " \
+                    "matches no tab."
+        option :label, :string, doc: "The tablist's accessible name - recommended when a page has several tab sets."
+        option :orientation, :symbol, default: :horizontal,
+                                      doc: "The tab axis; :vertical stacks the triggers and flips the arrow keys."
+        option :variant, :symbol, default: :default,
+                                  doc: "The list's visual treatment: :default a filled capsule, :line an underline " \
+                                       "indicator."
+
+        validates :orientation, inclusion: { in: ORIENTATIONS }
+        validates :variant, inclusion: { in: VARIANTS }
+
+        part "tabs", "Root wrapper - the orientation rides here and flips the flex direction",
+             states: {
+               "data-orientation" => { condition: "the tab axis (matches aria-orientation on the list)",
+                                       values: %w[horizontal vertical] }
+             }
+        part "tabs-list", "The role=tablist row of triggers - the roving-focus keyboard group and " \
+                          "the visual variant ride here",
+             states: {
+               "data-variant" => "the list treatment - default (filled capsule) or line (underline indicator)"
+             }
+        part "tabs-trigger", "One role=tab button per tab",
+             states: {
+               "data-active" => "the selected tab (the controller moves it with aria-selected on activation)",
+               "data-disabled" => "tab is disabled - also filters it from the roving-focus collection",
+               "data-value" => "the tab's value - the key the controller matches panels against"
+             }
+        part "tabs-content", "One role=tabpanel per tab - only the active panel is visible",
+             states: {
+               "data-hidden" => "panel is inactive (paired with the hidden property - the controller " \
+                                "flips both)",
+               "data-value" => "the owning tab's value"
+             }
+
+        # @api private
+        def before_render
+          raise ArgumentError, "Tabs requires at least one with_tab" unless tabs?
+
+          return unless default.present? && tab_defs.none? { |tab| tab.value == default }
+
+          raise ArgumentError, "Tabs default: #{default.inspect} matches no tab value " \
+                               "(#{tab_defs.map(&:value).inspect})"
+        end
+
+        # @api private
+        def tab_defs
+          @tab_defs ||= []
+        end
+
+        # The server-rendered active tab: default: when given, else the
+        # first enabled tab.
+        # @api private
+        def active_value
+          @active_value ||= default.presence || tab_defs.reject(&:disabled).first&.value || tab_defs.first.value
+        end
+
+        # @api private
+        def active?(tab)
+          tab.value == active_value
+        end
+
+        # @api private
+        def trigger_id(tab) = "#{instance_id}-trigger-#{tab.value}"
+        # @api private
+        def panel_id(tab) = "#{instance_id}-panel-#{tab.value}"
+
+        # defer: swaps the panel body for a lazy turbo-frame - a
+        # hidden panel is not visible, so Turbo fetches on first
+        # activation with zero tabs-controller involvement. The panel
+        # block (if given) becomes the frame's placeholder.
+        # @api private
+        def panel_body(tab)
+          return capture(&tab.panel) unless tab.defer
+
+          render(Poetry::Ui::Deferred::Component.new(src: tab.defer)) { tab.panel ? capture(&tab.panel) : nil }
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "tabs", "data-orientation" => orientation
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def list_attributes
+          attrs = {
+            "role" => "tablist", "data-slot" => "tabs-list", "data-variant" => variant,
+            "aria-orientation" => orientation,
+            "class" => "#{css(:list)} #{css(:"list_#{variant}")}".strip
+          }
+          attrs["aria-label"] = label if label.present?
+          attrs.merge(stimulus_attributes_for(:list))
+        end
+
+        # @api private
+        def trigger_attributes(tab)
+          attrs = {
+            "type" => "button", "role" => "tab", "id" => trigger_id(tab),
+            "data-slot" => "tabs-trigger", "data-value" => tab.value,
+            "data-poetry-collection-item" => "",
+            "aria-selected" => active?(tab).to_s,
+            "tabindex" => active?(tab) ? "0" : "-1",
+            "class" => css(:trigger)
+          }.merge(stimulus_attributes_for(:trigger))
+          attrs["aria-controls"] = panel_id(tab) unless tab.panel_less
+          attrs["data-active"] = "" if active?(tab)
+          if tab.disabled
+            attrs["disabled"] = true
+            attrs["data-disabled"] = "" # the roving-focus collection filter
+          end
+          attrs
+        end
+
+        # @api private
+        def panel_attributes(tab)
+          attrs = {
+            "role" => "tabpanel", "id" => panel_id(tab), "data-slot" => "tabs-content",
+            "data-value" => tab.value, "aria-labelledby" => trigger_id(tab),
+            "tabindex" => "0", "class" => css(:content)
+          }
+          unless active?(tab)
+            attrs["hidden"] = true
+            attrs["data-hidden"] = ""
+          end
+          attrs
+        end
+
+        # One declared tab (built by with_tab).
+        # @api private
+        Tab = Data.define(:title, :value, :disabled, :panel, :defer, :panel_less)
+
+        private
+
+        def instance_id
+          @instance_id ||= poetry_instance_id("poetry-tabs")
+        end
+
+        private :tab_defs, :active_value, :active?, :trigger_id, :panel_id, :panel_body, :root_attributes
+        private :list_attributes, :trigger_attributes, :panel_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/tabs/preview.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Tabs
+      # The Tabs preview: the default boxed list, the line variant, and a
+      # vertical set with a disabled tab.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(label: "Account settings") do |tabs|
+            tabs.with_tab("Account", value: "account") { "Make changes to your account here." }
+            tabs.with_tab("Password", value: "password") { "Change your password here." }
+          end
+        end
+
+        def line_variant
+          render_component(variant: :line, label: "Docs sections", default: "usage") do |tabs|
+            tabs.with_tab("Overview", value: "overview") { "The component at a glance." }
+            tabs.with_tab("Usage", value: "usage") { "How to compose it." }
+            tabs.with_tab("API", value: "api") { "Options and slots." }
+          end
+        end
+
+        # The list-only arrangement (panel: false): no tabpanels at all,
+        # triggers without aria-controls - upstream's line/disabled demos.
+        def list_only
+          render_component(label: "List-only demo") do |tabs|
+            tabs.with_tab("Home", value: "home", panel: false)
+            tabs.with_tab("Disabled", value: "settings", disabled: true, panel: false)
+          end
+        end
+
+        def vertical_with_disabled
+          render_component(orientation: :vertical, label: "Project areas") do |tabs|
+            tabs.with_tab("General", value: "general") { "Project defaults." }
+            tabs.with_tab("Members", value: "members") { "Who has access." }
+            tabs.with_tab("Billing", value: "billing", disabled: true) { "Plan and invoices." }
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/tabs/style.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Tabs
+      # Re-expressed through the cn-* theme layer. The group/tabs and
+      # group/tabs-list markers stay inline (the theme rules key on them);
+      # the trigger's whole text-color cluster moved theme-side TOGETHER
+      # (split-side rule: the base dims must lose to data-active in-layer).
+      # The after:* line-indicator geometry stays inline except its paint.
+      # The indicator's OPACITY PAIR (rest 0 / active 100) lives fully
+      # inline: the rest state is a utility, so a theme-side activation
+      # sits in layer(base) and loses to it unconditionally - splitting
+      # the pair leaves the line variant's indicator invisible.
+      class Style < Poetry::Core::Style
+        base "cn-tabs group/tabs flex data-horizontal:flex-col"
+
+        element :list, "cn-tabs-list group/tabs-list inline-flex w-fit items-center justify-center " \
+                       "group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col"
+        element :list_default, "cn-tabs-list-variant-default"
+        element :list_line, "cn-tabs-list-variant-line"
+
+        element :trigger,
+                "cn-tabs-trigger relative inline-flex h-[calc(100%-1px)] flex-1 items-center " \
+                "justify-center whitespace-nowrap transition-all group-data-vertical/tabs:w-full " \
+                "group-data-vertical/tabs:justify-start focus-visible:border-ring " \
+                "focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 " \
+                "focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 " \
+                "aria-disabled:pointer-events-none aria-disabled:opacity-50 " \
+                "[&_svg]:pointer-events-none [&_svg]:shrink-0 after:absolute after:opacity-0 " \
+                "after:transition-opacity " \
+                "group-data-[variant=line]/tabs-list:data-active:after:opacity-100 " \
+                "after:bg-foreground dark:data-active:bg-input/30 dark:data-active:border-input " \
+                "dark:data-active:text-foreground " \
+                "dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent " \
+                "dark:group-data-[variant=line]/tabs-list:data-active:border-transparent " \
+                "dark:hover:text-foreground dark:text-muted-foreground data-active:bg-background " \
+                "data-active:text-foreground group-data-[variant=line]/tabs-list:bg-transparent " \
+                "group-data-[variant=line]/tabs-list:data-active:bg-transparent " \
+                "group-data-horizontal/tabs:after:bottom-[-5px] " \
+                "group-data-horizontal/tabs:after:h-0.5 group-data-horizontal/tabs:after:inset-x-0 " \
+                "group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:inset-y-0 " \
+                "group-data-vertical/tabs:after:w-0.5 hover:text-foreground text-foreground/60"
+
+        element :content, "cn-tabs-content flex-1 outline-none"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/tag_group/component.html.erb

@@ -0,0 +1,8 @@
+<%# Grid semantics: caption span (aria-labelledby - a grid is not a
+    labelable control), then the roving row collection. %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:span, label, "id" => label_id, "data-slot" => "tag-group-label", "class" => css(:label)) %>
+  <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(grid_attributes).to_attributes) do %>
+    <% tags.each do |tag_slot| %><%= tag_slot %><% end %>
+  <% end %>
+<% end %>