poetry-ui 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83490085dc76d9571592fc20f909ed21c4dc36625df781b284e552396ed39db9
-  data.tar.gz: 92251c4128e98d2d1d4ab452cd8723fe722c30ae4cd97d8f1aafb4b1968c8ef4
+  metadata.gz: 27935417c8f6663b28bc05dc0d7dabbd326996ff8fd7e36437a069114c1bf7a3
+  data.tar.gz: 4249407b7b6e91b02a38846b8927e6a50cc13897a15626f55312974bc54915f2
 SHA512:
-  metadata.gz: 321ecf105f65b599312096b0d77b54ee9bc829ed86ff44f96f71e660bc1de0b64e2432b21567a978fb05e2beab37a31a188c9b8c012ac85b628d39687880e401
-  data.tar.gz: 474c0a4c380e214e2b98452105f0859ddaac4385480170a647d1fd556b8a01d25cb40955666bfcadde26c568bed8cefafba746eda7468ab38d9c9f6d70ffdeda
+  metadata.gz: 927db8c50cc562398078117ec76828112eae5618fef74e33813b710c3b1ee49d3d6e40c1f2b372663891259f43520f894c19797dab9b299611dbde6fc224df52
+  data.tar.gz: b12b930bb1ada7389f82366d6a3864d908021ee152e6fc018216ed8dfa157dbff7c096ad1c3d72dd94e0bb1b3031b6e8947464462a406a2fd47807d1fcb2ec06

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.1.8] - 2026-09-22
+
+The robosite proof: a full Jumpstart Pro application re-skinned on Poetry surfaced 28 findings; the 20 that were Poetry's to fix land here, with the form builder taking most of them.
+
+### Added
+
+- `form.checkbox_group` maps records through `value_method:` and `label_method:` (a symbol sent to the item, or a callable), and `checked:` names the checked values explicitly for a collection the object has no reader for.
+- `form.file_input` flips the form to multipart (Rails' own `file_field` line), and a block given to it renders beside the control inside the Field: the seat for the current attachment's preview.
+- Every builder method takes `label:` for the visible Field label (`label: false` drops it) and `aria_label:` for an accessible name alone; `label:` on a control used to become that control's `aria-label`, invisible.
+- Model-less forms: `form_with(url:, scope:)` renders every builder method, with labels from the scope's i18n or the humanized method and empty values, where the object-less call raised before.
+- NavigationMenu `with_link(title, href:, active: true)` marks the current page's top-level link (`data-active` plus `aria-current="page"`, the trigger's open treatment); the top-nav block marks its Docs link.
+- AlertDialog `with_action(submit: "form-id")` makes the action that form's submit button (`type="submit"` plus the `form` attribute), so a confirmation submits a form on the page without nesting one inside the dialog; the destructive-panel block adopts it.
+- MessageScroller `content_id:` names the content element's dom id directly (the default stays `"<id>-messages"`), and `poetry_message_scroller_item` takes `dom_id:` for a row's own DOM id beside its message id.
+- NativeSelect routes `id:` and every `aria-*` attribute (flat, or nested `aria:`) onto the `<select>` itself, so a Field's `control_attributes` splat straight in; `described_by:` stays as the older spelling. The builder's `native_select` now hands the select `aria-required` too.
+- Autocomplete lands the given `id:` on its `<input>` (the Field label's `for=` target) and derives the root, list and item ids from it; `aria-*` attributes move to the input the same way.
+- The table part helpers consume `key:` (it never renders as an attribute): `poetry_table_row(key: record)` derives `id="table-row-<dom_id>"` for a morph to follow; the other parts drop it. The registry declares the seven parts `identity: false`, so `poetry check` stops asking them for a key.
+
+### Changed
+
+- `form.submit` renders the Button named `commit` with the label as its value, so `params[:commit]` reads as it does under Rails' own submit; `form.button` is named `button`, Rails' own name for it. Pass `name:` or `value:` to override either.
+- `form.check_box` and `form.switch` render inside the horizontal Field with the visible label, the shape boolean `f.input` already had; the Rails arity (`checked_value`, `unchecked_value`) is unchanged.
+- The builder reads `false` and `0` as values: a tristate select shows No and a zero count shows 0, where `.presence` had blanked both. A virtual attribute with no reader renders empty instead of raising.
+- Labels resolve from Rails' `helpers.label.<object_name>.<method>` first, the key `f.label` reads, then `poetry_form.labels` / `simple_form.labels`, then `human_attribute_name`; placeholders read `helpers.placeholder.*` first. Hints and placeholders now resolve on direct control calls (`form.field`, `form.native_select`), not only through `f.input`.
+- Collapsible's `with_trigger` composes a poetry Button, the way Popover's does: keywords are Button props (`variant:`, `size:`), and the trigger wears Button's treatment. The previews use `variant: :ghost, size: :sm`.
+- Button's anchor form (`tag: :a`, or `href:`) renders no `role="button"`: a link stays a link, announced by its destination and activated by Enter. A caller's `role:` still lands.
+- Avatar's `label:` is no longer required: without one the avatar renders decorative (`aria-hidden`, no `role="img"`) with its initials fallback, the right shape beside a visible name; the content block is still required.
+- InputOTP stamps its default `aria-label` only when nothing names the input already: an `aria-label`, an `aria-labelledby`, or an `id` a Field label points at.
+- Card renders its `card-content` cell only when the content block gives content; a header-and-footer card no longer carries an empty body cell.
+- FieldSeparator is the labelled rule anywhere ("Or continue with" under a sign-in form, a date break), not only between fields in a FieldGroup.
+
+## [0.1.7] - 2026-09-20
+
+### Changed
+
+- Version bump with the family; no changes in this gem.
+
 ## [0.1.6] - 2026-09-20
 
 ### Changed

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

@@ -36,6 +36,8 @@ module Poetry
           "never a bare Dialog, never data-turbo-confirm.",
           "with_title AND with_description are REQUIRED (both raise).",
           "The action must be an explicit user activation - agents NEVER auto-submit the action.",
+          "with_action(submit: \"form-id\") makes the action that form's submit button (type=submit plus the " \
+          "form attribute - no form nests inside the dialog); the activation stays the user's.",
           "No extra form fields inside an AlertDialog - if input is needed, use a Dialog.",
           "Cancel keeps variant: :outline; do not make cancel visually primary."
         ].freeze
