poetry-ui 0.0.2

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Sidebar
+      # Style dictionary for the Sidebar family. The collapse / rail /
+      # inset geometry chains (width vars, offcanvas math, icon-mode
+      # size! pads, peer-size action tops) stay ENTIRELY inline - the
+      # machinery a swapped theme must never break; surfaces, tints, and
+      # type ride the theme. The mobile <dialog> keeps m-0 and the side
+      # margins BOTH inline so the class merger keeps collapsing them.
+      class Style < Poetry::Core::Style
+        base ""
+
+        # The provider wrapper carries the width custom properties.
+        # group/sidebar-wrapper has an in-repo consumer: the app-shell
+        # block's topbar answers the collapsed state
+        # (group-has-data-[collapsible=icon]/sidebar-wrapper)
+        # - the upstream site-header pattern. Two upstream markers stay
+        # dropped: group/menu-button's upstream consumer is a collapsible
+        # menu-button composition poetry does not ship yet, and
+        # group/menu-sub-item has no consumer anywhere in the current
+        # upstream tree.
+        element :wrapper, "group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar"
+
+        # The peer group (the desktop shell; below md the mobile <dialog>
+        # takes over).
+        element :peer, "group peer hidden text-sidebar-foreground md:block"
+
+        # The mobile sheet: open:flex not flex (the Dialog lesson).
+        element :mobile, "cn-sidebar-mobile relative m-0 open:flex h-full max-h-none " \
+                         "w-(--sidebar-width) max-w-none flex-col md:hidden"
+        element :mobile_left, "cn-sidebar-mobile-left mr-auto"
+        element :mobile_right, "cn-sidebar-mobile-right ml-auto"
+        element :mobile_inner, "flex h-full w-full flex-col"
+
+        # The mobile side's edge classes for the <dialog>.
+        def self.mobile_side(value)
+          resolver.render(:"mobile_#{value}")
+        end
+
+        # The desktop gap that pushes the inset over.
+        element :gap, "cn-sidebar-gap relative w-(--sidebar-width) bg-transparent " \
+                      "group-data-[collapsible=offcanvas]:w-0 group-data-[side=right]:rotate-180 " \
+                      "group-data-[collapsible=icon]:w-(--sidebar-width-icon)"
+        element :gap_inset, "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]"
+
+        element :container,
+                "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] " \
+                "duration-200 ease-linear data-[side=left]:left-0 " \
+                "data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] " \
+                "data-[side=right]:right-0 " \
+                "data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)] " \
+                "md:flex group-data-[collapsible=icon]:w-(--sidebar-width-icon) " \
+                "group-data-[side=left]:border-r group-data-[side=right]:border-l"
+        element :container_inset,
+                "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
+
+        element :inner, "cn-sidebar-inner flex size-full flex-col"
+
+        element :inset, "cn-sidebar-inset relative flex w-full flex-1 flex-col"
+
+        # The rail (desktop-only click strip).
+        element :rail,
+                "cn-sidebar-rail absolute inset-y-0 z-20 hidden w-4 transition-all ease-linear " \
+                "group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 " \
+                "after:start-1/2 after:w-[2px] sm:flex " \
+                "group-data-[collapsible=offcanvas]:translate-x-0 " \
+                "group-data-[collapsible=offcanvas]:after:left-full hover:group-data-[collapsible=offcanvas]:bg-sidebar"
+
+        element :header, "cn-sidebar-header flex flex-col"
+        element :footer, "cn-sidebar-footer flex flex-col"
+        element :separator, "cn-sidebar-separator w-auto"
+        element :content, "cn-sidebar-content no-scrollbar flex min-h-0 flex-1 flex-col overflow-auto " \
+                          "group-data-[collapsible=icon]:overflow-hidden"
+
+        element :group, "cn-sidebar-group relative flex w-full min-w-0 flex-col"
+        element :group_label, "cn-sidebar-group-label flex shrink-0 items-center outline-hidden " \
+                              "transition-[margin,opacity] duration-200 ease-linear " \
+                              "group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 " \
+                              "[&>svg]:shrink-0"
+        element :group_content, "cn-sidebar-group-content w-full"
+
+        element :menu, "cn-sidebar-menu flex w-full min-w-0 flex-col"
+        element :menu_item, "group/menu-item relative"
+        element :menu_button,
+                "cn-sidebar-menu-button peer/menu-button flex w-full items-center overflow-hidden " \
+                "text-left outline-hidden transition-[width,height,padding] " \
+                "group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! " \
+                "disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none " \
+                "aria-disabled:opacity-50 [&_svg]:shrink-0 [&>span:last-child]:truncate " \
+                "[&_svg]:size-4 group/menu-button"
+        element :menu_button_default, "cn-sidebar-menu-button-size-default"
+
+        # The item-corner action + badge - positions and
+        # reveal machinery inline, tints/type themed.
+        element :menu_action,
+                "cn-sidebar-menu-action absolute top-1.5 right-1 flex aspect-square items-center " \
+                "justify-center outline-hidden transition-transform " \
+                "group-data-[collapsible=icon]:hidden " \
+                "peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 " \
+                "peer-data-[size=sm]/menu-button:top-1 after:absolute after:-inset-2 " \
+                "md:after:hidden [&>svg]:shrink-0"
+        element :menu_action_hover,
+                "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 " \
+                "peer-data-active/menu-button:text-sidebar-accent-foreground aria-expanded:opacity-100 " \
+                "md:opacity-0"
+        # Dictionary-held surfaces so the safelist harvests the classes
+        # (helper strings are invisible to it).
+        element :group_action_button, "cn-sidebar-group-action"
+        element :input_control, "cn-sidebar-input"
+        element :menu_skeleton, "cn-sidebar-menu-skeleton flex items-center"
+        element :menu_skeleton_icon, "cn-sidebar-menu-skeleton-icon"
+        element :menu_skeleton_text, "cn-sidebar-menu-skeleton-text max-w-(--skeleton-width) flex-1"
+
+        element :menu_badge,
+                "cn-sidebar-menu-badge pointer-events-none absolute right-1 flex items-center " \
+                "justify-center select-none group-data-[collapsible=icon]:hidden " \
+                "peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 " \
+                "peer-data-[size=sm]/menu-button:top-1 tabular-nums"
+        element :menu_button_sm, "cn-sidebar-menu-button-size-sm"
+        element :menu_button_lg, "cn-sidebar-menu-button-size-lg group-data-[collapsible=icon]:p-0!"
+
+        element :menu_sub, "cn-sidebar-menu-sub mx-3.5 flex min-w-0 translate-x-px flex-col " \
+                           "group-data-[collapsible=icon]:hidden"
+        element :menu_sub_item, "relative"
+        element :menu_sub_button, "cn-sidebar-menu-sub-button flex min-w-0 -translate-x-px items-center " \
+                                  "overflow-hidden outline-hidden disabled:pointer-events-none " \
+                                  "disabled:opacity-50 aria-disabled:pointer-events-none " \
+                                  "aria-disabled:opacity-50 [&>svg]:shrink-0 [&>span:last-child]:truncate"
+
+        # The size-variant classes for a menu button.
+        def self.menu_button_size(value)
+          css(:"menu_button_#{value}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A pulsing placeholder box shown while content loads.
+    module Skeleton
+      # A pulsing placeholder while content loads. Size it with
+      # utility classes (h-4 w-32, size-10 rounded-full, ...); the content
+      # block is optional (usually empty - the box IS the placeholder).
+      #
+      # @example An avatar-and-line placeholder pair
+      #   render Poetry::Ui::Skeleton::Component.new(class: "size-10 rounded-full")
+      #   render Poetry::Ui::Skeleton::Component.new(class: "h-4 w-32")
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Skeleton is a loading placeholder - size it with classes (h-4 w-32); it has no content of its own.",
+          "Mark the live region that will replace it (aria-busy on the container), not the skeleton."
+        ].freeze
+
+        part "skeleton", "The pulsing placeholder box itself - sized entirely by utility classes"
+
+        # @api private
+        def call
+          content_tag(:div, content, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "skeleton" }.merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Skeleton
+      # The Skeleton preview: placeholders in the common shapes.
+      class Preview < Poetry::Core::Preview::Base
+        def line
+          render_component(class: "h-4 w-48")
+        end
+
+        def avatar
+          render_component(class: "size-12 rounded-full")
+        end
+
+        def block
+          render_component(class: "h-24 w-full rounded-xl")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Skeleton
+      # Style dictionary for the Skeleton family: the pulse is the
+      # mechanism (inline), the box treatment is the theme's.
+      class Style < Poetry::Core::Style
+        base "cn-skeleton animate-pulse"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+<%# Track + range ride the geometry vars; each thumb sits in an
+    absolutely positioned anchor (Radix's thumb-wrapper span, poetry
+    edition) with its hidden input alongside - thumbs and inputs stay
+    index-aligned with the value array. %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:div, content_tag(:div, nil, **range_attributes), **track_attributes) %>
+  <% thumb_values.each_index do |index| %>
+    <%= content_tag(:span, **anchor_attributes(index)) do %>
+      <%= content_tag(:div, nil, **thumb_attributes(index)) %>
+      <%= tag.input(**input_attributes(index)) %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A draggable numeric value (or range) on a continuous track.
+    module Slider
+      # A numeric value (or a [low, high] range - two thumbs) picked by
+      # dragging along a continuous track. Reach for it when the value is
+      # approximate by nature; precise known-number entry belongs in a
+      # number input. Every thumb is its own Tab stop, and arrow keys move
+      # the focused thumb by step:.
+      #
+      # The server renders everything the controller would: aria-value*
+      # per thumb (range bounds clamped to the neighboring thumb), the
+      # --slider-start/--slider-end geometry vars (no first-paint jump),
+      # and one hidden <input type=hidden> per thumb - name single,
+      # name[] range, which is precisely Rails' array-param convention
+      # (params: "50" / ["200", "800"]). Change fires per mutation,
+      # commit once per gesture; native input/change fire on COMMIT only.
+      #
+      # @example
+      #   render Poetry::Ui::Slider::Component.new(name: "volume", value: 50, label: "Volume")
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the axis option.
+        ORIENTATIONS = %i[horizontal vertical].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_slider / form.slider - never hand-roll a draggable div.",
+          "Every thumb MUST have a distinct accessible name (label: - array of two for ranges). " \
+          "ArgumentError otherwise.",
+          "Give value_text: whenever the number alone is meaningless ('$200', '80%') - SR users hear " \
+          "aria-valuetext.",
+          "Range mode: values must be sorted [low, high]; use min_steps_between_thumbs to keep a " \
+          "meaningful gap.",
+          "Do not use Slider for precise known-number entry (use Input type=number) or in " \
+          "no-JS-required forms (native input type=range).",
+          "Debounce on poetry:slider:commit, never on :change (change fires every drag frame).",
+          "Never transition the thumb/range position with CSS - geometry must track the pointer."
+        ].freeze
+
+        # One dedicated controller on purpose: slider keys move VALUES on
+        # one focused thumb - value-math no focus-moving primitive covers.
+        use_stimulus do
+          on :root do
+            controller :slider do
+              register
+              value :min, from: :min_number
+              value :max, from: :max_number
+              value :step, from: :step_number
+              value :value, from: :value_numbers
+              value :min_steps_between_thumbs
+              value :orientation
+              value :inverted
+              action :pointerdown, on: :pointerdown
+            end
+          end
+          on :track do
+            controller(:slider) { target :track }
+          end
+          on :range do
+            controller(:slider) { target :range }
+          end
+          on :thumb do
+            controller :slider do
+              target :thumb
+              action :keydown, on: :keydown
+            end
+          end
+          # The form bridge: hidden inputs submit the server value even
+          # when disabled.
+          on :input do
+            controller(:slider) { target :input }
+          end
+        end
+
+        option :name, :string, required: true,
+                               doc: "Form name; single thumb -> name; range -> name + \"[]\" per input (the Rails " \
+                                    "array-param convention)."
+        option :value, ActiveModel::Type::Value.new, doc: "Single-thumb value. ArgumentError if given with values:."
+        option :values, ActiveModel::Type::Value.new,
+               doc: "Range mode: [low, high] -> two thumbs, sorted. ArgumentError if given with value:, unsorted, or " \
+                    "length != 2."
+        option :min, :float, default: 0.0, doc: "The track's lower bound."
+        option :max, :float, default: 100.0, doc: "The track's upper bound; must exceed min:."
+        option :step, :float, default: 1.0,
+                              doc: "Snap increment; decimal steps supported (precision-aware rounding lives in the " \
+                                   "controller's math core)."
+        option :min_steps_between_thumbs, :integer, default: 0,
+                                                    doc: "Range-mode minimum gap in STEPS: high - low >= n*step; " \
+                                                         "thumbs can never cross."
+        option :orientation, :symbol, default: :horizontal, doc: "The track axis."
+        option :inverted, :boolean, default: false,
+                                    doc: "Flips the value direction along the axis; composes with RTL (both = ltr " \
+                                         "math)."
+        option :disabled, :boolean, default: false,
+                                    doc: "Renders the control inert; the hidden inputs still submit the server value."
+        option :label, ActiveModel::Type::Value.new,
+               doc: "Per-thumb accessible names -> aria-label; range REQUIRES two. Alternatively labelled_by " \
+                    "(external wiring). Enforced."
+        option :labelled_by, :string,
+               doc: "aria-labelledby for the thumb(s) - the Field-wrapped single slider derives its name from the " \
+                    "field label this way."
+        option :value_text, ActiveModel::Type::Value.new,
+               doc: "aria-valuetext formatter: a proc (v -> \"$200\") or an i18n key " \
+                    "with %{value}; optional - falls back to the bare number." # rubocop:disable Style/FormatStringToken
+        option :described_by, :string, doc: "Field hint/error wiring -> aria-describedby on EACH thumb."
+
+        validates :orientation, inclusion: { in: ORIENTATIONS }
+
+        part "slider", "Root - the controller, the geometry vars, and pointer capture ride here",
+             states: {
+               "data-orientation" => { condition: "always - the axis",
+                                       values: ORIENTATIONS.map(&:to_s) },
+               "data-disabled" => "disabled: is set (the control is inert; the hidden inputs " \
+                                  "still submit)",
+               "data-dragging" => "a pointer drag is in flight (the controller sets it for the " \
+                                  "gesture; never rendered server-side)"
+             },
+             vars: {
+               "--slider-start" => "the filled range's start edge as a percentage - " \
+                                   "server-rendered (no first-paint jump), rewritten by the " \
+                                   "controller on every move",
+               "--slider-end" => "the filled range's end edge as a percentage (the single-thumb " \
+                                 "value rides here)"
+             }
+        part "slider-track", "The full-length rail the range paints over",
+             states: {
+               "data-orientation" => { condition: "always - mirrors the root",
+                                       values: ORIENTATIONS.map(&:to_s) }
+             }
+        part "slider-range", "The filled span between --slider-start and --slider-end",
+             states: {
+               "data-orientation" => { condition: "always - mirrors the root",
+                                       values: ORIENTATIONS.map(&:to_s) }
+             }
+        part "slider-anchor", "Absolutely positioned thumb wrapper (one per thumb, with its " \
+                              "hidden input alongside) seated on the geometry vars",
+             states: {
+               "data-orientation" => { condition: "always - mirrors the root",
+                                       values: ORIENTATIONS.map(&:to_s) }
+             }
+        part "slider-thumb", "The role=slider handle - its own Tab stop, carrying the " \
+                             "aria-value* surface (bounds neighbor-clamped in range mode)",
+             states: {
+               "data-orientation" => { condition: "always - mirrors the root",
+                                       values: ORIENTATIONS.map(&:to_s) },
+               "data-disabled" => "disabled: is set (tabindex drops to -1)",
+               "data-dragging" => "this thumb is the one being dragged (the controller pairs it " \
+                                  "with the root's)"
+             }
+
+        # @api private
+        def initialize(attributes = {})
+          if attributes.values_at(:value, "value").any? && attributes.values_at(:values, "values").any?
+            raise ArgumentError, "value: is the single-thumb API and values: the range API - pass one"
+          end
+
+          super
+
+          validate_numbers!
+          validate_labels!
+        end
+
+        # Always an array internally: [v] single, [low, high] range.
+        # @api private
+        def thumb_values
+          @thumb_values ||= if values.present?
+                              Array(values).map { |item| numeric(item, "values") }
+                            else
+                              # No value at all -> ONE thumb at min.
+                              [numeric(value.presence || min, "value")]
+                            end
+        end
+
+        # @api private
+        def range?
+          thumb_values.length > 1
+        end
+
+        # @api private
+        def input_name
+          range? ? "#{name}[]" : name
+        end
+
+        # @api private
+        def control_id
+          @control_id ||= poetry_instance_id("poetry-slider")
+        end
+
+        # @api private
+        def thumb_id(index)
+          "#{control_id}-thumb-#{index}"
+        end
+
+        # The thumb's EFFECTIVE bounds (the high thumb's min is the low
+        # thumb's value + the gap) - server-rendered, then rewritten by
+        # the controller on every neighbor move.
+        # @api private
+        def thumb_min(index)
+          index.zero? ? number(min) : number(thumb_values[index - 1] + gap)
+        end
+
+        # @api private
+        def thumb_max(index)
+          index == thumb_values.length - 1 ? number(max) : number(thumb_values[index + 1] - gap)
+        end
+
+        # @api private
+        def thumb_label(index)
+          Array(label)[index]
+        end
+
+        # @api private
+        def thumb_text(index)
+          return unless value_text.present?
+
+          value = number(thumb_values[index])
+          value_text.respond_to?(:call) ? value_text.call(value) : I18n.t(value_text, value: value)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "data-slot" => "slider", "id" => control_id,
+            "data-orientation" => orientation, "style" => geometry_style
+          }
+          attrs["data-disabled"] = "" if disabled
+          html_attributes.merge_if_not_set(
+            attrs.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def track_attributes
+          { class: css(:track), "data-slot" => "slider-track", "data-orientation" => orientation }
+            .merge(stimulus_attributes_for(:track))
+        end
+
+        # @api private
+        def range_attributes
+          { class: css(:range), "data-slot" => "slider-range", "data-orientation" => orientation }
+            .merge(stimulus_attributes_for(:range))
+        end
+
+        # @api private
+        def anchor_attributes(index)
+          anchor = if range? && index.zero? then :anchor_start
+                   elsif index == thumb_values.length - 1 then :anchor_end
+                   else :anchor_mid
+                   end
+          attrs = { class: classnames(css(:anchor), css(anchor)), "data-slot" => "slider-anchor",
+                    "data-orientation" => orientation }
+          attrs[:style] = "--slider-mid: #{number(percent(thumb_values[index]).to_f)}%;" if anchor == :anchor_mid
+          attrs
+        end
+
+        # @api private
+        def thumb_attributes(index)
+          attrs = {
+            role: "slider", id: thumb_id(index), class: css(:thumb),
+            tabindex: disabled ? "-1" : "0",
+            "data-slot" => "slider-thumb", "data-orientation" => orientation,
+            "aria-valuemin" => thumb_min(index), "aria-valuemax" => thumb_max(index),
+            "aria-valuenow" => number(thumb_values[index]),
+            "aria-orientation" => orientation
+          }
+          attrs["aria-valuetext"] = thumb_text(index) if value_text.present?
+          attrs["aria-label"] = thumb_label(index) if thumb_label(index).present?
+          attrs["aria-labelledby"] = labelled_by if labelled_by.present?
+          attrs["aria-describedby"] = described_by if described_by.present?
+          attrs["data-disabled"] = "" if disabled
+          attrs.merge(stimulus_attributes_for(:thumb))
+        end
+
+        # The form bridge: hidden inputs submit the server value even when
+        # disabled (a slider always HAS a value; the control is inert, the
+        # datum is not) - contrast native disabled fields.
+        # @api private
+        def input_attributes(index)
+          { type: "hidden", name: input_name, value: number(thumb_values[index]) }
+            .merge(stimulus_attributes_for(:input))
+        end
+
+        # Trailing-zero-free rendering: 50.0 -> "50", 0.5 -> "0.5" (aria
+        # announcements and params never carry float noise).
+        # @api private
+        def number(value)
+          value == value.to_i ? value.to_i : value
+        end
+
+        private
+
+        def gap
+          min_steps_between_thumbs * step
+        end
+
+        def percent(value)
+          span = max - min
+          return 0 if span <= 0
+
+          ((value - min) / span * 100).round(4)
+        end
+
+        def geometry_style
+          start = range? ? percent(thumb_values.first) : 0
+          "--slider-start: #{number(start.to_f)}%; --slider-end: #{number(percent(thumb_values.last).to_f)}%;"
+        end
+
+        def numeric(value, option_name)
+          Float(value)
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "Slider #{option_name}: must be numeric - got #{value.inspect}"
+        end
+
+        def validate_numbers!
+          raise ArgumentError, "Slider max: must be greater than min:" unless max > min
+          raise ArgumentError, "Slider step: must be positive" unless step.positive?
+
+          if values.present?
+            list = thumb_values
+            raise ArgumentError, "Slider values: takes two or more thumbs" unless list.length >= 2
+            raise ArgumentError, "Slider values: must be sorted ascending" unless list.each_cons(2).all? do |a, b|
+              a <= b
+            end
+          end
+          return if thumb_values.all? { |item| item.between?(min, max) }
+
+          raise ArgumentError, "Slider value(s) #{thumb_values.inspect} outside #{number(min)}..#{number(max)}"
+        end
+
+        # Per-thumb accessible names, ENFORCED: a range announcing
+        # "slider, 200" twice is useless to AT.
+        def validate_labels!
+          if range?
+            labels = Array(label)
+            return if labels.length == thumb_values.length && labels.all?(&:present?)
+
+            raise ArgumentError, "a multi-thumb Slider requires one distinct name per thumb - " \
+                                 "label: ['Minimum price', 'Maximum price']"
+          else
+            return if Array(label).first.present? || labelled_by.present?
+
+            raise ArgumentError, "Slider requires an accessible name - label: (aria-label) or " \
+                                 "labelled_by: (aria-labelledby)"
+          end
+        end
+
+        def min_number = number(min)
+        def max_number = number(max)
+        def step_number = number(step)
+        def value_numbers = thumb_values.map { |item| number(item) }
+
+        private :thumb_values, :range?, :input_name, :control_id, :thumb_id, :thumb_min, :thumb_max, :thumb_label
+        private :thumb_text, :root_attributes, :track_attributes, :range_attributes, :anchor_attributes
+        private :thumb_attributes, :input_attributes, :number
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Slider
+      # The Slider preview matrix: modes (single, range, range+gap) x
+      # orientation x states, the slider-demo port, and the edge
+      # geometries (pinned at min/max, decimal step, inverted).
+      class Preview < Poetry::Core::Preview::Base
+        # @!group Modes
+
+        # The slider-demo port: defaultValue [50], max 100, step 1,
+        # constrained width.
+        def default
+          render_component(name: "progress", value: 50, label: "Progress", class: "w-[60%]")
+        end
+
+        # Range mode (field-slider parity): two thumbs, name[] array
+        # params, TWO distinct thumb names (enforced).
+        def range
+          render_component(name: "price_range", values: [200, 800], min: 0, max: 1000, step: 10,
+                           label: ["Minimum price", "Maximum price"],
+                           value_text: ->(value) { "$#{value}" })
+        end
+
+        # min_steps_between_thumbs: the thumbs can never close under
+        # 10 steps - Home/End clamp at the neighbor's gap.
+        def range_with_gap
+          render_component(name: "hours", values: [9, 17], min: 0, max: 24,
+                           min_steps_between_thumbs: 4,
+                           label: %w[Start End])
+        end
+
+        # @!endgroup
+
+        # @!group Geometry
+
+        # Vertical grows BOTTOM-up (APG); ArrowUp still increments.
+        def vertical
+          render_component(name: "volume", value: 65, orientation: :vertical, label: "Volume",
+                           value_text: ->(value) { "#{value}%" }, class: "h-48")
+        end
+
+        # inverted: the value direction flips along the axis (increment
+        # keys decrement); composes with RTL (both = ltr math).
+        def inverted
+          render_component(name: "depth", value: 30, inverted: true, label: "Depth")
+        end
+
+        # Decimal step: the controller's precision-aware rounding keeps
+        # 0.1 grids exact (0.3, never 0.30000000000000004).
+        def decimal_step
+          render_component(name: "opacity", value: 0.5, min: 0, max: 1, step: 0.1, label: "Opacity")
+        end
+
+        # Pinned at the edges: range renders 0%/100% deterministically.
+        def at_the_edges
+          render_component(name: "bounds", values: [0, 100], label: %w[Low High])
+        end
+
+        # @!endgroup
+
+        # @!group States
+
+        def disabled
+          render_component(name: "volume", value: 40, disabled: true, label: "Volume")
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end