poetry-ui 0.0.2

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

@@ -0,0 +1,11 @@
+<div class="p-4">
+  <%= render Poetry::Ui::ToastTrigger::Component.new(template: "trigger-preview-toast") do %>
+    Show toast
+  <% end %>
+</div>
+<template id="trigger-preview-toast">
+  <%= poetry_toast(variant: :success, duration: 4000) do |toast| %>
+    <% toast.with_title { "Stamped into the region" } %>
+  <% end %>
+</template>
+<%= poetry_toaster %>

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module ToastTrigger
+      # The stamp pattern end-to-end: trigger + <template> toast + region.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_with_template(template: "poetry/ui/toast_trigger/default_preview")
+        end
+
+        # toaster: addressing - the stamp scoped to one region id.
+        def addressed
+          render_with_template(template: "poetry/ui/toast_trigger/addressed_preview")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1 @@
+<%= content_tag(:ol, content, **root_attributes.to_attributes) %>

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The toast viewport.
+    module Toaster
+      # The closed vocabulary for the corner axis.
+      POSITIONS = %i[top-left top-center top-right bottom-left bottom-center bottom-right].freeze
+
+      # The toast viewport: a labeled role=region list rendered once in
+      # the layout, and the append target for streamed toasts
+      # (id=poetry-toaster). It is data-turbo-permanent - toasts survive
+      # Drive visits, so flash-after-redirect stays visible. The region
+      # owns the hotkey (F8 by default: focus the most recent toast, with
+      # prior focus restored after dismiss), enforces the visible limit
+      # (overflow queues hidden with timers held), and keeps the stack's
+      # positions as toasts come and go.
+      #
+      # Server code appends toasts with turbo_stream.poetry_toast(title:
+      # "Saved", variant: :success) - from controller responses, form
+      # streams, and broadcasts. To surface Rails flash as toasts, render
+      # the mapping next to the toaster in the layout (see the example).
+      #
+      # @example The flash -> toast mapping in the layout
+      #   <%= poetry_toaster do %>
+      #     <% flash.each do |kind, message| %>
+      #       <%= poetry_toast(variant: kind.to_s == "alert" ? :destructive : :default) do |toast| %>
+      #         <% toast.with_title { message } %>
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # The stream append target (the turbo_stream.poetry_toast default).
+        DEFAULT_ID = "poetry-toaster"
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Exactly ONE poetry_toaster per layout; it is data-turbo-permanent.",
+          "Server-side toasts go through turbo_stream.poetry_toast / the flash recipe - never " \
+          "hand-append into #poetry-toaster.",
+          "Client-side (no round-trip) toasts go through poetry_toast_trigger(template:) + a " \
+          "<template> holding the rendered poetry_toast - the trigger stamps it into the region.",
+          "Do not announce() toast content yourself - the toast controller already does; " \
+          "double-announcing is a regression."
+        ].freeze
+
+        # Values only, zero actions: the controller wires its own
+        # window-keydown (hotkey) and dismiss listeners in connect.
+        use_stimulus do
+          on :root do
+            controller :toaster do
+              register
+              value :hotkey
+              value :limit
+              value :position
+            end
+          end
+        end
+
+        style :position, default: :"bottom-right", required: true, variants: POSITIONS,
+                         doc: "The stack's corner - set here, not per toast; each toast's slide direction follows it."
+
+        option :hotkey, :string, default: "F8", doc: "The keyboard shortcut that focuses the most recent toast."
+        option :limit, :integer, default: 3, doc: "The maximum visible toasts; overflow queues hidden with timers held."
+
+        part "toaster", "The toast viewport itself (<ol>, role=region, data-turbo-permanent) - " \
+                        "the corner geometry and the Turbo Stream append target ride here",
+             states: {
+               "data-position" => { condition: "always - the corner; each toast's slide " \
+                                               "direction keys off it via group/toaster",
+                                    values: POSITIONS.map(&:to_s) },
+               "data-poetry-top-layer" => { condition: "always - the dismissal layer exempts " \
+                                                       "presses here, so clicking a toast never " \
+                                                       "dismisses the overlay under it" }
+             }
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "id" => DEFAULT_ID, "data-slot" => "toaster",
+              "role" => "region", "aria-label" => t("poetry.toast.region_label", hotkey: hotkey),
+              "tabindex" => "-1", "data-turbo-permanent" => "",
+              # The dismissal layer's top-layer exemption: presses inside
+              # the toaster are never "outside" an open overlay.
+              "data-poetry-top-layer" => "",
+              # The toast items key their slide direction on this via the
+              # group-data selector (items render independently of the
+              # region - a streamed toast cannot know the corner).
+              "data-position" => position
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/toaster/positions_preview.html.erb