@@ -66,10 +68,20 @@ module Poetry
         renders_one :media, doc: "Optional icon/illustration well above the title."
         renders_one :action,
                     doc: "The confirming choice (required) - a Button; pass variant: :destructive for deletes. " \
-                         "Activating it also closes the dialog (a caller-supplied data-action opts out).",
-                    renders: lambda { |**options, &block|
+                         "Activating it also closes the dialog (a caller-supplied data-action opts out). " \
+                         "submit: names the form it submits (type=submit plus the form attribute).",
+                    renders: lambda { |submit: nil, **options, &block|
+                      if submit && options[:href]
+                        raise ArgumentError,
+                              "AlertDialog with_action(submit:) is a form's submit button - it takes no href:"
+                      end
+
                       options[:data] =
                         { slot: "alert-dialog-action", action: stimulus_action(:close) }.merge(options[:data] || {})
+                      if submit
+                        options[:type] = :submit
+                        options[:form] = submit
+                      end
                       Button::Component.new(**options, &block)
                     }
         renders_one :cancel,

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

@@ -25,9 +25,16 @@ module Poetry
           "empty_text: renders the no-matches state (hidden while anything matches).",
           "open_on_focus: false waits for typing before suggesting.",
           "Server-side filtering stays yours: render fewer items on re-render - the client " \
-          "filter only narrows what the server sent."
+          "filter only narrows what the server sent.",
+          "id: is the INPUT's id (a Field's label for= target); the root, list and item ids derive " \
+          "from it, and every aria-* attribute lands on the input (Field control_attributes splat in)."
         ].freeze
 
+        # The aria attributes a caller (or a Field's control_attributes)
+        # passes name the INPUT, not the root: pulled off the root in
+        # #initialize and merged into the input's attributes.
+        INPUT_ARIA = /\Aaria-/
+
         use_stimulus do
           on :root do
             controller :autocomplete do
@@ -69,7 +76,8 @@ module Poetry
 
         option :name, :string, required: true, doc: "The form param key; the input's text submits under it as-is."
         option :value, :string, doc: "The initial input text."
-        option :id, :string, doc: "Stable DOM id token for the root and list ids."
+        option :id, :string, doc: "The input's DOM id (the Field label target); the root, list and item ids " \
+                                  "derive from it (-root, -list, -item-n)."
         option :placeholder, :string, doc: "Placeholder text shown while the input is empty."
         option :label, :string, doc: "The accessible name (or wire aria-labelledby via html attrs)."
         option :empty_text, :string, default: "No results.",
