poetry-ui 0.0.2

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

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A mutually exclusive option set: radio dots or selectable choice cards.
+    module RadioGroup
+      # A set of mutually exclusive options, exactly one checkable -
+      # radio dots with labels, or selectable choice cards (item
+      # variant: :card). Reach for it when a handful of options should all
+      # be visible at once; larger lists belong in a Select.
+      #
+      # Keyboard: the group is one Tab stop; arrow keys move between items
+      # and selection follows that navigation - Tab into the group never
+      # changes the value. Form participation: one hidden native
+      # <input type=radio> per item under the shared name:, so the checked
+      # value serializes exactly like collection_radio_buttons and NOTHING
+      # submits while none is checked (presence validation stays honest).
+      # The server renders the roving tab stop (checked item tabindex=0,
+      # rest -1) so the one-Tab-stop contract holds before JS connects.
+      #
+      # @example
+      #   render Poetry::Ui::RadioGroup::Component.new(
+      #     name: "plan", value: "monthly", label: "Billing plan"
+      #   ) do |group|
+      #     group.with_item(value: "monthly", label: "Monthly")
+      #     group.with_item(value: "yearly", label: "Yearly")
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the keyboard-axis option.
+        ORIENTATIONS = %i[both vertical horizontal].freeze
+
+        # The closed vocabulary for the per-item variant axis.
+        ITEM_VARIANTS = %i[default card].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_radio_group / form.radio_group - never hand-roll role=radio buttons.",
+          "Every item MUST have a unique value: (ArgumentError on duplicates).",
+          "The GROUP must be labelled - label: (or aria-labelledby) - an unlabelled radiogroup is an " \
+          "APG violation (ArgumentError).",
+          "Pair every item with a visible label (item label: renders the Label for= pairing) - a bare " \
+          "dot is not an option.",
+          "variant: :card renders the choice-card row (title + description: inside a selectable " \
+          "bordered label) - the pick-a-plan pattern; the whole card toggles the radio.",
+          "NEVER write the checked attributes (data-checked/data-unchecked) without aria-checked (the " \
+          "controller writes both; agents patching DOM must too).",
+          "Do not use RadioGroup for navigation or immediate actions; checking must not submit or " \
+          "navigate by itself.",
+          "7+ options: use Select instead.",
+          "Wire errors through Field/FormBuilder (invalid: + describedby on the root) - never a bare " \
+          "red ring."
+        ].freeze
+
+        # The same facts the before_render raise enforces, stated statically
+        # so static checks can flag a missing item without rendering.
+        REQUIRED_SLOTS = { item: "at least one radio item" }.freeze
+
+        renders_many :items,
+                     doc: "One item per option: a real button[role=radio] carrying its own hidden native radio; " \
+                          "label: renders the dot beside a paired Label. variant: :card renders the choice-card row " \
+                          "instead - title (+ optional description:) inside a selectable bordered label, the radio " \
+                          "pinned to the right.",
+                     renders: lambda { |value:, label: nil, id: nil, disabled: false,
+                                       description: nil, variant: :default, **options|
+                       unless ITEM_VARIANTS.include?(variant)
+                         raise ArgumentError,
+                               "unknown RadioGroup item variant #{variant.inspect} - known: #{ITEM_VARIANTS.join(", ")}"
+                       end
+
+                       item_value = register_item_value!(value)
+                       item_id = id.presence || "#{control_id}-#{slug(item_value)}"
+                       item_disabled = disabled || self.disabled
+                       item = radio_item(item_value, item_id, item_disabled, options)
+
+                       next card_row(item, item_id, label, description) if variant == :card
+
+                       if description.present?
+                         raise ArgumentError, "RadioGroup description: rides the choice-card form - pass variant: :card"
+                       end
+
+                       next item if label.blank?
+
+                       # The item + Label pairing row. The for= targets the BUTTON id -
+                       # label clicks check via the controller (native label->button
+                       # activation).
+                       content_tag(:div, class: css(:row)) do
+                         safe_join([item, render(Label::Component.new(for_id: item_id).with_content(label))])
+                       end
+                     }
+
+        use_stimulus do
+          on :root do
+            controller :radio_group do
+              register
+              value :value, from: :value_string, if: :value?
+              # Selection follows focus: entry fires ONLY on arrow/Home/End
+              # navigation (never Tab), so checking on entry IS the APG
+              # radio contract.
+              action :entry_check, on: event(:roving_focus, :entry)
+            end
+            controller :roving_focus do
+              register
+              # DEFAULT tabindex-managing mode: the group is ONE Tab stop.
+              value :orientation
+              value :loop
+              action :keydown, on: :keydown
+            end
+          end
+          on :item do
+            controller(:radio_group) { action :check, on: :click }
+          end
+          # THE form participant: the hidden native radio the controller
+          # syncs.
+          on :input do
+            controller(:radio_group) { target :input }
+          end
+        end
+
+        option :name, :string, required: true,
+                               doc: "The shared form name for every hidden radio (FormBuilder derives object[method])."
+        option :value, :string, doc: "The checked item's value; nil = nothing checked (pre-selection)."
+        option :required, :boolean, default: false,
+                                    doc: "aria-required on the ROOT only - never native required on the hidden " \
+                                         "inputs (constraint-validation focus would land on an aria-hidden input)."
+        option :disabled, :boolean, default: false, doc: "Disables every item (root-level)."
+        option :loop, :boolean, default: true, doc: "Arrow-key navigation wraps at the ends."
+        option :orientation, :symbol, default: :both,
+                                      doc: "Keyboard axis: :both allows all four arrows (the standard radio " \
+                                           "pattern); :vertical/:horizontal restrict the axis. No visual effect."
+        option :invalid, :boolean, default: false,
+                                   doc: "aria-invalid on the items (the destructive ring) - set by Field/FormBuilder " \
+                                        "from model errors."
+        option :label, :string,
+               doc: "The group accessible name -> aria-label (or wire aria-labelledby yourself) - REQUIRED: an " \
+                    "unlabelled radiogroup fails the audit."
+
+        validates :orientation, inclusion: { in: ORIENTATIONS }
+
+        part "radio-group", "The role=radiogroup root - one Tab stop; items (and their " \
+                            "label-pairing rows) render as direct children",
+             states: {
+               "data-disabled" => "disabled: is set on the root - every item disables with it"
+             }
+        part "radio-group-item", "A button[role=radio] per item - carries its own hidden " \
+                                 "native radio as a sibling",
+             states: {
+               "data-checked" => "the checked item (the controller writes the pair and " \
+                                 "aria-checked together on every item)",
+               "data-unchecked" => "every other item",
+               "data-disabled" => "the item (or the whole group) is disabled - also the " \
+                                  "roving-focus collection filter",
+               "data-value" => "always - the item's value (keys the checked-value machine)"
+             }
+        part "radio-group-indicator", "The theme-sized centering box holding the checked dot " \
+                                      "(the dot itself is the themed " \
+                                      ".cn-radio-group-indicator-icon span) - hidden (the " \
+                                      "native attribute, toggled by the controller) while " \
+                                      "unchecked"
+        part "radio-group-card", "The choice-card row (variant: :card) - a <label> for= the " \
+                                 "radio button, so the whole card toggles; the checked " \
+                                 "treatments key on data-checked inside it"
+        part "radio-group-card-content", "Text column of a choice-card item (variant: :card) - " \
+                                         "title and description stack inside the card label"
+        part "radio-group-card-title", "The choice card's title line (the item label:)"
+        part "radio-group-card-description", "Muted copy under the choice card's title " \
+                                             "(description:)"
+
+        # @api private
+        def before_render
+          raise ArgumentError, "RadioGroup requires at least one with_item" unless items?
+
+          return if named?
+
+          raise ArgumentError,
+                "unlabelled RadioGroup - give it label: (or aria-labelledby); a radiogroup without an " \
+                "accessible name is an APG violation"
+        end
+
+        # @api private
+        def checked?(item_value)
+          value.present? && value.to_s == item_value
+        end
+
+        # The label-for/aria target root id - server-stable (Field-issued
+        # or auto) so item ids derive deterministically.
+        # @api private
+        def control_id
+          @control_id ||= poetry_instance_id("poetry-radio-group")
+        end
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "role" => "radiogroup", "data-slot" => "radio-group", "id" => control_id
+          }
+          attrs["aria-required"] = true if required
+          attrs["aria-label"] = label if label.present?
+          attrs["data-disabled"] = "" if disabled
+          html_attributes.merge_if_not_set(
+            attrs.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        private
+
+        def register_item_value!(value)
+          @item_values ||= Set.new
+          item_value = value.to_s
+          unless @item_values.add?(item_value)
+            raise ArgumentError, "duplicate RadioGroup item value #{item_value.inspect} - values key " \
+                                 "the checked-value machine"
+          end
+
+          item_value
+        end
+
+        # No raw user string becomes an id/selector fragment.
+        def slug(value)
+          value.gsub(/[^a-zA-Z0-9_-]+/, "-")
+        end
+
+        # The choice-card row: the whole card IS a label (for= the radio
+        # button, native label->button activation), title + description
+        # stacked left, the radio right. A plain <label> with its own
+        # radio-group-card slot, NOT the Label component - a nested
+        # data-component boundary would hand this subtree's part
+        # ownership to Label (the part-contract walker attributes DOM to
+        # the nearest component). The checked/bordered treatments ride
+        # the theme's cn-field-label rules off the item's data-checked
+        # inside.
+        def card_row(item, item_id, label, description)
+          raise ArgumentError, "RadioGroup card items need label: (the card title)" if label.blank?
+
+          text = content_tag(:div, "data-slot" => "radio-group-card-content", class: css(:card_content)) do
+            parts = [content_tag(:div, label, "data-slot" => "radio-group-card-title",
+                                              class: css(:card_title))]
+            if description.present?
+              parts << content_tag(:p, description, "data-slot" => "radio-group-card-description",
+                                                    class: css(:card_description))
+            end
+            safe_join(parts)
+          end
+          content_tag(:label, safe_join([text, item]),
+                      "data-slot" => "radio-group-card", "for" => item_id, class: css(:card))
+        end
+
+        def named?
+          aria = html_attributes["aria"] || {}
+          label.present? ||
+            html_attributes["aria-label"].present? || html_attributes["aria-labelledby"].present? ||
+            aria["label"].present? || aria["labelledby"].present?
+        end
+
+        def radio_item(item_value, item_id, item_disabled, options)
+          checked = checked?(item_value)
+
+          attrs = {
+            type: "button", role: "radio", id: item_id, class: item_classes(options.delete(:class)),
+            "data-slot" => "radio-group-item", "data-poetry-collection-item" => "",
+            "data-value" => item_value,
+            "aria-checked" => checked.to_s, (checked ? "data-checked" : "data-unchecked") => "",
+            "tabindex" => tab_stop?(item_value, item_disabled) ? "0" : "-1"
+          }
+          attrs["aria-invalid"] = "true" if invalid
+          if item_disabled
+            attrs[:disabled] = true
+            attrs["data-disabled"] = "" # the roving-focus collection filter
+          end
+          attrs.merge!(stimulus_attributes_for(:item))
+
+          # The native input is the button's SIBLING - a focusable native
+          # control inside a role=radio button is an axe nested-interactive
+          # violation.
+          safe_join([
+                      content_tag(:button, Poetry::Core::HTML::Attributes.merged(attrs, options)) do
+                        indicator(checked)
+                      end,
+                      hidden_radio(item_value, item_id, checked, item_disabled)
+                    ])
+        end
+
+        def indicator(checked)
+          attrs = { class: css(:indicator), "data-slot" => "radio-group-indicator" }
+          # A hidden attr toggle, not element presence - no check animation
+          # is rendered (morph-safe).
+          attrs[:hidden] = true unless checked
+          content_tag(:span, content_tag(:span, "", class: css(:dot)), attrs)
+        end
+
+        # THE form participant: native radio serialization (same form+name
+        # group), aria-hidden + tabindex=-1 (the role=radio button is the
+        # focusable/AT surface - render tests pin the no-double-Tab-stop
+        # invariant).
+        def hidden_radio(item_value, item_id, checked, item_disabled)
+          tag.input(type: "radio", name: name, value: item_value, id: "#{item_id}-input",
+                    checked: checked, disabled: item_disabled, "aria-hidden": true,
+                    tabindex: "-1", class: css(:input),
+                    **stimulus_attributes_for(:input).transform_keys(&:to_sym))
+        end
+
+        # The server renders the roving contract: exactly one tabindex=0 -
+        # the checked item, else the FIRST enabled item (Tab lands there
+        # when nothing is checked). Sequential across item registration.
+        def tab_stop?(item_value, item_disabled)
+          return false if @tab_stop_assigned || item_disabled
+
+          stop = value.present? ? checked?(item_value) : true
+          @tab_stop_assigned = true if stop
+          stop
+        end
+
+        def item_classes(extra)
+          classnames(css(:item), extra)
+        end
+
+        def value_string = value.to_s
+        def value? = value.present?
+
+        private :checked?, :control_id, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module RadioGroup
+      # The RadioGroup preview matrix: group configs (none-checked,
+      # one-checked, required, disabled) x item states (checked, disabled,
+      # invalid), the radio-group-demo port, and the horizontal-layout
+      # recipe (caller classes; the keyboard stays both-axis).
+      class Preview < Poetry::Core::Preview::Base
+        # @!group States
+
+        # The radio-group-demo port: value pre-checked, items paired with
+        # Labels via item label:.
+        def default
+          render_component(name: "density", value: "comfortable", label: "Density") do |group|
+            group.with_item(value: "default", label: "Default")
+            group.with_item(value: "comfortable", label: "Comfortable")
+            group.with_item(value: "compact", label: "Compact")
+          end
+        end
+
+        # Nothing checked (pre-selection): Tab lands on the FIRST enabled
+        # item; nothing submits until the user chooses (presence
+        # validation stays honest).
+        def none_checked
+          render_component(name: "plan", label: "Plan") do |group|
+            group.with_item(value: "monthly", label: "Monthly")
+            group.with_item(value: "yearly", label: "Yearly")
+          end
+        end
+
+        # A disabled option mid-list: skipped by Tab AND filtered from the
+        # arrow collection.
+        def disabled_item
+          render_component(name: "tier", value: "free", label: "Tier") do |group|
+            group.with_item(value: "free", label: "Free")
+            group.with_item(value: "pro", label: "Pro (unavailable)", disabled: true)
+            group.with_item(value: "enterprise", label: "Enterprise")
+          end
+        end
+
+        # Root-level disabled: a locked-in choice still renders its dot
+        # (and still submits - hidden radios disable too, so it does NOT).
+        def disabled_group
+          render_component(name: "plan", value: "yearly", disabled: true, label: "Plan") do |group|
+            group.with_item(value: "monthly", label: "Monthly")
+            group.with_item(value: "yearly", label: "Yearly")
+          end
+        end
+
+        # The field-level error treatment: aria-invalid on every item (the
+        # destructive ring), wired by Field/FormBuilder upstream.
+        def invalid
+          render_component(name: "plan", invalid: true, required: true, label: "Plan") do |group|
+            group.with_item(value: "monthly", label: "Monthly")
+            group.with_item(value: "yearly", label: "Yearly")
+          end
+        end
+
+        # The choice-card items (variant: :card): title + description
+        # inside a selectable bordered label - the whole card toggles the
+        # radio (the upstream Choice Card recipe).
+        def choice_cards
+          render_component(name: "compute", value: "kubernetes", label: "Compute environment",
+                           class: "w-80") do |group|
+            group.with_item(value: "kubernetes", label: "Kubernetes", variant: :card,
+                            description: "Run GPU workloads on a K8s cluster.")
+            group.with_item(value: "vm", label: "Virtual Machine", variant: :card,
+                            description: "Access a cluster to run GPU workloads.")
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Recipes
+
+        # Horizontal layout is a CALLER class (source has no orientation
+        # styling); the keyboard stays both-axis.
+        def horizontal_layout
+          render_component(name: "align", value: "left", label: "Alignment", class: "grid-flow-col") do |group|
+            group.with_item(value: "left", label: "Left")
+            group.with_item(value: "center", label: "Center")
+            group.with_item(value: "right", label: "Right")
+          end
+        end
+
+        # Field-bound (the FormBuilder shape): the group takes the Field's
+        # id + describedby; the hint reads on the ROOT (group-level).
+        def in_a_field
+          field = Field::Component.new(
+            id: "preview-plan", label_text: "Plan",
+            hint: "You can change this anytime.", required: true
+          )
+          render_component(field) do
+            embed(Component.new(name: "plan", value: "monthly", required: true, label: "Plan",
+                                id: "preview-plan",
+                                "aria-describedby": "preview-plan-hint")) do |group|
+              group.with_item(value: "monthly", label: "Monthly")
+              group.with_item(value: "yearly", label: "Yearly")
+            end
+          end
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module RadioGroup
+      # Style dictionary for the RadioGroup family: the well + dot
+      # treatments ride the themes. The indicator is a theme-SIZED box so
+      # the absolutely-centered dot anchors against a real rect regardless
+      # of the item's display - an unsized anchor span centers only by
+      # flow accident (7px off under nova's flex item). :input stays the
+      # hidden native form bridge and :row the label pairing row - both
+      # structural, no cn names.
+      class Style < Poetry::Core::Style
+        base "cn-radio-group w-full"
+
+        element :item, "cn-radio-group-item group/radio-group-item peer relative aspect-square " \
+                       "shrink-0 border outline-none after:absolute after:-inset-x-3 " \
+                       "after:-inset-y-2 disabled:cursor-not-allowed disabled:opacity-50"
+
+        element :indicator, "cn-radio-group-indicator"
+
+        # The checked dot - a bare themed span (bg + size + centering all
+        # live in the theme's cn-radio-group-indicator-icon rule).
+        element :dot, "cn-radio-group-indicator-icon"
+
+        # The form participant: one hidden native radio PER item, shared
+        # name - out of the Tab order and the accessibility tree (the
+        # role=radio button is the accessible control).
+        element :input, "sr-only"
+
+        # The item+Label pairing row (radio-group-demo parity) rendered
+        # when an item passes label:.
+        element :row, "flex items-center gap-3"
+
+        # The choice-card row (item variant: :card): the card IS the
+        # label, wearing the Field family's cn-field-label hooks so one
+        # theme rule styles choice cards wherever they appear. Upstream
+        # nests FieldLabel > Field > FieldContent; poetry flattens the
+        # row onto the label (cn-field-label-card carries the border/
+        # padding the nested [data-slot=field] selectors keyed upstream).
+        # cn-label rides along because the card is a plain <label>, not
+        # the Label component (part-ownership: a nested data-component
+        # boundary would hand the card slots to Label).
+        element :card, "cn-label cn-field-label cn-field-label-card flex w-full items-center " \
+                       "select-none has-data-disabled:opacity-50"
+        element :card_content, "cn-field-content group/field-content flex flex-1 flex-col " \
+                               "leading-snug"
+        element :card_title, "cn-field-title flex w-fit items-center"
+        element :card_description, "cn-field-description"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <% panel_defs.each_with_index do |panel, index| %>
+    <% unless index.zero? %>
+      <%= content_tag(:div, handle_attributes(index - 1)) do %>
+        <% if grip %><div class="<%= css(:grip) %>"></div><% end %>
+      <% end %>
+    <% end %>
+    <%= content_tag(:div, capture(&panel.block), panel_attributes(panel, index)) %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A panel group divided by draggable splitter handles.
+    module Resizable
+      # A group of panels - side by side or stacked - divided by draggable
+      # splitter handles, so the reader can redistribute the space. Panels
+      # are flex children whose flex-grow IS the percentage, handles are
+      # role=separator splitters with full keyboard support (arrows step,
+      # Home/End jump), and the controller owns the drag + keyboard
+      # redistribution. Declare panels with with_panel; the component
+      # interleaves the handles and wires the ARIA.
+      #
+      # @example
+      #   render Poetry::Ui::Resizable::Component.new(class: "h-48 rounded-lg border") do |group|
+      #     group.with_panel(default_size: 25) { tag.div("Sidebar") }
+      #     group.with_panel { tag.div("Content") }
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the group-axis option.
+        DIRECTIONS = %i[horizontal vertical].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Declare panels with with_panel(default_size:, min_size:, max_size:) - sizes are " \
+          "PERCENTAGES and the component interleaves the separator handles.",
+          "direction: :horizontal is side-by-side (the default); :vertical stacks.",
+          "Handles are keyboard splitters (arrows step, Home/End jump) - never replace them " \
+          "with styled divs.",
+          "Nest a group inside a panel for two-axis layouts - groups self-scope."
+        ].freeze
+
+        # The with_panel content-block requirement, stated statically for
+        # static checks.
+        SLOT_REQUIRED_CONTENT = { panel: "the panel content" }.freeze
+
+        # The same facts the before_render raise enforces, stated statically
+        # so static checks can flag too few panels without rendering.
+        REQUIRED_SLOTS = { panel: "at least two panels" }.freeze
+
+        renders_many :panels,
+                     doc: "One panel per call: default_size/min_size/max_size are percentages of the group; the " \
+                          "content block is required.",
+                     renders: lambda { |default_size: nil, min_size: nil, max_size: nil, classes: nil, &block|
+                       unless block
+                         raise ArgumentError,
+                               "Resizable with_panel requires a content block (the panel content)"
+                       end
+
+                       panel_defs << Panel.new(default_size: default_size, min_size: min_size,
+                                               max_size: max_size, classes: classes, block: block)
+                       nil
+                     }
+
+        use_stimulus do
+          on :root do
+            controller :resizable do
+              register
+              value :orientation, from: :direction
+            end
+          end
+          # The full drag trio + keyboard on each handle; panels are found
+          # by DOM position (no targets).
+          on :handle do
+            controller :resizable do
+              action :drag_start, on: :pointerdown
+              action :drag_move, on: :pointermove
+              action :drag_end, on: :pointerup
+              action :keydown, on: :keydown
+            end
+          end
+        end
+
+        option :direction, :symbol, default: :horizontal,
+                                    doc: "The group axis: :horizontal lays panels side by side, :vertical stacks them."
+        option :grip, :boolean, default: false, doc: "Renders the grip dots on each handle."
+
+        validates :direction, inclusion: { in: DIRECTIONS }
+
+        part "resizable-panel-group", "The flex group root - the splitter controller rides here",
+             states: {
+               "data-orientation" => { condition: "the group axis", values: DIRECTIONS.map(&:to_s) }
+             }
+        part "resizable-panel", "One flex child whose flex-grow IS its percentage - the controller " \
+                                "rewrites the inline flex on every resize",
+             states: {
+               "data-min-size" => "the panel's minimum percentage, rendered when with_panel passes " \
+                                  "min_size: (the controller's clamp floor)",
+               "data-max-size" => "the panel's maximum percentage, rendered when with_panel passes " \
+                                  "max_size: (the controller's clamp ceiling)"
+             }
+        part "resizable-handle", "The role=separator splitter between panels - drag and keyboard " \
+                                 "resizing live here; its aria-valuenow tracks the preceding panel"
+
+        # @api private
+        def before_render
+          # panels? forces the render block (the slot-predicate rule -
+          # panel_defs is empty until it runs).
+          raise ArgumentError, "Resizable requires at least two with_panel declarations" unless
+            panels? && panel_defs.size >= 2
+        end
+
+        # @api private
+        def panel_defs
+          @panel_defs ||= []
+        end
+
+        # Even shares when default_size: is omitted.
+        # @api private
+        def size_of(panel)
+          panel.default_size || (100.0 / panel_defs.size).round(2)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "resizable-panel-group", "data-orientation" => direction
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def panel_attributes(panel, index)
+          attrs = {
+            "id" => panel_id(index), "data-slot" => "resizable-panel",
+            "class" => [css(:panel), panel.classes].compact.join(" "),
+            "style" => "flex: #{size_of(panel)} 1 0px"
+          }
+          attrs["data-min-size"] = panel.min_size if panel.min_size
+          attrs["data-max-size"] = panel.max_size if panel.max_size
+          attrs
+        end
+
+        # The splitter: a separator whose value tracks the PRECEDING
+        # panel; its visual orientation is PERPENDICULAR to the group axis
+        # (a side-by-side group has a vertical bar), which is also what
+        # the dictionary's aria-[orientation] selectors key on.
+        # @api private
+        def handle_attributes(index)
+          before = panel_defs[index]
+          {
+            "role" => "separator", "tabindex" => "0",
+            "data-slot" => "resizable-handle",
+            "aria-orientation" => direction == :horizontal ? "vertical" : "horizontal",
+            "aria-controls" => panel_id(index),
+            # Server-rendered initial value (the controller reconciles on
+            # connect) - the splitter announces even before JS.
+            "aria-valuenow" => size_of(before).round,
+            # The announced bounds fall back to 10/90 percent when the
+            # panel declares no min_size:/max_size: clamp.
+            "aria-valuemin" => before.min_size || 10,
+            "aria-valuemax" => before.max_size || 90,
+            "class" => css(:handle)
+          }.merge(stimulus_attributes_for(:handle))
+        end
+
+        # @api private
+        def panel_id(index)
+          "#{instance_id}-panel-#{index}"
+        end
+
+        # One declared panel: its size bounds, extra classes, and content block.
+        # @api private
+        Panel = Data.define(:default_size, :min_size, :max_size, :classes, :block)
+
+        private
+
+        def instance_id
+          @instance_id ||= poetry_instance_id("poetry-resizable")
+        end
+
+        private :panel_defs, :size_of, :root_attributes, :panel_attributes, :handle_attributes, :panel_id
+      end
+    end
+  end
+end