poetry-ui 0.0.2

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Select
+      # The Select preview matrix: the ported select-demo composition, the
+      # scrollable grouped list (scroll-button case), placeholder vs
+      # valued, both trigger sizes, disabled, invalid (the Field
+      # aria-invalid chain), RTL, and the server-rendered open state.
+      class Preview < Poetry::Core::Preview::Base
+        # The select-demo port: grouped fruit, placeholder shown until a
+        # commit writes the native select + the value display together.
+        def default
+          render_component(placeholder: "Select a fruit", "aria-label": "Fruit") do |select|
+            select.with_group(label: "Fruits") do |group|
+              group.with_item(value: "apple") { "Apple" }
+              group.with_item(value: "banana") { "Banana" }
+              group.with_item(value: "blueberry") { "Blueberry" }
+              group.with_item(value: "grapes", disabled: true) { "Grapes" }
+              group.with_item(value: "pineapple") { "Pineapple" }
+            end
+          end
+        end
+
+        # select-scrollable parity: grouped timezones behind max-h - the
+        # scroll buttons appear per-direction at the extremes.
+        def scrollable
+          render_component(placeholder: "Select a timezone", "aria-label": "Timezone") do |select|
+            select.with_group(label: "North America") do |group|
+              group.with_item(value: "est") { "Eastern Standard Time (EST)" }
+              group.with_item(value: "cst") { "Central Standard Time (CST)" }
+              group.with_item(value: "mst") { "Mountain Standard Time (MST)" }
+              group.with_item(value: "pst") { "Pacific Standard Time (PST)" }
+            end
+            select.with_separator
+            select.with_group(label: "Europe & Africa") do |group|
+              group.with_item(value: "gmt") { "Greenwich Mean Time (GMT)" }
+              group.with_item(value: "cet") { "Central European Time (CET)" }
+              group.with_item(value: "eet") { "Eastern European Time (EET)" }
+              group.with_item(value: "west") { "Western European Summer Time (WEST)" }
+            end
+            select.with_separator
+            select.with_group(label: "Asia") do |group|
+              group.with_item(value: "ist") { "India Standard Time (IST)" }
+              group.with_item(value: "cst_china") { "China Standard Time (CST)" }
+              group.with_item(value: "jst") { "Japan Standard Time (JST)" }
+            end
+          end
+        end
+
+        # The server-rendered value: display label + native option selected
+        # + aria-selected/data-selected on the option, all in one pass.
+        def valued
+          render_component(value: "banana", placeholder: "Select a fruit", "aria-label": "Fruit") do |select|
+            select.with_item(value: "apple") { "Apple" }
+            select.with_item(value: "banana") { "Banana" }
+            select.with_item(value: "blueberry") { "Blueberry" }
+          end
+        end
+
+        # data-size=sm - h-8, matching Input's dense form rows.
+        def small
+          render_component(size: :sm, placeholder: "Per page", "aria-label": "Per page") do |select|
+            select.with_item(value: "10") { "10" }
+            select.with_item(value: "25") { "25" }
+            select.with_item(value: "50") { "50" }
+          end
+        end
+
+        # Disables the trigger AND the native select together.
+        def disabled
+          render_component(disabled: true, placeholder: "Select a fruit", "aria-label": "Fruit") do |select|
+            select.with_item(value: "apple") { "Apple" }
+            select.with_item(value: "banana") { "Banana" }
+          end
+        end
+
+        # The Field error chain lands aria-invalid on the trigger - the
+        # source aria-invalid: classes fire with zero Select-side code.
+        def invalid
+          render_component(placeholder: "Choose department", required: true,
+                           "aria-label": "Department", "aria-invalid": "true") do |select|
+            select.with_item(value: "eng") { "Engineering" }
+            select.with_item(value: "design") { "Design" }
+          end
+        end
+
+        # dir=rtl flips popper alignment via the direction helper; the
+        # listbox itself is flat (Left/Right stay no-ops).
+        def rtl
+          render_component(dir: :rtl, value: "ar", "aria-label": "اللغة") do |select|
+            select.with_item(value: "ar") { "العربية" }
+            select.with_item(value: "he") { "עברית" }
+          end
+        end
+
+        # Server-rendered open state (controllable-state: the attributes
+        # are the store; the controller reconciles on connect).
+        def open
+          render_component(open: true, value: "apple", placeholder: "Select a fruit",
+                           "aria-label": "Fruit") do |select|
+            select.with_group(label: "Fruits") do |group|
+              group.with_item(value: "apple") { "Apple" }
+              group.with_item(value: "banana") { "Banana" }
+            end
+            select.with_separator
+            select.with_item(value: "other") { "Other" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Select
+      # Style dictionary for the Select family.
+      class Style < Poetry::Core::Style
+        element :trigger, "cn-select-trigger flex w-fit items-center justify-between whitespace-nowrap " \
+                          "outline-none disabled:cursor-not-allowed disabled:opacity-50 " \
+                          "*:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex " \
+                          "*:data-[slot=select-value]:items-center " \
+                          "[&_svg]:pointer-events-none [&_svg]:shrink-0"
+
+        element :content, "cn-select-content cn-menu-translucent relative z-50 max-h-(--available-height) " \
+                          "origin-(--transform-origin) overflow-x-hidden overflow-y-auto " \
+                          "isolate w-(--anchor-width)"
+
+        # Padding/scroll-margin are theme-owned via cn-select-viewport
+        # (sera runs p-1.5). Sizing vars stay structural.
+        # min-h on purpose, never a hard h: a hard h collapses the whole
+        # popup to trigger height (62px for a five-item list) the moment
+        # the trigger-height var is fed (goldens never see open popups, so
+        # only a human catches it).
+        element :viewport, "cn-select-viewport min-h-[var(--radix-select-trigger-height)] w-full " \
+                           "min-w-[var(--radix-select-trigger-width)]"
+
+        element :item, "cn-select-item relative flex w-full cursor-default items-center outline-hidden " \
+                       "select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 data-disabled:opacity-50 " \
+                       "data-disabled:pointer-events-none"
+
+        element :label, "cn-select-label"
+
+        element :separator, "cn-select-separator pointer-events-none"
+
+        element :scroll_button, ""
+
+        # The indicator wrapper span - the RIGHT-2 gutter, the mirror image
+        # of dropdown-menu's left gutter.
+        element :item_indicator, "cn-select-item-indicator absolute flex items-center justify-center"
+
+        # The check stays in the DOM always; the parent item's bare
+        # data-selected drives visibility (unselected = attribute ABSENCE -
+        # no data-unselected exists), so the controller's
+        # aria-selected/data-selected twin-flip is the whole toggle.
+        element :item_indicator_state, "[:not([data-selected])>&]:hidden"
+
+        # The form bubble: visually hidden but PAINTED (sr-only clips, never
+        # display:none - browser autofill heuristics skip unpainted controls).
+        element :native, "sr-only"
+
+        # The source's inline lucide icon classes, named per part.
+        element :trigger_icon, "cn-select-trigger-icon"
+        element :indicator_check, "size-4"
+        element :scroll_icon, ""
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+<%# InputGroup anatomy: the real input (inert + transparent while masked),
+    the aria-hidden mask overlay (dots swapping to the reveal hint on
+    hover/focus), the trailing eye (revealed-only) and copy: affordance,
+    and the sr hint the masked group is described by. %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:div, **group_attributes.to_attributes) do %>
+    <%= tag.input(**input_attributes.to_attributes) %>
+    <%= content_tag(:span, **mask_attributes.to_attributes) do %>
+      <span class="relative">
+        <span class="<%= css(:mask_dots) %>">••••••••</span>
+        <span class="<%= css(:mask_reveal) %>"><%= t("poetry.sensitive_input.reveal_hint") %></span>
+      </span>
+    <% end %>
+    <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(addon_attributes).to_attributes) do %>
+      <%= render toggle_button do %>
+        <%= render Poetry::Ui::Icon::Component.new(name: :"eye-off") %>
+      <% end %>
+      <% if copy %>
+        <%= render copy_button do %>
+          <span class="<%= css(:icon_stack) %>">
+            <%= render Poetry::Ui::Icon::Component.new(name: :copy, class: css(:icon_copy)) %>
+            <%= render Poetry::Ui::Icon::Component.new(name: :check, class: css(:icon_check)) %>
+          </span>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+  <%= content_tag(:span, t("poetry.sensitive_input.hint"), **hint_attributes.to_attributes) %>
+<% end %>

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

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A secret field that stays masked until deliberately revealed.
+    module SensitiveInput
+      # A secret field - API keys, tokens, credentials - shown masked
+      # until deliberately revealed. Three states ride data-state on the
+      # root: masked (the value hidden behind an overlay that IS the
+      # reveal button, while the real input stays rendered for layout but
+      # goes inert), revealed (type=text, editable, the eye re-masks), and
+      # empty (a plain password input; the first character typed
+      # auto-reveals so composition happens visibly). Re-mask via Escape
+      # (focus returns to the group), leaving the component, or the eye.
+      # copy: adds a copy button - a real keyboard tab stop - that copies
+      # the value WITHOUT revealing it. The no-JS story is a plain
+      # password input that still submits.
+      #
+      # @example An API key with copy-without-reveal
+      #   render Poetry::Ui::SensitiveInput::Component.new(name: "api_key", label: "API key",
+      #                                                    value: token, copy: true)
+      class Component < Poetry::Core::Component
+        include Poetry::Ui::InputGroupField
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Secrets shown-on-demand are a SensitiveInput (poetry_sensitive_input) - never a bare " \
+          "password Input with a hand-rolled eye; the masked-container contract (role=button, " \
+          "focus discipline, blur re-mask) rides the controller.",
+          "label: feeds the masked announcement (\"{label}, masked.\") - pair with a Label/Field " \
+          "for the visible caption.",
+          "copy: true adds copy-without-revealing; leave it off for password-change forms.",
+          "Values re-mask on blur BY DESIGN - do not fight it with reveal-state persistence."
+        ].freeze
+
+        # Both engines declare on the root; the clipboard-text controller
+        # rides along only when copy: is set.
+        use_stimulus do
+          on :root do
+            controller :sensitive_input do
+              register
+              value :masked_label
+              value :hidden_message, from: :hidden_message_text
+              value :read_only, "true", if: :readonly
+              action :blurred, on: :focusout
+            end
+            controller :clipboard_text, if: :copy do
+              register
+              value :message, from: :copied_message_text
+            end
+          end
+          # Clicks anywhere on the bordered surface reveal (the mask's own
+          # clicks bubble here); Enter/Space ride the mask button.
+          on :group do
+            controller(:sensitive_input) { action :reveal, on: :click }
+          end
+          on :mask do
+            controller :sensitive_input do
+              target :mask
+              action :maskKeydown, on: :keydown
+            end
+          end
+          on :input do
+            controller :sensitive_input do
+              target :input
+              action :changed, on: :input
+              action :inputKeydown, on: :keydown
+            end
+            controller(:clipboard_text, if: :copy) { target :input }
+          end
+          on :toggle do
+            controller :sensitive_input do
+              target :toggle
+              action :toggle, on: :click
+            end
+          end
+          on :copy_button do
+            controller(:clipboard_text) { action :copy, on: :click }
+          end
+          # The sr hint the masked group is described by.
+          on :hint do
+            controller(:sensitive_input) { target :hint }
+          end
+        end
+
+        option :name, :string, required: true, doc: "The form field name on the real input."
+        option :value, :string,
+               doc: "The secret's current value; present = first paint is masked, blank = the empty state."
+        option :id, :string, doc: "The input's DOM id - what a Field label's for: must reference."
+        option :label, :string,
+               doc: "The accessible name - feeds the input's aria-label and the masked announcement (\"{label}, " \
+                    "masked.\"); pair with a visible Label/Field caption."
+        option :placeholder, :string, doc: "Hint text shown while the field is empty."
+        option :described_by, :string, doc: "aria-describedby on the input - Field hint/error wiring."
+        option :copy, :boolean, default: false, doc: "Adds the copy-without-revealing button in the trailing cell."
+        option :disabled, :boolean, default: false, doc: "Disables the input and drops the masked group's tab stop."
+        option :readonly, :boolean, default: false, doc: "The value can be revealed and copied but not edited."
+        option :required, :boolean, default: false, doc: "Marks the real input required."
+        option :invalid, :boolean, default: false,
+                                   doc: "aria-invalid on the input - set by Field/FormBuilder from model errors."
+
+        part "sensitive-input", "Root - the state machine rides here",
+             states: {
+               "data-state" => { condition: "always - masked (value hidden, group is the reveal " \
+                                            "button), revealed, or empty",
+                                 values: %w[masked revealed empty] },
+               "data-copied" => "copy: only - stamped for a beat after a successful copy " \
+                                "(the clipboard-text engine)",
+               "data-disabled" => "disabled: - the masked group loses its tab stop and pointer " \
+                                  "affordances"
+             }
+        part "sensitive-input-group", "The bordered field surface (InputGroup's chrome) - " \
+                                      "clicks anywhere on it reveal; wears the focus ring when " \
+                                      "the mask button inside holds focus"
+        part "input-group-control", "The real input - rendered in every state for layout " \
+                                    "stability; inert while masked (aria-hidden, tabindex -1, " \
+                                    "readonly, transparent); type=password unless revealed"
+        part "sensitive-input-mask", "The overlay painting the masked state - while masked it " \
+                                     "IS the reveal button (role=button, tabindex 0, " \
+                                     "\"{label}, masked.\", described by the sr hint; only text " \
+                                     "spans inside, so no nested-interactive); bullet dots swap " \
+                                     "to the reveal hint on hover/focus with no layout shift"
+        part "input-group-addon", "The trailing cell holding the eye (and copy: affordance)",
+             states: {
+               "data-align" => { condition: "always - inline-end holds the actions",
+                                 values: %w[inline-end] }
+             }
+        # The eye and copy affordances render as composed ghost Buttons
+        # carrying data-slot=sensitive-input-toggle / clipboard-text-copy
+        # on Button's root - part ownership attributes them to Button. The
+        # eye exists ONLY while revealed (hidden otherwise; the masked
+        # group is the reveal path), re-masks and hands focus back to the
+        # group; copy is a real tab stop wired to the clipboard-text
+        # engine.
+
+        # @api private
+        def hint_id
+          "#{control_id}-hint"
+        end
+
+        # @api private
+        def state
+          value.present? ? "masked" : "empty"
+        end
+
+        # @api private
+        def masked?
+          state == "masked"
+        end
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "data-slot" => "sensitive-input",
+            "data-state" => state,
+            "class" => css
+          }.merge(component_data_attributes)
+          attrs["data-disabled"] = "" if disabled
+          html_attributes.merge_if_not_set(attrs.merge(stimulus_attributes_for(:root)))
+        end
+
+        # @api private
+        def group_attributes
+          attrs = Poetry::Core::HTML::Attributes.new(
+            "data-slot" => "sensitive-input-group",
+            "class" => InputGroup::Style.css(class: css(:group))
+          )
+          attrs.merge!(stimulus_attributes_for(:group))
+          attrs
+        end
+
+        # Fixed inline-end - the reveal/copy cell.
+        # @api private
+        def addon_attributes
+          super(:end)
+        end
+
+        # The mask overlay IS the reveal button while masked (never the
+        # group: a role=button ancestor around the inert input trips axe
+        # nested-interactive). Display:none in every other state keeps it
+        # out of the a11y tree.
+        # @api private
+        def mask_attributes
+          attrs = Poetry::Core::HTML::Attributes.new(
+            "data-slot" => "sensitive-input-mask",
+            "class" => css(:mask)
+          )
+          if masked?
+            attrs["role"] = "button"
+            attrs["tabindex"] = disabled ? "-1" : "0"
+            attrs["aria-label"] = masked_label
+            attrs["aria-describedby"] = hint_id
+          end
+          attrs.merge!(stimulus_attributes_for(:mask))
+          attrs
+        end
+
+        # @api private
+        def input_attributes
+          attrs = Poetry::Core::HTML::Attributes.new(
+            "type" => "password",
+            "name" => name,
+            "id" => control_id,
+            "data-slot" => "input-group-control",
+            "class" => "#{Input::Style.css(class: InputGroup::Style.css(:control_input))} #{css(:input)}",
+            "autocomplete" => "off",
+            "spellcheck" => "false"
+          )
+          attrs["value"] = value if value.present?
+          attrs["placeholder"] = placeholder if placeholder.present?
+          attrs["aria-label"] = label if label.present?
+          attrs["aria-invalid"] = "true" if invalid && !disabled
+          attrs["aria-describedby"] = described_by if described_by.present?
+          attrs["disabled"] = "" if disabled
+          attrs["required"] = "" if required
+          if masked?
+            attrs["aria-hidden"] = "true"
+            attrs["tabindex"] = "-1"
+            attrs["readonly"] = ""
+          elsif readonly
+            attrs["readonly"] = ""
+          end
+          attrs.merge!(stimulus_attributes_for(:input))
+          attrs
+        end
+
+        # The eye: exists only while revealed (the masked group is the
+        # reveal path), so the server always renders it hidden.
+        # @api private
+        def toggle_button
+          group_tool_button(slot: "sensitive-input-toggle",
+                            label: t("poetry.sensitive_input.hide"),
+                            tabindex: nil, extra: { "hidden" => "" },
+                            wiring: stimulus_attributes_for(:toggle))
+        end
+
+        # A REAL tab stop (no tabindex -1): copy must be keyboard-reachable.
+        # @api private
+        def copy_button
+          group_tool_button(slot: "clipboard-text-copy",
+                            label: t("poetry.clipboard_text.copy"),
+                            tabindex: nil,
+                            wiring: stimulus_attributes_for(:copy_button))
+        end
+
+        # @api private
+        def masked_label
+          if label.present?
+            t("poetry.sensitive_input.masked_label", label: label)
+          else
+            t("poetry.sensitive_input.masked_fallback")
+          end
+        end
+
+        # The sr hint the masked group is described by (always rendered;
+        # only referenced while masked).
+        # @api private
+        def hint_attributes
+          attrs = Poetry::Core::HTML::Attributes.new("id" => hint_id, "class" => "sr-only")
+          attrs.merge!(stimulus_attributes_for(:hint))
+          attrs
+        end
+
+        private
+
+        def hidden_message_text = t("poetry.sensitive_input.hidden")
+        def copied_message_text = t("poetry.clipboard_text.copied")
+
+        private :hint_id, :state, :masked?, :root_attributes, :group_attributes, :addon_attributes, :mask_attributes
+        private :input_attributes, :toggle_button, :copy_button, :masked_label, :hint_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module SensitiveInput
+      class Preview < Poetry::Core::Preview::Base
+        # Masked: the group IS the reveal affordance (click/Enter/Space);
+        # the value re-masks on blur, Escape, or the eye.
+        def default
+          render_component(name: "api_key", label: "API key",
+                           value: "sk_demo_4eC39HqLyjWDarjtT1zdp7dc")
+        end
+
+        # copy: adds copy-WITHOUT-revealing (the clipboard-text engine).
+        def with_copy
+          render_component(name: "api_key", label: "API key",
+                           value: "sk_demo_4eC39HqLyjWDarjtT1zdp7dc", copy: true)
+        end
+
+        # readonly: reveal and copy still work; editing never does.
+        def readonly
+          render_component(name: "api_key", label: "API key", readonly: true,
+                           value: "sk_demo_4eC39HqLyjWDarjtT1zdp7dc", copy: true)
+        end
+
+        # Empty: a plain password field; the first character typed
+        # auto-reveals so composition happens visibly.
+        def empty
+          render_component(name: "new_secret", label: "New secret",
+                           placeholder: "Paste the token…")
+        end
+
+        def disabled
+          render_component(name: "api_key", label: "API key",
+                           value: "rotated-out", disabled: true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module SensitiveInput
+      # InputGroup + Input + Button wear the chrome (the SearchField
+      # composition); the machine's rendering is structural utilities keyed
+      # on the root's data-state. The one theme-owned name is the group's
+      # OWN focus ring (cn-sensitive-input-group): while masked the group
+      # is the focusable button, and every theme keys its input ring on the
+      # CONTROL's focus-visible - the group needs each theme's treatment in
+      # that theme's own vocabulary (sera underlines, mira rings at 2).
+      class Style < Poetry::Core::Style
+        base "flex w-full flex-col"
+
+        # group/sensitive powers the mask's hover swap; disabled kills the
+        # pointer affordances at the root.
+        element :group, "cn-sensitive-input-group group/sensitive relative " \
+                        "[[data-state=masked]:not([data-disabled])_&]:cursor-pointer " \
+                        "[[data-disabled]_&]:pointer-events-none"
+
+        # The real input goes transparent (not hidden - it defines the
+        # width) and inert while masked.
+        element :input, "[[data-state=masked]_&]:pointer-events-none " \
+                        "[[data-state=masked]_&]:text-transparent " \
+                        "[[data-state=masked]_&]:select-none"
+
+        # The overlay paints the masked state only - and while masked it IS
+        # the reveal button (pointer target + focusable); display:none in
+        # every other state keeps it out of the a11y tree. Both texts render
+        # stacked so the hover swap never shifts layout.
+        element :mask, "pointer-events-none absolute inset-y-0 start-0 hidden items-center " \
+                       "px-3 text-base outline-none md:text-sm [[data-state=masked]_&]:flex " \
+                       "[[data-state=masked]:not([data-disabled])_&]:pointer-events-auto " \
+                       "[[data-state=masked]:not([data-disabled])_&]:cursor-pointer"
+        element :mask_dots, "group-focus-within/sensitive:invisible group-hover/sensitive:invisible"
+        element :mask_reveal, "invisible absolute start-0 top-0 whitespace-nowrap " \
+                              "text-muted-foreground group-focus-within/sensitive:visible " \
+                              "group-hover/sensitive:visible"
+
+        element :icon_stack, "relative flex size-4 items-center justify-center"
+        element :icon_copy, "absolute inset-0 m-auto transition-all duration-200 " \
+                            "[[data-copied]_&]:scale-0 [[data-copied]_&]:opacity-0"
+        element :icon_check, "absolute inset-0 m-auto scale-0 opacity-0 transition-all duration-200 " \
+                             "[[data-copied]_&]:scale-100 [[data-copied]_&]:opacity-100"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A thin divider line between content regions.
+    module Separator
+      # A thin divider. Decorative by default (aria-hidden;
+      # it separates visually but adds nothing for AT). Set decorative: false
+      # for a semantic boundary (role=separator with the orientation), e.g.
+      # between toolbar groups.
+      #
+      # @example Horizontal divider between sections
+      #   render Poetry::Ui::Separator::Component.new
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "A purely visual divider stays decorative (the default): aria-hidden, role absent.",
+          "Set decorative: false only when the divide is semantically meaningful (role=separator)."
+        ].freeze
+
+        option :orientation, :symbol, default: :horizontal, doc: "The divider's axis."
+        option :decorative, :boolean, default: true,
+                                      doc: "Whether the divide is purely visual (aria-hidden) or a semantic boundary " \
+                                           "(role=separator)."
+
+        validates :orientation, inclusion: { in: %i[horizontal vertical] }
+
+        part "separator", "The divider itself - decorative (aria-hidden) by default, " \
+                          "role=separator when decorative: false",
+             states: {
+               "data-orientation" => { condition: "always - the resolved orientation",
+                                       values: %w[horizontal vertical] }
+             }
+
+        # @api private
+        def call
+          content_tag(:div, nil, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = { "data-slot" => "separator", "data-orientation" => orientation }
+          if decorative
+            attrs["aria-hidden"] = "true"
+          else
+            attrs["role"] = "separator"
+            # ARIA default orientation is horizontal; only mark the exception.
+            attrs["aria-orientation"] = "vertical" if orientation == :vertical
+          end
+          html_attributes.merge_if_not_set(attrs.merge(component_data_attributes))
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Separator
+      # The Separator preview: a decorative horizontal rule, and a semantic
+      # vertical divider (role=separator).
+      class Preview < Poetry::Core::Preview::Base
+        def horizontal
+          render_component(class: "my-2")
+        end
+
+        def vertical_semantic
+          render_component(orientation: :vertical, decorative: false, class: "h-8")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Separator
+      # Style dictionary for the Separator family. The thickness/length
+      # flips on data-horizontal / data-vertical, driven by the rendered
+      # data-orientation.
+      class Style < Poetry::Core::Style
+        base "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full " \
+             "data-vertical:w-px data-vertical:self-stretch"
+      end
+    end
+  end
+end