@@ -125,19 +133,19 @@ module Poetry
         # @api private
         def item_models = (@item_models ||= [])
 
-        # The root id: the given id as a token, else a stable instance id.
+        # The input's id: the given id, else a stable instance id.
         # @api private
-        def autocomplete_id
-          @autocomplete_id ||= if (token = dom_id_token(id))
-                                 "poetry-autocomplete-#{token}"
-                               else
-                                 poetry_instance_id("poetry-autocomplete")
-                               end
+        def input_id
+          @input_id ||= id.presence || poetry_instance_id("poetry-autocomplete")
         end
 
-        # The listbox's id.
+        # The root id, derived from the input's.
+        # @api private
+        def autocomplete_id = "#{input_id}-root"
+
+        # The listbox's id, derived from the input's.
         # @api private
-        def list_id = "#{autocomplete_id}-list"
+        def list_id = "#{input_id}-list"
 
         # The root's attributes: this component's markup over the core default.
         def root_attributes
@@ -148,11 +156,12 @@ module Poetry
         # @api private
         def input_attributes
           attrs = {
-            name: name, value: value, placeholder: placeholder, type: :text,
+            name: name, value: value, placeholder: placeholder, type: :text, id: input_id,
             autocomplete: "off", role: "combobox",
             "aria-autocomplete": "list", "aria-expanded": open.to_s, "aria-controls": list_id,
             "data-slot": "autocomplete-input"
           }
+          attrs.merge!(@input_aria)
           attrs[:"aria-label"] = label if label.present?
           attrs.merge(stimulus_attributes_for(:input).transform_keys(&:to_sym))
         end
@@ -177,7 +186,7 @@ module Poetry
         def item_attributes(item, index)
           attrs = {
             "class" => Poetry::Ui::Command::Style.css(:item), "data-slot" => "autocomplete-item",
-            "id" => "#{autocomplete_id}-item-#{index}", "role" => "option",
+            "id" => "#{input_id}-item-#{index}", "role" => "option",
             "data-label" => item.label
           }
           attrs["data-value"] = item.value if item.value.present?
@@ -191,7 +200,19 @@ module Poetry
         # @api private
         Item = Struct.new(:label, :value, :disabled, :highlighted, keyword_init: true)
 
-        private :item_models, :autocomplete_id, :list_id, :input_attributes, :content_attributes
+        private
+
+        # Pulls the aria-* attributes (flat, or nested aria: {}) off the
+        # root for the input - the Select trigger pattern, so a Field's
+        # control_attributes name the real control.
+        def initialize(**)
+          super
+          @input_aria = @html_attributes.keys.grep(INPUT_ARIA).to_h { |key| [key.to_sym, @html_attributes.delete(key)] }
+          nested = @html_attributes.delete("aria")
+          nested.each { |key, value| @input_aria[:"aria-#{key}"] = value } if nested.is_a?(Hash)
+        end
+
+        private :item_models, :input_id, :autocomplete_id, :list_id, :input_attributes, :content_attributes
         private :item_attributes
       end
     end

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

