poetry-ui 0.0.2

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Dated event sequences as ordered lists.
+    module Timeline
+      # A sequence of dated events rendered as a real ordered list
+      # (<ol>/<li>) - activity feeds, order status, deploy history. Each
+      # item carries a decorative indicator (a dot, or icon:'s glyph) on
+      # a connector rail; completed: marks progress and recolors the
+      # item's indicator and rail segment. orientation: :horizontal lays
+      # the steps left-to-right (an order tracker); the vertical default
+      # reads as a feed.
+      #
+      # A Timeline records history - for steps the user advances through,
+      # use Stepper. Styling is utility-only: the data-slot names are the
+      # restyle seam.
+      #
+      # @example
+      #   render Poetry::Ui::Timeline::Component.new do |timeline|
+      #     timeline.with_item(title: "Order placed", time: "Mar 15", completed: true)
+      #     timeline.with_item(title: "In transit") { "Estimated delivery Thursday." }
+      #   end
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "A sequence of dated events (activity feed, order status, deploy history) is a " \
+          "Timeline - never a hand-rolled stack of dots and left borders (this is the <ol> " \
+          "the sequence owes its readers).",
+          "Each with_item takes title:, optional time: (renders a <time>), optional icon: " \
+          "(swaps the dot for a glyph), completed: for progress - the description is the block.",
+          "completed: colors the item's indicator and its rail segment - mark every step up to " \
+          "the current one, not just the latest.",
+          "orientation: :horizontal lays the steps left-to-right (an order tracker); the " \
+          "vertical default reads as a feed. For steps the USER advances through, use " \
+          "Stepper - a Timeline records, it never navigates."
+        ].freeze
+
+        # The same fact the before_render raise enforces, stated
+        # statically: poetry check flags the omission without rendering.
+        REQUIRED_SLOTS = { item: "at least one item (title:, with the description as its block)" }.freeze
+
+        renders_many :items,
+                     doc: "Declares one event: title:, optional time: (renders a <time>), optional icon: (replaces " \
+                          "the dot), completed: for progress - the description is the block.",
+                     renders: lambda { |title:, time: nil, icon: nil, completed: false,
+                                       **options, &block|
+                       # class: merges through the dictionary (caller classes win on
+                       # conflicts) - a plain hash merge would REPLACE css(:item).
+                       attrs = { "data-slot" => "timeline-item", class: css(:item, class: options.delete(:class)) }
+                       attrs["data-completed"] = "" if completed
+                       content_tag(:li, attrs.merge(options)) do
+                         body = [item_indicator(icon), item_separator, item_header(title, time)]
+                         if block
+                           body << content_tag(:div, { "data-slot" => "timeline-content",
+                                                       class: css(:content) }, &block)
+                         end
+                         safe_join(body)
+                       end
+                     }
+
+        style :orientation, default: :vertical, variants: %i[vertical horizontal],
+                            doc: "The layout axis: :vertical reads as a feed, :horizontal as a step tracker."
+
+        part "timeline", "The <ol> root - the event sequence",
+             states: {
+               "data-orientation" => { condition: "always - the layout axis",
+                                       values: %w[vertical horizontal] }
+             }
+        part "timeline-item", "One event (<li>): indicator + rail segment + header + description",
+             states: {
+               "data-completed" => "the step is done - recolors its indicator and rail segment"
+             }
+        part "timeline-indicator", "The decorative marker on the rail - a dot, or icon:'s glyph " \
+                                   "(aria-hidden; the sequence lives in the list semantics)"
+        part "timeline-separator", "The decorative rail segment toward the next item - hidden " \
+                                   "on the last"
+        part "timeline-header", "The title/time row"
+        part "timeline-title", "The event's name"
+        part "timeline-time", "The event's <time> - muted, small"
+        part "timeline-content", "Muted description under the header (the item's block)"
+
+        # @api private
+        def before_render
+          raise ArgumentError, "Timeline requires at least one with_item" unless items?
+        end
+
+        # @api private
+        def call
+          content_tag(:ol, safe_join(items.map(&:to_s)), **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "timeline", "data-orientation" => orientation }
+              .merge(component_data_attributes)
+          )
+        end
+
+        private
+
+        # Decorative twins (the Tree toggle-spacer rule): indicator and
+        # rail carry no semantics - the sequence is the <ol>, progress is
+        # data-completed.
+        def item_indicator(icon)
+          content_tag(:div, "data-slot" => "timeline-indicator", "aria-hidden" => "true",
+                            "class" => css(:indicator)) do
+            if icon
+              render(Icon::Component.new(name: icon, class: css(:indicator_icon)))
+            else
+              content_tag(:span, nil, class: css(:indicator_dot))
+            end
+          end
+        end
+
+        def item_separator
+          content_tag(:div, nil, "data-slot" => "timeline-separator", "aria-hidden" => "true",
+                                 "class" => css(:separator))
+        end
+
+        def item_header(title, time)
+          content_tag(:div, "data-slot" => "timeline-header", class: css(:header)) do
+            parts = [content_tag(:div, title, "data-slot" => "timeline-title", class: css(:title))]
+            parts << content_tag(:time, time, "data-slot" => "timeline-time", class: css(:time)) if time
+            safe_join(parts)
+          end
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Timeline
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |timeline|
+            timeline.with_item(title: "Order placed", time: "Mar 15, 09:12", completed: true) do
+              "Payment authorized and inventory reserved."
+            end
+            timeline.with_item(title: "Packed", time: "Mar 15, 14:03", completed: true) do
+              "Two parcels sealed at dock B."
+            end
+            timeline.with_item(title: "In transit", time: "Mar 16") do
+              "Handed to the carrier - estimated delivery Thursday."
+            end
+            timeline.with_item(title: "Delivered")
+          end
+        end
+
+        # The order tracker: steps left-to-right, progress recoloring the
+        # rail up to the current step.
+        def horizontal
+          render_component(orientation: :horizontal) do |timeline|
+            timeline.with_item(title: "Ordered", time: "Mar 15", completed: true)
+            timeline.with_item(title: "Packed", time: "Mar 15", completed: true)
+            timeline.with_item(title: "Shipped", time: "Mar 16")
+            timeline.with_item(title: "Delivered")
+          end
+        end
+
+        # icon: swaps the dot for a glyph - the indicator stays decorative.
+        def with_icons
+          render_component do |timeline|
+            timeline.with_item(title: "Repository created", time: "Jun 2",
+                               icon: :"git-branch", completed: true) do
+              "poetry-ui scaffolded from the gem template."
+            end
+            timeline.with_item(title: "First deploy", time: "Jun 4",
+                               icon: :rocket, completed: true) do
+              "Shipped to staging behind the feature flag."
+            end
+            timeline.with_item(title: "Incident opened", time: "Jun 9", icon: :"triangle-alert") do
+              "Elevated 5xx rate on checkout - rolled back in 12 minutes."
+            end
+          end
+        end
+
+        # Titles alone: the anatomy holds without times or descriptions.
+        def titles_only
+          render_component do |timeline|
+            timeline.with_item(title: "Draft", completed: true)
+            timeline.with_item(title: "In review")
+            timeline.with_item(title: "Published")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Timeline
+      # Utility-only (the Separator/Spinner rule): no upstream cn hook
+      # exists for a Timeline, so the surface is structural utilities on
+      # semantic tokens - data-slot selectors are the restyle seam. Both
+      # orientations live in ONE dictionary via the named-group pattern:
+      # the root carries group/timeline + data-orientation, each item
+      # group/timeline-item + data-completed, and every element restyles
+      # itself off those two markers - so one attribute flip re-lays the
+      # whole sequence.
+      class Style < Poetry::Core::Style
+        base "group/timeline flex"
+
+        variant :orientation, {
+          vertical: "flex-col",
+          horizontal: "w-full flex-row"
+        }
+
+        element :item, "group/timeline-item relative flex flex-1 flex-col gap-0.5 " \
+                       "group-data-[orientation=vertical]/timeline:ps-9 " \
+                       "group-data-[orientation=vertical]/timeline:not-last:pb-7 " \
+                       "group-data-[orientation=horizontal]/timeline:pt-9 " \
+                       "group-data-[orientation=horizontal]/timeline:not-last:pe-8"
+        element :indicator, "absolute top-0 left-0 flex size-6 items-center justify-center " \
+                            "rounded-full border border-border bg-background " \
+                            "text-muted-foreground " \
+                            "group-data-[completed]/timeline-item:border-primary " \
+                            "group-data-[completed]/timeline-item:text-primary"
+        element :indicator_dot, "size-1.5 rounded-full bg-current"
+        element :indicator_icon, "size-3.5"
+        element :separator, "absolute bg-border group-last/timeline-item:hidden " \
+                            "group-data-[completed]/timeline-item:bg-primary " \
+                            "group-data-[orientation=vertical]/timeline:top-7 " \
+                            "group-data-[orientation=vertical]/timeline:left-3 " \
+                            "group-data-[orientation=vertical]/timeline:h-[calc(100%-2rem)] " \
+                            "group-data-[orientation=vertical]/timeline:w-px " \
+                            "group-data-[orientation=vertical]/timeline:-translate-x-1/2 " \
+                            "group-data-[orientation=horizontal]/timeline:top-3 " \
+                            "group-data-[orientation=horizontal]/timeline:left-7 " \
+                            "group-data-[orientation=horizontal]/timeline:h-px " \
+                            "group-data-[orientation=horizontal]/timeline:w-[calc(100%-2rem)] " \
+                            "group-data-[orientation=horizontal]/timeline:-translate-y-1/2"
+        element :header, "flex flex-wrap items-baseline gap-x-2 gap-y-0.5 " \
+                         "group-data-[orientation=vertical]/timeline:min-h-6"
+        element :title, "text-sm font-medium"
+        element :time, "text-xs font-medium text-muted-foreground"
+        element :content, "text-sm text-muted-foreground"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+<%= content_tag(:li, **root_attributes.to_attributes) do %>
+  <% if variant_icon %>
+    <span data-slot="toast-icon" aria-hidden="true" class="<%= css(:icon) %>">
+      <%= render Poetry::Ui::Icon::Component.new(name: variant_icon,
+                                                 class: ("animate-spin" if variant == :loading)) %>
+    </span>
+  <% end %>
+  <div class="<%= css(:body) %>">
+    <div data-slot="toast-title" class="<%= css(:title) %>"><%= title %></div>
+    <% if description? %>
+      <div data-slot="toast-description" class="<%= css(:description) %>"><%= description %></div>
+    <% end %>
+    <%= content %>
+  </div>
+  <% if action? %><span class="<%= css(:action) %>"><%= action %></span><% end %>
+  <% if show_close_button %>
+    <%= render Poetry::Ui::Button::Component.new(variant: :ghost, size: :"icon-sm",
+                                                 label: t("poetry.toast.close"),
+                                                 class: css(:close),
+                                                 **close_button_attributes) do %>
+      <%= render Poetry::Ui::Icon::Component.new(name: :x) %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Transient notifications.
+    module Toast
+      # The closed vocabulary for the variant axis.
+      VARIANTS = %i[default success info warning destructive loading].freeze
+      # The closed vocabulary for announcement politeness.
+      POLITENESS = %i[polite assertive].freeze
+
+      # One notification, rendered inside a Toaster region. The item
+      # itself is role=status with aria-live off: it never announces
+      # itself - on arrival the controller speaks it exactly once through
+      # a shared live region at the variant's politeness (:destructive
+      # announces assertively), so duplicating the announcement by hand
+      # is a regression.
+      #
+      # The auto-dismiss timer pauses on hover, focus-within, window
+      # blur, and hidden tabs; duration <= 0 means persistent - and an
+      # action-bearing toast defaults to persistent (a missable undo is a
+      # bug). Toasts never steal focus on show; the toaster's hotkey
+      # (F8 by default) reaches them.
+      #
+      # @example An undo toast (persistent because it carries an action)
+      #   render Poetry::Ui::Toast::Component.new(variant: :success) do |toast|
+      #     toast.with_title { "Message archived" }
+      #     toast.with_action { "Undo" }
+      #   end
+      class Component < Poetry::Core::Component
+        # The icon each variant renders (:default ships none; :loading spins).
+        VARIANT_ICONS = {
+          success: :"circle-check", info: :info, warning: :"triangle-alert",
+          destructive: :"octagon-x", loading: :"loader-circle"
+        }.freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Server-side toasts go through turbo_stream.poetry_toast / the flash recipe - never " \
+          "hand-append into #poetry-toaster.",
+          "Undo/consequence toasts MUST carry an action slot - action-bearing toasts default to " \
+          "persistent (duration nil); give an explicit duration only when missing the action is safe.",
+          "variant: :destructive is for failures the user must hear about (it announces ASSERTIVELY); " \
+          "do not use it for styling.",
+          "Never put required interactions in a toast (toasts are missable) - that is AlertDialog.",
+          "Toasts are supplementary: never the only place an outcome is recorded."
+        ].freeze
+
+        # The same facts the before_render raise enforces, stated statically:
+        # poetry check flags the omission without rendering.
+        REQUIRED_SLOTS = { title: "the message" }.freeze
+
+        # The component behind the forwarding slot: with_action renders a Button.
+        SLOT_RENDERS = { action: Button::Component }.freeze
+
+        renders_one :title, doc: "The message (REQUIRED - the announced payload's first line)."
+
+        renders_one :description, doc: "Supporting copy under the title."
+
+        renders_one :action,
+                    doc: "Typed Button slot (undo / view / retry): clicking it dismisses the toast with reason " \
+                         "\"action\". Its presence makes the toast persistent by default.",
+                    renders: lambda { |**options, &block|
+                      wiring = { "data-slot" => "toast-action" }.merge(stimulus_attributes_for(:action))
+                      # Caller attribute keys merge WITH the wiring (stimulus concat)
+                      # instead of replacing it at the kwargs splat; component options
+                      # (variant: etc.) stay plain kwargs.
+                      attr_keys = options.keys.select { |k| k == :data || k.to_s.start_with?("data-", "aria-") }
+                      caller_attrs = attr_keys.to_h { |k| [k, options.delete(k)] }
+                      merged = Poetry::Core::HTML::Attributes.merged(wiring, caller_attrs)
+                      Button::Component.new(variant: :outline, size: :sm, **merged.symbolize_keys, **options, &block)
+                    }
+
+        # APG timing wiring: hover and focus-within hold the timer (the
+        # window-blur / tab-hidden holds are wired by the controller).
+        use_stimulus do
+          on :root do
+            controller :toast do
+              register
+              value :duration, from: :effective_duration
+              value :politeness
+              action :pause, on: %i[mouseenter focusin]
+              action :resume, on: %i[mouseleave focusout]
+            end
+          end
+          on :action do
+            controller :toast do
+              target :action
+              action :dismiss, on: :click
+            end
+          end
+          on :close do
+            controller :toast do
+              target :close
+              action :dismiss, on: :click
+            end
+          end
+        end
+
+        style :variant, default: :default, required: true, variants: VARIANTS,
+                        doc: "The intent axis: it picks the icon, and :destructive announces assertively while " \
+                             ":loading defaults to persistent."
+
+        option :duration, :integer,
+               doc: "nil = derived: 5000ms, or PERSISTENT when an action slot is present (the missable-undo guard). " \
+                    "<= 0 = persistent."
+        option :politeness, :symbol, default: -> { variant == :destructive ? :assertive : :polite },
+                                     doc: "Derived from the variant: destructive announces assertively."
+        option :show_close_button, :boolean, default: true,
+                                             doc: "The corner dismiss button - named as the dialog family names it."
+
+        validates :politeness, inclusion: { in: POLITENESS }
+
+        part "toast", "The notification item itself (<li>, role=status) - variant, open state, " \
+                      "and the toaster's stack facts all ride here",
+             states: {
+               "data-open" => "toast is showing (the server-rendered state; the dismiss exit " \
+                              "flips the pair before removal)",
+               "data-closed" => "toast is animating out",
+               "data-variant" => { condition: "always - the resolved variant",
+                                   values: VARIANTS.map(&:to_s) },
+               "data-queued" => "the toaster holds it hidden past the visible limit " \
+                                "(timer paused until a slot frees up)"
+             },
+             vars: {
+               "--poetry-toast-index" => "stack position written by the toaster's reflow " \
+                                         "(newest visible toast = 0)"
+             }
+        part "toast-icon", "The variant's icon well (aria-hidden; the default variant " \
+                           "renders none)"
+        part "toast-title", "The message - the announced payload's first line (required slot)"
+        part "toast-description", "Supporting copy under the title"
+
+        # @api private
+        def before_render
+          raise ArgumentError, "Toast requires with_title (the message)" unless title?
+        end
+
+        # @api private
+        def effective_duration
+          return duration unless duration.nil?
+
+          # Action-bearing toasts are persistent (a missable undo is a
+          # bug); so are loading toasts - the promise recipe REPLACES
+          # them (turbo_stream.replace on the toast id) when the job
+          # settles, and an auto-dismissed loading state is a lie.
+          action? || variant == :loading ? 0 : 5000
+        end
+
+        # @api private
+        def variant_icon
+          VARIANT_ICONS[variant]
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "toast", "data-variant" => variant, "data-open" => "",
+              # aria-live=off ON PURPOSE: the announce singleton does the
+              # talking, exactly once (an item that is itself a live
+              # region would announce a second time).
+              "role" => "status", "aria-live" => "off", "aria-atomic" => "true",
+              "tabindex" => "0"
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def close_button_attributes
+          stimulus_attributes_for(:close).merge("data-slot" => "toast-close")
+        end
+
+        private :effective_duration, :variant_icon, :root_attributes, :close_button_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toast
+      # The Toast preview matrix: every variant (each with its icon +
+      # politeness derivation), the description pairing, the
+      # action-bearing (persistent) undo shape, and a persistent error.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          toast_example(:default, "Event scheduled", "Friday, July 10 at 5:00 PM")
+        end
+
+        def success
+          toast_example(:success, "Changes saved", "Your profile has been updated.")
+        end
+
+        def info
+          toast_example(:info, "Heads up", "A new version is available.")
+        end
+
+        def warning
+          toast_example(:warning, "Storage almost full", "You have used 90% of your quota.")
+        end
+
+        # Destructive announces ASSERTIVELY (politeness derives from the
+        # variant) - failures the user must hear about.
+        def destructive
+          toast_example(:destructive, "Payment failed", "Your card was declined.")
+        end
+
+        # An action-bearing toast defaults to PERSISTENT (duration nil ->
+        # 0): a missable undo is a bug.
+        # The promise-lifecycle opener: a spinning persistent toast the
+        # job later REPLACES (turbo_stream.replace on its id) with the
+        # settled success/destructive toast.
+        def loading
+          render_component(variant: :loading) do |toast|
+            toast.with_title { "Creating event…" }
+          end
+        end
+
+        def with_action
+          render_component do |toast|
+            toast.with_title { "Message deleted" }
+            toast.with_action { "Undo" }
+          end
+        end
+
+        # Explicit duration: 0 keeps a plain toast on screen until closed.
+        def persistent
+          render_component(variant: :destructive, duration: 0) do |toast|
+            toast.with_title { "Sync failed" }
+            toast.with_description { "Changes will retry when you're back online." }
+          end
+        end
+
+        private
+
+        def toast_example(variant, title, description)
+          render_component(variant: variant) do |toast|
+            toast.with_title { title }
+            toast.with_description { description }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toast
+      # Re-expressed through the cn-* theme layer - poetry's own visual
+      # (no upstream treatment to mirror). The corner-aware slide chains
+      # ride the theme with the rest of the treatment (they key on the
+      # TOASTER's data-position through group/toaster at runtime); the
+      # default variant stays an empty string (the base IS the default -
+      # nothing to name).
+      class Style < Poetry::Core::Style
+        base "cn-toast pointer-events-auto relative flex w-full items-start outline-hidden"
+
+        variant :variant, {
+          default: "",
+          success: "cn-toast-variant-success",
+          info: "cn-toast-variant-info",
+          warning: "cn-toast-variant-warning",
+          destructive: "cn-toast-variant-destructive"
+        }
+
+        element :icon, "cn-toast-icon flex shrink-0 items-center justify-center " \
+                       "[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none"
+        element :body, "cn-toast-body flex min-w-0 flex-1 flex-col"
+        element :title, "cn-toast-title font-medium text-sm"
+        element :description, "cn-toast-description text-muted-foreground text-sm"
+        element :action, "shrink-0 self-start"
+        element :close, "shrink-0 self-start"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/toast_trigger/addressed_preview.html.erb

