poetry-ui 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1346a1ff6a62e643e9440c7c42e835d643b55ea2dbcf8bc7938d800964995306
-  data.tar.gz: a569d21afd89f4f611309bab9c05492bc47d1ff4e9997d1178bcfd8859c840de
+  metadata.gz: be9d330390d3bf48c36cd783dfaf4fdd00a0cf6073b9b8944caf10104abf66b7
+  data.tar.gz: 99aa8e106788b9a8d597b149e68c8d6353c7a49876a32969f106327a7d1be813
 SHA512:
-  metadata.gz: '01872acf5407b8d3b14bb91c10f33f19b9fca4124f39338d8f88560c86bb6d41913ff50b92ef3dfa3293f4d14500fd3faa67395109a6d6f41a16412ab80c26ed'
-  data.tar.gz: 4180cbf5784bc923d57da1394c91542959570209ae1f8beb89e68d31e1c80f7ec5c0809fc65f363f6c6b3b025e72851f0ec08614b2020e94bee5df44ca6ccea0
+  metadata.gz: 6f60d8c522645d60374997d18bcea9ff4baaeb2f5fd888374966d008ef362f216b7cb0fa2f022f4f6b2127c10aa6750de2e37546c9aec380b37e79a909cee29a
+  data.tar.gz: 1b8bf7807b8f0836d702577677038fd1d42a5b2a8283579eee0471bd20026de193487d42ebe5861615fa9b2b1969087e1201a7fb5791b6715c4d6cdec63824d9

data/CHANGELOG.md

@@ -1,6 +1,28 @@
 # Changelog
 
-## [Unreleased]
+## [0.1.1] - 2026-09-08
+
+### Added
+
+- `content_class:` on `poetry_dropdown_menu` and `poetry_context_menu`, on Menubar's `with_menu`, and on every menu family's `with_sub`: the panel's class merge seam, the one Popover, HoverCard and Dialog already had. A dropdown panel opens at its trigger's width (minimum 8rem), so `content_class: "w-56"` is how a menu with icons, shortcuts or long labels gets its width.
+- NavigationMenu `with_item(title, value:, disabled: true)`: an inert trigger (`disabled` + `data-disabled`) that hover, click and the arrows skip. `disabled:` on a link raises.
+- `Poetry::Ui::Chat::Error`, a `Poetry::Core::Error`: `AssistantTurn#continuation_frames` raises it on a turn without an approval pause, where a missing constant raised NameError before.
+- `poetry:install --skip-bundle`.
+
+### Changed
+
+- `poetry:install` adds the `herb` gem to the development group (once, never when the Gemfile already declares it) and runs `bundle install`, so `bin/rails poetry:check` works on a fresh app with no manual step. `poetry:check`'s missing-parser message points at the installer.
+- The upstream pin is shadcn@4.21.0. The theme CSS is unchanged between the releases; both fidelity ledgers are re-snapshotted at the new pin.
+- MessageScroller renders `data-pending-scroll` on its root and viewport for `:end` and `:"last-anchor"`; the viewport hides while it is set (visibility, so the layout stays) and the hold lifts without JavaScript. The part contracts declare the state.
+- Select, Combobox and Command group headings are `aria-hidden`: the group's name flows through `aria-labelledby`, so screen readers stop announcing the heading a second time. Menu groups wire `aria-labelledby` to a label rendered inside them and hide it the same way; a label outside any group stays plain text.
+- HoverCard's trigger wiring is `pointerdown->pointerDown` (was `touchstart->touchGuard`), and NumberField's input no longer wires a `focus` action. A copy made with `poetry:add hover_card` or `poetry:add number_field` before this version carries the old wiring and logs a Stimulus "undefined method" error on those events: run `bin/rails g poetry:diff` and update the two lines. Apps on the gem-owned tier need nothing.
+- ToastTrigger names its Button root through `identity:`.
+- NavigationMenu's agent rules state the keyboard contract: ArrowLeft/ArrowRight between triggers and links, ArrowDown opens the focused trigger's panel, Escape closes.
+
+### Fixed
+
+- HoverCard: a tap on the trigger clicks through on touch devices (the collapsed sidebar's icons did nothing on a tablet).
+- NumberField: Tab's select-all and a click's caret placement stay native.
 
 ## [0.1.0] - 2026-09-05
 

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

@@ -236,9 +236,12 @@ module Poetry
           "#{group_id}-heading"
         end
 
+        # The group's name flows through aria-labelledby; aria-hidden keeps
+        # the text from being read a second time as a stray child of the
+        # listbox.
         def heading_part
           content_tag(:div, @heading_text, "data-slot" => "combobox-label", "id" => heading_id,
-                                           "class" => Style.css(:label))
+                                           "aria-hidden" => "true", "class" => Style.css(:label))
         end
       end
 

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