@@ -0,0 +1,24 @@
+<%# The four placements no other example renders, on one canvas - a
+    coverage fixture: real layouts run ONE toaster per page, and
+    default/top_center own bottom-right and top-center. This page exists so
+    every declared position renders in the golden and axe walks. %>
+<%= poetry_toaster(position: :"top-left", id: "toaster-top-left") do %>
+  <%= poetry_toast(variant: :default) do |toast| %>
+    <% toast.with_title { "Top left" } %>
+  <% end %>
+<% end %>
+<%= poetry_toaster(position: :"top-right", id: "toaster-top-right") do %>
+  <%= poetry_toast(variant: :default) do |toast| %>
+    <% toast.with_title { "Top right" } %>
+  <% end %>
+<% end %>
+<%= poetry_toaster(position: :"bottom-left", id: "toaster-bottom-left") do %>
+  <%= poetry_toast(variant: :default) do |toast| %>
+    <% toast.with_title { "Bottom left" } %>
+  <% end %>
+<% end %>
+<%= poetry_toaster(position: :"bottom-center", id: "toaster-bottom-center") do %>
+  <%= poetry_toast(variant: :default) do |toast| %>
+    <% toast.with_title { "Bottom center" } %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toaster
+      # The Toaster preview: the labeled region with a server-rendered
+      # stack (the no-JS baseline: flash toasts appear as a static list),
+      # plus a top-center corner sample. One toaster per page in real
+      # layouts - previews render in isolation.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do
+            embed(stack_toast(:success, "Changes saved")) +
+              embed(stack_toast(:default, "Event scheduled"))
+          end
+        end
+
+        def top_center
+          render_component(position: :"top-center") do
+            embed(stack_toast(:info, "A new version is available"))
+          end
+        end
+
+        # The stamp path: trigger button + <template> toast + region (the
+        # no-round-trip delivery poetry_toast_trigger drives).
+        def stamp_trigger
+          render_with_template(template: "poetry/ui/toaster/stamp_preview")
+        end
+
+        def positions
+          # The four placements the examples above don't render, one canvas
+          # (axis coverage) - see the template's fixture note.
+          render_with_template(template: "poetry/ui/toaster/positions_preview")
+        end
+
+        private
+
+        def stack_toast(variant, title)
+          Toast::Component.new(variant: variant).tap do |toast|
+            toast.with_title { title }
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/toaster/stamp_preview.html.erb

