poetry-ui 0.0.2

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A streaming-aware chat transcript scroller.
+    module MessageScroller
+      # A scrollable chat transcript that follows the newest message
+      # while streaming, releases when the reader scrolls up, and offers
+      # a jump-to-latest button. Without JavaScript it is a plain
+      # scrollable region, fully readable.
+      #
+      # The content element is the Turbo Stream append target (stable
+      # dom id "<id>-messages"); rows are poetry_message_scroller_item
+      # wrappers keyed by message id. History prepends keep the reading
+      # position; a row rendered with anchor: true becomes the held
+      # reading line.
+      #
+      # @example A chat transcript
+      #   render Poetry::Ui::MessageScroller::Component.new(id: "chat") do
+      #     # poetry_message_scroller_item rows
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the default_scroll_position axis.
+        SCROLL_POSITIONS = %i[start end last-anchor].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Stream by UPDATING a row's text (morph/replace) - appending nodes per token re-announces the row to AT.",
+          "Rows are poetry_message_scroller_item(id: message.id) - the id is how anchoring and Streams find them.",
+          "Append new turns with a Turbo Stream targeting the content element's dom id.",
+          "History loads PREPEND into the content element - the controller preserves the reading position.",
+          "Never nest a second scroll container inside the viewport."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller :message_scroller do
+              register
+              value :auto_scroll
+              value :default_scroll_position
+              value :preserve_scroll_on_prepend
+              value :track_visibility
+            end
+          end
+          on :viewport do
+            controller(:message_scroller) { target :viewport }
+          end
+          on :content do
+            controller(:message_scroller) { target :content }
+          end
+          on :spacer do
+            controller(:message_scroller) { target :spacer }
+          end
+          # The jump affordance: a bare descriptor (element-default click)
+          # plus the button target, forwarded into Button kwargs.
+          on :jump_button do
+            controller :message_scroller do
+              target :button
+              action :scroll_to_end
+            end
+          end
+        end
+
+        option :id, :string, required: true,
+                             doc: "The transcript's stable identifier - the content element renders dom id " \
+                                  "\"<id>-messages\" for Turbo Streams to target."
+        option :auto_scroll, :boolean, default: true,
+                                       doc: "Follows the newest message while the reader sits at the bottom; " \
+                                            "scrolling up releases the follow."
+        option :default_scroll_position, :symbol, default: :end,
+                                                  doc: "Where the viewport lands on connect: the newest message " \
+                                                       "(:end), the oldest (:start), or the last anchor: true row " \
+                                                       "(:\"last-anchor\")."
+        option :preserve_scroll_on_prepend, :boolean, default: true,
+                                                      doc: "Keeps the reading position stable when history prepends " \
+                                                           "into the content element."
+        option :track_visibility, :boolean, default: false,
+                                            doc: "Opt-in observation of which rows are on screen - emits a " \
+                                                 "visibility event as the visible set changes."
+        option :jump_button, :boolean, default: true,
+                                       doc: "Renders the floating jump-to-latest button (shown once the reader " \
+                                            "leaves the bottom)."
+
+        validates :default_scroll_position, inclusion: { in: SCROLL_POSITIONS }
+
+        part "message-scroller", "The transcript root the controller drives - runtime " \
+                                 "scroll state is mirrored here",
+             states: {
+               "data-mode" => { condition: "always once connected - the 4-state machine",
+                                values: %w[following-bottom free-scrolling
+                                           anchored-to-message settling-jump] },
+               "data-scrollable" => "overflow exists - carries which edges have room " \
+                                    "(start, end, or both as a space-separated pair)",
+               "data-autoscrolling" => "a programmatic scroll is settling - the " \
+                                       "follow-bottom release is suppressed while set"
+             }
+        part "message-scroller-viewport", "The native scroll region (role=region, " \
+                                          "focusable) - the controller mirrors the same " \
+                                          "runtime attributes here",
+             states: {
+               "data-scrollable" => "overflow exists - the same edge tokens as the root",
+               "data-autoscrolling" => "a programmatic scroll is settling"
+             }
+        part "message-scroller-content", "The row container and Turbo Stream append target " \
+                                         "(stable dom id <id>-messages); role=log announces " \
+                                         "additions"
+        part "message-scroller-item", "One transcript row (poetry_message_scroller_item) - " \
+                                      "the id is how anchoring and Streams find it",
+             states: {
+               "data-message-id" => "always - the row's message id",
+               "data-scroll-anchor" => "anchor: true - the turn the controller holds at " \
+                                       "the reading line"
+             }
+        part "message-scroller-spacer", "Tail spacer faking scroll room below a short " \
+                                        "anchored turn - hidden at height 0"
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "message-scroller" }
+              .merge(stimulus_attributes_for(:root))
+              .merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def viewport_attributes
+          {
+            "class" => css(:viewport), "data-slot" => "message-scroller-viewport",
+            "role" => "region", "tabindex" => "0",
+            "aria-label" => t("poetry.message_scroller.region")
+          }.merge(stimulus_attributes_for(:viewport))
+        end
+
+        # @api private
+        def content_attributes
+          {
+            "id" => "#{id}-messages", "class" => css(:content),
+            "data-slot" => "message-scroller-content",
+            "role" => "log", "aria-relevant" => "additions"
+          }.merge(stimulus_attributes_for(:content))
+        end
+
+        # @api private
+        def spacer_attributes
+          { "data-slot" => "message-scroller-spacer", "aria-hidden" => "true", "hidden" => true }
+            .merge(stimulus_attributes_for(:spacer))
+        end
+
+        # @api private
+        def button_attributes
+          {
+            class: css(:button),
+            data: { slot: "message-scroller-button", direction: "end", active: "false" },
+            tabindex: "-1"
+          }.merge(stimulus_attributes_for(:jump_button))
+        end
+
+        private :root_attributes, :viewport_attributes, :content_attributes, :spacer_attributes, :button_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module MessageScroller
+      # The MessageScroller preview - a bounded transcript frame (the
+      # geometry behaviors need the browser loop; previews cover markup).
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(id: "demo", class: "h-80 rounded-lg border") do
+            safe_join(Array.new(12) { |i| item("m#{i}") { row(i) } })
+          end
+        end
+
+        def without_jump_button
+          render_component(id: "plain", jump_button: false, class: "h-60 rounded-lg border") do
+            item("only") { row(0) }
+          end
+        end
+
+        private
+
+        def item(id, &)
+          tag.div(class: Style.css(:item), data: { slot: "message-scroller-item", "message-id": id }, &)
+        end
+
+        def row(index)
+          tag.div("Message #{index + 1}", class: "rounded-xl bg-muted px-3 py-2 w-fit")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module MessageScroller
+      # Re-expressed through the cn-* theme layer - minimally: the
+      # 4-state scroll machine's whole surface is machinery (viewport
+      # containment/scrollbar choreography, row content-visibility, the
+      # jump button's show/hide translate dance - upstream keeps every one
+      # of those inline too). Only the row rhythm is design: gap-8 rides
+      # .cn-message-scroller-content.
+      class Style < Poetry::Core::Style
+        # Source also stamps a group/message-scroller named-group marker;
+        # dropped until a dictionary consumer references it - an unconsumed
+        # named group never reaches the compiled CSS, and the verify gate
+        # (rightly) rejects classes no build can produce.
+        base "relative flex size-full min-h-0 flex-col overflow-hidden group/message-scroller"
+
+        element :viewport, "size-full min-h-0 min-w-0 scroll-fade-b scrollbar-thin scrollbar-gutter-stable " \
+                           "overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-none"
+
+        element :content, "cn-message-scroller-content flex h-max min-h-full flex-col"
+
+        element :item, "min-w-0 shrink-0 [contain-intrinsic-size:auto_10rem] [content-visibility:auto]"
+
+        element :button, "absolute inset-s-1/2 -translate-x-1/2 border-border bg-background text-foreground " \
+                         "transition-[translate,scale,opacity] duration-200 hover:bg-muted hover:text-foreground " \
+                         "data-[active=false]:pointer-events-none data-[active=false]:scale-95 " \
+                         "data-[active=false]:opacity-0 data-[active=false]:duration-400 " \
+                         "data-[active=false]:ease-[cubic-bezier(0.7,0,0.84,0)] " \
+                         "data-[active=true]:translate-y-0 data-[active=true]:scale-100 " \
+                         "data-[active=true]:opacity-100 data-[active=true]:ease-[cubic-bezier(0.23,1,0.32,1)] " \
+                         "data-[direction=end]:bottom-4 data-[direction=end]:data-[active=false]:translate-y-full " \
+                         "data-[direction=start]:top-4 data-[direction=start]:data-[active=false]:-translate-y-full " \
+                         "rtl:translate-x-1/2 data-[direction=start]:[&_svg]:rotate-180"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Labeled facts about one record, as a description list.
+    module MetadataList
+      # Labeled facts about one record - a real description list (<dl>)
+      # for detail pages, in one or more columns, with each label above
+      # its value (vertical) or beside it (horizontal). Values compose
+      # freely: text, a Badge, a Link, a Timestamp.
+      #
+      # @example A record's fact sheet
+      #   render Poetry::Ui::MetadataList::Component.new(columns: :two) do |list|
+      #     list.with_item(label: "Status") { "Active" }
+      #     list.with_item(label: "Owner") { "Ada Lovelace" }
+      #   end
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Record facts on a detail page belong in a MetadataList - never a hand-rolled grid of " \
+          "label/value divs (this is the <dl> the page owes its readers).",
+          "Each with_item takes label: and the value as its block - values compose freely " \
+          "(text, a Badge, a Link, a Timestamp).",
+          "columns: :two / :three spread the facts on wide viewports; orientation: :horizontal " \
+          "puts labels beside values (the classic key/value sheet) - pick one per surface.",
+          "For editable facts pair each value with its edit affordance inside the item block; " \
+          "the list itself stays read-only vocabulary."
+        ].freeze
+
+        # Slots the component cannot render without; static checks read this without rendering.
+        REQUIRED_SLOTS = { item: "at least one item (label: plus the value block)" }.freeze
+
+        renders_many :items,
+                     doc: "The facts. Each takes label: (the fact's name, the <dt>) and the value as its block (the " \
+                          "<dd>).",
+                     renders: lambda { |label:, **options, &block|
+                       # class: merges through the dictionary (caller classes win on
+                       # conflicts) - a plain hash merge would REPLACE css(:item).
+                       item_class = css(:item, class: options.delete(:class))
+                       content_tag(:div, { "data-slot" => "metadata-list-item", class: item_class }.merge(options)) do
+                         safe_join([
+                                     content_tag(:dt, label, "data-slot" => "metadata-list-label", class: css(:label)),
+                                     content_tag(:dd, { "data-slot" => "metadata-list-value", class: css(:value) },
+                                                 &block)
+                                   ])
+                       end
+                     }
+
+        style :orientation, default: :vertical, variants: %i[vertical horizontal],
+                            doc: "Label placement - above the value, or beside it for the classic key/value sheet."
+        style :columns, default: :one, variants: %i[one two three],
+                        doc: "How many columns the facts spread across on wide viewports."
+
+        part "metadata-list", "The <dl> root - the record's fact sheet",
+             states: {
+               "data-orientation" => { condition: "always - label placement",
+                                       values: %w[vertical horizontal] },
+               "data-columns" => { condition: "always - the column count word",
+                                   values: %w[one two three] }
+             }
+        part "metadata-list-item", "One fact group (a <div> holding its <dt>/<dd> pair)"
+        part "metadata-list-label", "The fact's name (<dt>) - muted, small"
+        part "metadata-list-value", "The fact's value (<dd>) - composes text, badges, links"
+
+        # Enforces the required item slot.
+        # @api private
+        def before_render
+          raise ArgumentError, "MetadataList requires at least one with_item" unless items?
+        end
+
+        # @api private
+        def call
+          content_tag(:dl, safe_join(items.map(&:to_s)), **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "metadata-list", "data-orientation" => orientation,
+              "data-columns" => columns }.merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module MetadataList
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |list|
+            list.with_item(label: "Status") { "Active" }
+            list.with_item(label: "Owner") { "Ada Lovelace" }
+            list.with_item(label: "Created") { "June 12, 2026" }
+          end
+        end
+
+        def two_columns
+          render_component(columns: :two) do |list|
+            list.with_item(label: "Invoice") { "INV-0042" }
+            list.with_item(label: "Amount") { "$1,250.00" }
+            list.with_item(label: "Due") { "July 31, 2026" }
+            list.with_item(label: "Method") { "ACH transfer" }
+          end
+        end
+
+        def horizontal
+          render_component(orientation: :horizontal) do |list|
+            list.with_item(label: "Environment") { "production" }
+            list.with_item(label: "Region") { "us-east-1" }
+            list.with_item(label: "Version") { "2.14.0" }
+          end
+        end
+
+        def three_columns
+          render_component(columns: :three) do |list|
+            list.with_item(label: "CPU") { "42%" }
+            list.with_item(label: "Memory") { "3.1 GB" }
+            list.with_item(label: "Disk") { "58%" }
+            list.with_item(label: "Region") { "us-east-1" }
+            list.with_item(label: "Uptime") { "14 days" }
+            list.with_item(label: "Status") { "Healthy" }
+          end
+        end
+
+        # Values compose: a status Badge inside the <dd>.
+        def composed_values
+          render_component(columns: :two) do |list|
+            list.with_item(label: "Status") do
+              embed(Poetry::Ui::Badge::Component.new(variant: :success).with_content("Fulfilled"))
+            end
+            list.with_item(label: "Tracking") { "1Z 999 AA1 01" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module MetadataList
+      # Utility-only (the Separator/Spinner rule): no upstream cn hook
+      # exists for a description list, so the surface is structural
+      # utilities on semantic tokens; data-slot selectors are the restyle
+      # seam. The horizontal orientation restyles the ITEMS from the root
+      # (a root descendant utility outranks the item's own class), so one
+      # attribute flip re-lays the whole sheet.
+      class Style < Poetry::Core::Style
+        base "grid gap-x-8 gap-y-4"
+
+        variant :columns, {
+          one: "grid-cols-1",
+          two: "grid-cols-1 sm:grid-cols-2",
+          three: "grid-cols-1 sm:grid-cols-3"
+        }
+
+        variant :orientation, {
+          vertical: "",
+          horizontal: "[&_[data-slot=metadata-list-item]]:grid " \
+                      "[&_[data-slot=metadata-list-item]]:grid-cols-[minmax(0,8rem)_1fr] " \
+                      "[&_[data-slot=metadata-list-item]]:items-baseline " \
+                      "[&_[data-slot=metadata-list-item]]:gap-x-4"
+        }
+
+        element :item, "flex min-w-0 flex-col gap-1"
+        element :label, "text-sm text-muted-foreground"
+        element :value, "min-w-0 text-sm font-medium break-words"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A quantity within a known range.
+    module Meter
+      # A QUANTITY within a known range - battery, disk usage, seats
+      # taken, password strength - never the progress of an operation
+      # over time (that is Progress; a meter has no indeterminate
+      # state). Renders role=meter with a visible caption (label:), a
+      # readout, and a filled track; visually it shares Progress's
+      # chrome, so themes style both together.
+      #
+      # @example
+      #   render Poetry::Ui::Meter::Component.new(value: 62, label: "Storage used")
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "A quantity within a range is a Meter (disk, seats, strength); an operation's " \
+          "completion over time is Progress. There is NO indeterminate meter - unknown " \
+          "duration means Spinner.",
+          "label: is REQUIRED - the meter's accessible name and visible caption.",
+          "value_text: replaces the visible readout verbatim (\"3 of 4 seats\"); without it " \
+          "the readout shows the percentage of the RANGE. No aria-valuetext - ARIA 1.2 " \
+          "deprecated it on role=meter; aria-valuenow carries the value."
+        ].freeze
+
+        option :value, :integer, required: true, doc: "The measured quantity, clamped into min:..max:."
+        option :min, :integer, default: 0, doc: "The range's lower bound."
+        option :max, :integer, default: 100, doc: "The range's upper bound - must exceed min:."
+        option :label, :string, required: true, doc: "The meter's accessible name and visible caption."
+        option :value_text, :string,
+               doc: "Verbatim human-readable value (\"3 of 4 seats\") replacing the percentage readout. Visible " \
+                    "readout only - ARIA 1.2 deprecated aria-valuetext on role=meter, so aria-valuenow carries the " \
+                    "value."
+        option :show_value, :boolean, default: true, doc: "Set false to hide the visible readout."
+
+        part "meter", "Root (role=meter, aria-value*, and the accessible name); label, " \
+                      "readout, and track stack here"
+        part "meter-label", "The visible caption span (label:)"
+        part "meter-value", "The readout - value_text: verbatim, else the range percentage; " \
+                            "renders unless show_value: false"
+        part "meter-track", "The full-width rail (Progress's cn chrome)"
+        part "meter-indicator", "The filled bar - inline width percentage of the range"
+
+        # Enforces the required label and a coherent range.
+        # @api private
+        def before_render
+          raise ArgumentError, "Meter requires label: (the meter's accessible name)" if label.blank?
+          raise ArgumentError, "Meter max: must exceed min:" unless max > min
+        end
+
+        # @api private
+        def call
+          content_tag(:div, root_attributes.to_attributes) do
+            safe_join([label_part, value_part, track].compact)
+          end
+        end
+
+        # The fraction of the RANGE - (value - min)/(max - min), never the
+        # raw value.
+        # @api private
+        def percent
+          ((clamped - min).to_f / (max - min) * 100).clamp(0, 100)
+        end
+
+        # @api private
+        def readout
+          value_text.presence || "#{percent.round}%"
+        end
+
+        # The role is the single token "meter" - a two-token fallback
+        # ("meter progressbar") makes checkers treat the element as generic
+        # and flag every aria-value* attribute.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "meter", "role" => "meter",
+              # No aria-valuetext: ARIA 1.2 deprecated it on role=meter -
+              # the visible readout carries the human string, aria-valuenow
+              # the value.
+              "aria-valuemin" => min, "aria-valuemax" => max, "aria-valuenow" => clamped,
+              "aria-label" => label
+            }.merge(component_data_attributes)
+          )
+        end
+
+        private
+
+        def clamped
+          value.clamp(min, max)
+        end
+
+        def label_part
+          content_tag(:span, label, "data-slot" => "meter-label", class: Progress::Style.css(:label))
+        end
+
+        def value_part
+          return unless show_value
+
+          content_tag(:span, readout, "data-slot" => "meter-value", class: Progress::Style.css(:value))
+        end
+
+        def track
+          content_tag(:div, "data-slot" => "meter-track", class: Progress::Style.css(:track)) do
+            content_tag(:div, nil, "data-slot" => "meter-indicator",
+                                   class: Progress::Style.css(:indicator),
+                                   style: "width: #{percent.round(4)}%")
+          end
+        end
+
+        private :percent, :readout, :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Meter
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(value: 62, label: "Storage used")
+        end
+
+        # value_text: replaces the readout AND aria-valuetext verbatim.
+        def with_value_text
+          render_component(value: 3, max: 4, label: "Seats", value_text: "3 of 4 seats")
+        end
+
+        # A non-zero minimum: the readout is the fraction of the RANGE.
+        def with_range
+          render_component(value: 210, min: 100, max: 300, label: "Battery voltage",
+                           value_text: "210 V")
+        end
+
+        def without_readout
+          render_component(value: 45, label: "Password strength", show_value: false)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Meter
+      # Progress's chrome verbatim (the NumberField composition precedent):
+      # the template calls Progress::Style.css for track/indicator/label/
+      # value, so the themes' cn-progress-* rules dress meters too - zero
+      # new theme CSS, and a theme that restyles progress restyles meters
+      # with it. The root only stacks.
+      class Style < Poetry::Core::Style
+        base "flex flex-wrap gap-3"
+      end
+    end
+  end
+end