@@ -207,10 +207,11 @@ module Poetry
         end
 
         # A styled heading, no ARIA role - the group points at it via
-        # aria-labelledby.
+        # aria-labelledby, and aria-hidden keeps the text from being read a
+        # second time as a stray child of the listbox.
         def heading_part
           content_tag(:div, @heading_text, "data-slot" => "command-group-heading", "id" => heading_id,
-                                           "class" => Style.css(:heading))
+                                           "aria-hidden" => "true", "class" => Style.css(:heading))
         end
       end
 

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

@@ -135,6 +135,9 @@ module Poetry
         option :loop, :boolean, default: false, doc: "Wraps arrow-key movement past either end of the menu."
         option :long_press_delay, :integer, default: 700, doc: "Touch long-press duration in ms before the menu opens."
         option :disabled, :boolean, default: false, doc: "Inerts the surface - no gesture opens the menu."
+        option :content_class, :string,
+               doc: "Class merge seam for the menu panel (e.g. content_class: \"w-48\"). Root-level " \
+                    "class: styles the surface wrapper, not the panel."
         option :label, :string, doc: "The menu's accessible name (localized fallback when omitted)."
         option :focusable_surface, :boolean, default: false,
                                              doc: "Puts the surface in the tab order and advertises Shift+F10."
@@ -278,7 +281,7 @@ module Poetry
             "data-slot" => "context-menu-content", (open ? "data-open" : "data-closed") => "",
             # The initial placement (side: option; re-resolved live by popper).
             "data-side" => side.to_s, "data-align" => "start",
-            "class" => css(:content)
+            "class" => css(:content, class: content_class)
           }.merge(stimulus_attributes_for(:content))
           attrs["hidden"] = true unless open
           attrs

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

@@ -142,6 +142,9 @@ module Poetry
         tool :open, description: "Open the drawer.", executes: :open, mutating: true
         tool :close, description: "Close the drawer.", executes: :close, mutating: true
 
+        # The inherited render checks, then the snap-point rules when
+        # snap_points: is given.
+        # @api private
         def before_render
           super
           validate_snap_points! if snap_points.present?

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

@@ -143,6 +143,10 @@ module Poetry
         option :loop, :boolean, default: false, doc: "Arrow-key navigation wraps from the last item back to the first."
         option :dir, :symbol, doc: "Reading direction; :rtl flips submenu sides and indicators."
         option :disabled, :boolean, default: false, doc: "Disables the menu trigger button."
+        option :content_class, :string,
+               doc: "Class merge seam for the menu panel - the panel opens at the trigger's width " \
+                    "(min 8rem), so content_class: \"w-56\" widens it. Root-level class: styles the " \
+                    "wrapper, not the panel."
 
         validates :side, inclusion: { in: SIDES }
         validates :align, inclusion: { in: ALIGNS }
@@ -272,7 +276,7 @@ module Poetry
             "data-slot" => "dropdown-menu-content", (open ? "data-open" : "data-closed") => "",
             # Initial placement, re-resolved live by popper on open.
             "data-side" => side, "data-align" => align,
-            "class" => css(:content)
+            "class" => css(:content, class: content_class)
           }.merge(stimulus_attributes_for(:content))
           attrs["hidden"] = true unless open
           attrs

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

@@ -95,14 +95,15 @@ module Poetry
           end
           # The trigger handlers: pointerenter/leave pair
           # timers (touch excluded), focus opens immediately / blur closes,
-          # and the touchstart guard (a tap navigates, never focus-opens).
+          # and the pointerdown latch (a tap or click never focus-opens; the
+          # tap keeps its click, so it navigates).
           on :trigger do
             controller :hover_card do
               action :pointer_enter, on: :pointerenter
               action :pointer_leave, on: :pointerleave
               action :focus_open, on: :focus
               action :blur_close, on: :blur
