poetry-ui 0.0.2

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The InputGroup family - one bordered field surface for a control plus addons.
+    module InputGroup
+      # The InputGroup - one bordered field surface holding a control plus
+      # addons (icons, text, kbd hints, tiny buttons). The GROUP wears the
+      # border and focus ring; the control inside is borderless
+      # (poetry_input_group_input / _textarea strip the Input's own chrome
+      # and stamp data-slot=input-group-control, which the group's
+      # focus-within/invalid selectors key on). Addons align inline
+      # (start/end) or block (start/end - full-width rows).
+      #
+      # @example
+      #   <%= poetry_input_group do %>
+      #     <%= poetry_input_group_addon do %>
+      #       <%= poetry_icon(name: :search) %>
+      #     <% end %>
+      #     <%= poetry_input_group_input(name: "q", placeholder: "Search...") %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        requires_content "its control + addons"
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "The control INSIDE must be poetry_input_group_input/_textarea - a plain poetry_input " \
+          "keeps its own border+ring and double-chromes the group.",
+          "Addons are poetry_input_group_addon(align:) wrapping icons/text/buttons; use " \
+          "poetry_input_group_text for muted captions and poetry_input_group_button for tiny actions.",
+          "The group is a surface, not a label - the control still needs its Label/Field pairing."
+        ].freeze
+
+        part "input-group", "The bordered group surface (role=group) - wears the border, the " \
+                            "focus-within ring, and the invalid ring for the borderless " \
+                            "control inside"
+        part "input-group-addon", "One addon cell (icons, text, kbd hints, tiny buttons) " \
+                                  "rendered by poetry_input_group_addon around the control",
+             states: {
+               "data-align" => { condition: "always - the addon's align: axis (inline rides " \
+                                            "the row, block takes a full-width row)",
+                                 values: %w[inline-start inline-end block-start block-end] }
+             }
+
+        # Enforces the required content block before render.
+        # @api private
+        def before_render
+          ensure_content!
+        end
+
+        # Renders the group surface around the content.
+        # @api private
+        def call
+          content_tag(:div, content, **root_attributes.to_attributes)
+        end
+
+        # The group surface's attributes.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "role" => "group", "data-slot" => "input-group" }.merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module InputGroup
+      # The InputGroup preview: the search pattern (icon + control + kbd),
+      # a button addon, and the block-aligned textarea form.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_with_template(template: "poetry/ui/input_group/search_preview")
+        end
+
+        def with_button
+          render_with_template(template: "poetry/ui/input_group/button_preview")
+        end
+
+        def textarea_block
+          render_with_template(template: "poetry/ui/input_group/textarea_preview")
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/input_group/search_preview.html.erb

@@ -0,0 +1,13 @@
+<%# The search pattern: leading icon, borderless control, trailing kbd. %>
+<div class="w-80 p-4">
+  <%= poetry_label(for_id: "input-group-search", class: "sr-only") { "Search" } %>
+  <%= poetry_input_group do %>
+    <%= poetry_input_group_addon do %>
+      <%= poetry_icon(name: :search) %>
+    <% end %>
+    <%= poetry_input_group_input(id: "input-group-search", name: "q", placeholder: "Search…") %>
+    <%= poetry_input_group_addon(align: :"inline-end") do %>
+      <%= poetry_kbd { "⌘K" } %>
+    <% end %>
+  <% end %>
+</div>

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module InputGroup
+      # Re-expressed through the cn-* theme layer. The structural
+      # reflow chain (block addons force h-auto/flex-col) stays inline -
+      # it is layout mechanism; the chrome (border, focus-within ring,
+      # invalid ring, paddings) rides themes/default.css. Upstream's addon
+      # click-to-focus handler remains skipped (static port).
+      class Style < Poetry::Core::Style
+        base "cn-input-group group/input-group relative flex w-full min-w-0 items-center outline-none " \
+             "has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col " \
+             "has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col " \
+             "has-[>textarea]:h-auto"
+
+        # The addon: shared chrome + one align axis (inline = in the row,
+        # block = its own full-width row).
+        element :addon, "cn-input-group-addon flex cursor-text items-center justify-center select-none"
+        element :addon_inline_start, "cn-input-group-addon-align-inline-start order-first"
+        element :addon_inline_end, "cn-input-group-addon-align-inline-end order-last"
+        element :addon_block_start, "cn-input-group-addon-align-block-start order-first w-full justify-start"
+        element :addon_block_end, "cn-input-group-addon-align-block-end order-last w-full justify-start"
+
+        element :text, "cn-input-group-text flex items-center [&_svg]:pointer-events-none"
+
+        # The borderless control overrides (merged over Input/Textarea).
+        element :control_input, "cn-input-group-input flex-1"
+        element :control_textarea, "cn-input-group-textarea flex-1 resize-none"
+
+        # The tiny in-group Button sizes (merged over the ghost Button).
+        element :button, "cn-input-group-button flex items-center shadow-none"
+        element :button_xs, "cn-input-group-button-size-xs"
+        element :button_sm, "cn-input-group-button-size-sm"
+        element :button_icon_xs, "cn-input-group-button-size-icon-xs"
+        element :button_icon_sm, "cn-input-group-button-size-icon-sm"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/input_group/textarea_preview.html.erb