@@ -20,7 +20,8 @@ module Poetry
 
         # Projected into the registry, llms.txt, and the agent surface.
         AGENT_RULES = [
-          "label: (the person's name) is REQUIRED - it is the avatar's accessible name (role=img).",
+          "label: (the person's name) is the avatar's accessible name (role=img); without one the avatar " \
+          "renders decorative (aria-hidden) - right beside the visible name, wrong on its own.",
           "The content block is the fallback (initials) and is also required - it is what shows " \
           "while the image loads or when it fails.",
           "The badge slot is decorative (a presence dot); put the status meaning in label:, " \
@@ -31,15 +32,15 @@ module Poetry
         renders_one :badge, doc: "Decorative presence dot, bottom-right; keep the status meaning in label:."
 
         option :src, :string, doc: "The image URL; without it only the initials fallback shows."
-        option :label, :string, required: true,
-                                doc: "The person's name - the avatar's accessible name (blank raises). The required " \
-                                     "flag also carries the fact to the registry so static checks see it."
+        option :label, :string, doc: "The person's name - the avatar's accessible name (role=img). Without one " \
+                                     "the avatar is decorative (aria-hidden, no role): use that beside the " \
+                                     "visible name, never for an avatar that stands alone."
         option :size, :symbol, default: :default, doc: "The diameter axis."
 
         validates :size, inclusion: { in: SIZES }
 
-        part "avatar", "Root span (role=img carrying the accessible name) - fallback, image, " \
-                       "and badge layer inside it",
+        part "avatar", "Root span (role=img carrying the accessible name, or aria-hidden without label:) - " \
+                       "fallback, image, and badge layer inside it",
              states: {
                "data-size" => { condition: "always - the resolved size", values: SIZES.map(&:to_s) }
              }
@@ -49,11 +50,9 @@ module Poetry
                              "is given; a failed load paints nothing"
         part "avatar-badge", "The decorative presence dot (the badge slot), bottom-right"
 
-        # Enforces label: and the initials content block.
+        # Enforces the initials content block.
         # @api private
         def before_render
-          raise ArgumentError, "Avatar requires label: (the person's name - its accessible name)" if label.blank?
-
           ensure_content!
         end
 
@@ -65,14 +64,11 @@ module Poetry
           end
         end
 
-        # The root's attributes: this component's markup over the core default.
+        # The root's attributes: this component's markup over the core
+        # default - named (role=img) with a label, decorative without.
         def root_attributes
-          super(
-            {
-              "data-size" => size,
-              "role" => "img", "aria-label" => label
-            }
-          )
+          naming = label.present? ? { "role" => "img", "aria-label" => label } : { "aria-hidden" => "true" }
+          super({ "data-size" => size }.merge(naming))
         end
 
         private

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

@@ -54,7 +54,8 @@ module Poetry
         option :type, :symbol, default: :button,
                                doc: "The native button type; ignored when the button renders as an anchor."
         option :tag, :symbol, default: :button,
-                              doc: "Renders the same styling on an <a> when :a - navigation wearing button clothes."
+                              doc: "Renders the same styling on an <a> when :a - navigation wearing button clothes; " \
+                                   "the anchor keeps its link semantics (no role)."
         option :disabled, :boolean, default: false,
                                     doc: "Disables the control (native disabled; aria-disabled on the anchor form)."
         option :loading, :boolean, default: false,
@@ -139,15 +140,18 @@ module Poetry
         end
 
         # Native <button> gets native semantics (type, real disabled);
-        # `tag: :a` is navigation-styled-as-button: role="button" + the
-        # faux-disabled convention (aria-disabled, href withheld).
+        # `tag: :a` is navigation-styled-as-button: a link that stays a
+        # link (no role - assistive tech announces the destination, and
+        # Enter, not Space, activates it) plus the faux-disabled
+        # convention (aria-disabled, href withheld). A caller's role:
+        # still lands through the passthrough.
         def tag_attributes
           link_tag? ? link_attributes : button_attributes
         end
 
-        # The anchor's attributes: the button role, and the href or the disabled state.
+        # The anchor's attributes: the href or the disabled state.
         def link_attributes
-          attrs = { "role" => "button" }
+          attrs = {}
           if disabled || loading
             attrs["aria-disabled"] = true
           elsif href.present?

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

@@ -6,6 +6,6 @@
       <% if action? %><div data-slot="card-action" class="<%= css(:action) %>"><%= action %></div><% end %>
     </div>
   <% end %>
-  <div data-slot="card-content" class="<%= css(:content, class: content_class) %>"><%= content %></div>
+  <% if content.present? %><div data-slot="card-content" class="<%= css(:content, class: content_class) %>"><%= content %></div><% end %>
   <% if footer? %><%= content_tag(:div, footer_attributes) do %><%= capture(&footer_block) if footer_block %><% end %><% end %>
 <% end %>

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

@@ -56,7 +56,8 @@ module Poetry
         part "card-title", "The heading (title_tag, h3 by default)"
         part "card-description", "Muted one-liner under the title"
         part "card-action", "The header's trailing corner control"
-        part "card-content", "The body - the content block renders here"
+        part "card-content", "The body - renders when the content block gives content (a header-and-footer " \
+                             "card has no empty body cell)"
         part "card-footer", "The bottom row (actions/meta)"
 
         # The caller's footer block, captured by with_footer.

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

@@ -21,7 +21,8 @@ module Poetry
         # Projected into the registry, llms.txt, and the agent surface.
         AGENT_RULES = [
           ComposableTrigger::AGENT_RULE,
-          "The trigger is with_trigger { \"label\" } - a real button, wired for you (aria-expanded/controls).",
+          "The trigger is with_trigger { \"label\" } - a poetry Button (keywords are Button props: variant:, " \
+          "size:), wired for you (aria-expanded/controls).",
           "Server-render the initial state via open: - never toggle data-open/data-closed by hand.",
           "Content stays in the DOM when closed (hidden) - do not conditionally render it.",
           "For URL-controlled disclosure without JS, render open: from params - the same markup serves both."
@@ -31,16 +32,20 @@ module Poetry
         # a missing trigger without rendering.
         REQUIRED_SLOTS = { trigger: "the disclosure control" }.freeze
 
+        # The class the trigger slot renders - with_trigger composes a
+        # Button, so callers get Button's full option contract.
+        SLOT_RENDERS = { trigger: Button::Component }.freeze
+
         renders_one :trigger,
-                    doc: "The disclosure control - a real button, wired for you (aria-expanded, aria-controls); " \
-                         "options merge onto it.",
+                    doc: "The disclosure control - a composed Button (keywords are Button props), wired for you " \
+                         "(aria-expanded, aria-controls).",
                     renders: lambda { |**options, &block|
-                      attrs = {
-                        type: "button", "data-slot" => "collapsible-trigger",
+                      wiring = {
+                        "data-slot" => "collapsible-trigger",
                         "aria-expanded" => open.to_s, "aria-controls" => content_id
                       }.merge(stimulus_attributes_for(:trigger))
-                      composed_trigger(attrs, options, &block) ||
-                        content_tag(:button, Poetry::Core::HTML::Attributes.merged(attrs, options), &block)
+                      composed_trigger(wiring, options, &block) ||
+                        Button::Component.new(**wiring, **options, &block)
                     }
 
         use_stimulus do
@@ -66,10 +71,12 @@ module Poetry
                "data-open" => "expanded (server-rendered from open:; the controller flips the pair at runtime)",
                "data-closed" => "collapsed (the server-rendered default)"
              }
-        part "collapsible-trigger", "The disclosure button - mirrors aria-expanded",
+        part "collapsible-trigger", "The disclosure button - a composed Button - mirrors aria-expanded",
              states: {
                "data-panel-open" => "its content is open (controller-written; " \
-                                    "absent while closed)"
+                                    "absent while closed)",
+               "data-variant" => "always - the composed Button's variant axis",
+               "data-size" => "always - the composed Button's size axis"
              }
         part "collapsible-content", "The disclosure panel - stays in the DOM when closed (hidden) " \
                                     "and rides the presence helper on exit",

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

@@ -7,14 +7,14 @@ module Poetry
       class Preview < Poetry::Core::Preview::Base
         def default
           render_component do |collapsible|
-            collapsible.with_trigger(class: "text-sm font-medium underline-offset-4 hover:underline") { "Show details" }
+            collapsible.with_trigger(variant: :ghost, size: :sm) { "Show details" }
             tag.div("Hidden until disclosed.", class: "pt-2 text-sm text-muted-foreground")
           end
         end
 
         def initially_open
           render_component(open: true) do |collapsible|
-            collapsible.with_trigger(class: "text-sm font-medium") { "Hide details" }
+            collapsible.with_trigger(variant: :ghost, size: :sm) { "Hide details" }
             tag.div("Server-rendered open.", class: "pt-2 text-sm text-muted-foreground")
           end
         end

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

@@ -4,19 +4,21 @@ module Poetry
   module Ui
     # The FieldSeparator family - the divider row between stacked fields.
     module FieldSeparator
-      # The FieldSeparator - the divider between stacked fields inside a
-      # FieldGroup: a Separator drawn across the
-      # row, with an optional inline caption riding on top ("Or continue
-      # with"). The caption is visual chrome on a decorative rule - the
-      # Separator inside stays aria-hidden either way.
+      # The FieldSeparator - the labelled rule: a Separator drawn across
+      # the row with an optional inline caption riding on top ("Or
+      # continue with"). Between stacked fields in a FieldGroup, under a
+      # sign-in form before the provider buttons, at a date break in a
+      # list - anywhere a rule needs a caption. The caption is visual
+      # chrome on a decorative rule - the Separator inside stays
+      # aria-hidden either way.
       #
       # @example A captioned divider between stacked fields
       #   render Poetry::Ui::FieldSeparator::Component.new { "Or continue with" }
       class Component < Poetry::Core::Component
         # Projected into the registry, llms.txt, and the agent surface.
         AGENT_RULES = [
-          "Divides stacked fields inside a poetry_field_group - not a general-purpose rule " \
-          "(that is poetry_separator).",
+          "The labelled rule, anywhere: between stacked fields in a poetry_field_group, under a sign-in " \
+          "form (\"Or continue with\"), at a date break; poetry_separator is the bare rule.",
           "Pass a block for the inline caption form (\"Or continue with\") - the caption sits " \
           "on the line, backed by the page background."
         ].freeze

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

@@ -33,7 +33,7 @@ module Poetry
         }.freeze
         # Field control_attributes land on the INPUT (the real control);
         # everything else the caller passes styles the container.
-        INPUT_FACING = %w[id aria-label aria-describedby aria-invalid aria-required].freeze
+        INPUT_FACING = %w[id aria-label aria-labelledby aria-describedby aria-invalid aria-required].freeze
 
         # Projected into the registry, llms.txt, and the agent surface.
         AGENT_RULES = [
@@ -147,6 +147,13 @@ module Poetry
           @input_id ||= poetry_instance_id("poetry-input-otp")
         end
 
+        # Whether the caller named the input already - an aria-label, an
+        # aria-labelledby, or an id a Field label points at.
+        # @api private
+        def named_by_caller?
+          html_attributes.slice("id", "aria-label", "aria-labelledby").values.any?(&:present?)
+        end
+
         # Whether the rendered value already fills every cell.
         # @api private
         def complete?
@@ -177,9 +184,10 @@ module Poetry
             "data-slot" => "input-otp", "class" => css(:input)
           }
           # The invisible input is the ONLY AT surface - it must always
-          # carry a name (the axe label rule); callers override via
-          # aria-label / Field labelling.
-          attrs["aria-label"] = t("poetry.input_otp.label")
+          # carry a name (the axe label rule): the caller's aria-label or
+          # aria-labelledby, a Field's label through the id (label for=),
+          # else the translated default.
+          attrs["aria-label"] = t("poetry.input_otp.label") unless named_by_caller?
           attrs["value"] = display_value if display_value.present?
           attrs["disabled"] = true if disabled
           attrs["aria-required"] = true if required

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

@@ -20,10 +20,11 @@ module Poetry
       # (a scripting: none media rule), so the region stays readable.
       #
       # The content element is the Turbo Stream append target (stable
-      # dom id "<id>-messages"); rows are poetry_message_scroller_item
-      # wrappers keyed by message id. History prepends keep the reading
-      # position; a row rendered with anchor: true becomes the held
-      # reading line.
+      # dom id "<id>-messages", or content_id:); rows are
+      # poetry_message_scroller_item wrappers keyed by message id (dom_id:
+      # gives a row its own DOM id for Streams). History prepends keep
+      # the reading position; a row rendered with anchor: true becomes the
+      # held reading line.
       #
       # @example A chat transcript
       #   render Poetry::Ui::MessageScroller::Component.new(id: "chat") do
@@ -36,8 +37,10 @@ module Poetry
         # Projected into the registry, llms.txt, and the agent surface.
         AGENT_RULES = [
           "Stream by UPDATING a row's text (morph/replace) - appending nodes per token re-announces the row to AT.",
-          "Rows are poetry_message_scroller_item(id: message.id) - the id is how anchoring and Streams find them.",
-          "Append new turns with a Turbo Stream targeting the content element's dom id.",
+          "Rows are poetry_message_scroller_item(id: message.id) - the id is how anchoring and Streams find " \
+          "them; dom_id: gives the row a DOM id (dom_id(message)) for replace/morph streams.",
+          "Append new turns with a Turbo Stream targeting the content element's dom id - content_id:, " \
+          "\"<id>-messages\" by default.",
           "History loads PREPEND into the content element - the controller preserves the reading position.",
           "Never nest a second scroll container inside the viewport."
         ].freeze
@@ -73,7 +76,10 @@ module Poetry
 
         option :id, :string, required: true,
                              doc: "The transcript's stable identifier - the content element renders dom id " \
-                                  "\"<id>-messages\" for Turbo Streams to target."
+                                  "\"<id>-messages\" for Turbo Streams to target (content_id: overrides it)."
+        option :content_id, :string, default: -> { "#{id}-messages" },
+                                     doc: "The content element's dom id - the Turbo Stream append target; " \
+                                          "defaults to \"<id>-messages\"."
         option :auto_scroll, :boolean, default: true,
                                        doc: "Follows the newest message while the reader sits at the bottom; " \
                                             "scrolling up releases the follow."
@@ -155,7 +161,7 @@ module Poetry
         # @api private
         def content_attributes
           {
-            "id" => "#{id}-messages", "class" => css(:content),
+            "id" => content_id, "class" => css(:content),
             "data-slot" => "message-scroller-content",
             "role" => "log", "aria-relevant" => "additions"
           }.merge(stimulus_attributes_for(:content))

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

@@ -23,7 +23,8 @@ module Poetry
         # Projected into the registry, llms.txt, and the agent surface.
         AGENT_RULES = [
           "This is a REAL <select> - use it for plain picking; the JS Select is for styled options.",
-          "Pair it with a Label (for_id: its id) or a Field - a bare select has no accessible name.",
+          "Pair it with a Label (for_id: its id) or a Field - a bare select has no accessible name; id: and " \
+          "every aria-* attribute land on the <select> itself (a Field's control_attributes splat straight in).",
           "The fast path is options: [[label, value], ...] + selected:; a content block overrides it."
         ].freeze
 
@@ -36,8 +37,8 @@ module Poetry
         option :disabled, :boolean, default: false, doc: "Disables the native select; the wrapper dims the whole pair."
         option :invalid, :boolean, default: false, doc: "Marks the select invalid (aria-invalid on the element itself)."
         option :described_by, :string,
-               doc: "Space-separated hint/error ids wired to the SELECT itself - a raw aria-describedby in " \
-                    "html_attributes would land on the wrapper div, unassociated for assistive technology."
+               doc: "Space-separated hint/error ids wired to the SELECT itself - the older spelling of a raw " \
+                    "aria-describedby, which lands on the select too (every aria-* attribute does)."
 
         validates :size, inclusion: { in: SIZES }
 
@@ -77,10 +78,12 @@ module Poetry
           )
         end
 