-              action :touch_guard, on: :touchstart
+              action :pointer_down, on: :pointerdown
             end
             controller(:popper) { target :anchor }
           end

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

@@ -73,7 +73,7 @@ module Poetry
         renders_many :menus,
                      doc: "The top-level menus. Each takes with_trigger (the menu button) plus the family item " \
                           "slots (with_item, with_checkbox_item, with_radio_group, with_sub, with_separator, ...); " \
-                          "value: defaults to the menu's position.",
+                          "value: defaults to the menu's position; content_class: is the panel's class merge seam.",
                      renders: ->(**options) { Menu.new(bar: self, dir: dir, **options) }
 
         use_stimulus do
@@ -341,11 +341,12 @@ module Poetry
                       content_tag(:button, Poetry::Core::HTML::Attributes.merged(attrs, options)) { capture(&block) }
                     }
 
-        def initialize(bar:, value: nil, disabled: false, dir: nil, **extra_attributes)
+        def initialize(bar:, value: nil, disabled: false, dir: nil, content_class: nil, **extra_attributes)
           super(extra_attributes)
           @bar = bar
           @disabled = disabled
           @dir = dir
+          @content_class = content_class
           position = @bar.register_menu(self)
           @value = (value || "menu-#{position}").to_s
         end
@@ -419,7 +420,7 @@ module Poetry
             "data-slot" => "menubar-content", (open? ? "data-open" : "data-closed") => "",
             # Initial placement, re-resolved live by popper on open.
             "data-side" => "bottom", "data-align" => "start",
-            "class" => Style.css(:content)
+            "class" => Style.css(:content, class: @content_class)
           }.merge(stimulus_attributes(:popper) { |popper| popper.with_target(:content) })
           attrs["hidden"] = true unless open?
           content_tag(:div, attrs) { safe_join(items.map(&:to_s)) }

data/app/components/poetry/ui/menus.rb

@@ -226,11 +226,28 @@ module Poetry
 
         def call
           attrs = { "data-slot" => "#{family_slot_prefix}-group", "role" => "group" }
+          attrs["aria-labelledby"] = label_id if @labelled
           content_tag(:div, Poetry::Core::HTML::Attributes.merged(attrs, html_attributes)) { safe_join(items.map(&:to_s)) }
         end
 
         private
 
+        # A label inside a group names the group (aria-labelledby) and is
+        # aria-hidden, so its text is not read a second time as a stray child
+        # of the menu; a label outside any group stays plain text.
+        def label_part(**, &)
+          @labelled = true
+          super("id" => label_id, "aria-hidden" => "true", **, &)
+        end
+
+        def group_id
+          @group_id ||= poetry_instance_id("poetry-#{family_slot_prefix}-group")
+        end
+
+        def label_id
+          "#{group_id}-label"
+        end
+
         def menu_dir
           @dir
         end
@@ -311,9 +328,11 @@ module Poetry
                       end
                     }
 
-        def initialize(dir: nil, **extra_attributes)
+        # content_class: is the sub-panel's class merge seam (with_sub(content_class: "w-40")).
+        def initialize(dir: nil, content_class: nil, **extra_attributes)
           super(extra_attributes)
           @dir = dir
+          @content_class = content_class
         end
 
         def before_render
@@ -363,7 +382,7 @@ module Poetry
             "id" => content_id, "role" => "menu", "aria-orientation" => "vertical",
             "aria-labelledby" => trigger_id, "tabindex" => "-1",
             "data-slot" => "#{family_slot_prefix}-sub-content", "data-closed" => "", "hidden" => true,
-            "class" => family_style.css(:sub_content)
+            "class" => family_style.css(:sub_content, class: @content_class)
           }.merge(stimulus_attributes(:popper) { |popper| popper.with_target(:content) })
           content_tag(:div, attrs) { safe_join(items.map(&:to_s)) }
         end

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

@@ -9,6 +9,16 @@ module Poetry
       # a jump-to-latest button. Without JavaScript it is a plain
       # scrollable region, fully readable.
       #
