poetry-ui 0.0.2

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Slider
+      # Style dictionary for the Slider family. The geometry spine stays
+      # ENTIRELY inline: the --slider-start/--slider-end custom properties
+      # (server-rendered, controller-rewritten via CSSOM) and every calc()
+      # consumer on :range and the :anchor trio - a swapped theme can
+      # restyle the surfaces but can never break the math. The thumb keeps
+      # the ring-4 swelling focus ring, and bg-white is literal (the thumb
+      # stays white in dark mode).
+      class Style < Poetry::Core::Style
+        base "cn-slider relative flex w-full touch-none items-center select-none " \
+             "data-[disabled]:opacity-50 data-[orientation=vertical]:h-full " \
+             "data-[orientation=vertical]:w-auto data-[orientation=vertical]:flex-col"
+
+        element :track, "cn-slider-track relative grow overflow-hidden select-none"
+
+        # The geometry rules: horizontal spans [--slider-start,
+        # --slider-end] along the inline axis; vertical grows BOTTOM-up
+        # (APG). Logical properties (start-*) flip RTL for free.
+        element :range, "cn-slider-range absolute data-[orientation=horizontal]:h-full " \
+                        "data-[orientation=vertical]:w-full " \
+                        "data-[orientation=horizontal]:start-(--slider-start) " \
+                        "data-[orientation=horizontal]:end-[calc(100%-var(--slider-end))] " \
+                        "data-[orientation=vertical]:bottom-(--slider-start) " \
+                        "data-[orientation=vertical]:top-[calc(100%-var(--slider-end))] select-none"
+
+        element :thumb, "cn-slider-thumb block shrink-0 disabled:pointer-events-none disabled:opacity-50 " \
+                        "select-none"
+
+        # The per-thumb positioning anchor - an absolutely positioned span
+        # riding the geometry vars; calc(P% - 0.5rem) centers the 1rem
+        # thumb at P%.
+        element :anchor, "absolute data-[orientation=horizontal]:top-1/2 " \
+                         "data-[orientation=horizontal]:-translate-y-1/2 " \
+                         "data-[orientation=vertical]:left-1/2 data-[orientation=vertical]:-translate-x-1/2"
+
+        # The low thumb (range mode) anchors at --slider-start...
+        element :anchor_start, "data-[orientation=horizontal]:start-[calc(var(--slider-start)-0.5rem)] " \
+                               "data-[orientation=vertical]:bottom-[calc(var(--slider-start)-0.5rem)]"
+
+        # ...the high (or single) thumb at --slider-end.
+        element :anchor_end, "data-[orientation=horizontal]:start-[calc(var(--slider-end)-0.5rem)] " \
+                             "data-[orientation=vertical]:bottom-[calc(var(--slider-end)-0.5rem)]"
+
+        # Middle thumbs (N-thumb sliders) carry their own inline
+        # --slider-mid var - two shared vars cannot place N positions.
+        element :anchor_mid, "data-[orientation=horizontal]:start-[calc(var(--slider-mid)-0.5rem)] " \
+                             "data-[orientation=vertical]:bottom-[calc(var(--slider-mid)-0.5rem)]"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A spinning loader glyph that announces itself to assistive tech.
+    module Spinner
+      # A spinning loader glyph that announces itself (role=status +
+      # aria-label). Renders the loader-circle glyph as its own svg (so
+      # the root carries the spinner identity, not the icon's).
+      #
+      # @example
+      #   render Poetry::Ui::Spinner::Component.new(label: "Saving...")
+      class Component < Poetry::Core::Component
+        # The icon-set glyph the spinner renders.
+        GLYPH = :"loader-circle"
+        # The svg root's fixed attributes (icon-standard 24px viewBox).
+        SVG_BOX = {
+          "xmlns" => "http://www.w3.org/2000/svg", "width" => "24", "height" => "24",
+          "viewBox" => "0 0 24 24", "fill" => "none", "stroke" => "currentColor",
+          "stroke-width" => "2", "stroke-linecap" => "round", "stroke-linejoin" => "round"
+        }.freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Spinner announces itself (role=status + aria-label) - never a bare spinning div.",
+          "Set label: for the loading context ('Saving…'); the default is 'Loading'."
+        ].freeze
+
+        option :label, :string, default: "Loading", doc: "What assistive tech announces - name the loading context."
+
+        part "spinner", "The spinning <svg> itself (the lucide loader-circle) - announces " \
+                        "as role=status with aria-label from label:"
+
+        # @api private
+        def call
+          content_tag(:svg, glyph, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            SVG_BOX.merge(
+              "data-slot" => "spinner", "role" => "status", "aria-label" => label
+            ).merge(component_data_attributes)
+          )
+        end
+
+        private
+
+        def glyph
+          Poetry::Core::Icons.set(nil).fetch(GLYPH).html_safe
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Spinner
+      # The Spinner preview: the default, a larger one, and a labelled one.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component
+        end
+
+        def large
+          render_component(class: "size-8")
+        end
+
+        def with_context_label
+          render_component(label: "Saving your changes")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Spinner
+      # Style dictionary for the Spinner family: the loader glyph, spinning.
+      class Style < Poetry::Core::Style
+        base "size-4 animate-spin"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <div data-slot="stat-label" class="<%= css(:label) %>"><%= label %></div>
+  <div class="<%= css(:row) %>">
+    <div data-slot="stat-value" class="<%= css(:value) %>"><%= content %></div>
+    <% if delta.present? %>
+      <span data-slot="stat-delta" data-trend="<%= trend %>" data-sentiment="<%= resolved_sentiment %>" class="<%= delta_classes %>">
+        <%= render Poetry::Ui::Icon::Component.new(name: trend_icon) %><%= delta %><span class="sr-only"><%= t("poetry.stat.trend_#{trend}") %></span>
+      </span>
+    <% end %>
+  </div>
+  <% if description? %><div data-slot="stat-description" class="<%= css(:description) %>"><%= description %></div><% end %>
+  <% if media? %><div data-slot="stat-media" class="<%= css(:media) %>"><%= media %></div><% end %>
+<% end %>

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # One KPI: a labelled value with an optional sentiment-aware delta.
+    module Stat
+      # One KPI: a muted label over a large tabular-nums value, with an
+      # optional sentiment-aware delta, supporting description, and a
+      # media slot for a trend visual. Reach for it on dashboards - one
+      # Stat per metric, composed in a grid. Styling is utility-only:
+      # data-slot names are the restyle seam.
+      #
+      # @example Revenue KPI with a delta
+      #   render Poetry::Ui::Stat::Component.new(label: "Revenue", delta: "+12.5%", trend: :up) do
+      #     "$45,231"
+      #   end
+      class Component < Poetry::Core::Component
+        requires_content "the metric value"
+
+        # The closed vocabulary for the trend axis.
+        TRENDS = %i[up down flat].freeze
+        # The closed vocabulary for the sentiment axis.
+        SENTIMENTS = %i[positive negative neutral].freeze
+
+        # trend picks the arrow; sentiment defaults FROM the trend (up is
+        # good, down is bad) and is overridden when the metric inverts.
+        DEFAULT_SENTIMENT = { up: :positive, down: :negative, flat: :neutral }.freeze
+        # The arrow glyph each trend renders in the delta pill.
+        TREND_ICON = { up: :"trending-up", down: :"trending-down", flat: :minus }.freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "One Stat is ONE metric: label: names it, the content block is the value - compose " \
+          "several in a grid (typically each inside a Card) for a dashboard row.",
+          "delta: carries the change text ('+12.5%'); trend: (up/down/flat) sets the arrow and " \
+          "the default sentiment. Override sentiment: :positive when DOWN is the good direction " \
+          "(costs, churn, error rate) - color follows sentiment, never the arrow.",
+          "Keep the value textual - tabular numerals are already applied; units and formatting " \
+          "belong in the content ('$45,231', '99.98%').",
+          "A Stat is not a chart: a trend over time goes in the media slot (or use poetry-charts)."
+        ].freeze
+
+        renders_one :description, doc: "Muted supporting copy rendered under the value."
+        renders_one :media, doc: "The trend-visual slot (sparkline, chart, glyph) below the text stack."
+
+        option :label, :string, required: true, doc: "The metric's name, shown muted above the value."
+        option :delta, :string, doc: "The change text shown in the pill beside the value (\"+12.5%\")."
+        option :trend, :symbol, default: :up, doc: "The arrow direction; also derives the default sentiment."
+        option :sentiment, :symbol,
+               doc: "Overrides the trend-derived sentiment - color follows sentiment, never the arrow (set :positive " \
+                    "when DOWN is the good direction)."
+
+        validates :trend, inclusion: { in: TRENDS }
+        validates :sentiment, inclusion: { in: SENTIMENTS }, allow_nil: true
+
+        part "stat", "The stat root - a label/value/delta/description column"
+        part "stat-label", "The muted metric name above the value"
+        part "stat-value", "The metric itself - large, semibold, tabular numerals"
+        part "stat-delta", "The change pill beside the value - arrow icon + delta text with an " \
+                           "sr-only trend word",
+             states: {
+               "data-trend" => { condition: "always - the arrow direction",
+                                 values: TRENDS.map(&:to_s) },
+               "data-sentiment" => { condition: "always - resolved sentiment (trend-derived " \
+                                                "unless overridden)",
+                                     values: SENTIMENTS.map(&:to_s) }
+             }
+        part "stat-description", "Muted supporting copy under the value"
+        part "stat-media", "The trend-visual slot (sparkline, chart, glyph) below the text stack"
+
+        # @api private
+        def before_render
+          ensure_content!
+        end
+
+        # @api private
+        def resolved_sentiment
+          sentiment || DEFAULT_SENTIMENT.fetch(trend)
+        end
+
+        # @api private
+        def delta_classes
+          "#{css(:delta)} #{css(:"delta_#{resolved_sentiment}")}"
+        end
+
+        # @api private
+        def trend_icon
+          TREND_ICON.fetch(trend)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "stat" }.merge(component_data_attributes)
+          )
+        end
+
+        private :resolved_sentiment, :delta_classes, :trend_icon, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Stat
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(label: "Revenue") { "$45,231" }
+        end
+
+        def delta_up
+          render_component(label: "Active users", delta: "+12.5%", trend: :up) { "2,847" }
+        end
+
+        def delta_down
+          render_component(label: "Conversion rate", delta: "-0.4pt", trend: :down) { "3.1%" }
+        end
+
+        # The inverted metric: DOWN is the good direction, so sentiment
+        # overrides the trend-derived color while the arrow stays honest.
+        def inverted_down_good
+          render_component(label: "Churn", delta: "-0.8%", trend: :down, sentiment: :positive) { "2.1%" }
+        end
+
+        def flat
+          render_component(label: "Uptime", delta: "0.00%", trend: :flat) { "99.98%" }
+        end
+
+        def with_description
+          render_component(label: "Open invoices", delta: "+4", trend: :up, sentiment: :negative) do |stat|
+            stat.with_description { "12 overdue past 30 days" }
+            "38"
+          end
+        end
+
+        # The media slot: a trend visual under the text stack (a sparkline
+        # or chart in a real app; a glyph suffices to pin the anatomy).
+        def with_media
+          render_component(label: "Deploy frequency", delta: "+18%", trend: :up) do |stat|
+            stat.with_media { embed(Poetry::Ui::Icon::Component.new(name: :"trending-up", label: "Trend")) }
+            "4.2/day"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Stat
+      # Style dictionary for the Stat family - structural utilities on
+      # semantic tokens; data-slot selectors remain the always-on restyle
+      # seam, and cn names arrive only when a theme wants to own this look.
+      class Style < Poetry::Core::Style
+        base "flex min-w-0 flex-col gap-1.5"
+
+        element :label, "text-sm text-muted-foreground"
+        element :row, "flex flex-wrap items-baseline gap-x-2 gap-y-1"
+        element :value, "text-3xl font-semibold tracking-tight tabular-nums"
+        element :delta, "inline-flex items-center gap-1 text-sm font-medium tabular-nums " \
+                        "[&_svg]:size-3.5 [&_svg]:shrink-0"
+        # Theme-owned: the AA-safe success text needs a derived-lightness
+        # treatment, and an arbitrary oklch utility in the DICTIONARY
+        # would trip the no_raw_colors gate on every consumer page - the
+        # design lives in the theme files under this one name.
+        element :delta_positive, "cn-stat-delta-positive"
+        element :delta_negative, "text-destructive"
+        element :delta_neutral, "text-muted-foreground"
+        element :description, "text-sm text-muted-foreground"
+        element :media, "pt-1"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+<%# Fragment - button + input(s) as SIBLINGS, no wrapper (the peer
+    contract; Checkbox-identical). The thumb slide is pure CSS off the
+    checked pair; the controller reflects it on every part. %>
+<%= content_tag(:button, **root_attributes.to_attributes) do %>
+  <span data-slot="switch-thumb" <% if checked %>data-checked=""<% else %>data-unchecked=""<% end %> aria-hidden="true" class="<%= css(:thumb) %>"></span>
+<% end %>
+<% if form_participant? %>
+  <%# Rails parity hidden FIRST (unchecked_value submits when off). %>
+  <% if unchecked_value %>
+    <%= tag.input(type: "hidden", name: name, value: unchecked_value, disabled: disabled) %>
+  <% end %>
+  <%= tag.input(type: "checkbox", id: input_id, name: name, value: value, checked: checked,
+                disabled: disabled, "data-slot": "switch-input", "aria-hidden": true,
+                tabindex: "-1", class: css(:input)) %>
+<% end %>

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Instant-effect on/off controls.
+    module Switch
+      # An on/off control whose effect applies immediately - flip it and
+      # the change happens now, where a Checkbox stages a value for a
+      # later submit. Renders a button[role=switch] backed by a hidden
+      # native input: give it name: and it participates in form
+      # submission and fires a real change event on toggle, so a settings
+      # form can auto-submit (e.g. Turbo's
+      # data-action: "change->form#requestSubmit").
+      #
+      # A switch is strictly binary - :indeterminate raises ArgumentError.
+      # Give every switch an accessible name via label: or a paired
+      # Label/Field.
+      #
+      # @example A named setting switch
+      #   render Poetry::Ui::Switch::Component.new(name: "notifications", checked: true,
+      #                                            label: "Email notifications")
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the size axis.
+        SIZES = %i[default sm].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_switch - never a styled checkbox pretending to be a switch (role=switch announces " \
+          "on/off; that's the point).",
+          "Switch = instant effect; Checkbox = staged for submit. If nothing happens until a Save " \
+          "button, use Checkbox.",
+          "Every switch needs an accessible name (Label/Field for= or label:).",
+          "Switches are BINARY - no indeterminate, ever (ArgumentError). A third state means a " \
+          "different component.",
+          "The instant-effect recipe pairs the flip with server persistence (Turbo auto-submit) - " \
+          "never flip UI-only for a setting the user believes is saved.",
+          "NEVER write the checked attributes (data-checked/data-unchecked) without aria-checked and " \
+          "the input sync (the controller writes all three)."
+        ].freeze
+
+        # Click toggles the hidden input first (firing a real change
+        # event), then reflects the new state onto the control.
+        use_stimulus do
+          on :root do
+            controller :checked do
+              register
+              value :input_id, if: :form_participant?
+              action :toggle, on: :click
+            end
+          end
+        end
+
+        style :size, default: :default, required: true, variants: SIZES,
+                     doc: "The control's size axis; the thumb scales to match."
+
+        option :checked, :boolean, default: false, doc: "The server-rendered on/off state."
+        option :name, :string, doc: "Names the hidden input, making the switch a form participant."
+        option :value, :string, default: "1", doc: "Submitted when the switch is on. Ignored without name:."
+        option :unchecked_value, :string, default: "0",
+                                          doc: "Submitted when the switch is off, so the field always posts. Ignored " \
+                                               "without name:."
+        option :disabled, :boolean, default: false,
+                                    doc: "Disables the control and its hidden input - a disabled switch neither " \
+                                         "toggles nor submits."
+        option :required, :boolean, default: false,
+                                    doc: "Marks the switch required via aria-required (never the native attribute)."
+        option :label, :string, doc: "The accessible name, rendered as aria-label - not visible text."
+
+        part "switch", "The visual button[role=switch] - reflects the hidden input via " \
+                       "aria-checked plus the checked pair (never indeterminate)",
+             states: {
+               "data-checked" => "on (the shared checked controller reflects every toggle " \
+                                 "here, aria-checked in step)",
+               "data-unchecked" => "off (the server-rendered default)",
+               "data-size" => { condition: "always - the resolved size (the thumb reads it " \
+                                           "via group/switch selectors)",
+                                values: SIZES.map(&:to_s) }
+             }
+        part "switch-thumb", "The sliding knob - travel is pure CSS off the checked pair",
+             states: {
+               "data-checked" => "mirrors the control (the controller reflects state on " \
+                                 "every part wearing the pair)",
+               "data-unchecked" => "mirrors the control - the thumb sits at the start"
+             }
+
+        # @api private
+        def initialize(attributes = {})
+          # A switch is strictly binary: aria-checked on role=switch must
+          # never be "mixed" - the violation is unrepresentable. Guarded
+          # BEFORE the boolean cast would silently truthy it away.
+          if attributes.values_at(:checked, "checked").any? { |value| value.to_s == "indeterminate" }
+            raise ArgumentError, "Switch is strictly binary - no :indeterminate (use Checkbox for tri-state)"
+          end
+
+          super
+        end
+
+        # @api private
+        def state
+          checked ? "checked" : "unchecked"
+        end
+
+        # @api private
+        def control_id
+          @control_id ||= poetry_instance_id("poetry-switch")
+        end
+
+        # @api private
+        def input_id
+          "#{control_id}-input"
+        end
+
+        # @api private
+        def form_participant?
+          name.present?
+        end
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "type" => "button", "role" => "switch", "id" => control_id,
+            "aria-checked" => checked.to_s, "data-#{state}" => "",
+            "data-slot" => "switch", "data-size" => size, "disabled" => disabled
+          }
+          attrs["aria-required"] = true if required
+          attrs["aria-label"] = label if label.present?
+          html_attributes.merge_if_not_set(
+            attrs.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        private :state, :control_id, :input_id, :form_participant?, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Switch
+      # The Switch preview matrix: both sizes x both states x disabled,
+      # the Field-bound recipe, and the RTL thumb-travel fix (the poetry
+      # addition over the source's LTR-only translate).
+      class Preview < Poetry::Core::Preview::Base
+        # @!group States
+
+        def default
+          render_component(name: "airplane_mode", label: "Airplane mode")
+        end
+
+        def checked
+          render_component(name: "airplane_mode", checked: true, label: "Airplane mode")
+        end
+
+        def disabled
+          render_component(name: "airplane_mode", disabled: true, label: "Airplane mode")
+        end
+
+        def disabled_checked
+          render_component(name: "airplane_mode", checked: true, disabled: true, label: "Locked on")
+        end
+
+        # @!endgroup
+
+        # @!group Sizes
+
+        # size: :sm for dense settings lists - the thumb derives its size
+        # via group-data-[size=sm]/switch (no per-element size classes).
+        def small
+          render_component(name: "compact", size: :sm, checked: true, label: "Compact density")
+        end
+
+        # @!endgroup
+
+        # @!group Recipes
+
+        # Field-bound: control_attributes land on the BUTTON (the label-for
+        # target).
+        def in_a_field
+          field = Field::Component.new(
+            id: "preview-notifications", label_text: "Notifications",
+            hint: "Applied the moment it flips."
+          )
+          render_component(field) do
+            embed(Component.new(name: "notifications", checked: true,
+                                **field.control_attributes.transform_keys(&:to_sym)))
+          end
+        end
+
+        # The RTL travel fix: the knob still moves toward the "on" end
+        # (rtl:data-checked:-translate-x-... - a poetry addition;
+        # the source's translate is physical/LTR-only).
+        def rtl
+          render_component(name: "rtl_demo", checked: true, label: "وضع الطيران", dir: "rtl")
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Switch
+      # Re-expressed through the cn-* theme layer. The thumb's travel
+      # (data-checked translate + the rtl: fix) lives in the theme rule.
+      # The size axis still travels by data attribute; :input stays the
+      # sr-only form store.
+      class Style < Poetry::Core::Style
+        base "cn-switch peer group/switch inline-flex items-center transition-all outline-none " \
+             "disabled:cursor-not-allowed disabled:opacity-50 after:-inset-x-3 after:-inset-y-2 " \
+             "after:absolute relative"
+
+        element :thumb, "cn-switch-thumb pointer-events-none block ring-0 transition-transform"
+
+        # The form participant + the store (the Checkbox architecture).
+        element :input, "sr-only"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+<%= content_tag(:div, **container_attributes) do %>
+  <%= content_tag(:table, content, **root_attributes.to_attributes) %>
+<% end %>