@@ -0,0 +1,12 @@
+<div class="p-4">
+  <%= render Poetry::Ui::ToastTrigger::Component.new(template: "addressed-preview-toast",
+                                                     toaster: "preview-region") do %>
+    Show in region
+  <% end %>
+</div>
+<template id="addressed-preview-toast">
+  <%= poetry_toast(duration: 4000) do |toast| %>
+    <% toast.with_title { "Addressed stamp" } %>
+  <% end %>
+</template>
+<%= poetry_toaster(id: "preview-region") %>

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

@@ -0,0 +1,3 @@
+<%= render Poetry::Ui::Button::Component.new(**button_options) do %>
+  <%= content %>
+<% end %>

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Client-side toast delivery.
+    module ToastTrigger
+      # A button that shows a toast without a server round-trip: on press
+      # the toaster stamps a clone of an addressed <template>'s toast
+      # into its region. The template holds one fully rendered
+      # poetry_toast - exactly what a Turbo Stream would append - so the
+      # visible limit, queueing, and stacking behave the same on either
+      # path. For purely client-side moments: copied, undone, queued.
+      #
+      # @example
+      #   <%= render Poetry::Ui::ToastTrigger::Component.new(template: "copied-toast") do %>
+      #     Copy link
+      #   <% end %>
+      #   <template id="copied-toast">
+      #     <%= poetry_toast(duration: 4000) do |toast| %>
+      #       <% toast.with_title { "Copied" } %>
+      #     <% end %>
+      #   </template>
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "template: names a <template> element id holding ONE rendered poetry_toast - " \
+          "the trigger stamps a clone into the toaster on press.",
+          "toaster: scopes the stamp to one region id on multi-toaster pages; omit it for " \
+          "the page's toaster.",
+          "Give the templated toast a duration (auto-dismiss) - repeated presses stack " \
+          "persistent toasts.",
+          "Server round-trips keep using turbo_stream.poetry_toast - this trigger is for " \
+          "purely client-side moments (copied, undone, queued)."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller :"toast-trigger" do
+              register
+              value :template
+              value :toaster, if: -> { toaster.present? }
+              action :fire, on: :click
+            end
+          end
+        end
+
+        option :template, :string, required: true,
+                                   doc: "The id of the <template> element holding the rendered toast to stamp."
+        option :toaster, :string,
+               doc: "Scopes the stamp to one toaster region id on multi-toaster pages; omit for the page's toaster."
+        option :variant, :symbol, default: :outline, doc: "The Button variant the trigger renders at."
+        option :size, :symbol, default: :default, doc: "The Button size the trigger renders at."
+
+        part "toast-trigger", "The stamping button - press clones the template's toast " \
+                              "into the toaster region",
+             states: {
+               "data-variant" => "always - the Button variant the trigger renders at",
+               "data-size" => "always - the Button size the trigger renders at"
+             }
+        # The trigger IS a poetry Button (no wrapper element), so Button's
+        # inner anatomy lands in this component's data-component scope.
+        part "label", "The Button's label span (the trigger renders AS a poetry Button)"
+
+        # @api private
+        def button_options
+          wiring = { data: { slot: "toast-trigger" } }
+                   .merge(stimulus_attributes_for(:root))
+                   .merge(component_data_attributes)
+
+          # Caller attributes never clobber the trigger's wiring: both sides
+          # flow through Attributes, so a host data-controller/action
+          # concatenates instead of silently killing fire-on-click.
+          { variant: variant, size: size }
+            .merge(Poetry::Core::HTML::Attributes.merged(wiring, html_attributes))
+            .symbolize_keys
+        end
+
+        private :button_options
+      end
+    end
+  end
+end