+      # Opening position: a scroll container always opens at the top, so a
+      # transcript opening at the newest message would paint the oldest
+      # rows first and jump once the controller runs. For :end and
+      # :"last-anchor" the root and the viewport render
+      # data-pending-scroll; the viewport's dictionary hides it while the
+      # attribute is present (visibility, so layout exists for the scroll)
+      # and the controller clears it once the position lands, or at once
+      # for an empty transcript. Without JavaScript the hold is lifted
+      # (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
@@ -92,14 +102,20 @@ module Poetry
                "data-scrollable" => "overflow exists - carries which edges have room " \
                                     "(start, end, or both as a space-separated pair)",
                "data-autoscrolling" => "a programmatic scroll is settling - the " \
-                                       "follow-bottom release is suppressed while set"
+                                       "follow-bottom release is suppressed while set",
+               "data-pending-scroll" => "the opening-position hold - rendered for " \
+                                        "default_scroll_position :end / :\"last-anchor\", " \
+                                        "cleared once the position lands (at once for an " \
+                                        "empty transcript)"
              }
         part "message-scroller-viewport", "The native scroll region (role=region, " \
                                           "focusable) - the controller mirrors the same " \
                                           "runtime attributes here",
              states: {
                "data-scrollable" => "overflow exists - the same edge tokens as the root",
-               "data-autoscrolling" => "a programmatic scroll is settling"
+               "data-autoscrolling" => "a programmatic scroll is settling",
+               "data-pending-scroll" => "the opening-position hold (the root's) - the " \
+                                        "dictionary hides the viewport while it is set"
              }
         part "message-scroller-content", "The row container and Turbo Stream append target " \
                                          "(stable dom id <id>-messages); role=log announces " \
@@ -120,6 +136,7 @@ module Poetry
             { "data-slot" => "message-scroller" }
               .merge(stimulus_attributes_for(:root))
               .merge(component_data_attributes)
+              .merge(pending_scroll_attributes)
           )
         end
 
@@ -129,7 +146,13 @@ module Poetry
             "class" => css(:viewport), "data-slot" => "message-scroller-viewport",
             "role" => "region", "tabindex" => "0",
             "aria-label" => t("poetry.message_scroller.region")
-          }.merge(stimulus_attributes_for(:viewport))
+          }.merge(stimulus_attributes_for(:viewport)).merge(pending_scroll_attributes)
+        end
+
+        # The opening-position hold (the class doc) - the server renders it so
+        # the first paint never shows the top of the thread.
+        def pending_scroll_attributes
+          %i[end last-anchor].include?(default_scroll_position) ? { "data-pending-scroll" => "" } : {}
         end
 
         # @api private
@@ -156,7 +179,8 @@ module Poetry
           }.merge(stimulus_attributes_for(:jump_button))
         end
 
-        private :root_attributes, :viewport_attributes, :content_attributes, :spacer_attributes, :button_attributes
+        private :root_attributes, :viewport_attributes, :content_attributes, :spacer_attributes, :button_attributes,
+                :pending_scroll_attributes
       end
     end
   end

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

@@ -16,8 +16,14 @@ module Poetry
         # (rightly) rejects classes no build can produce.
         base "relative flex size-full min-h-0 flex-col overflow-hidden group/message-scroller"
 
+        # data-pending-scroll:invisible = the opening-position hold: the
+        # viewport hides (layout intact) until the controller lands the
+        # opening position. The noscript pair lifts it when scripts are off -
+        # the plain scrollable region stays readable, this component's no-JS
+        # contract.
         element :viewport, "size-full min-h-0 min-w-0 scroll-fade-b scrollbar-thin scrollbar-gutter-stable " \
-                           "overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-none"
+                           "overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-none " \
+                           "data-pending-scroll:invisible noscript:data-pending-scroll:visible"
 
         element :content, "cn-message-scroller-content flex h-max min-h-full flex-col"
 

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

@@ -30,27 +30,36 @@ module Poetry
           "Panel content is poetry_navigation_menu_link entries (active: marks the current page) - " \
           "never buttons; navigation navigates.",
           "This is a DISCLOSURE bar: Tab moves through it normally and nothing traps - do not " \