@@ -0,0 +1,10 @@
+<%# The block form: a textarea with a full-width footer row. %>
+<div class="w-80 p-4">
+  <%= poetry_label(for_id: "input-group-notes", class: "sr-only") { "Notes" } %>
+  <%= poetry_input_group do %>
+    <%= poetry_input_group_textarea(id: "input-group-notes", name: "notes", placeholder: "Add a note…") %>
+    <%= poetry_input_group_addon(align: :"block-end") do %>
+      <%= poetry_input_group_text { "Markdown supported" } %>
+    <% end %>
+  <% end %>
+</div>

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Gives a field component InputGroup's chrome: the control-id
+    # ladder, the bordered group shell, the addon cells, and the ghost
+    # tool-button recipe (steppers, clear, reveal, copy). Used by the
+    # affix-field controls (NumberField, SearchField, SensitiveInput);
+    # each includer keeps its own visible-input skeleton, since those
+    # attribute sets genuinely differ.
+    module InputGroupField
+      include FamilyIdentity
+
+      # The control-id ladder: a caller id wins, else the family
+      # instance seed.
+      # @api private
+      def control_id
+        @control_id ||= id.presence || instance_id
+      end
+
+      # The bordered role=group shell wearing InputGroup's chrome.
+      # @api private
+      def group_attributes
+        {
+          "role" => "group",
+          "data-slot" => "#{family_slot_prefix}-group",
+          "class" => InputGroup::Style.css
+        }
+      end
+
+      # One addon cell aligned inline-start or inline-end on the group row.
+      # @api private
+      def addon_attributes(align)
+        {
+          "data-slot" => "input-group-addon",
+          "data-align" => "inline-#{align}",
+          "class" => InputGroup::Style.css(:addon, class: InputGroup::Style.css(:"addon_inline_#{align}"))
+        }
+      end
+
+      private
+
+      # The ghost icon-xs tool button riding the group chrome (steppers,
+      # clear, reveal, copy). tabindex -1 by default (keyboard users act
+      # on the control); nil drops it (SensitiveInput's copy is a real
+      # tab stop).
+      def group_tool_button(slot:, label:, wiring:, tabindex: "-1", extra: {})
+        Button::Component.new({
+          variant: :ghost, size: :"icon-xs", disabled: disabled, label: label,
+          class: InputGroup::Style.css(:button, class: InputGroup::Style.css(:button_icon_xs)),
+          "data-slot" => slot,
+          "tabindex" => tabindex,
+          **extra,
+          "aria-controls" => control_id
+        }.compact.merge(wiring))
+      end
+
+      private :control_id, :group_attributes, :addon_attributes
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+<%# ONE real input over aria-hidden mirror cells. The char renders as the
+    slot's LEADING text node (the controller repaints the same node); the
+    caret element hides server-side - it exists only for the active EMPTY
+    cell under JS. Cells count from 0 across groups (slot order == string
+    index order; the row is dir=ltr). %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= tag.input(**input_attributes.to_attributes) %>
+  <% cell = -1 %>
+  <% group_sizes.each_with_index do |group_size, group_index| %>
+    <div data-slot="input-otp-group" aria-hidden="true" class="<%= css(:group) %>">
+      <% group_size.times do %>
+        <% cell += 1 %>
+        <%= content_tag(:div, **slot_attributes(cell)) do %><%= char_at(cell) %><div data-slot="input-otp-caret" hidden class="<%= css(:caret) %>"><div class="<%= css(:caret_bar) %>"></div></div><% end %>
+      <% end %>
+    </div>
+    <% if separator && group_index < group_sizes.size - 1 %>
+      <%# aria-hidden DESPITE the source's bare role=separator - between
+          chunks of ONE field a semantic separator is AT noise (recorded
+          divergence; the role stays for styling/self-id parity). %>
+      <div data-slot="input-otp-separator" class="<%= css(:separator) %>" role="separator" aria-hidden="true">
+        <%= render Poetry::Ui::Icon::Component.new(name: :minus) %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The InputOtp family - fixed-length one-time-code entry.
+    module InputOtp
+      # Fixed-length one-time-code entry built around a single input:
+      # there are NO per-cell inputs. One real
+      # native <input> (autocomplete one-time-code) holds the whole value,
+      # stretched invisibly over the row, so paste, SMS autofill, IME,
+      # constraint validation and serialization are all native and
+      # assistive technology
+      # sees ONE text field. The n slot cells are a purely presentational
+      # aria-hidden MIRROR painted by JS: auto-advance and
+      # backspace-retreat are not features, they are the native caret
+      # PROJECTED (data-active follows selectionStart).
+      #
+      # The server renders the value's chars into the cells AND the input
+      # (no-JS honesty: typing/submitting works JS-free; only the live
+      # cell paint needs the controller). The cell row forces dir=ltr -
+      # codes are LTR strings, slot order == string index order even on
+      # RTL pages.
+      #
+      # @example
+      #   render Poetry::Ui::InputOtp::Component.new(name: "code", length: 6, groups: [3, 3])
+      class Component < Poetry::Core::Component
+        # The supported code lengths - cell UIs degrade past ~8.
+        LENGTH_RANGE = (1..12)
+        # The built-in per-char filters with their native pattern + inputmode.
+        PATTERNS = {
+          digits: { js: "\\d", char: "[0-9]", inputmode: "numeric" },
+          alphanumeric: { js: "[a-zA-Z0-9]", char: "[a-zA-Z0-9]", inputmode: "text" }
+        }.freeze
+        # Field control_attributes land on the INPUT (the real control);
+        # everything else the caller passes styles the container.
+        INPUT_FACING = %w[id aria-label aria-describedby aria-invalid aria-required].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_input_otp / form.otp_field - NEVER build per-cell inputs (n Tab stops, broken " \
+          "paste, broken SMS autofill, unnameable cells).",
+          "Label via Field always ('Verification code'); put the length in the hint.",
+          "groups must sum to length (ArgumentError).",
+          "Do NOT auto-submit on poetry:otp:complete without a visible confirm affordance - silent " \
+          "submit on the 6th keystroke strands users who mistyped char 3.",
+          "Never pre-fill value: with a real code in previews/test fixtures beyond dummies; never log " \
+          "the value (it is a live credential).",
+          "InputOTP is for CODES - passwords use Input type=password, longer identifiers use Input."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller :otp do
+              register
+              value :length
+              value :pattern, from: :pattern_js
+              # The input already covers the cells at z-20; this catches
+              # gap/separator clicks.
+              action :focus_input, on: :click
+            end
+          end
+          on :input do
+            controller :otp do
+              target :input
+              action :sync, on: %i[input focus blur]
+              # maxlength truncates RAW clipboard text before the input
+              # event - the controller filters the paste itself.
+              action :paste, on: :paste
+            end
+          end
+          on :slot do
+            controller(:otp) { target :slot }
+          end
+        end
+
+        option :name, :string, required: true, doc: "The ONE input serializes params[name] = the code string."
+        option :length, :integer, required: true, doc: "Code length = slot count = maxlength."
+        option :value, :string,
+               doc: "Current code (server-rendered into the input AND the cells). The FormBuilder deliberately never " \
+                    "round-trips it (a rejected code is dead)."
+        option :groups, ActiveModel::Type::Value.new,
+               doc: "Cell clustering, e.g. [3, 3] -> two groups with a separator."
+        option :pattern, ActiveModel::Type::Value.new, default: :digits,
+                                                       doc: ":digits (numeric keypad) | :alphanumeric | a custom " \
+                                                            "Regexp - the per-char filter + the native pattern " \
+                                                            "attribute + inputmode."
+        option :disabled, :boolean, default: false, doc: "Disables the native input (the whole row dims)."
+        option :required, :boolean, default: false,
+                                    doc: "aria-required on the input - never native required (the Field rule: " \
+                                         "required rides server-side validation + aria)."
+        option :invalid, :boolean, default: false,
+                                   doc: "aria-invalid on the input; the cells mirror the destructive treatment (set " \
+                                        "by Field/FormBuilder from the failed verify)."
+        option :separator, :boolean, default: true,
+                                     doc: "role=separator dash between groups (meaningful with 2+ groups)."
+
+        part "input-otp-container", "Root row (forced dir=ltr - slot order equals string index " \
+                                    "order even on RTL pages) wrapping the real input and the " \
+                                    "mirror cells"
+        part "input-otp", "THE real native <input> (autocomplete one-time-code) stretched " \
+                          "invisibly over the row - the only AT and serialization surface"
+        part "input-otp-group", "One aria-hidden cluster of mirror cells (groups: clustering)"
+        part "input-otp-slot", "One presentational mirror cell - paints its char and the " \
+                               "active-cell ring",
+             states: {
+               "data-active" => { condition: "\"true\" while the native caret sits on this cell " \
+                                             "(the controller projects selectionStart while the " \
+                                             "input is focused; the server renders \"false\")",
+                                  values: %w[true false] }
+             }
+        part "input-otp-caret", "The fake-caret overlay - hidden server-side; the controller " \
+                                "unhides it on the active EMPTY cell"
+        part "input-otp-separator", "The between-groups dash - role=separator kept for parity " \
+                                    "but aria-hidden (a recorded divergence)"
+
+        # Validates length, groups, and pattern up front.
+        # @api private
+        def initialize(attributes = {})
+          super
+
+          validate_length!
+          validate_groups!
+          pattern_spec # raises on garbage patterns up front
+        end
+
+        # The resolved cell clustering ([length] when groups: is absent).
+        # @api private
+        def group_sizes
+          @group_sizes ||= (groups.presence || [length]).map { |size| Integer(size) }
+        end
+
+        # The value truncated to length, as rendered into input and cells.
+        # @api private
+        def display_value
+          value.to_s[0, length].to_s
+        end
+
+        # The character painted into the cell at index ("" when empty).
+        # @api private
+        def char_at(index)
+          display_value[index].to_s
+        end
+
+        # The native input's server-stable id.
+        # @api private
+        def input_id
+          @input_id ||= poetry_instance_id("poetry-input-otp")
+        end
+
+        # Whether the rendered value already fills every cell.
+        # @api private
+        def complete?
+          display_value.length >= length
+        end
+
+        # The row container's attributes.
+        # @api private
+        def root_attributes
+          attrs = {
+            "data-slot" => "input-otp-container",
+            # Codes are LTR strings: slot order must equal string index
+            # order even on RTL pages (the one place forcing ltr is right).
+            "dir" => "ltr"
+          }
+          container_attributes.merge_if_not_set(
+            attrs.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # The real native input's attributes.
+        # @api private
+        def input_attributes
+          attrs = {
+            "type" => "text", "name" => name, "id" => input_id,
+            "maxlength" => length, "pattern" => html_pattern, "inputmode" => inputmode,
+            "autocomplete" => "one-time-code", "spellcheck" => "false",
+            "autocapitalize" => "off", "autocorrect" => "off",
+            "data-slot" => "input-otp", "class" => css(:input)
+          }
+          # The invisible input is the ONLY AT surface - it must always
+          # carry a name (the axe label rule); callers override via
+          # aria-label / Field labelling.
+          attrs["aria-label"] = t("poetry.input_otp.label")
+          attrs["value"] = display_value if display_value.present?
+          attrs["disabled"] = true if disabled
+          attrs["aria-required"] = true if required
+          attrs["aria-invalid"] = true if invalid
+          Poetry::Core::HTML::Attributes.new(html_attributes.slice(*INPUT_FACING))
+                                        .merge_if_not_set(attrs.merge(stimulus_attributes_for(:input)))
+        end
+
+        # One mirror cell's attributes.
+        # @api private
+        def slot_attributes(_index)
+          attrs = {
+            class: css(:slot), "data-slot" => "input-otp-slot", "data-active" => "false"
+          }
+          # Styling-only on an aria-hidden cell (the source's
+          # aria-invalid: variants key on it); AT never sees it.
+          attrs["aria-invalid"] = "true" if invalid
+          attrs.merge(stimulus_attributes_for(:slot))
+        end
+
+        private
+
+        # Everything NOT input-facing styles the container.
+        def container_attributes
+          Poetry::Core::HTML::Attributes.new(html_attributes.except(*INPUT_FACING))
+        end
+
+        def pattern_spec
+          return PATTERNS.fetch(pattern.to_sym) if pattern.respond_to?(:to_sym) && PATTERNS.key?(pattern.to_sym)
+          return { js: pattern.source, char: "(?:#{pattern.source})", inputmode: "text" } if pattern.is_a?(Regexp)
+
+          raise ArgumentError, "InputOTP pattern: must be :digits, :alphanumeric, or a Regexp - " \
+                               "got #{pattern.inspect}"
+        end
+
+        def html_pattern
+          "#{pattern_spec[:char]}{#{length}}"
+        end
+
+        def inputmode
+          pattern_spec[:inputmode]
+        end
+
+        def validate_length!
+          return if LENGTH_RANGE.cover?(length)
+
+          raise ArgumentError, "InputOTP length: must be in #{LENGTH_RANGE} (cell UIs degrade past ~8) - " \
+                               "got #{length.inspect}"
+        end
+
+        def validate_groups!
+          return if group_sizes.sum == length
+
+          raise ArgumentError, "InputOTP groups: must sum to length (#{length}) - " \
+                               "#{group_sizes.inspect} sums to #{group_sizes.sum}"
+        rescue TypeError
+          raise ArgumentError, "InputOTP groups: must be an array of integers - got #{groups.inspect}"
+        end
+
+        def pattern_js = pattern_spec[:js]
+
+        private :group_sizes, :display_value, :char_at, :input_id, :complete?, :root_attributes, :input_attributes
+        private :slot_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module InputOtp
+      # The InputOTP preview matrix: the four ported examples (demo,
+      # pattern, controlled, separator) plus fill states, invalid, and
+      # disabled. Values are DUMMIES only - never a real code (the value
+      # is a live credential in production).
+      class Preview < Poetry::Core::Preview::Base
+        # @!group Groupings
+
+        # The input-otp-demo port: 6 digits as [3, 3] with a separator.
+        def default
+          render_component(name: "code", length: 6, groups: [3, 3],
+                           "aria-label": "Verification code")
+        end
+
+        # One group of six (no separator rendered for a single group).
+        def single_group
+          render_component(name: "code", length: 6, "aria-label": "Verification code")
+        end
+
+        # The separator example's [2, 2, 2] shape.
+        def three_groups
+          render_component(name: "code", length: 6, groups: [2, 2, 2],
+                           "aria-label": "Verification code")
+        end
+
+        # @!endgroup
+
+        # @!group Fill states
+
+        # Server-rendered partial value (no-JS honesty: the chars paint
+        # server-side; the caret cell needs the controller).
+        def partial
+          render_component(name: "code", length: 6, groups: [3, 3], value: "12",
+                           "aria-label": "Verification code")
+        end
+
+        def complete
+          render_component(name: "code", length: 6, groups: [3, 3], value: "123456",
+                           "aria-label": "Verification code")
+        end
+
+        # @!endgroup
+
+        # @!group States
+
+        # The alphanumeric pattern (input-otp-pattern parity):
+        # inputmode=text, autocapitalize off.
+        def alphanumeric
+          render_component(name: "code", length: 6, pattern: :alphanumeric,
+                           "aria-label": "Verification code")
+        end
+
+        def disabled
+          render_component(name: "code", length: 6, groups: [3, 3], disabled: true,
+                           "aria-label": "Verification code")
+        end
+
+        # The failed-verify re-render: aria-invalid on the input, the
+        # destructive treatment on the cells, value BLANKED (the
+        # otp_field default - a rejected code is dead).
+        def invalid
+          render_component(name: "code", length: 6, groups: [3, 3], invalid: true,
+                           "aria-label": "Verification code")
+        end
+
+        # @!endgroup
+
+        # @!group Recipes
+
+        # The Field recipe: label 'Verification code', length in the hint,
+        # id/describedby landing on the INPUT (the real control).
+        def in_a_field
+          field = Field::Component.new(
+            id: "preview-code", label_text: "Verification code",
+            hint: "Enter the 6-digit code we sent to your phone."
+          )
+          render_component(field) do
+            embed(Component.new(name: "code", length: 6, groups: [3, 3],
+                                **field.control_attributes.transform_keys(&:to_sym)))
+          end
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module InputOtp
+      # Re-expressed through the cn-* theme layer. The invisible-
+      # control mechanism stays ENTIRELY inline (:input stretched over the
+      # slot row at opacity 0.005 - clickable, focusable, AT-visible; NEVER
+      # sr-only) as does the caret overlay geometry + blink motion; the
+      # cell chrome (borders, active ring, invalid) rides
+      # .cn-input-otp-slot in themes/default.css.
+      class Style < Poetry::Core::Style
+        base "cn-input-otp relative flex items-center has-disabled:opacity-50"
+
+        # THE control: one real native input, full-length value, stretched
+        # invisibly over the slot row.
+        element :input, "absolute inset-0 z-20 h-full w-full opacity-[0.005] text-transparent " \
+                        "caret-transparent outline-none selection:bg-transparent " \
+                        "disabled:cursor-not-allowed"
+
+        element :group, "cn-input-otp-group flex items-center"
+        element :separator, "cn-input-otp-separator flex items-center"
+
+        element :slot, "cn-input-otp-slot relative flex items-center justify-center " \
+                       "data-[active=true]:z-10"
+
+        # The fake-caret overlay + the blinking bar (visible only on the
+        # active EMPTY cell; steady under prefers-reduced-motion via the
+        # utilities layer).
+        element :caret, "pointer-events-none absolute inset-0 flex items-center justify-center"
+
+        element :caret_bar, "cn-input-otp-caret-line animate-caret-blink duration-1000"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+<%= content_tag(tag, **root_attributes.to_attributes) do %>
+  <% if header? %><div data-slot="item-header" class="<%= css(:header) %>"><%= header %></div><% end %>
+  <% if media? %><div data-slot="item-media" data-variant="<%= media_variant %>" class="<%= media_classes %>"><%= media %></div><% end %>
+  <% if content_column? %>
+    <div data-slot="item-content" class="<%= css(:content) %>">
+      <% if title? %><div data-slot="item-title" class="<%= css(:title) %>"><%= title %></div><% end %>
+      <% if description? %><p data-slot="item-description" class="<%= css(:description) %>"><%= description %></p><% end %>
+      <%= content %>
+    </div>
+  <% end %>
+  <% if actions? %><div data-slot="item-actions" class="<%= css(:actions) %>"><%= actions %></div><% end %>
+  <% if footer? %><div data-slot="item-footer" class="<%= css(:footer) %>"><%= footer %></div><% end %>
+<% end %>