poetry-ui 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf138359fce6d2db2f40a9e357c588b079dfae6a7ee9a15210c0caf30b9a306b
-  data.tar.gz: 9d0fad8f5c02bc302ecfef5ec213986300e64a9b66290e4e1e1c8868f46e3505
+  metadata.gz: 311078c0215e2e504b32301efa8e51f0e7e108d8788587337689f356e72423e0
+  data.tar.gz: 1d58b4704974eeb18b59a1f7a32f8d51fcb0598f846ba1d5864507b482d875eb
 SHA512:
-  metadata.gz: d6c8a18d198775d026f6c86e4a0fde403eae9ef65148471efb88b9c834583a8650f60511dcee1df8fa58560ee18b4161b4e4020f7cac86d194c545b2623cc0a2
-  data.tar.gz: 9934f30c07106f4500160b125ea3d48b6f8d62482d40164e064214ea4f42c697daedba4efde17625d520c9d2bcec059222972cd395343fa69a4a33793076bbfc
+  metadata.gz: 1f8a5636a3b349a718912cc30df3675b45858c9fcb0f15c50772e578f6c7c35fefa5729717207ecc0daa05dbf5aac44688896369001ac19b93e6430e5e2fab12
+  data.tar.gz: 6d587c9fa1a023a7ced7a1bf176c6b775198e0acb684781ae868321175ad91199f644e3f12081cf9624dc8dc19a1cd3489daf06f2933b5fdcb24b57b40714288

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.1.9] - 2026-09-30
+
+### Changed
+
+- `bin/rails poetry:check` compiles the templates that sit beside components, which `bin/rails herb:check` never reaches: the app's own under `app/components/`, and the ones the gems in the boot ship. A template Herb refuses is a `herb-compile` finding, an error when the app renders through Herb (Rails' 8.2 defaults, or ReActionView) and a warning until then. A finding on a template a gem ships names what fixes it: the gem, or the herb the bundle resolves. A herb older than 0.11.0 leaves the compile out and says so on stderr, and the rest of the check runs as before.
+- `rails g poetry:install` adds no `herb` line when Action View depends on the gem, as it does from Rails 8.2, and says where the parser comes from. On an earlier Rails it adds the line as before, and a `herb` the Gemfile declares is left alone on either.
+- `rails g poetry:editor` writes a `.herb.yml` pinned to Herb 0.11.0. The two rules it used to switch off for slot setters (`erb-no-unused-expressions`, `actionview-no-silent-helper`) are fixed in 0.11 and stay on. One rule starts off instead: `html-no-nested-forms` reports a form inside a block helper, a `form_with` inside `poetry_card do`, as a form nested in another form. An existing `.herb.yml` is kept as it is; move its `version` to 0.11.0 and drop the two entries to get the same.
+- Every component template builds its elements through `element_tag` and hands `tag.attributes` its hash as an argument, never as a splat. A component now renders the same in a host that compiles its templates with Herb's slots (ReActionView's `config.slots`) as in one that does not; before, such a host rendered most components without their root attributes and could not compile Button, Marker or Item at all. What a component renders without slots is unchanged, byte for byte: the suite, the behaviour tier and the 455 visual baselines hold.
+
+### Fixed
+
+- NumberField with `format:` renders on Rails 8.2, and through the renderer on any Rails. Rails reads `format` off what it renders and takes the answer for the format of the template. The option's reader answered with its Hash, so the render raised `Invalid formats`. A render from a controller asked already; from Rails 8.2 a render in a view asks too, which is every `poetry_number_field(format: ...)`. The option keeps its name and the component leaves Rails with its default.
+
+## [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

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