-          "wire menu/menuitem roles.",
+          "wire menu/menuitem roles. Keys: ArrowLeft/ArrowRight step between triggers and links, " \
+          "ArrowDown opens the focused trigger's panel (focus stays on the trigger; Tab enters it), " \
+          "Escape closes and returns focus to the trigger.",
           "Rich panels (title + description grids) want viewport: true - the shared morphing " \
           "card contains and sizes them; the default per-item mode suits simple link lists " \
           "(the top-nav block shows the viewport pattern)."
         ].freeze
 
-        # One declared bar entry - a link (href:) or a trigger + panel pair.
+        # One declared bar entry - a link (href:) or a trigger + panel pair
+        # (disabled: renders the trigger inert).
         # @api private
-        Entry = Data.define(:title, :value, :href, :panel)
+        Entry = Data.define(:title, :value, :href, :panel, :disabled)
 
         renders_many :items,
-                     doc: "The bar entries. with_item(title, value:) { panel } declares a trigger + panel; " \
-                          "with_item(title, href:) a top-level link (with_link is the shorthand).",
-                     renders: lambda { |title, value: nil, href: nil, &panel|
+                     doc: "The bar entries. with_item(title, value:) { panel } declares a trigger + panel " \
+                          "(disabled: true renders the trigger inert - native disabled plus data-disabled; hover " \
+                          "and click never open its panel); with_item(title, href:) a top-level link (with_link " \
+                          "is the shorthand).",
+                     renders: lambda { |title, value: nil, href: nil, disabled: false, &panel|
                        if href.nil? && panel.nil?
                          raise ArgumentError,
                                "NavigationMenu item #{title.inspect} needs href: (a link) or a panel block"
                        end
+                       if href && disabled
+                         raise ArgumentError,
+                               "NavigationMenu item #{title.inspect}: disabled: applies to a trigger, not a link"
+                       end
 
                        entries << Entry.new(title: title, value: value&.to_s || title.to_s.parameterize, href: href,
-                                            panel: panel)
+                                            panel: panel, disabled: disabled)
                        nil
                      }
 
@@ -116,7 +125,9 @@ module Poetry
                "data-popup-open" => "its panel is open (written with aria-expanded - the chevron " \
                                     "rotation hook)",
                "data-open" => "its panel is open (the controller writes both vocabularies)",
-               "data-closed" => "its panel is closed (written after the first close)"
+               "data-closed" => "its panel is closed (written after the first close)",
+               "data-disabled" => "disabled: true - inert (native disabled rides along; hover and " \
+                                  "click never open the panel, the arrows step over it)"
              }
         part "navigation-menu-content", "One item's panel - presence-animated; in viewport mode it is " \
                                         "adopted into the shared viewport on first activation",
@@ -203,11 +214,16 @@ module Poetry
 
         # @api private
         def trigger_attributes(entry)
-          {
+          attrs = {
             "type" => "button", "data-slot" => "navigation-menu-trigger",
             "aria-expanded" => "false", "aria-controls" => panel_id(entry),
             "class" => "#{css(:trigger)} group"
-          }.merge(stimulus_attributes_for(:trigger))
+          }
+          if entry.disabled
+            attrs["disabled"] = true # inert: no focus, no click
+            attrs["data-disabled"] = "" # the contract's styling hook
+          end
+          attrs.merge(stimulus_attributes_for(:trigger))
         end
 
         # @api private

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

@@ -59,7 +59,6 @@ module Poetry
               target :input
               action :keydown, on: :keydown
               action :input, on: :input
-              action :focus, on: :focus
               action :blur, on: :blur
             end
           end

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

@@ -626,12 +626,14 @@ module Poetry
         end
 
         # A styled heading, no ARIA role - the group points at it via
-        # aria-labelledby.
+        # aria-labelledby, and aria-hidden keeps the text from being read a
+        # second time as a stray child of the listbox (the name still flows
+        # through the reference).
         def label_part
           return if @label_text.blank?
 
           content_tag(:div, @label_text, "data-slot" => "select-label", "id" => label_id,
-                                         "class" => Style.css(:label))
+                                         "aria-hidden" => "true", "class" => Style.css(:label))
         end
       end
     end

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

@@ -65,12 +65,13 @@ module Poetry
         def button_options
           wiring = { data: { slot: "toast-trigger" } }
                    .merge(stimulus_attributes_for(:root))