-        # The select's attributes: name, id, label, described-by, disabled and invalid state.
+        # The select's attributes: name, id, label, described-by, disabled
+        # and invalid state, over the caller's aria-* (pulled off the root
+        # in #initialize).
         # @api private
         def select_attributes
-          attrs = { "data-slot" => "native-select", "data-size" => size, "class" => css(:select) }
+          attrs = { "data-slot" => "native-select", "data-size" => size, "class" => css(:select) }.merge(@select_aria)
           attrs["name"] = name if name.present?
           attrs["id"] = id if id.present?
           attrs["aria-label"] = label if label.present?
@@ -92,11 +95,17 @@ module Poetry
 
         private
 
-        # options: pairs are structural data, not a typed option.
+        # options: pairs are structural data, not a typed option. The
+        # aria-* attributes (flat, or nested aria: {}) come off the root for
+        # the select - the Select trigger pattern, so a Field's
+        # control_attributes name the real control.
         def initialize(options: nil, selected: nil, **)
           super(**)
           @options = options
           @selected = selected
+          @select_aria = @html_attributes.keys.grep(/\Aaria-/).to_h { |key| [key, @html_attributes.delete(key)] }
+          nested = @html_attributes.delete("aria")
+          nested.each { |key, value| @select_aria["aria-#{key}"] = value } if nested.is_a?(Hash)
         end
 
         # The select element with its content.

data/app/components/poetry/ui/navigation_menu/bar_preview.html.erb

@@ -9,6 +9,6 @@
       </div>
     <% end %>
     <% nav.with_link("Pricing", href: "#") %>
-    <% nav.with_link("Docs", href: "#") %>
+    <% nav.with_link("Docs", href: "#", active: true) %>
   <% end %>
 </div>

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

@@ -10,7 +10,7 @@
           <% end %>
           <%= content_tag(:div, capture(&entry.panel), panel_attributes(entry)) %>
         <% else %>
-          <a href="<%= entry.href %>" data-slot="navigation-menu-link" class="<%= css(:trigger) %>"><%= entry.title %></a>
+          <a href="<%= entry.href %>" data-slot="navigation-menu-link" class="<%= css(:trigger) %> data-active:bg-muted/50 data-active:hover:bg-muted data-active:focus:bg-muted" <%= tag.attributes(active_attributes(entry)) %>><%= entry.title %></a>
         <% end %>
       <% end %>
     <% end %>