@@ -1,3 +1,3 @@
-<%= content_tag(:div, **root_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
   <% items.each do |item| %><%= item %><% end %>
 <% end %>

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

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
   <%= icon %>
   <% if title? %><div data-slot="alert-title" class="<%= css(:title) %>"><%= title %></div><% end %>
   <div data-slot="alert-description" class="<%= css(:description) %>"><%= content %></div>

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

@@ -1,6 +1,6 @@
-<%= content_tag(:div, **root_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
   <%= trigger %>
-  <%= content_tag(:dialog, **dialog_attributes) do %>
+  <%= element_tag(:dialog, **dialog_attributes) do %>
     <div data-slot="alert-dialog-header" class="<%= header_classes %>">
       <% if media? %>
         <div data-slot="alert-dialog-media" class="<%= media_classes %>"><%= media %></div>

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/attachment/component.html.erb

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
   <%= trigger %>
   <%= media %>
   <% if title? || description? %>

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

@@ -1,11 +1,11 @@
-<%= content_tag(:div, **root_attributes) do %>
-  <%= tag.input(**input_attributes, class: Poetry::Ui::Input::Style.css) %>
-  <%= tag.div(**content_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
+  <%= element_tag(:input, **input_attributes, class: Poetry::Ui::Input::Style.css) %>
+  <%= element_tag(:div, **content_attributes) do %>
     <div data-slot="autocomplete-list" role="listbox" id="<%= list_id %>"
          class="<%= Poetry::Ui::Command::Style.css(:list) %>"
          <%= tag.attributes(stimulus_attributes_for(:list)) %>>
       <% item_models.each_with_index do |item, index| %>
-        <%= tag.div(**item_attributes(item, index)) do %>
+        <%= element_tag(:div, **item_attributes(item, index)) do %>
           <span><%= item.label %></span>
         <% end %>
       <% end %>

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/breadcrumb/component.html.erb

@@ -1,4 +1,4 @@
-<%= content_tag(:nav, **root_attributes) do %>
+<%= element_tag(:nav, **root_attributes) do %>
   <ol data-slot="breadcrumb-list" class="<%= css(:list) %>">
     <% entries.each_with_index do |entry, index| %>
       <li data-slot="breadcrumb-item" class="<%= css(:item) %>">

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

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes) do %>
-  <%= content_tag(content_tag_name, content, **content_attributes) %>
+<%= element_tag(:div, **root_attributes) do %>
+  <%= element_tag(content_tag_name, content, **content_attributes) %>
   <%= reactions %>
 <% end %>

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

@@ -1,4 +1,4 @@
-<%= content_tag(root_tag, **root_attributes) do %>
+<%= element_tag(root_tag, **root_attributes) do %>
   <% if loading %>
     <span data-slot="spinner" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="animate-spin"><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg></span>
   <% end %>

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/calendar/component.html.erb

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
   <div data-slot="calendar-nav" class="<%= css(:nav) %>">
     <%= render Poetry::Ui::Button::Component.new(**previous_options) do |button| %>
       <% button.with_leading { render Poetry::Ui::Icon::Component.new(name: :"chevron-left") } %>
@@ -13,7 +13,7 @@
         <% { "month" => [month_options, @month.month, t("poetry.calendar.month"), month_names_list[@month.month - 1]],
              "year" => [year_options, @month.year, t("poetry.calendar.year"), @month.year.to_s] }.each do |unit, (options, current, label, text)| %>
           <span data-slot="calendar-dropdown" data-calendar-unit="<%= unit %>" class="<%= css(:dropdown_root) %>"
-                <%= tag.attributes(**stimulus_attributes_for(:dropdown)) %>>
+                <%= tag.attributes(stimulus_attributes_for(:dropdown)) %>>
             <span data-slot="calendar-caption-label" aria-hidden="true" class="<%= css(:dropdown_label) %>">
               <span data-slot="calendar-dropdown-value"><%= text %></span>
               <%= render Poetry::Ui::Icon::Component.new(name: :"chevron-down") %>
@@ -27,14 +27,14 @@
         <% end %>
       </div>
     <% else %>
-      <div data-slot="calendar-caption" class="<%= css(:caption) %>" <%= tag.attributes(**stimulus_attributes_for(:caption)) %>><%= caption %></div>
+      <div data-slot="calendar-caption" class="<%= css(:caption) %>" <%= tag.attributes(stimulus_attributes_for(:caption)) %>><%= caption %></div>
     <% end %>
     <%= render Poetry::Ui::Button::Component.new(**next_options) do |button| %>
       <% button.with_leading { render Poetry::Ui::Icon::Component.new(name: :"chevron-right") } %>
     <% end %>
   </div>
   <div role="grid" data-slot="calendar-grid" class="<%= css(:grid) %>"
-       <%= tag.attributes(**stimulus_attributes_for(:grid)) %>>
+       <%= tag.attributes(stimulus_attributes_for(:grid)) %>>
     <div role="row" data-slot="calendar-weekdays" class="<%= css(:weekdays) %>">
       <% if week_numbers %>
         <div role="columnheader" data-slot="calendar-week-number" class="<%= css(:weekday) %>"><span class="sr-only">Week</span></div>
@@ -49,8 +49,8 @@
           <div role="rowheader" data-slot="calendar-week-number" class="<%= css(:weekday) %>"><%= iso_week(week) %></div>
         <% end %>
         <% week.each do |date| %>
-          <%= content_tag(:div, cell_attributes(date)) do %>
-            <%= content_tag(:button, day_attributes(date)) do %>
+          <%= element_tag(:div, cell_attributes(date)) do %>
+            <%= element_tag(:button, day_attributes(date)) do %>
               <span data-slot="calendar-day-label"><%= date.day %></span>
             <% end %>
           <% end %>
@@ -61,12 +61,12 @@
   <% if name.present? %>
     <% if range? %>
       <input type="hidden" name="<%= name %>[start]" value="<%= range_start&.iso8601 %>"
-             <%= tag.attributes(**stimulus_attributes_for(:start_input)) %>>
+             <%= tag.attributes(stimulus_attributes_for(:start_input)) %>>
       <input type="hidden" name="<%= name %>[end]" value="<%= range_end&.iso8601 %>"
-             <%= tag.attributes(**stimulus_attributes_for(:end_input)) %>>
+             <%= tag.attributes(stimulus_attributes_for(:end_input)) %>>
     <% else %>
       <input type="hidden" name="<%= name %>" value="<%= selected&.iso8601 %>"
-             <%= tag.attributes(**stimulus_attributes_for(:hidden_input)) %>>
+             <%= tag.attributes(stimulus_attributes_for(:hidden_input)) %>>
     <% end %>
   <% end %>
 <% end %>

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

@@ -1,11 +1,11 @@
-<%= content_tag(:div, **root_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
   <% if header? %>
     <div data-slot="card-header" class="<%= css(:header, class: header_class) %>">
-      <% if title? %><%= content_tag(title_tag, title, "data-slot" => "card-title", class: css(:title)) %><% end %>
+      <% if title? %><%= element_tag(title_tag, title, "data-slot" => "card-title", class: css(:title)) %><% end %>
       <% if description? %><div data-slot="card-description" class="<%= css(:description) %>"><%= description %></div><% end %>
       <% 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 footer? %><%= content_tag(:div, footer_attributes) do %><%= capture(&footer_block) if footer_block %><% end %><% end %>
+  <% if content.present? %><div data-slot="card-content" class="<%= css(:content, class: content_class) %>"><%= content %></div><% end %>
+  <% if footer? %><%= element_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/carousel/component.html.erb

@@ -1,8 +1,8 @@
-<%= content_tag(:div, **root_attributes) do %>
-  <%= content_tag(:div, viewport_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
+  <%= element_tag(:div, viewport_attributes) do %>
     <div class="<%= css(:track, class: [css(vertical? ? :track_vertical : :track_horizontal), track_classes].compact) %>">
       <% slides.each do |slide| %>
-        <%= content_tag(:div, capture(&slide.block), item_attributes(slide)) %>
+        <%= element_tag(:div, capture(&slide.block), item_attributes(slide)) %>
       <% end %>
     </div>
   <% end %>

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

@@ -1,7 +1,7 @@
 <%# Fragment - button + input(s) as SIBLINGS, no wrapper: the source's
     `peer` class contract (labels style via peer-*) breaks if poetry wraps.
     The controller lives on the button; the input resolves by stable id. %>
-<%= content_tag(:button, **root_attributes) do %>
+<%= element_tag(:button, **root_attributes) do %>
   <span data-slot="checkbox-indicator" <% if indeterminate? %>data-indeterminate=""<% elsif checked? %>data-checked=""<% else %>data-unchecked=""<% end %> aria-hidden="true" class="<%= css(:indicator) %>">
     <%# MinusIcon on indeterminate is a POETRY ADDITION (shadcn renders a
         check for mixed state - a real gap). %>
@@ -12,11 +12,11 @@
   <%# Rails parity hidden FIRST (last-wins ordering, Tags::CheckBox-exact)
       so unchecked SUBMITS unchecked_value; disabled fields submit nothing. %>
   <% if unchecked_value %>
-    <%= tag.input(type: "hidden", name: name, value: unchecked_value, disabled: disabled) %>
+    <%= element_tag(:input, type: "hidden", name: name, value: unchecked_value, disabled: disabled) %>
   <% end %>
   <%# THE form participant + the store: input.indeterminate is a JS-only
       property - the controller derives it from the checked attributes on connect. %>
-  <%= tag.input(type: "checkbox", id: input_id, name: name, value: value, checked: checked?,
-                disabled: disabled, "data-slot": "checkbox-input", "aria-hidden": true,
-                tabindex: "-1", class: css(:input)) %>
+  <%= element_tag(:input, type: "checkbox", id: input_id, name: name, value: value, checked: checked?,
+                  disabled: disabled, "data-slot": "checkbox-input", "aria-hidden": true,
+                  tabindex: "-1", class: css(:input)) %>
 <% end %>

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

@@ -1,9 +1,9 @@
 <%# InputGroup anatomy: the readonly mono control, trailing copy
     affordance with stacked copy/check glyphs swapping on data-copied. %>
-<%= content_tag(:div, **root_attributes) do %>
-  <%= content_tag(:div, **group_attributes) do %>
-    <%= tag.input(**input_attributes) %>
-    <%= content_tag(:div, **addon_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
+  <%= element_tag(:div, **group_attributes) do %>
+    <%= element_tag(:input, **input_attributes) %>
+    <%= element_tag(:div, **addon_attributes) do %>
       <%= render copy_button do %>
         <span class="<%= css(:icon_stack) %>">
           <%= render Poetry::Ui::Icon::Component.new(name: :copy, class: css(:icon_copy)) %>

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

@@ -1,7 +1,7 @@
 <%# The pre/code nesting stays on one line - literal template whitespace
     inside <pre> would render. %>
-<%= content_tag(:div, **root_attributes) do %>
-  <%= content_tag(:pre, content_tag(:code, highlighted || code, **code_attributes), **pre_attributes) %>
+<%= element_tag(:div, **root_attributes) do %>
+  <%= element_tag(:pre, element_tag(:code, highlighted || code, **code_attributes), **pre_attributes) %>
   <% if copy %>
     <%= render copy_button do %>
       <span class="<%= css(:icon_stack) %>">

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

@@ -1,4 +1,4 @@
-<%= content_tag(:div, **root_attributes) do %>
+<%= element_tag(:div, **root_attributes) do %>
   <%= trigger %>
-  <%= content_tag(:div, content, **content_attributes) %>
+  <%= element_tag(:div, content, **content_attributes) %>
 <% end %>

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