-                   .merge(component_data_attributes)
 
           # Caller attributes never clobber the trigger's wiring: both sides
           # flow through Attributes, so a host data-controller/action
-          # concatenates instead of silently killing fire-on-click.
-          { variant: variant, size: size }
+          # concatenates instead of silently killing fire-on-click. The
+          # Button root wears THIS component's identity through the
+          # identity: seam (the raw data-component is reserved).
+          { variant: variant, size: size, identity: self.class.component_title }
             .merge(Poetry::Core::HTML::Attributes.merged(wiring, html_attributes))
             .symbolize_keys
         end

data/config/component_registry.yml

@@ -2924,6 +2924,10 @@ components:
     bem_block: poetry-ui-context_menu
     styles: []
     options:
+    - name: content_class
+      type: string
+      description: 'Class merge seam for the menu panel (e.g. content_class: "w-48").
+        Root-level class: styles the surface wrapper, not the panel.'
     - name: dir
       type: symbol
       variants:
@@ -4527,6 +4531,11 @@ components:
       type: boolean
       default: true
       description: Flips/shifts placement to keep the menu inside the viewport.
+    - name: content_class
+      type: string
+      description: 'Class merge seam for the menu panel - the panel opens at the trigger''s
+        width (min 8rem), so content_class: "w-56" widens it. Root-level class: styles
+        the wrapper, not the panel.'
     - name: dir
       type: symbol
       variants:
@@ -5651,9 +5660,9 @@ components:
       - blurClose
       - focusOpen
       - openValueChanged
+      - pointerDown
       - pointerEnter
       - pointerLeave
-      - touchGuard
       events:
       - poetry:hover-card:closed
       - poetry:hover-card:open
@@ -5773,8 +5782,8 @@ components:
           'on': focus
         - method: blurClose
           'on': blur
-        - method: touchGuard
-          'on': touchstart
+        - method: pointerDown
+          'on': pointerdown
       - identifier: poetry--core--popper
         targets:
         - name: anchor
@@ -6362,7 +6371,8 @@ components:
       many: true
       description: 'The top-level menus. Each takes with_trigger (the menu button)
         plus the family item slots (with_item, with_checkbox_item, with_radio_group,
-        with_sub, with_separator, ...); value: defaults to the menu''s position.'
+        with_sub, with_separator, ...); value: defaults to the menu''s position; content_class:
+        is the panel''s class merge seam.'
       setter_args:
         menu: 0
       builders:
@@ -7083,7 +7093,7 @@ components:
     - content
     - item
     - button
-    capsule: cc8c5beaabc7
+    capsule: 7baeb0a95efa
     controllers:
     - identifier: poetry--core--message-scroller
       targets:
@@ -7143,6 +7153,10 @@ components:
       - attr: data-autoscrolling
         condition: a programmatic scroll is settling - the follow-bottom release is
           suppressed while set
+      - attr: data-pending-scroll
+        condition: the opening-position hold - rendered for default_scroll_position
+          :end / :"last-anchor", cleared once the position lands (at once for an empty
+          transcript)
     - name: message-scroller-viewport
       description: The native scroll region (role=region, focusable) - the controller
         mirrors the same runtime attributes here
@@ -7151,6 +7165,9 @@ components:
         condition: overflow exists - the same edge tokens as the root
       - attr: data-autoscrolling
         condition: a programmatic scroll is settling
+      - attr: data-pending-scroll
+        condition: the opening-position hold (the root's) - the dictionary hides the
+          viewport while it is set
     - name: message-scroller-content
       description: The row container and Turbo Stream append target (stable dom id
         <id>-messages); role=log announces additions
@@ -7420,9 +7437,10 @@ components:
     slots:
     - name: items
       many: true
-      description: The bar entries. with_item(title, value:) { panel } declares a
-        trigger + panel; with_item(title, href:) a top-level link (with_link is the
-        shorthand).
+      description: 'The bar entries. with_item(title, value:) { panel } declares a
+        trigger + panel (disabled: true renders the trigger inert - native disabled
+        plus data-disabled; hover and click never open its panel); with_item(title,
+        href:) a top-level link (with_link is the shorthand).'
       setter_args:
         item: 1
       yieldless:
@@ -7485,7 +7503,9 @@ components:
     - 'Panel content is poetry_navigation_menu_link entries (active: marks the current
       page) - never buttons; navigation navigates.'
     - 'This is a DISCLOSURE bar: Tab moves through it normally and nothing traps -
