poetry-ui 0.0.2

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Inline callouts for statuses and errors.
+    module Alert
+      # An inline callout for statuses and errors, with the live-region
+      # wiring built in. The default variant announces politely
+      # (role=status); :destructive announces assertively (role=alert),
+      # so reserve it for genuine errors.
+      #
+      # @example Destructive alert with a title
+      #   render Poetry::Ui::Alert::Component.new(variant: :destructive) do |alert|
+      #     alert.with_title { "Payment failed" }
+      #     "Your card was declined. Update your billing details."
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the variant axis.
+        VARIANTS = %i[default destructive].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_alert for inline callouts - it carries role/aria-live; never a hand-rolled div.",
+          "destructive announces assertively (role=alert) - reserve it for errors, not emphasis."
+        ].freeze
+
+        renders_one :icon, Poetry::Ui::Icon::Component, doc: "Optional leading icon; pass icon props (e.g. name: " \
+                                                             ":\"triangle-alert\"), not a block."
+        renders_one :title, doc: "The heading line of the callout."
+        renders_one :action, doc: "Optional corner action (a dismiss button or link), pinned to the top-right."
+
+        style :variant, default: :default, required: true, variants: VARIANTS,
+                        doc: "The intent axis; :destructive marks errors and announces assertively."
+
+        part "alert", "The callout root - role rides the variant (destructive announces " \
+                      "assertively via role=alert; default is a polite role=status)",
+             states: {
+               "data-variant" => { condition: "always - the resolved variant",
+                                   values: VARIANTS.map(&:to_s) }
+             }
+        part "alert-title", "The heading line, rendered when the title slot is set"
+        part "alert-action", "The corner action well (with_action) - a dismiss or link " \
+                             "pinned to the top-right by the theme"
+        part "alert-description", "The body copy - the content block renders here"
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "alert",
+              "data-variant" => variant,
+              "role" => (variant == :destructive ? "alert" : "status")
+            }.merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Alert
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |alert|
+            alert.with_title { "Heads up" }
+            "You can adjust preferences at any time."
+          end
+        end
+
+        def destructive
+          render_component(variant: :destructive) do |alert|
+            alert.with_icon(name: :"triangle-alert")
+            alert.with_title { "Payment failed" }
+            "Your card was declined - update your billing details."
+          end
+        end
+
+        # The corner action well (theme pins it top-right).
+        def with_action
+          render_component(variant: :default) do |alert|
+            alert.with_title { "Update available" }
+            alert.with_action do
+              tag.button("Dismiss", type: "button", class: "text-sm underline-offset-4 hover:underline")
+            end
+            "A new version is ready to install."
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Alert
+      # Re-expressed through the cn-* theme layer: entries carry the
+      # stable names + the structural inline set; themes/default.css holds
+      # the design (the grid treatment, variants).
+      class Style < Poetry::Core::Style
+        base "cn-alert relative w-full group/alert"
+
+        variant :variant, {
+          default: "cn-alert-variant-default",
+          destructive: "cn-alert-variant-destructive"
+        }
+
+        element :title, "cn-alert-title [&_a]:hover:text-foreground [&_a]:underline [&_a]:underline-offset-3"
+        element :action, "cn-alert-action"
+        element :description, "cn-alert-description [&_a]:hover:text-foreground [&_a]:underline " \
+                              "[&_a]:underline-offset-3"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= trigger %>
+  <%= content_tag(:dialog, **Poetry::Core::HTML::Attributes.new(dialog_attributes).to_attributes) do %>
+    <div data-slot="alert-dialog-header" class="<%= header_classes %>">
+      <% if media? %>
+        <div data-slot="alert-dialog-media" class="<%= media_classes %>"><%= media %></div>
+      <% end %>
+      <h2 id="<%= title_id %>" data-slot="alert-dialog-title" class="<%= title_classes %>"><%= title %></h2>
+      <p id="<%= description_id %>" data-slot="alert-dialog-description" class="<%= css(:description) %>"><%= description %></p>
+    </div>
+    <%= content %>
+    <div data-slot="alert-dialog-footer" class="<%= footer_classes %>">
+      <%= cancel %>
+      <%= action %>
+    </div>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Modal confirmations that must be answered.
+    module AlertDialog
+      # A modal confirmation that must be answered before anything else.
+      # Built on the native <dialog> element: clicking the backdrop never
+      # dismisses it, though Esc still cancels. Use it for destructive or
+      # irreversible actions; for anything needing input, use Dialog.
+      #
+      # Title and description are both required, as are the action and
+      # cancel buttons - both close the dialog when activated, and cancel
+      # (the least-destructive choice) takes initial focus. There is no
+      # corner close button.
+      #
+      # @example Destructive confirmation
+      #   render Poetry::Ui::AlertDialog::Component.new do |dialog|
+      #     dialog.with_trigger(variant: :destructive) { "Delete project" }
+      #     dialog.with_title { "Delete this project?" }
+      #     dialog.with_description { "This cannot be undone." }
+      #     dialog.with_cancel { "Cancel" }
+      #     dialog.with_action(variant: :destructive) { "Delete" }
+      #   end
+      class Component < Poetry::Core::Component
+        include Poetry::Ui::ComposableTrigger
+        include Poetry::Ui::FamilyIdentity
+
+        # The closed vocabulary for the size axis.
+        SIZES = %i[default sm].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          ComposableTrigger::AGENT_RULE,
+          "Destructive confirmations use AlertDialog with with_action(variant: :destructive) - " \
+          "never a bare Dialog, never data-turbo-confirm.",
+          "with_title AND with_description are REQUIRED (both raise).",
+          "The action must be an explicit user activation - agents NEVER auto-submit the action.",
+          "No extra form fields inside an AlertDialog - if input is needed, use a Dialog.",
+          "Cancel keeps variant: :outline; do not make cancel visually primary."
+        ].freeze
+
+        # Slots the component cannot render without; static checks read this without rendering.
+        REQUIRED_SLOTS = {
+          title: "the accessible name", description: "the alertdialog must explain itself",
+          action: "the confirming choice", cancel: "the safe way out"
+        }.freeze
+
+        # Slots that render a Button; slot keywords are forwarded as Button props.
+        SLOT_RENDERS = { trigger: Button::Component, action: Button::Component, cancel: Button::Component }.freeze
+
+        renders_one :trigger,
+                    doc: "The button that opens the dialog; keywords are forwarded as Button props.",
+                    renders: lambda { |**options, &block|
+                      composed_trigger({ "data-action" => stimulus_action(:open) }, options, &block) || begin
+                        merger = Poetry::Core::Config.current.stimulus_merger
+                        wired_data = { action: stimulus_action(:open) }
+                        options[:data] = wired_data.merge(options[:data] || {}) do |key, wired, caller|
+                          key == :action ? merger.merge_actions(wired, caller) : caller
+                        end
+                        Button::Component.new(**options, &block)
+                      end
+                    }
+        renders_one :title, doc: "The heading - the dialog's accessible name (required)."
+        renders_one :description, doc: "The explanation read alongside the title by assistive tech (required)."
+        renders_one :media, doc: "Optional icon/illustration well above the title."
+        renders_one :action,
+                    doc: "The confirming choice (required) - a Button; pass variant: :destructive for deletes. " \
+                         "Activating it also closes the dialog (a caller-supplied data-action opts out).",
+                    renders: lambda { |**options, &block|
+                      options[:data] =
+                        { slot: "alert-dialog-action", action: stimulus_action(:close) }.merge(options[:data] || {})
+                      Button::Component.new(**options, &block)
+                    }
+        renders_one :cancel,
+                    doc: "The safe way out (required) - an outline Button that takes initial focus and closes the " \
+                         "dialog on activation.",
+                    renders: lambda { |**options, &block|
+                      merger = Poetry::Core::Config.current.stimulus_merger
+                      wired_data = { slot: "alert-dialog-cancel", action: stimulus_action(:close) }
+                      options[:data] = wired_data.merge(options[:data] || {}) do |key, wired, caller|
+                        key == :action ? merger.merge_actions(wired, caller) : caller
+                      end
+                      Button::Component.new(variant: :outline, autofocus: true, **options, &block)
+                    }
+
+        # The SHARED dialog controller (zero new JS) under AlertDialog's
+        # own declarations - dismissible is the hard-coded false posture.
+        use_stimulus do
+          on :root do
+            controller :dialog do
+              register
+              # The posture IS the identity - never caller-settable.
+              value :dismissible, false
+            end
+          end
+          on :content do
+            controller :dialog do
+              target :dialog
+              action :close, on: :cancel
+              # Wired but inert: backdropClose no-ops on dismissibleValue
+              # false. Keep it - removing it would fork the Dialog wiring.
+              action :backdrop_close, on: :click
+            end
+          end
+          on :trigger do
+            controller(:dialog) { action :open }
+          end
+          # Both the action and cancel Buttons close (same descriptor).
+          on :close do
+            controller(:dialog) { action :close }
+          end
+        end
+
+        style :size, default: :default, required: true, variants: SIZES,
+                     doc: "The panel size; :sm compacts the layout and switches the footer to a two-column grid."
+
+        option :content_class, :string, doc: "Extra classes merged onto the panel element."
+
+        part "alert-dialog", "Root wrapper around the trigger and the <dialog> element"
+        part "alert-dialog-content", "The role=alertdialog <dialog> panel - sizing, animation, " \
+                                     "and the open state ride here",
+             states: {
+               "data-open" => "panel is open (the shared dialog controller flips the pair " \
+                              "at runtime)",
+               "data-closed" => "panel is closed (the server-rendered state)",
+               "data-size" => { condition: "always - the resolved size",
+                                values: SIZES.map(&:to_s) }
+             }
+        part "alert-dialog-header", "Title block - holds the optional media well, the title, " \
+                                    "and the description"
+        part "alert-dialog-media", "The optional media well above the title (an icon or illustration) - the " \
+                                   "header's first row; absent unless with_media is used"
+        part "alert-dialog-title", "The heading - the alertdialog's accessible name " \
+                                   "(required slot)"
+        part "alert-dialog-description", "The explanation, wired to aria-describedby " \
+                                         "(required slot)"
+        part "alert-dialog-footer", "The choice row - cancel then action"
+
+        # Enforces the four required slots.
+        # @api private
+        def before_render
+          raise ArgumentError, "AlertDialog requires with_title (the accessible name)" unless title?
+          unless description?
+            raise ArgumentError, "AlertDialog requires with_description (the alertdialog must explain itself)"
+          end
+          raise ArgumentError, "AlertDialog requires with_action (the confirming choice)" unless action?
+          raise ArgumentError, "AlertDialog requires with_cancel (the safe way out)" unless cancel?
+        end
+
+        # @api private
+        def title_id
+          "#{instance_id}-title"
+        end
+
+        # @api private
+        def description_id
+          "#{instance_id}-description"
+        end
+
+        # @api private
+        def dialog_attributes
+          {
+            "class" => css(:content, class: content_class),
+            # Explicit role: overrides the implicit dialog role (aria-modal
+            # still comes from showModal).
+            "role" => "alertdialog",
+            "data-slot" => "alert-dialog-content",
+            "data-size" => size,
+            "data-closed" => "",
+            "aria-labelledby" => title_id,
+            "aria-describedby" => description_id
+          }.merge(stimulus_attributes_for(:content))
+        end
+
+        # The media/size layout branches emitted as explicit server-side
+        # conditionals - poetry knows at render time whether media exists
+        # and which size was picked, so no CSS selector gymnastics.
+        # @api private
+        def header_classes
+          css(:header, class: [
+            (css(:header_with_media) if media?),
+            (css(:header_size_default) if size == :default),
+            (css(:header_size_default_with_media) if media? && size == :default)
+          ].compact.join(" "))
+        end
+
+        # @api private
+        def media_classes
+          css(:media, class: (css(:media_size_default) if size == :default))
+        end
+
+        # @api private
+        def title_classes
+          css(:title, class: (css(:title_beside_media) if media? && size == :default))
+        end
+
+        # @api private
+        def footer_classes
+          css(:footer, class: (css(:footer_size_sm) if size == :sm))
+        end
+
+        private :title_id, :description_id, :dialog_attributes, :header_classes, :media_classes, :title_classes
+        private :footer_classes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module AlertDialog
+      class Preview < Poetry::Core::Preview::Base
+        # The canonical recipe: a destructive confirmation. Backdrop clicks
+        # never dismiss it; Esc still cancels (source-exact posture).
+        def destructive_confirm
+          render_component do |dialog|
+            dialog.with_trigger(variant: :destructive) { "Delete account" }
+            dialog.with_title { "Are you absolutely sure?" }
+            dialog.with_description { "This permanently deletes your account and all of its data." }
+            dialog.with_cancel { "Cancel" }
+            dialog.with_action(variant: :destructive) { "Delete account" }
+            ""
+          end
+        end
+
+        # The media well above the title (an icon), the header's third row.
+        def with_media
+          render_component do |dialog|
+            dialog.with_trigger(variant: :outline) { "Archive project" }
+            dialog.with_media { embed(Icon::Component.new(name: :archive)) }
+            dialog.with_title { "Archive this project?" }
+            dialog.with_description { "Archived projects are read-only until restored." }
+            dialog.with_cancel { "Keep it" }
+            dialog.with_action { "Archive" }
+            ""
+          end
+        end
+
+        # Initial focus lands on Cancel (autofocus - APG: focus the
+        # least-destructive action); the compact sm size for quick confirms.
+        def cancel_autofocus
+          render_component(size: :sm) do |dialog|
+            dialog.with_trigger(variant: :outline) { "Publish changes" }
+            dialog.with_title { "Publish these changes?" }
+            dialog.with_description { "Your edits go live immediately." }
+            dialog.with_cancel { "Cancel" }
+            dialog.with_action { "Publish" }
+            ""
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module AlertDialog
+      # Re-expressed through the cn-* theme layer, ported like the
+      # parent Dialog: panel chrome + size branches + backdrop + enter
+      # animation ride themes/default.css; native-dialog mechanisms and
+      # the explicit server-side media/size layout branches stay inline
+      # (the source's group/has- gymnastics remain conditionals, not CSS).
+      class Style < Poetry::Core::Style
+        # open:grid, NOT grid (the Dialog's UA display:none lesson). No
+        # `relative`: it is discarded in the top layer (the UA reasserts
+        # `absolute`, pinning the panel to the document origin so it scrolls
+        # off-screen below the fold); the UA `:modal` rule keeps it fixed and
+        # viewport-centered instead. See the parent Dialog.
+        element :content, "cn-alert-dialog-content m-auto open:grid group/alert-dialog-content"
+
+        element :header, "cn-alert-dialog-header grid grid-rows-[auto_1fr] place-items-center text-center"
+        # The with-media x-gap is theme-side (.cn-alert-dialog-header
+        # has-data-[slot=alert-dialog-media]:gap-x-*) - inline it and no
+        # theme could ever tighten it.
+        element :header_with_media, "grid-rows-[auto_auto_1fr]"
+        # default size: centered on mobile, left from sm (sm size stays
+        # centered at every breakpoint - source).
+        element :header_size_default, "sm:place-items-start sm:text-left"
+        element :header_size_default_with_media, "sm:grid-rows-[auto_1fr]"
+
+        element :media, "cn-alert-dialog-media inline-flex items-center justify-center"
+        element :media_size_default, "sm:row-span-2"
+
+        element :title, "cn-alert-dialog-title"
+        element :title_beside_media, "sm:col-start-2"
+
+        element :description, "cn-alert-dialog-description"
+
+        # Footer hook is themable (nova bands it); gap-2 moved
+        # theme-side with the name - direction/justify stay inline (the
+        # sm-size grid branch below replaces them via the class: merge).
+        element :footer, "cn-alert-dialog-footer flex flex-col-reverse sm:flex-row sm:justify-end"
+        # sm size: the compact 2-col grid footer (source).
+        element :footer_size_sm, "grid grid-cols-2"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Ratio-locked media containers.
+    module AspectRatio
+      # A container that locks its width:height ratio (CSS aspect-ratio
+      # via the --ratio custom property). The content is whatever should
+      # keep the shape: an image, an embed, a placeholder.
+      #
+      # @example A 16:9 media box
+      #   render Poetry::Ui::AspectRatio::Component.new(ratio: "16/9") do
+      #     image_tag "cover.jpg", class: "size-full object-cover"
+      #   end
+      class Component < Poetry::Core::Component
+        # The accepted CSS <ratio> grammar for ratio: ("16/9", "1", "1.5").
+        RATIO = %r{\A\d+(\.\d+)?(\s*/\s*\d+(\.\d+)?)?\z}
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Pass ratio: as a string fraction ('16/9', '1/1') - Ruby's 16/9 is integer division (1).",
+          "The child fills the box itself (size-full object-cover on an image)."
+        ].freeze
+
+        option :ratio, :string, required: true,
+                                doc: "A CSS <ratio>: \"16/9\", \"1\", \"1.5\" - kept a string so the fraction " \
+                                     "survives verbatim into the --ratio custom property."
+
+        part "aspect-ratio", "The ratio-locked box - the content block fills it",
+             vars: {
+               "--ratio" => "always - the ratio: fraction verbatim ('16/9'), consumed by the " \
+                            "theme's aspect-ratio rule"
+             }
+
+        # Validates the ratio: grammar.
+        # @api private
+        def before_render
+          return if ratio.present? && ratio.match?(RATIO)
+
+          raise ArgumentError,
+                "AspectRatio ratio: must be a CSS ratio ('16/9', '1', '1.5') - got #{ratio.inspect}"
+        end
+
+        # @api private
+        def call
+          content_tag(:div, content, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "aspect-ratio",
+              "style" => "--ratio: #{ratio}"
+            }.merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module AspectRatio
+      # The AspectRatio preview: the common shapes, each holding a muted
+      # placeholder that fills the locked box.
+      class Preview < Poetry::Core::Preview::Base
+        def video
+          render_component(ratio: "16/9", class: "w-64 overflow-hidden rounded-lg bg-muted") do
+            tag.div("16 / 9", class: "flex size-full items-center justify-center text-sm text-muted-foreground")
+          end
+        end
+
+        def square
+          render_component(ratio: "1", class: "w-40 overflow-hidden rounded-lg bg-muted") do
+            tag.div("1 / 1", class: "flex size-full items-center justify-center text-sm text-muted-foreground")
+          end
+        end
+
+        def portrait
+          render_component(ratio: "9/16", class: "w-24 overflow-hidden rounded-lg bg-muted") do
+            tag.div("9 / 16", class: "flex size-full items-center justify-center text-sm text-muted-foreground")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module AspectRatio
+      # Style dictionary for the AspectRatio family: aspect-(--ratio) reads
+      # the --ratio custom property the component writes inline.
+      class Style < Poetry::Core::Style
+        base "relative aspect-(--ratio)"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= trigger %>
+  <%= media %>
+  <% if title? || description? %>
+    <div data-slot="attachment-content" class="<%= css(:content) %>">
+      <% if title? %><span data-slot="attachment-title" class="<%= css(:title) %>"><%= title %></span><% end %>
+      <% if description? %><span data-slot="attachment-description" class="<%= css(:description) %>"><%= description %></span><% end %>
+    </div>
+  <% end %>
+  <%= content %>
+  <% if actions? %><div data-slot="attachment-actions" class="<%= css(:actions) %>"><% actions.each do |action| %><%= action %><% end %></div><% end %>
+  <% if announced? %><span data-slot="attachment-status" role="status" class="sr-only"><%= t("poetry.attachment.state.#{state}") %></span><% end %>
+<% end %>