@@ -0,0 +1,15 @@
+<%# The stamp delivery path end-to-end: a poetry_toast_trigger button, the
+    <template> holding a real rendered toast, and the toaster region the
+    stamp lands in. What the template holds is byte-for-byte what a Turbo
+    Stream would append. %>
+<div class="p-4">
+  <%= poetry_toast_trigger(template: "preview-stamp-toast", variant: :outline) do %>
+    Show toast
+  <% end %>
+</div>
+<template id="preview-stamp-toast">
+  <%= poetry_toast(variant: :success, duration: 4000) do |toast| %>
+    <% toast.with_title { "Stamped into the region" } %>
+  <% end %>
+</template>
+<%= poetry_toaster %>

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toaster
+      # Re-expressed through the cn-* theme layer. The position
+      # variants stay INLINE, unnamed: corner placement is pure positioning
+      # mechanism (fixed-corner geometry the slide selectors key on), with
+      # zero conflicts against the themed spacing/width.
+      class Style < Poetry::Core::Style
+        # max-w-full rides the theme WITH its sm: cap (split-side rule for
+        # responsive pairs - inline it would beat the themed cap always).
+        base "cn-toaster group/toaster pointer-events-none fixed z-50 flex w-full flex-col"
+
+        variant :position, {
+          "top-left": "top-0 left-0",
+          "top-center": "top-0 left-1/2 -translate-x-1/2",
+          "top-right": "top-0 right-0",
+          "bottom-left": "bottom-0 left-0",
+          "bottom-center": "bottom-0 left-1/2 -translate-x-1/2",
+          "bottom-right": "bottom-0 right-0"
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Pressed-state buttons.
+    module Toggle
+      # A pressed-state button: aria-pressed plus a bare data-pressed
+      # presence attribute on a plain <button> - the standard ARIA
+      # toggle-button pattern. Pressed state is UI state
+      # (bold-in-a-toolbar, bookmark-on), so a Toggle carries no form
+      # machinery: state that must submit with a form is a Checkbox, an
+      # instant on/off setting is a Switch, and exclusive or grouped sets
+      # are a ToggleGroup.
+      #
+      # Icon-only toggles require label:, and the label must not change
+      # with state ("Bookmark", never "Remove bookmark") - aria-pressed
+      # already carries the state.
+      #
+      # @example An icon-only bookmark toggle
+      #   render Poetry::Ui::Toggle::Component.new(label: "Bookmark", pressed: bookmarked?) do
+      #     poetry_icon(name: :bookmark)
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the variant axis.
+        VARIANTS = %i[default outline].freeze
+        # The closed vocabulary for the size axis.
+        SIZES = %i[default sm lg].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_toggle - never a Button with hand-managed aria-pressed.",
+          "Toggle is UI state, NOT form data: never try to submit it. Form value -> Checkbox; instant " \
+          "setting -> Switch; exclusive/grouped -> ToggleGroup.",
+          "Icon-only toggles MUST pass label:, and the label must NOT change with state ('Bookmark', " \
+          "never 'Remove bookmark').",
+          "aria-pressed is the vocabulary - never aria-checked or aria-expanded on a Toggle.",
+          "Wire the EFFECT to poetry:toggle:change (or click) and revert via set(false) on failure - " \
+          "a pressed toggle whose effect failed is a lie.",
+          "Pressed visual is accent - don't override data-pressed colors per-instance (theme-level only)."
+        ].freeze
+
+        # Click flips aria-pressed and data-pressed together; the DOM is
+        # the store (no Values). No keydown wiring - Space and Enter
+        # already activate a native button.
+        use_stimulus do
+          on :root do
+            controller :pressed do
+              register
+              action :toggle, on: :click
+            end
+          end
+        end
+
+        style :variant, default: :default, required: true, variants: VARIANTS,
+                        doc: "The visual treatment; :outline adds a border for standalone use."
+        style :size, default: :default, required: true, variants: SIZES, doc: "The control's size axis."
+
+        option :pressed, :boolean, default: false, doc: "The server-rendered pressed state."
+        option :disabled, :boolean, default: false, doc: "Disables the control and forwards to the native button."
+        option :label, :string,
+               doc: "REQUIRED when icon-only; must be state-INVARIANT (APG: aria-pressed carries the state - a " \
+                    "flipping name makes SRs announce nonsense)."
+
+        part "toggle", "The pressed-state <button> - the whole component; aria-pressed carries the " \
+                       "state and the controller flips both together",
+             states: {
+               "data-pressed" => "pressed (bare presence boolean - absent when unpressed, never " \
+                                 "data-pressed=false)",
+               "data-disabled" => "disabled (rendered alongside native disabled for styling-hook parity)",
+               "data-variant" => { condition: "the visual variant", values: VARIANTS.map(&:to_s) },
+               "data-size" => { condition: "the size", values: SIZES.map(&:to_s) }
+             }
+
+        # An icon-only (or empty) toggle without an accessible name never
+        # ships.
+        # @api private
+        def before_render
+          return if label.present? || visible_text?
+
+          raise ArgumentError,
+                "icon-only Toggle requires label: (the accessible name, state-invariant - " \
+                "'Bookmark', never 'Remove bookmark')"
+        end
+
+        # @api private
+        def call
+          content_tag(:button, content, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = {
+            "type" => "button", "data-slot" => "toggle",
+            "aria-pressed" => pressed.to_s,
+            "data-variant" => variant, "data-size" => size,
+            "disabled" => disabled
+          }
+          # Pressed is a bare presence attribute: data-pressed when on,
+          # absent when off (never data-pressed=false).
+          attrs["data-pressed"] = "" if pressed
+          # data-disabled renders alongside native disabled - kept for
+          # styling-hook parity (and the group-context roving filter).
+          attrs["data-disabled"] = "" if disabled
+          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
+
+        def visible_text?
+          content? && content.to_s.gsub(/<[^>]+>/, " ").strip.present?
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toggle
+      # The Toggle preview matrix: 2 variants x 3 sizes x pressed states,
+      # icon-only (label enforced) and icon+text - the toggle-demo corpus.
+      class Preview < Poetry::Core::Preview::Base
+        # @!group Variants
+
+        # The toggle-demo port: icon-only bookmark with a state-invariant
+        # accessible name.
+        def default
+          render_component(label: "Bookmark") do |_component|
+            embed(Icon::Component.new(name: :bookmark))
+          end
+        end
+
+        def outline
+          render_component(variant: :outline, label: "Italic") do |_component|
+            embed(Icon::Component.new(name: :italic))
+          end
+        end
+
+        # @!endgroup
+
+        # @!group States
+
+        def pressed
+          render_component(pressed: true, label: "Bold") do |_component|
+            embed(Icon::Component.new(name: :bold))
+          end
+        end
+
+        def disabled
+          render_component(disabled: true, variant: :outline, label: "Underline") do |_component|
+            embed(Icon::Component.new(name: :underline))
+          end
+        end
+
+        def disabled_pressed
+          render_component(disabled: true, pressed: true, label: "Bold") do |_component|
+            embed(Icon::Component.new(name: :bold))
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Sizes
+
+        def small
+          render_component(size: :sm, variant: :outline, label: "Italic") do |_component|
+            embed(Icon::Component.new(name: :italic))
+          end
+        end
+
+        def large
+          render_component(size: :lg, label: "Bold") do |_component|
+            embed(Icon::Component.new(name: :bold))
+          end
+        end
+
+        # @!endgroup
+
+        # @!group Composition
+
+        # toggle-with-text: the visible text IS the accessible name - no
+        # label: needed.
+        def with_text
+          render_component(variant: :outline) do |_component|
+            embed(Icon::Component.new(name: :italic)).concat("Italic")
+          end
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Toggle
+      # Re-expressed through the cn-* theme layer. Still the family's
+      # shared dictionary: ToggleGroup items consume it through
+      # Toggle::Style.css (shared, never copied). The muted-not-accent
+      # hover note now reads off the theme rules: .cn-toggle hovers MUTED
+      # (pressed owns accent), .cn-toggle-variant-outline hovers accent -
+      # both source-exact, in themes/default.css. hover:bg-muted deviates
+      # from upstream's inline split DELIBERATELY: outline's themed accent
+      # hover can only beat it from the same layer (the split-side conflict
+      # rule - an inline utility would win the cascade unconditionally).
+      class Style < Poetry::Core::Style
+        base "cn-toggle group/toggle inline-flex items-center justify-center whitespace-nowrap " \
+             "outline-none focus-visible:ring-[3px] disabled:pointer-events-none " \
+             "disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0"
+
+        variant :variant, {
+          default: "cn-toggle-variant-default",
+          outline: "cn-toggle-variant-outline"
+        }
+
+        variant :size, {
+          default: "cn-toggle-size-default",
+          sm: "cn-toggle-size-sm",
+          lg: "cn-toggle-size-lg"
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+<%# Items render as DIRECT children - the segmented data-[spacing=0]
+    first:/last:/border-l-0 chain depends on DOM order with no stray
+    wrappers between items (stream-appends must land inside this root). %>
+<%= content_tag(:div, safe_join(items.map(&:to_s)), **root_attributes.to_attributes) %>