-      do not wire menu/menuitem roles.'
+      do not wire menu/menuitem roles. Keys: ArrowLeft/ArrowRight step between triggers
+      and links, ArrowDown opens the focused trigger''s panel (focus stays on the
+      trigger; Tab enters it), Escape closes and returns focus to the trigger.'
     - 'Rich panels (title + description grids) want viewport: true - the shared morphing
       card contains and sizes them; the default per-item mode suits simple link lists
       (the top-nav block shows the viewport pattern).'
@@ -7513,6 +7533,9 @@ components:
         condition: its panel is open (the controller writes both vocabularies)
       - attr: data-closed
         condition: its panel is closed (written after the first close)
+      - attr: data-disabled
+        condition: 'disabled: true - inert (native disabled rides along; hover and
+          click never open the panel, the arrows step over it)'
     - name: navigation-menu-content
       description: One item's panel - presence-animated; in viewport mode it is adopted
         into the shared viewport on first activation
@@ -7709,7 +7732,6 @@ components:
       - wheel
       actions:
       - blur
-      - focus
       - hiddenChanged
       - input
       - keydown
@@ -7788,8 +7810,6 @@ components:
           'on': keydown
         - method: input
           'on': input
-        - method: focus
-          'on': focus
         - method: blur
           'on': blur
     - element: hidden

data/lib/generators/poetry/agents_section.rb

@@ -60,7 +60,7 @@ module Poetry
             the last edit (unknown components/slots/variants/wiring, icon names,
             enum values, typed-slot props, helper + setter arity, yield-less
             blocks, setter keywords, required content blocks, required slots,
-            did-you-mean, `--json`; needs the `herb` gem in the Gemfile). An edit
+            did-you-mean, `--json`; `poetry:install` adds the `herb` gem it parses with). An edit
             made after your last check is unverified markup - re-run it.
           - Faster: the `poetry` MCP server (`.mcp.json`: command `bundle`, args
             `["exec", "poetry-agent"]`, the poetry-agent gem) serves ten tools from the live registry

data/lib/generators/poetry/install/install_generator.rb

@@ -43,6 +43,12 @@ module Poetry
 
     class_option :charts, type: :boolean, default: false,
                           desc: %(Also wire poetry-charts (requires gem "poetry-charts" in the bundle))
