poetry-ui 0.0.2

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

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A numeric input with steppers and display formatting.
+    module NumberField
+      # A numeric field with stepper buttons and locale-aware display
+      # formatting. The anatomy is a formatted visible <input type=text>
+      # (announced as "Number field") beside a visually-hidden
+      # <input type=number> that is the form and validation truth: the
+      # raw number submits (a currency field showing $1,234.50 submits
+      # 1234.5), and native required/min/max validation rides the hidden
+      # input.
+      #
+      # Visuals compose from existing primitives - the group wears
+      # InputGroup's chrome and the steppers are ghost icon Buttons - so
+      # themes restyle it through those components. The server renders
+      # the raw number; the display formats on connect. Typed input
+      # parses Latin digits (locale separators and currency/percent
+      # symbols are handled).
+      #
+      # @example
+      #   render Poetry::Ui::NumberField::Component.new(
+      #     name: "quantity", value: 2, min: 0, label: "Quantity"
+      #   )
+      class Component < Poetry::Core::Component
+        include Poetry::Ui::InputGroupField
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_number_field / form.number_field - never a hand-rolled spinner or a bare " \
+          "input type=number.",
+          "The server reads params[<name>] as the raw number string - display formatting " \
+          "(format:) never changes what submits.",
+          "Steppers are mouse/touch affordances (tabindex -1); keyboard users step with " \
+          "ArrowUp/Down (Shift = large_step, Alt = small_step) on the input itself.",
+          "Pair it with a Label/Field for the accessible name - the component ships none.",
+          "format: takes Intl.NumberFormatOptions as a Hash ({ style: \"currency\", " \
+          "currency: \"USD\" }); pick locale: to pin parsing separators."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller :number_field do
+              register
+              value :min, from: :min_number, if: -> { min.present? }
+              value :max, from: :max_number, if: -> { max.present? }
+              value :step, from: :step_number
+              value :large_step, from: :large_step_number
+              value :small_step, from: :small_step_number
+              value :snap, if: :snap
+              value :wheel, if: :wheel
+              value :format, from: :format_json, if: -> { format.present? }
+              value :locale, if: -> { locale.present? }
+            end
+          end
+          on :input do
+            controller :number_field do
+              target :input
+              action :keydown, on: :keydown
+              action :input, on: :input
+              action :focus, on: :focus
+              action :blur, on: :blur
+            end
+          end
+          # The form/validation truth: the sr-only native number input.
+          on :hidden do
+            controller :number_field do
+              target :hidden
+              action :hiddenChanged, on: :change
+            end
+          end
+          # One element per stepper direction, so stepper(direction)
+          # forwards stimulus_attributes_for(direction) into Button kwargs.
+          %i[increment decrement].each do |direction|
+            on direction do
+              controller :number_field do
+                target direction
+                action :press, on: :pointerdown
+                action :tap, on: :click
+                action :leave, on: :pointerleave
+              end
+            end
+          end
+        end
+
+        option :name, :string, required: true, doc: "The submitted field name - rides the hidden number input."
+        option :value, ActiveModel::Type::Value.new,
+               doc: "Initial value - a number; nil renders empty (null semantics)."
+        option :min, :float, doc: "The lower clamp for stepping and native validation."
+        option :max, :float, doc: "The upper clamp for stepping and native validation."
+        option :step, :float, default: 1.0, doc: "The arrow-key / stepper increment."
+        option :large_step, :float, default: 10.0, doc: "The Shift-arrow step size (the coarse jump)."
+        option :small_step, :float, default: 0.1, doc: "The Alt-arrow step size (the fine adjustment)."
+        option :snap, :boolean, default: false, doc: "Snaps stepped values to step multiples counted from min:."
+        option :wheel, :boolean, default: false, doc: "Opt-in wheel stepping while the input is focused."
+        option :format, ActiveModel::Type::Value.new,
+               doc: "Intl.NumberFormatOptions for the DISPLAY (submission stays raw)."
+        option :locale, :string,
+               doc: "Locale tag pinning the display and parsing separators; the page locale otherwise."
+        option :placeholder, :string, doc: "Placeholder text for the empty input."
+        option :disabled, :boolean, default: false, doc: "Disables both inputs and the steppers; the group chrome dims."
+        option :readonly, :boolean, default: false,
+                                    doc: "Makes the visible input read-only (steppers and typing inert)."
+        option :required, :boolean, default: false, doc: "Requires a value - native validation rides the hidden input."
+        option :invalid, :boolean, default: false,
+                                   doc: "Marks the field invalid (aria-invalid on the visible input; the group wears " \
+                                        "the destructive ring)."
+        option :id, :string, doc: "The visible input's dom id - the seam a Label's for_id: points at."
+        option :label, :string,
+               doc: "Standalone accessible name -> aria-label on the visible input. Inside a form, the Field label " \
+                    "wires ids instead - pass neither and pair with poetry_label/form."
+        option :described_by, :string, doc: "aria-describedby wiring for Field hint/error pairing."
+
+        validates :step, numericality: { greater_than: 0 }
+
+        part "number-field", "Root wrapper - the controller, disabled/invalid/filled state, " \
+                             "and the two-input pair ride here",
+             states: {
+               "data-disabled" => "disabled: is set (steppers disable, the group chrome dims)",
+               "data-invalid" => "invalid: is set (the group wears the destructive ring via " \
+                                 "the control's aria-invalid)",
+               "data-filled" => "the value is non-null (the controller keeps it live)"
+             }
+        part "number-field-group", "The bordered field surface - wears InputGroup's chrome " \
+                                   "(cn-input-group), focus ring keyed on the control inside"
+        part "input-group-addon", "The two stepper cells - InputGroup's addon vocabulary, " \
+                                  "reused so the group paddings compose",
+             states: {
+               "data-align" => { condition: "always - inline-start holds the decrement, " \
+                                            "inline-end the increment",
+                                 values: %w[inline-start inline-end] }
+             }
+        part "input-group-control", "The visible formatted <input type=text> - InputGroup's " \
+                                    "control slot (the themes' focus-ring hook); " \
+                                    "aria-roledescription \"Number field\", never a spinbutton"
+        # The steppers render as composed ghost Buttons and carry
+        # data-slot=number-field-increment/-decrement on Button's root -
+        # ownership attributes them to Button (the date-picker-trigger
+        # pattern), so they are documented here in prose only.
+
+        # Rejects a non-numeric value: early.
+        # @api private
+        def initialize(attributes = {})
+          super
+          return unless value.present? && !numeric?(value)
+
+          raise ArgumentError, "value: must be a number (got #{value.inspect})"
+        end
+
+        # Enforces the format: Hash contract.
+        # @api private
+        def before_render
+          return unless format.present? && !format.is_a?(Hash)
+
+          raise ArgumentError, "format: takes an Intl.NumberFormatOptions Hash"
+        end
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "data-slot" => "number-field",
+            "class" => css
+          }.merge(component_data_attributes)
+          attrs["data-disabled"] = "" if disabled
+          attrs["data-invalid"] = "" if invalid
+          attrs["data-filled"] = "" if value.present?
+          html_attributes.merge_if_not_set(attrs.merge(stimulus_attributes_for(:root)))
+        end
+
+        # @api private
+        def input_attributes
+          attrs = Poetry::Core::HTML::Attributes.new(
+            "type" => "text",
+            "id" => control_id,
+            "data-slot" => "input-group-control",
+            "class" => Input::Style.css(class: InputGroup::Style.css(:control_input)),
+            "inputmode" => inputmode,
+            "autocomplete" => "off",
+            "autocorrect" => "off",
+            "spellcheck" => "false",
+            "aria-roledescription" => t("poetry.number_field.roledescription")
+          )
+          attrs["placeholder"] = placeholder if placeholder.present?
+          attrs["value"] = number(value) if value.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["readonly"] = "" if readonly
+          attrs["required"] = "" if required
+          attrs.merge!(stimulus_attributes_for(:input))
+          attrs
+        end
+
+        # The form/validation truth: raw number out, native constraint
+        # validation on. Focus never lands here (tabindex -1, aria-hidden).
+        # @api private
+        def hidden_attributes
+          attrs = Poetry::Core::HTML::Attributes.new(
+            "type" => "number",
+            "name" => name,
+            "class" => "sr-only",
+            "tabindex" => "-1",
+            "aria-hidden" => "true"
+          )
+          attrs["value"] = number(value) if value.present?
+          attrs["min"] = number(min) if min.present?
+          attrs["max"] = number(max) if max.present?
+          attrs["step"] = number(step)
+          attrs["disabled"] = "" if disabled
+          attrs["required"] = "" if required
+          attrs.merge!(stimulus_attributes_for(:hidden))
+          attrs
+        end
+
+        # The stepper Buttons (ghost, icon-xs, InputGroup's tiny-button
+        # chrome): tabindex -1 keeps them off the Tab order - keyboard
+        # users step on the input. aria-hidden is deliberately NOT applied,
+        # so touch screen readers can still activate them.
+        # @api private
+        def stepper(direction)
+          group_tool_button(slot: "number-field-#{direction}",
+                            label: t("poetry.number_field.#{direction}"),
+                            wiring: stimulus_attributes_for(direction))
+        end
+
+        # @api private
+        def stepper_icon(direction)
+          direction == :increment ? :plus : :minus
+        end
+
+        private
+
+        def numeric?(candidate)
+          candidate.is_a?(Numeric) || candidate.to_s.match?(/\A-?\d+(\.\d+)?\z/)
+        end
+
+        # Integer ranges starting at zero take the digit keyboard; decimals
+        # or open/negative ranges need the full layout.
+        def inputmode
+          whole = step == step.to_i && (!min.present? || min == min.to_i)
+          min.present? && min >= 0 && whole && format.blank? ? "numeric" : "decimal"
+        end
+
+        # Trailing-zero-free numeric strings (5.0 -> "5"), the slider idiom.
+        def number(numeric)
+          float = Float(numeric)
+          float == float.to_i ? float.to_i.to_s : float.to_s
+        end
+
+        def min_number = number(min)
+        def max_number = number(max)
+        def step_number = number(step)
+        def large_step_number = number(large_step)
+        def small_step_number = number(small_step)
+        def format_json = format.to_json
+
+        private :root_attributes, :input_attributes, :hidden_attributes, :stepper, :stepper_icon
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module NumberField
+      # @label Number Field
+      class Preview < Poetry::Core::Preview::Base
+        # @!group Basics
+
+        def default
+          render_component({ name: "quantity", label: "Quantity", value: 5, min: 0, max: 100 })
+        end
+
+        def empty
+          render_component({ name: "amount", label: "Amount", placeholder: "0" })
+        end
+
+        def decimal_steps
+          render_component({ name: "opacity", label: "Opacity", value: 0.5, min: 0, max: 1, step: 0.1 })
+        end
+
+        def snapped
+          render_component({ name: "duration", label: "Duration", value: 15, min: 0, max: 120, step: 15, snap: true })
+        end
+
+        # wheel: opts the focused input into scroll-to-step (off by
+        # default - a page-scroll trap otherwise).
+        def wheel_stepping
+          render_component({ name: "zoom", label: "Zoom", value: 100, min: 25, max: 400, step: 25, wheel: true })
+        end
+
+        # @!endgroup
+
+        # @!group Formatted
+
+        def currency
+          render_component({ name: "price", label: "Price", value: 1234.5, min: 0, step: 0.5,
+                             format: { style: "currency", currency: "USD" }, locale: "en-US" })
+        end
+
+        def percent
+          render_component({ name: "ratio", label: "Ratio", value: 0.25, min: 0, max: 1, step: 0.05,
+                             format: { style: "percent" }, locale: "en-US" })
+        end
+
+        # @!endgroup
+
+        # @!group States
+
+        def disabled
+          render_component({ name: "locked", label: "Locked quantity", value: 42, disabled: true })
+        end
+
+        def invalid
+          render_component({ name: "faulty", label: "Faulty quantity", value: 999, invalid: true })
+        end
+
+        def readonly
+          render_component({ name: "fixed", label: "Fixed quantity", value: 7, readonly: true })
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module NumberField
+      # Deliberately near-empty (the composition decision): the
+      # group wears InputGroup's chrome, the control wears Input's, the
+      # steppers wear Button's - zero new theme CSS. The root only stacks.
+      class Style < Poetry::Core::Style
+        base "flex w-full flex-col"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+<%= content_tag(:nav, **root_attributes.to_attributes) do %>
+  <ul data-slot="pagination-content" class="<%= css(:content) %>">
+    <% if show_edges? %>
+      <li data-slot="pagination-item">
+        <%= render Poetry::Ui::Button::Component.new(**previous_options) do |button| %>
+          <% if icon_edges? %>
+            <%= render Poetry::Ui::Icon::Component.new(name: :"chevron-left", class: "cn-rtl-flip") %>
+          <% else %>
+            <% button.with_leading { render Poetry::Ui::Icon::Component.new(name: :"chevron-left", class: "cn-rtl-flip") } %>
+            <span class="<%= css(:label) %>"><%= previous_label %></span>
+          <% end %>
+        <% end %>
+      </li>
+    <% end %>
+    <% if pages %><% items.each do |item| %>
+      <li data-slot="pagination-item">
+        <% if item == :gap %>
+          <span aria-hidden="true" data-slot="pagination-ellipsis" class="<%= css(:ellipsis) %>">
+            <%= render Poetry::Ui::Icon::Component.new(name: :ellipsis) %>
+            <span class="sr-only">More pages</span>
+          </span>
+        <% else %>
+          <%= render(Poetry::Ui::Button::Component.new(**page_options(item))) { item.to_s } %>
+        <% end %>
+      </li>
+    <% end %><% end %>
+    <% if show_edges? %>
+      <li data-slot="pagination-item">
+        <%= render Poetry::Ui::Button::Component.new(**next_options) do |button| %>
+          <% if icon_edges? %>
+            <%= render Poetry::Ui::Icon::Component.new(name: :"chevron-right", class: "cn-rtl-flip") %>
+          <% else %>
+            <% button.with_trailing { render Poetry::Ui::Icon::Component.new(name: :"chevron-right", class: "cn-rtl-flip") } %>
+            <span class="<%= css(:label) %>"><%= next_label %></span>
+          <% end %>
+        <% end %>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Numbered page navigation.
+    module Pagination
+      # Numbered page navigation, data-driven: give it current + total
+      # and a path: callable (page -> url) and it owns the truncation
+      # math instead of making you compose every <li> - first and last
+      # always shown, a window of siblings around the current page,
+      # ellipses for the gaps. Renders a <nav> landmark of Button-styled
+      # links with the current page marked aria-current=page.
+      #
+      # @example Paginating a product list
+      #   render Poetry::Ui::Pagination::Component.new(current: 3, total: 12,
+      #                                                path: ->(page) { products_path(page: page) })
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the current_variant axis - how the
+        # current page link renders.
+        CURRENT_VARIANTS = %i[outline filled].freeze
+
+        # The closed vocabulary for the edges axis - the Previous/Next
+        # treatment.
+        EDGES = %i[labeled icons none].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "poetry_pagination(current:, total:, path:) - never hand-build the <nav>/<ul>/<li> list.",
+          "path: is a callable ->(page) { url } (e.g. ->(p) { products_path(page: p) }).",
+          "The current page is aria-current=page; current_variant: :outline (the " \
+          "default) or :filled (the primary treatment - unambiguous active state); the rest are " \
+          "ghost links.",
+          "edges: :icons renders chevron-only Previous/Next (the table-footer posture); " \
+          ":none drops them for a bare page list; pages: false drops the numbers " \
+          "(pair with edges: :icons for the compact pager).",
+          "Host paginates with kaminari, pagy (v43+), or will_paginate? Run " \
+          "bin/rails g poetry:pagination (no argument = detect and install an adapter for " \
+          "each loaded gem) and keep calling paginate / poetry_pagy_nav / " \
+          "will_paginate(renderer: PoetryLinkRenderer) - never hand-wire poetry_pagination " \
+          "around a paginator gem."
+        ].freeze
+
+        option :current, :integer, required: true, doc: "The current page number (1-based)."
+        option :total, :integer, required: true, doc: "The total page count."
+        option :siblings, :integer, default: 1,
+                                    doc: "How many page links flank the current page before gaps elide to ellipses."
+        option :edges, :symbol, default: :labeled,
+                                doc: "The Previous/Next treatment: :labeled (chevron + responsive text), :icons " \
+                                     "(chevron only - table footers), :none (no edge links)."
+        option :pages, :boolean, default: true,
+                                 doc: "Set false to drop the numbered links - the compact two-button pager (pair " \
+                                      "with edges: :icons)."
+        option :current_variant, :symbol, default: :outline,
+                                          doc: "How the current page link renders: :outline, or :filled for the " \
+                                               "primary Button treatment (an unambiguous active state)."
+        option :label, :string, default: "pagination", doc: "The nav landmark's accessible name."
+        option :previous_label, :string, default: "Previous",
+                                         doc: "The Previous link's visible text (hidden on narrow viewports)."
+        option :next_label, :string, default: "Next", doc: "The Next link's visible text (hidden on narrow viewports)."
+
+        validates :current_variant, inclusion: { in: CURRENT_VARIANTS }
+        validates :edges, inclusion: { in: EDGES }
+
+        # (pagination-link rides the composed Buttons, so those elements
+        # belong to Button's anatomy, not this contract.)
+        part "pagination", "The <nav> landmark (role=navigation, aria-label) around the page list"
+        part "pagination-content", "The <ul> holding every entry as one horizontal row"
+        part "pagination-item", "One <li> per entry - previous/next, a page link, or a gap"
+        part "pagination-ellipsis", "The elided-pages marker between windows - aria-hidden with an " \
+                                    "sr-only 'More pages'"
+
+        # Rejects the empty-nav combination.
+        # @api private
+        def before_render
+          return if pages || edges != :none
+
+          raise ArgumentError, "pagination with pages: false needs edges (:labeled or :icons) - " \
+                               "edges: :none would render an empty nav"
+        end
+
+        # @api private
+        def show_edges? = edges != :none
+        # @api private
+        def icon_edges? = edges == :icons
+
+        # The page sequence with :gap markers where pages are elided. Small
+        # ranges show every page; larger ones show first, last, and a window
+        # of +/- siblings around current.
+        # @api private
+        def items
+          return (1..total).to_a if total <= 5 + (siblings * 2)
+
+          window = ((current - siblings)..(current + siblings)).select { |page| page > 1 && page < total }
+          with_gaps([1, *window, total])
+        end
+
+        # @api private
+        def current?(page) = page == current
+        # @api private
+        def path_for(page) = @path.call(page)
+
+        # Ghost for other pages; the current page renders per
+        # current_variant (:outline, or :filled for the primary Button).
+        # @api private
+        def page_variant(page)
+          return :ghost unless current?(page)
+
+          current_variant == :filled ? :default : :outline
+        end
+
+        # A numbered page link: aria-current for the current page, ghost
+        # otherwise; icon-sized. data-slot + data-active are the restyle hooks.
+        # @api private
+        def page_options(page)
+          {
+            tag: :a, href: path_for(page), size: :icon,
+            # A descriptive accessible name that still contains the visible
+            # number (WCAG label-in-name); the icon-sized Button requires it.
+            label: "Go to page #{page}",
+            variant: page_variant(page),
+            "aria-current": current?(page) ? "page" : nil,
+            data: { slot: "pagination-link", active: current?(page) }
+          }.compact
+        end
+
+        # Prev/Next: default-sized ghost links with the edge padding tweak;
+        # disabled (aria-disabled, no navigation) at the boundary.
+        # @api private
+        def edge_options(page, aria_label, padding)
+          options = {
+            tag: :a, href: path_for(page), variant: :ghost,
+            disabled: page < 1 || page > total,
+            data: { slot: "pagination-link" }
+          }
+          if icon_edges?
+            # Icon-sized Buttons take label: (the accessible-name contract).
+            options[:size] = :icon
+            options[:label] = aria_label
+          else
+            options[:size] = :default
+            options[:"aria-label"] = aria_label
+            options[:class] = padding
+          end
+          options
+        end
+
+        # @api private
+        def previous_options = edge_options(current - 1, "Go to previous page", css(:edge_previous))
+        # @api private
+        def next_options = edge_options(current + 1, "Go to next page", css(:edge_next))
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "role" => "navigation", "aria-label" => label, "data-slot" => "pagination" }
+              .merge(component_data_attributes)
+          )
+        end
+
+        private
+
+        # path: is passed as a keyword but held as a callable, not an option
+        # (options are typed data; a proc is behavior).
+        def initialize(path:, **)
+          super(**)
+          @path = path
+        end
+
+        def with_gaps(pages)
+          pages.each_with_object([]) do |page, sequence|
+            previous = sequence.reject { |item| item == :gap }.last
+            sequence << :gap if previous && page - previous > 1
+            sequence << page
+          end
+        end
+
+        private :show_edges?, :icon_edges?, :current?, :path_for, :page_variant, :page_options, :edge_options
+        private :previous_options, :next_options, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Pagination
+      # The Pagination preview: a middle page of a long range (both ellipses
+      # show), a short range (every page, no truncation), and the first page
+      # (Previous disabled).
+      class Preview < Poetry::Core::Preview::Base
+        PATH = ->(page) { "?page=#{page}" }
+
+        def default
+          render_component(current: 4, total: 10, path: PATH)
+        end
+
+        def long_range_both_ellipses
+          render_component(current: 8, total: 20, path: PATH)
+        end
+
+        def short_range_no_truncation
+          render_component(current: 2, total: 4, path: PATH)
+        end
+
+        def first_page
+          render_component(current: 1, total: 10, path: PATH)
+        end
+
+        # The filled current-page treatment: the primary
+        # Button as the active marker - the data-index block's choice.
+        def filled_current
+          render_component(current: 4, total: 10, current_variant: :filled, path: PATH)
+        end
+
+        # edges: :none - the bare page list (upstream pagination-simple).
+        def simple_numbers_only
+          render_component(current: 2, total: 5, edges: :none, path: PATH)
+        end
+
+        # The compact two-button pager (upstream pagination-icons-only):
+        # chevron-only edges, no numbers.
+        def icons_only
+          render_component(current: 3, total: 10, edges: :icons, pages: false, path: PATH)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Pagination
+      # Re-expressed through the cn-* theme layer. The page links
+      # reuse Button styling; the nav root and the responsive label pair
+      # (hidden sm:block - a split-side responsive pair, kept together
+      # inline) stay utility-only.
+      class Style < Poetry::Core::Style
+        base "mx-auto flex w-full justify-center"
+
+        element :content, "cn-pagination-content flex items-center"
+        element :ellipsis, "cn-pagination-ellipsis flex items-center justify-center"
+        # The label span on prev/next: hidden below sm (icon-only on mobile).
+        element :label, "hidden sm:block"
+        # The edge-padding trim (upstream parity): the chevron side pulls
+        # in so the glyph's optical whitespace doesn't read as extra
+        # hover-box padding. Lives HERE because safelists harvest Style
+        # dictionaries and templates - a class string inside component.rb
+        # never compiles in any host.
+        element :edge_previous, "cn-pagination-previous"
+        element :edge_next, "cn-pagination-next"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= anchor %>
+  <%= trigger %>
+  <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(content_attributes).to_attributes) do %>
+    <% if title? || description? %>
+      <div data-slot="popover-header" class="<%= css(:header) %>">
+        <% if title? %>
+          <div data-slot="popover-title" id="<%= title_id %>" class="<%= css(:title) %>"><%= title %></div>
+        <% end %>
+        <% if description? %>
+          <p data-slot="popover-description" id="<%= description_id %>" class="<%= css(:description) %>"><%= description %></p>
+        <% end %>
+      </div>
+    <% end %>
+    <%= content %>
+  <% end %>
+<% end %>