poetry-ui 0.0.2

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

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Exclusive or multi-select toggle sets.
+    module ToggleGroup
+      # A set of Toggle-styled buttons under one value: type: :single
+      # keeps at most one pressed (re-pressing deselects to empty),
+      # :multiple toggles each item independently. The group is one Tab
+      # stop - arrow keys move focus between items WITHOUT selecting, so
+      # browsing options never fires effects; Space/Enter press the
+      # focused item. Single groups render role=radiogroup with
+      # aria-checked items; multiple groups render role=toolbar with
+      # aria-pressed items.
+      #
+      # A ToggleGroup is UI state, not form data: a single-select that
+      # must submit is a RadioGroup, a multi-select that must submit is a
+      # checkbox group. spacing: 0 renders the classic segmented control.
+      #
+      # @example A text-alignment switcher
+      #   render Poetry::Ui::ToggleGroup::Component.new(value: "left", label: "Text alignment") do |group|
+      #     group.with_item(value: "left", label: "Align left") { icon(:"align-left") }
+      #     group.with_item(value: "center", label: "Align center") { icon(:"align-center") }
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the type axis.
+        TYPES = %i[single multiple].freeze
+        # The closed vocabulary for the orientation axis.
+        ORIENTATIONS = %i[horizontal vertical].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_toggle_group - never hand-assemble Toggles with your own exclusivity logic.",
+          "ToggleGroup is UI state, NOT form data: submitting single-select -> RadioGroup; submitting " \
+          "multi-select -> Checkbox group. No name: exists; don't route around it.",
+          "Every item MUST have a unique value: (ArgumentError on duplicates); icon-only items MUST " \
+          "pass label: (state-invariant).",
+          "Name the group via label: - a nameless radiogroup/toolbar fails the audit.",
+          "Exclusive view/mode switching that shows PANELS is Tabs (aria-selected + tabpanels), not a " \
+          "single ToggleGroup.",
+          "Never mix vocabularies: single items carry aria-checked, multiple carry aria-pressed - the " \
+          "controller enforces it; agents patching DOM must too.",
+          "single deselects to empty by re-press - if your UI needs always-one-selected, " \
+          "handle the empty change in the host."
+        ].freeze
+
+        # The same facts the before_render raise enforces, stated statically:
+        # poetry check flags the omission without rendering.
+        REQUIRED_SLOTS = { item: "at least one item" }.freeze
+
+        renders_many :items,
+                     doc: "Declares one item: value: (unique - duplicates raise), label: (required when icon-only), " \
+                          "disabled:; the block is the content. Pressed state comes from value:/values:.",
+                     renders: lambda { |value:, label: nil, disabled: false, **options, &block|
+                       item_value = register_item_value!(value)
+                       content = capture(&block)
+                       ensure_item_name!(content, label, item_value)
+                       on = pressed_values.include?(item_value)
+                       item_disabled = disabled || self.disabled
+
+                       attrs = {
+                         type: "button", class: item_classes(options.delete(:class)),
+                         "data-slot" => "toggle-group-item", "data-poetry-collection-item" => "",
+                         "data-value" => item_value,
+                         "data-variant" => variant, "data-size" => size, "data-spacing" => spacing
+                       }
+                       # Pressed is a bare presence attribute: data-pressed when on,
+                       # absent when off (never data-pressed=false).
+                       attrs["data-pressed"] = "" if on
+                       # The role/vocabulary split: single wears the radio vocabulary
+                       # (aria-checked), never aria-pressed.
+                       if single?
+                         attrs["role"] = "radio"
+                         attrs["aria-checked"] = on.to_s
+                       else
+                         attrs["aria-pressed"] = on.to_s
+                       end
+                       if item_disabled
+                         attrs[:disabled] = true
+                         attrs["data-disabled"] = "" # the roving-focus collection filter
+                       end
+                       attrs["aria-label"] = label if label.present?
+                       attrs.merge!(stimulus_attributes_for(:item))
+
+                       content_tag(:button, content, Poetry::Core::HTML::Attributes.merged(attrs, options))
+                     }
+
+        use_stimulus do
+          on :root do
+            controller :toggle_group do
+              register
+              value :type
+            end
+            controller :roving_focus do
+              register
+              # DEFAULT tabindex-managing mode (contrast Accordion's
+              # manage_tabindex: false).
+              value :orientation
+              value :loop, true
+              action :keydown, on: :keydown
+            end
+          end
+          on :item do
+            controller(:toggle_group) { action :toggle, on: :click }
+          end
+        end
+
+        style :variant, default: :default, required: true, variants: Toggle::Component::VARIANTS,
+                        doc: "The shared Toggle variant axis, cascaded from the root to every item (root wins)."
+        style :size, default: :default, required: true, variants: Toggle::Component::SIZES,
+                     doc: "The shared Toggle size axis, cascaded from the root to every item (root wins)."
+
+        option :type, :symbol, default: :single,
+                               doc: ":single keeps at most one item pressed; :multiple toggles items independently."
+        option :value, :string, doc: "single: the pressed item's value. ArgumentError with :multiple."
+        option :values, :list, default: -> { [] },
+                               doc: "multiple: the pressed items' values. ArgumentError with :single."
+        option :spacing, :integer, default: 2,
+                                   doc: "0 = the classic segmented control (joined corners, collapsed outline " \
+                                        "borders); >0 = free-standing items separated by that gap step."
+        option :orientation, :symbol, default: :horizontal,
+                                      doc: "The roving axis; :vertical stacks the items and flips the arrow keys."
+        option :disabled, :boolean, default: false, doc: "Disables every item in the group."
+        option :label, :string,
+               doc: "The group's accessible name (aria-label) - a nameless radiogroup/toolbar logs a lint warning."
+
+        validates :orientation, inclusion: { in: ORIENTATIONS }
+
+        part "toggle-group", "The role=radiogroup (single) / role=toolbar (multiple) root - the " \
+                             "value-set machine and roving focus ride here; the axes cascade to items",
+             states: {
+               "data-variant" => { condition: "the shared Toggle variant (root wins)",
+                                   values: Toggle::Component::VARIANTS.map(&:to_s) },
+               "data-size" => { condition: "the shared Toggle size (root wins)",
+                                values: Toggle::Component::SIZES.map(&:to_s) },
+               "data-spacing" => "the gap step - 0 is the segmented chain (joined corners), >0 free-standing",
+               "data-orientation" => { condition: "the roving axis", values: ORIENTATIONS.map(&:to_s) },
+               "data-disabled" => "the whole group is disabled (disables every item)"
+             },
+             vars: {
+               "--gap" => "the item gap, set inline from spacing: - the root's gap utility consumes it"
+             }
+        part "toggle-group-item", "One dumb <button> under the group machine - Toggle-styled, no " \
+                                  "per-item controller",
+             states: {
+               "data-pressed" => "pressed (bare presence boolean - absent when off; the controller " \
+                                 "rederives the type-correct aria attribute from it)",
+               "data-disabled" => "the item (or the whole group) is disabled - the roving-focus " \
+                                  "collection filter",
+               "data-value" => "the item's key in the value set (always present, unique)",
+               "data-variant" => { condition: "cascaded from the root",
+                                   values: Toggle::Component::VARIANTS.map(&:to_s) },
+               "data-size" => { condition: "cascaded from the root",
+                                values: Toggle::Component::SIZES.map(&:to_s) },
+               "data-spacing" => "cascaded from the root - keys the segmented corner/border chain"
+             }
+
+        # The wrong value pair for the type is unrepresentable, not ignored.
+        # @api private
+        def initialize(attributes = {})
+          type = (attributes[:type] || attributes["type"] || :single).to_sym
+          raise ArgumentError, "ToggleGroup type must be :single or :multiple" unless TYPES.include?(type)
+
+          if type == :single && attributes.values_at(:values, "values").any?
+            raise ArgumentError, "values: is the :multiple API - single takes value: (one pressed item)"
+          end
+          if type == :multiple && attributes.values_at(:value, "value").any?
+            raise ArgumentError, "value: is the :single API - multiple takes values: (an array)"
+          end
+
+          super
+        end
+
+        # @api private
+        def before_render
+          raise ArgumentError, "ToggleGroup requires at least one with_item" unless items?
+
+          return if named?
+
+          # Lint-level warning, not an error: a radiogroup/toolbar SHOULD
+          # have an accessible name.
+          Rails.logger&.warn(
+            "poetry ToggleGroup: nameless #{single? ? "radiogroup" : "toolbar"} - give it label: (or aria-labelledby)"
+          )
+        end
+
+        # @api private
+        def single?
+          type != :multiple
+        end
+
+        # @api private
+        def pressed_values
+          @pressed_values ||= (single? ? Array(value) : Array(values)).compact.map(&:to_s)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "role" => single? ? "radiogroup" : "toolbar",
+            "data-slot" => "toggle-group",
+            "data-variant" => variant, "data-size" => size, "data-spacing" => spacing,
+            "data-orientation" => orientation, "style" => "--gap: #{spacing}"
+          }
+          attrs["aria-label"] = label if label.present?
+          attrs["data-disabled"] = "" if disabled
+          html_attributes.merge_if_not_set(
+            attrs.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        private
+
+        def register_item_value!(value)
+          @item_values ||= Set.new
+          item_value = value.to_s
+          unless @item_values.add?(item_value)
+            raise ArgumentError, "duplicate ToggleGroup item value #{item_value.inspect} - values key the set machine"
+          end
+
+          item_value
+        end
+
+        def ensure_item_name!(content, label, item_value)
+          return if label.present? || content.to_s.gsub(/<[^>]+>/, " ").strip.present?
+
+          raise ArgumentError,
+                "icon-only ToggleGroup item #{item_value.inspect} requires label: (the accessible name, " \
+                "state-invariant)"
+        end
+
+        def named?
+          aria = html_attributes["aria"] || {}
+          label.present? ||
+            html_attributes["aria-label"].present? || html_attributes["aria-labelledby"].present? ||
+            aria["label"].present? || aria["labelledby"].present?
+        end
+
+        # Shared-not-copied: the item's variant/size classes come from
+        # Toggle's dictionary (the toggleVariants import graph); this
+        # component's dictionary contributes only the item overrides. The
+        # merger collapses conflicts exactly as the source's cn() does
+        # (px-3 wins, min-w-0 wins).
+        def item_classes(extra)
+          classnames(Toggle::Style.css(variant: variant, size: size), css(:item), extra)
+        end
+
+        private :single?, :pressed_values, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module ToggleGroup
+      # The ToggleGroup preview matrix: both types x both variants x both
+      # spacing modes with mixed item states - the toggle-group-demo corpus
+      # plus the segmented picker and the disabled-item edge.
+      class Preview < Poetry::Core::Preview::Base
+        # @!group Types
+
+        # The toggle-group-demo port: MULTIPLE + outline, icon items each
+        # with a state-invariant aria-label (toolbar semantics).
+        def default
+          render_component(type: :multiple, variant: :outline, values: %w[bold],
+                           label: "Text formatting") do |group|
+            formatting_items(group)
+          end
+        end
+
+        # single = a radio group that can deselect to empty: role=radiogroup,
+        # items role=radio + aria-checked (aria-pressed stripped).
+        def single
+          render_component(type: :single, value: "center", label: "Text alignment") do |group|
+            alignment_items(group)
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Variants
+
+        # The classic segmented control: single + outline + spacing 0
+        # (joined corners, collapsed borders, focus ring painting over).
+        def segmented
+          render_component(type: :single, variant: :outline, value: "list", spacing: 0,
+                           label: "View") do |group|
+            group.with_item(value: "list", label: "List view") { embed(Icon::Component.new(name: :list)) }
+            group.with_item(value: "grid", label: "Grid view") { embed(Icon::Component.new(name: :"layout-grid")) }
+          end
+        end
+
+        # spacing > 0: free-standing toggles with a gap (each keeps its own
+        # rounded corners + shadow).
+        def spaced
+          render_component(type: :multiple, variant: :outline, spacing: 2, values: %w[bold italic],
+                           label: "Text formatting") do |group|
+            formatting_items(group)
+          end
+        end
+
+        # orientation: :vertical - the column layout (data-vertical flips
+        # the root; segment chains and radii are orientation-guarded).
+        def vertical
+          render_component(type: :multiple, orientation: :vertical, spacing: 1,
+                           values: %w[bold italic], label: "Text formatting") do |group|
+            formatting_items(group)
+          end
+        end
+
+        # The vertical SEGMENTED control: the orientation-guarded border/
+        # radius chain (border-t collapse, first rounded-t / last rounded-b).
+        def vertical_segmented
+          render_component(type: :single, variant: :outline, orientation: :vertical, spacing: 0,
+                           value: "list", label: "View") do |group|
+            group.with_item(value: "list", label: "List view") { embed(Icon::Component.new(name: :list)) }
+            group.with_item(value: "grid", label: "Grid view") { embed(Icon::Component.new(name: :"layout-grid")) }
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Sizes
+
+        def small
+          render_component(type: :multiple, size: :sm, variant: :outline, label: "Text formatting") do |group|
+            formatting_items(group)
+          end
+        end
+
+        def large
+          render_component(type: :multiple, size: :lg, label: "Text formatting") do |group|
+            formatting_items(group)
+          end
+        end
+
+        # @!endgroup
+
+        # @!group States
+
+        # A disabled item mid-group: skipped by Tab AND filtered from the
+        # roving collection; the segment borders still join.
+        def disabled_item
+          render_component(type: :single, variant: :outline, value: "left",
+                           label: "Text alignment") do |group|
+            group.with_item(value: "left", label: "Align left") { embed(Icon::Component.new(name: :"text-align-start")) }
+            group.with_item(value: "center", label: "Align center", disabled: true) do
+              embed(Icon::Component.new(name: :"text-align-center"))
+            end
+            group.with_item(value: "right", label: "Align right") { embed(Icon::Component.new(name: :"text-align-end")) }
+          end
+        end
+
+        def disabled_group
+          render_component(type: :multiple, variant: :outline, disabled: true,
+                           label: "Text formatting") do |group|
+            formatting_items(group)
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Composition
+
+        # Icon + text items (the caller's content block, Toggle-style).
+        def with_text
+          render_component(type: :single, variant: :outline, value: "preview", label: "Mode") do |group|
+            group.with_item(value: "code") { embed(Icon::Component.new(name: :bold)).concat("Code") }
+            group.with_item(value: "preview") { "Preview" }
+          end
+        end
+
+        # @!endgroup
+
+        private
+
+        def formatting_items(group)
+          group.with_item(value: "bold", label: "Toggle bold") { embed(Icon::Component.new(name: :bold)) }
+          group.with_item(value: "italic", label: "Toggle italic") { embed(Icon::Component.new(name: :italic)) }
+          group.with_item(value: "underline", label: "Toggle underline") do
+            embed(Icon::Component.new(name: :underline))
+          end
+        end
+
+        def alignment_items(group)
+          group.with_item(value: "left", label: "Align left") { embed(Icon::Component.new(name: :"text-align-start")) }
+          group.with_item(value: "center", label: "Align center") { embed(Icon::Component.new(name: :"text-align-center")) }
+          group.with_item(value: "right", label: "Align right") { embed(Icon::Component.new(name: :"text-align-end")) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module ToggleGroup
+      # Re-expressed through the cn-* theme layer. The gap mechanism
+      # (gap-[--spacing(var(--gap))]) and the whole data-[spacing=0]
+      # segmented-control chain stay inline - upstream's own split keeps
+      # the segmentation machinery in markup; the group radius + the
+      # flagged-dead shadow selector ride the theme. Item variant/size
+      # classes still come from Toggle::Style (shared, never copied).
+      class Style < Poetry::Core::Style
+        base "cn-toggle-group group/toggle-group flex w-fit flex-row items-center " \
+             "gap-[--spacing(var(--gap))] data-vertical:flex-col data-vertical:items-stretch"
+
+        # The item overrides over Toggle's classes: w-auto/min-w-0 relax the
+        # square-ish standalone shape, focus z-index lets the ring paint
+        # OVER adjacent joined segments, and the data-[spacing=0] chain is
+        # the segmented control (joined corners + collapsed outline borders).
+        # The WHOLE segment-radius cluster (rounded-none + first/last edge
+        # radii) is theme-side - split-side rule: an inline
+        # rounded-none would beat every theme's edge rounding by layer
+        # order (exactly that happened when only the edges moved).
+        element :item, "cn-toggle-group-item w-auto min-w-0 shrink-0 focus:z-10 focus-visible:z-10 " \
+                       "data-[spacing=0]:shadow-none " \
+                       "group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 " \
+                       "group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 " \
+                       "group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l " \
+                       "group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Single-Tab-stop control strips.
+    module Toolbar
+      # One Tab stop of grouped controls over a data surface - bulk
+      # actions above a table, an editor's control strip. The root wears
+      # role=toolbar; the typed slots render real Buttons, Inputs, and
+      # Separators, and arrow keys move between them while Tab leaves the
+      # whole strip. An Input inside stays safe to edit: horizontal
+      # arrows stay with the text caret until it reaches a boundary.
+      #
+      # label: is required - screen readers announce it on entering the
+      # toolbar. Styling is utility-only; restyle via data-slot=toolbar.
+      #
+      # @example
+      #   render Poetry::Ui::Toolbar::Component.new(label: "Bulk actions") do |toolbar|
+      #     toolbar.with_button(variant: :outline) { "Archive" }
+      #     toolbar.with_separator
+      #     toolbar.with_input(name: "q", placeholder: "Filter…")
+      #   end
+      class Component < Poetry::Core::Component
+        # The roving-focus controller's identifier path.
+        ROVING = %i[poetry core roving_focus].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "A Toolbar is ONE Tab stop: arrows move between its controls - use it for grouped " \
+          "actions over a surface (table bulk actions, editor strips), never as page navigation.",
+          "Compose through the typed slots: with_button (a real poetry Button - tag: :a makes it " \
+          "a link), with_input (search/filter - the caret keeps its arrow keys), with_separator " \
+          "(orientation flips automatically).",
+          "label: is the toolbar's accessible name and is required - screen readers announce it " \
+          "on entry.",
+          "A ToggleGroup composed inside keeps its own arrow navigation (its items rove locally); " \
+          "place it between separators so the seam reads as a group."
+        ].freeze
+
+        # The same fact the before_render raise enforces, stated
+        # statically: poetry check flags the omission without rendering.
+        REQUIRED_SLOTS = { button: "at least one control (with_button / with_input)" }.freeze
+
+        renders_many :items,
+                     doc: "The control slots: with_button (a real Button - tag: :a makes it a link), with_input " \
+                          "(search/filter), with_separator (its orientation flips automatically).",
+                     types: {
+                       button: {
+                         renders: ->(**options) { Poetry::Ui::Button::Component.new(**item_options(options)) },
+                         as: :button
+                       },
+                       input: {
+                         renders: ->(**options) { Poetry::Ui::Input::Component.new(**item_options(options)) },
+                         as: :input
+                       },
+                       separator: {
+                         renders: lambda { |**options|
+                           Poetry::Ui::Separator::Component.new(
+                             orientation: orientation == :horizontal ? :vertical : :horizontal,
+                             class: "self-stretch", **options
+                           )
+                         },
+                         as: :separator
+                       }
+                     }
+
+        style :orientation, default: :horizontal, variants: %i[horizontal vertical],
+                            doc: "The strip's axis; :vertical stacks the controls and flips the arrow keys."
+
+        option :label, :string, required: true, doc: "The toolbar's accessible name. Required."
+        option :loop, :boolean, default: true, doc: "Whether arrow navigation wraps at the ends."
+
+        part "toolbar", "The role=toolbar root - one Tab stop; arrow keys rove across the " \
+                        "slotted controls (roving-focus, with the caret guard protecting inputs)",
+             states: {
+               "data-orientation" => { condition: "always - which arrows rove",
+                                       values: %w[horizontal vertical] }
+             }
+
+        # @api private
+        def before_render
+          raise ArgumentError, "Toolbar requires at least one control slot" unless items?
+        end
+
+        # @api private
+        def call
+          content_tag(:div, safe_join(items.map(&:to_s)), **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "role" => "toolbar", "aria-label" => label, "aria-orientation" => orientation,
+              "data-slot" => "toolbar", "data-orientation" => orientation
+            }.merge(component_data_attributes).merge(roving_attributes)
+          )
+        end
+
+        private
+
+        # Every slotted control is a roving collection item; a disabled one
+        # is filtered from the collection (the tabs idiom - roving reads
+        # data-disabled, the native attribute alone is invisible to it).
+        def item_options(options)
+          extra = { "data-poetry-collection-item" => "" }
+          extra["data-disabled"] = "" if options[:disabled]
+          options.merge(extra)
+        end
+
+        def roving_attributes
+          attrs = Poetry::Core::HTML::Attributes.new
+          roving = Poetry::Core::Stimulus::Builder.new(ROVING, attrs)
+          roving.register_controller
+          roving.with_value(:orientation, orientation)
+          roving.with_value(:loop, loop)
+          roving.with_action(:keydown, on: :keydown)
+          attrs.to_attributes
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toolbar
+      # The Toolbar preview: a formatting strip, the table bulk-action
+      # row with a filter input, and the vertical orientation.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(label: "Text formatting") do |toolbar|
+            toolbar.with_button(variant: :ghost, size: :sm) { "Bold" }
+            toolbar.with_button(variant: :ghost, size: :sm) { "Italic" }
+            toolbar.with_separator
+            toolbar.with_button(variant: :ghost, size: :sm) { "Link" }
+          end
+        end
+
+        # The table bulk-action strip: actions, a seam, then the filter
+        # input - the roving caret guard keeps the input's arrow keys.
+        def bulk_actions_with_filter
+          render_component(label: "Invoice actions") do |toolbar|
+            toolbar.with_button(variant: :outline, size: :sm) { "Export" }
+            toolbar.with_button(variant: :outline, size: :sm, disabled: true) { "Archive" }
+            toolbar.with_separator
+            toolbar.with_input(type: "search", placeholder: "Filter invoices…",
+                               "aria-label": "Filter invoices")
+          end
+        end
+
+        def vertical
+          render_component(label: "Canvas tools", orientation: :vertical) do |toolbar|
+            toolbar.with_button(variant: :ghost, size: :sm) { "Select" }
+            toolbar.with_button(variant: :ghost, size: :sm) { "Draw" }
+            toolbar.with_separator
+            toolbar.with_button(variant: :ghost, size: :sm) { "Erase" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toolbar
+      # Utility-only (the Separator/Spinner rule): there is no upstream
+      # look to be faithful to - the strip is a structural gap row;
+      # data-slot=toolbar is the restyle seam for any theme that wants
+      # chrome (border, background) on it.
+      class Style < Poetry::Core::Style
+        base "flex w-fit items-center gap-1"
+
+        variant :orientation, {
+          horizontal: "flex-row",
+          vertical: "flex-col items-stretch"
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= trigger %>
+  <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(content_attributes).to_attributes) do %>
+    <% if label.present? %>
+      <%# label: substitutes the ANNOUNCED body - rich children stay visual
+          (one content node: visual wrapper hidden from AT, sr-only text
+          carries the announcement). %>
+      <span aria-hidden="true"><%= content %></span>
+      <span class="sr-only"><%= label %></span>
+    <% else %>
+      <%= content %>
+    <% end %>
+    <%# invisible until popper stamps data-side: an unpositioned arrow
+        (pinned/server-open, popper not yet run) is a stray nub in-flow. %>
+    <%# no whitespace inside the wrapper: a stray text node makes a line
+        box that stacks above the block diamond and inflates the measured
+        arrow height (28px for a 10px diamond - the bottom-side gap bug). %>
+    <span data-slot="tooltip-arrow" aria-hidden="true" class="invisible data-[side]:visible inline-block leading-none" <%= tag.attributes(**stimulus_attributes_for(:arrow)) %>><span class="<%= css(:arrow) %>"></span></span>
+  <% end %>
+<% end %>