+    class_option :skip_bundle, type: :boolean, default: false,
+                               desc: "Skip `bundle install` after adding the herb gem (poetry:check's parser)"
+
+    # A Gemfile line declaring herb, in any quoting, at any indentation
+    # (a `group :development do` block included).
+    HERB_GEM_LINE = /^\s*gem\s+["']herb["']/
 
     # Install-time theme selection. Every themes/<name>.css fragment is
     # a complete visual theme; the chosen one fills the style-default.css
@@ -253,6 +259,29 @@ module Poetry
       JS
     end
 
+    # poetry:check parses ERB with herb, which stays out of poetry's runtime
+    # dependencies on purpose (hosts never need it to render), so the
+    # install adds it to the development group - once, and never when the
+    # Gemfile already declares it anywhere. Then `bundle install`, unless
+    # --skip-bundle (the note says what is left to do).
+    # @api private
+    def add_herb_gem
+      gemfile = File.join(destination_root, "Gemfile")
+      return unless File.exist?(gemfile)
+
+      if File.read(gemfile).match?(HERB_GEM_LINE)
+        say_status :skip, "herb is already in the Gemfile (poetry:check's parser)", :cyan
+        return
+      end
+
+      gem "herb", group: :development, comment: "poetry:check parses ERB with herb (development only)"
+      if options[:skip_bundle]
+        say_status :note, "run `bundle install` to fetch herb before `bin/rails poetry:check`", :cyan
+      else
+        in_root { Bundler.with_unbundled_env { run "bundle install" } }
+      end
+    end
+
     # The llms.txt / llms-full.txt agent docs are engine routes - without
     # the mount they are unreachable (the fresh-app proof caught this).
     # @api private

data/lib/poetry/ui/chat.rb

@@ -37,6 +37,11 @@ module Poetry
         Script.new(&)
       end
 
+      # Raised when a script is asked for what its shape cannot give -
+      # continuation frames from a turn that has no approval pause.
+      # Inherits the family base, so `rescue Poetry::Core::Error` covers it.
+      class Error < Poetry::Core::Error; end
+
       # One rendered state of an assistant row mid-stream.
       Frame = Struct.new(:parts, :sleep_ms, :version, keyword_init: true)
 

data/lib/poetry/ui/themes.rb

@@ -22,7 +22,7 @@ module Poetry
 
       # The provenance line template for ported treatments,
       # format-interpolated with the upstream style name.
-      PORTED = "ported from the source style-%s.css at pin shadcn@4.19.0 (1773ecfe)"
+      PORTED = "ported from the source style-%s.css at pin shadcn@4.21.0 (7c9eaba1)"
 
       # Per-theme DESIGN.md metadata: the typography pairing and the
       # treatment provenance line.

data/lib/poetry/ui/version.rb

@@ -3,6 +3,6 @@
 module Poetry
   module Ui
     # The gem version.
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/lib/tasks/poetry/check.rake

@@ -12,7 +12,8 @@ namespace :poetry do
     # optional-parser posture as poetry:verify's template gate.
     unless Poetry::Core::CSS::TemplateClasses.available?
       abort "poetry:check: the herb gem is required to parse templates - " \
-            "add `gem \"herb\"` to your Gemfile (development group is enough)"
+            "`bin/rails g poetry:install` adds it to your development group " \
+            "(or add `gem \"herb\"` to the Gemfile yourself and bundle)"
     end
 
     # Default sweep: ERB through the template tier, app Ruby through the

data/themes/luma.css

@@ -1,5 +1,5 @@
 /* poetry luma theme - upstream style-luma.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme;
  * rule order per component = base < elements < variants < compounds;
  * split-side, no-empty-rules and cross-component-last rules apply.

data/themes/lyra.css

@@ -1,5 +1,5 @@
 /* poetry lyra theme - upstream style-lyra.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme;
  * rule order per component = base < elements < variants < compounds;
  * split-side, no-empty-rules and cross-component-last rules apply.

data/themes/maia.css

@@ -1,5 +1,5 @@
 /* poetry maia theme - upstream style-maia.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme;
  * rule order per component = base < elements < variants < compounds;
  * split-side, no-empty-rules and cross-component-last rules apply.

data/themes/mira.css

@@ -1,5 +1,5 @@
 /* poetry mira theme - upstream style-mira.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme;
  * rule order per component = base < elements < variants < compounds;
  * split-side, no-empty-rules and cross-component-last rules apply.

data/themes/nova.css

@@ -1,5 +1,5 @@
 /* poetry nova theme - upstream style-nova.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme;
  * rule order per component = base < elements < variants < compounds;
  * split-side, no-empty-rules and cross-component-last rules apply.

data/themes/rhea.css

@@ -1,5 +1,5 @@
 /* poetry rhea theme - upstream style-rhea.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme;
  * rule order per component = base < elements < variants < compounds;
  * split-side, no-empty-rules and cross-component-last rules apply.

data/themes/sera.css

@@ -1,5 +1,5 @@
 /* poetry sera theme - upstream style-sera.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme;
  * rule order per component = base < elements < variants < compounds;
  * split-side, no-empty-rules and cross-component-last rules apply.

data/themes/vega.css

@@ -1,5 +1,5 @@
 /* poetry vega theme - upstream style-vega.css ported onto the
- * cn-* layer (pinned clone 1773ecfe, the shadcn@4.19.0 release). Same contract as default.css:
+ * cn-* layer (pinned clone 7c9eaba1, the shadcn@4.21.0 release). Same contract as default.css:
  * imported layer(base); bare selectors while installs carry ONE theme
  * (the .style-<name> wrapper arrives with the docs switcher); rule order
  * per component = base < elements < variants < compounds; split-side,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: poetry-ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Matt Solt
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
 description: 'Poetry''s components for the AI-native UI component library: accessible,
   themeable, agent-legible ViewComponents built entirely on poetry-core''s public
   DSL.'