poetry-ui 0.0.2

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Poetry
+  module Ui
+    # Deferred family: lazy-loaded regions with loading and error states.
+    module Deferred
+      # A deferred region: a Turbo Frame that fetches its content when it
+      # becomes VISIBLE (loading: :lazy, the default - so a deferred Tabs
+      # panel or HoverCard body loads on first reveal with no extra
+      # wiring) or right after paint (:eager). The block is the loading
+      # placeholder (a Skeleton renders when absent), and a failed fetch
+      # shows a visible, retryable error card instead of silent
+      # blankness.
+      #
+      # @example
+      #   render Poetry::Ui::Deferred::Component.new(src: "/dashboard/activity")
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Use poetry_deferred(src:) for expensive regions - never a spinner div + a hand-rolled fetch.",
+          "loading: :lazy (the default) fetches on visibility: a deferred region inside a hidden " \
+          "Tabs panel (with_tab defer:) or HoverCard (defer:) loads on first reveal for free.",
+          "The block is the placeholder (a Skeleton renders when absent); failure shows a retryable " \
+          "error card automatically - never hand-wire loading or error states around it."
+        ].freeze
+
+        use_stimulus do
+          # src rides the controller value, NOT the frame markup: connect()
+          # arms it, so a fast response can never beat the controllers
+          # module graph to the frame.
+          on :root do
+            controller :deferred do
+              register
+              value :src
+            end
+          end
+          # Template-consumed elements (previously hand-written strings).
+          on :placeholder do
+            controller(:deferred) { target :placeholder }
+          end
+          on :error_template do
+            controller(:deferred) { target :error }
+          end
+          on :retry do
+            controller(:deferred) { action :retry, on: :click }
+          end
+        end
+
+        option :src, :string, required: true, doc: "The URL to fetch - required; rendering without it raises."
+        option :loading, :symbol, default: :lazy,
+                                  doc: ":lazy fetches when the frame becomes visible; :eager fetches right after paint."
+
+        part "deferred", "The <turbo-frame> root - src is armed at connect(); failure is " \
+                         "a state reflected here, never silent blankness",
+             states: {
+               "data-error" => "a frame fetch failed (error response, missing frame, or " \
+                               "network error) - the controller stamps the error card; " \
+                               "retry clears it"
+             }
+        part "deferred-error", "The retryable error card, stamped into the frame from the " \
+                               "slotted <template> on failure"
+
+        # Enforces the required src.
+        # @api private
+        def before_render
+          raise ArgumentError, "poetry_deferred requires src:" if src.blank?
+        end
+
+        # No src in the markup ON PURPOSE: the URL rides the controller
+        # value and connect() arms it, so a fast response can never beat
+        # the controllers module graph to the frame (Turbo 8's
+        # frame-missing default would promote that race to a full-page
+        # visit).
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "id" => "poetry-deferred-#{Digest::MD5.hexdigest(src.to_s).first(8)}",
+              "loading" => loading, "data-slot" => "deferred"
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Deferred
+      # The Deferred preview. The dummy loads no Turbo, so the frame stays
+      # inert: what renders (and what the baseline captures) IS the
+      # placeholder state - deterministic by construction. Live loading /
+      # error / retry behavior is proven in poetry-core's deferred.test.js
+      # and on the docs site's /deferred page.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(src: "/previews/activity")
+        end
+
+        def custom_placeholder
+          render_component(src: "/previews/activity") do
+            "Fetching the latest activity…"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+<%= 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="dialog-header" class="<%= css(:header) %>">
+      <h2 id="<%= title_id %>" data-slot="dialog-title" class="<%= css(:title) %>"><%= title %></h2>
+      <% if description? %>
+        <p id="<%= description_id %>" data-slot="dialog-description" class="<%= css(:description) %>"><%= description %></p>
+      <% end %>
+    </div>
+    <%= content %>
+    <% if footer? %><div data-slot="dialog-footer" class="<%= css(:footer) %>"><%= footer %></div><% end %>
+    <% if show_close_button %>
+      <%= render Poetry::Ui::Button::Component.new(variant: :ghost, size: :"icon-sm",
+                                                   label: t("poetry.dialog.close"),
+                                                   class: css(:close),
+                                                   data: { slot: "dialog-close", action: close_action }) do %>
+        <%= render Poetry::Ui::Icon::Component.new(name: :x) %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Dialog family: the modal overlay on the native <dialog> element.
+    module Dialog
+      # A modal dialog built ON the platform: a native <dialog> +
+      # showModal() owns focus trapping, Esc, top-layer stacking, and
+      # focus return; poetry adds the data-open/data-closed pair,
+      # backdrop dismissal, and the scroll lock. The title is REQUIRED
+      # (the accessible name - aria-labelledby is always wired).
+      #
+      # @example A confirmation dialog
+      #   render Poetry::Ui::Dialog::Component.new do |dialog|
+      #     dialog.with_trigger(variant: :outline) { "Open" }
+      #     dialog.with_title { "Are you sure?" }
+      #     dialog.with_description { "This cannot be undone." }
+      #   end
+      class Component < Poetry::Core::Component
+        include Poetry::Ui::ComposableTrigger
+        include Poetry::Ui::FamilyIdentity
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          ComposableTrigger::AGENT_RULE,
+          "Open dialogs with with_trigger(...) - never a hand-wired button.",
+          "with_title is REQUIRED (the accessible name); with_description when the purpose needs explaining.",
+          "Confirmations that must not be lost use dismissible: false (backdrop clicks stop closing).",
+          "show_close_button: false removes the corner X - keep a footer action (Esc still closes).",
+          "Destructive confirmations pair a destructive Button in the footer - never auto-submit."
+        ].freeze
+
+        # The required slots, stated statically so static checks can flag
+        # a missing title without rendering.
+        REQUIRED_SLOTS = { title: "the accessible name" }.freeze
+
+        # The forwarding-lambda fact: with_trigger renders a Button -
+        # callers get Button's full typed-slot contract statically.
+        SLOT_RENDERS = { trigger: Button::Component }.freeze
+
+        renders_one :trigger,
+                    doc: "The trigger is a poetry Button wired to open the dialog - agents pass Button props: " \
+                         "with_trigger(variant: :outline) { \"Open\" }.",
+                    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: "Muted copy under the title, wired to aria-describedby."
+        renders_one :footer, doc: "The action row at the bottom of the panel."
+
+        # Sheet and Drawer subclass this and REDECLARE both elements with
+        # their own controllers (replace-on-redeclare); the trigger lambda
+        # and close_action late-bind through stimulus_action, so subclasses
+        # never re-type the entry points.
+        use_stimulus do
+          on :root do
+            controller :dialog do
+              register
+              value :dismissible
+            end
+          end
+          on :content do
+            controller :dialog do
+              target :dialog
+              action :close, on: :cancel
+              action :backdrop_close, on: :click
+            end
+          end
+          # Forwarded descriptors (bare = element-default click): the
+          # trigger Button and the corner close button.
+          on :trigger do
+            controller(:dialog) { action :open }
+          end
+          on :close do
+            controller(:dialog) { action :close }
+          end
+        end
+
+        # The operate surface: open/close a rendered dialog (registered per
+        # instance, opt-in - see poetry-agent). Bare actions on purpose:
+        # Sheet and Drawer re-controller the root, and a bare `executes:`
+        # re-resolves to THEIR controller at projection time.
+        tool :open,
+             description: "Open the dialog.",
+             executes: :open,
+             mutating: true
+        tool :close,
+             description: "Close the dialog.",
+             executes: :close,
+             mutating: true
+
+        option :dismissible, :boolean, default: true,
+                                       doc: "Backdrop clicks close the dialog; false keeps confirmations from being " \
+                                            "dismissed accidentally (Esc still closes)."
+
+        option :show_close_button, :boolean, default: true,
+                                             doc: "Renders the corner X; false forces a deliberate footer choice " \
+                                                  "(footer actions and Esc remain). Sheet inherits this."
+        option :content_class, :string,
+               doc: "Extra classes merged onto the <dialog> panel (e.g. \"max-h-[50vh]\" caps a top/bottom sheet)."
+
+        part "dialog", "Root wrapper around the trigger and the <dialog> element"
+        part "dialog-content", "The <dialog> panel - positioning, animation, and the open " \
+                               "state ride here",
+             states: {
+               "data-open" => "panel is open (the controller flips the pair at runtime)",
+               "data-closed" => "panel is closed or animating out (the server-rendered state)"
+             }
+        part "dialog-header", "Title block at the top of the panel"
+        part "dialog-title", "The heading - the dialog's accessible name (required slot)"
+        part "dialog-description", "Muted copy under the title, wired to aria-describedby"
+        part "dialog-footer", "Action row at the bottom of the panel"
+
+        # Enforces the required title.
+        # @api private
+        def before_render
+          raise ArgumentError, "#{family_name} requires with_title (the accessible name)" unless title?
+        end
+
+        # The title's id - the aria-labelledby target.
+        # @api private
+        def title_id
+          "#{instance_id}-title"
+        end
+
+        # The description's id - the aria-describedby target.
+        # @api private
+        def description_id
+          "#{instance_id}-description"
+        end
+
+        # Attributes for the <dialog> panel.
+        # @api private
+        def dialog_attributes
+          attrs = {
+            "class" => css(:content, class: panel_classes),
+            "data-slot" => "#{family_slot_prefix}-content",
+            **panel_stamps,
+            "data-closed" => "",
+            "aria-labelledby" => title_id
+          }.merge(stimulus_attributes_for(:content))
+          attrs["aria-describedby"] = description_id if description?
+          attrs
+        end
+
+        # Validated action descriptor for the template's close button -
+        # resolves against the class's OWN declarations (Sheet/Drawer get
+        # their controller without overriding).
+        # @api private
+        def close_action
+          stimulus_action(:close)
+        end
+
+        # The dialog-family root wrapper is NON-VISUAL - the <dialog> is
+        # the visual root. The style resolver renders variant branches only
+        # at the dictionary root, so subclasses with a root-level style
+        # axis (Sheet's side:, Drawer's direction:) merge the branch into
+        # :content themselves - and the inherited html_attributes would
+        # paint the same branch on the in-flow wrapper too (the closed
+        # Drawer drew its themed border + w-full across the docs mounts).
+        # Only the tailwind resolution is stripped: in :bem mode the root
+        # block--modifier tokens ARE the host's styling contract.
+        # @api private
+        def html_attributes
+          return super unless Poetry::Core::Config.current.css_mode == :tailwind
+
+          @html_attributes.merge(class: classnames(@html_attributes[:class]))
+        end
+
+        private
+
+        # Subclass seams for the panel: extra class values and the family
+        # stamps between data-slot and data-closed (Sheet stamps its side,
+        # Drawer its swipe direction).
+        def panel_classes
+          content_class
+        end
+
+        def panel_stamps
+          {}
+        end
+
+        private :title_id, :description_id, :dialog_attributes, :close_action, :html_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Dialog
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component do |dialog|
+            dialog.with_trigger(variant: :outline) { "Edit profile" }
+            dialog.with_title { "Edit profile" }
+            dialog.with_description { "Make changes and save when done." }
+            dialog.with_footer do
+              embed(Poetry::Ui::Button::Component.new.with_content("Save changes"))
+            end
+            "Profile form goes here."
+          end
+        end
+
+        def confirmation
+          render_component(dismissible: false) 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 data." }
+            dialog.with_footer do
+              embed(Poetry::Ui::Button::Component.new(variant: :destructive).with_content("Delete"))
+            end
+            ""
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Dialog
+      # The root is a non-visual wrapper; the visual surface is the native
+      # <dialog> element (the :content element), centered by the top layer.
+      # Re-expressed through the cn-* theme layer: the panel chrome,
+      # backdrop tint, and enter animation ride themes/default.css; the
+      # native-dialog mechanisms stay inline.
+      class Style < Poetry::Core::Style
+        # open:grid, NOT grid: a bare display class would defeat the UA's
+        # dialog:not([open]) { display: none } and render the dialog inline
+        # while closed (invisible to jsdom, which has no UA stylesheet).
+        # No `relative`: a modal <dialog> lives in the top layer, where the
+        # browser drops a `position: relative` back to the UA `absolute` and
+        # pins the panel to the DOCUMENT origin (it then scrolls off-screen
+        # when opened below the fold). Letting position fall through to the
+        # UA `:modal` rule keeps it viewport-fixed and centered.
+        element :content, "cn-dialog-content m-auto open:grid"
+
+        element :header, "cn-dialog-header flex flex-col"
+        element :title, "cn-dialog-title"
+        element :description, "cn-dialog-description"
+        element :footer, "cn-dialog-footer flex flex-col-reverse gap-2 sm:flex-row sm:justify-end"
+        element :close, "cn-dialog-close"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= trigger %>
+  <%= content_tag(:dialog, **Poetry::Core::HTML::Attributes.new(dialog_attributes).to_attributes) do %>
+    <% if show_swipe_handle %>
+      <div data-slot="drawer-swipe-handle" aria-hidden="true" class="<%= css(:handle) %>"></div>
+    <% end %>
+    <div data-slot="drawer-header" class="<%= css(:header) %>">
+      <h2 id="<%= title_id %>" data-slot="drawer-title" class="<%= css(:title) %>"><%= title %></h2>
+      <% if description? %>
+        <p id="<%= description_id %>" data-slot="drawer-description" class="<%= css(:description) %>"><%= description %></p>
+      <% end %>
+    </div>
+    <div data-slot="drawer-body" class="<%= css(:body) %>"><%= content %></div>
+    <% if footer? %><div data-slot="drawer-footer" class="<%= css(:footer) %>"><%= footer %></div><% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Drawer family: the swipeable edge sheet on the dialog spine.
+    module Drawer
+      # A drawer: an edge-anchored dialog you can SWIPE away, most at
+      # home as the mobile bottom sheet. Everything hard is inherited
+      # from Dialog (the native <dialog> focus trap, required title,
+      # dismissible:); the drawer adds the swipe gesture, the
+      # edge-rounded popup with transition-driven enter/exit, the
+      # optional grab handle, and snap_points: preset resting heights
+      # for bottom sheets.
+      #
+      # Nested drawer stacking visuals and bleed are not supported.
+      #
+      # @example
+      #   render Poetry::Ui::Drawer::Component.new(show_swipe_handle: true) do |drawer|
+      #     drawer.with_trigger { "Open drawer" }
+      #     drawer.with_title { "Move goal" }
+      #     drawer.with_description { "Set your daily activity goal." }
+      #     "Drawer body"
+      #   end
+      class Component < Dialog::Component
+        # The closed vocabulary for the direction axis.
+        DIRECTIONS = %i[down up left right].freeze
+
+        # Accepted CSS length spellings for snap points (px or rem).
+        SNAP_POINT_LENGTH = /\A\d+(\.\d+)?(px|rem)\z/
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Open drawers with with_trigger(...) - never a hand-wired button.",
+          "with_title is REQUIRED (the accessible name) - the inherited Dialog rule.",
+          "direction: is the DISMISS direction: :down is the mobile bottom sheet (the default); " \
+          "left/right make an edge panel - prefer Sheet on desktop.",
+          "show_swipe_handle: true renders the grab pill - use it on bottom sheets so the " \
+          "gesture is discoverable.",
+          "Esc and the backdrop still dismiss (the platform trap) - the swipe is an addition, " \
+          "never the only way out.",
+          "modal: false keeps the page interactive (no scrim, no focus trap) - pair a wired " \
+          "footer close; Esc while focus is inside still exits.",
+          "snap_points: [\"31rem\", 1] snaps a bottom sheet between preset heights (ascending " \
+          "fractions or px/rem lengths; opens at the first) - direction: :down only."
+        ].freeze
+
+        # Replace-on-redeclare: both elements re-controller to :drawer;
+        # the inherited trigger lambda late-binds through stimulus_action.
+        use_stimulus do
+          on :root do
+            controller :drawer do
+              register
+              value :dismissible
+              value :direction
+              value :modal
+              value :snap_points, from: :snap_points_json, if: -> { snap_points.present? }
+            end
+          end
+          on :content do
+            controller :drawer do
+              target :dialog
+              action :close, on: :cancel
+              action :backdrop_close, on: :click
+              # A non-modal dialog never fires cancel - Esc rides its own
+              # keydown exit (guarded controller-side to modal: false).
+              action :escape_close, on: :keydown, unless: :modal
+              action :swipe_start, on: :pointerdown
+              action :swipe_move, on: :pointermove
+              action :swipe_end, on: :pointerup
+              action :swipe_cancel, on: :pointercancel
+            end
+          end
+          on :trigger do
+            controller(:drawer) { action :open }
+          end
+          # The Drawer renders no corner close button - an empty
+          # redeclaration ERASES Dialog's inherited :close element (and
+          # with it the dialog identifier that would make unqualified
+          # stimulus_action ambiguous).
+          on :close
+        end
+
+        style :direction, default: :down, required: true, variants: DIRECTIONS,
+                          doc: "The dismiss direction - :down is the mobile bottom sheet; the edge chrome and swipe " \
+                               "axis derive from it."
+
+        option :show_swipe_handle, :boolean, default: false,
+                                             doc: "Renders the grab pill so the swipe gesture is discoverable."
+
+        option :modal, :boolean, default: true,
+                                 doc: "Non-modal (false) opens with show() - no top layer, no scrim, no focus trap, " \
+                                      "no scroll lock; the page behind stays interactive. Esc (while focus is " \
+                                      "inside), the swipe, and any wired close button still exit; there is no " \
+                                      "backdrop to click, so pointer dismissal is off by nature."
+
+        option :snap_points, ActiveModel::Type::Value.new,
+               doc: "Preset resting heights for a bottom sheet, ascending: fractions of the full height (0..1] or " \
+                    "CSS px/rem lengths ([\"31rem\", 1]). The popup runs full-height and opens at the first point; " \
+                    "drags move between points, below the first dismisses. direction: :down only."
+
+        part "drawer", "Root wrapper around the trigger and the <dialog> element"
+        part "drawer-content", "The <dialog> popup - the edge chrome, presence animation, and " \
+                               "the swipe contract all ride here (::backdrop inherits the " \
+                               "swipe vars, so the overlay fade rides along)",
+             states: {
+               "data-open" => "popup is open (the controller flips the pair at runtime)",
+               "data-closed" => "popup is closed or animating out (the server-rendered state)",
+               "data-swipe-direction" => { condition: "always - the dismiss direction",
+                                           values: DIRECTIONS.map(&:to_s) },
+               "data-swiping" => "a pointer drag is tracking (transitions go duration-0 - the " \
+                                 "drawer follows the finger)",
+               "data-snap-points" => "snap_points: present - the popup runs full-height and " \
+                                     "--drawer-snap-point-offset rests it at the current point",
+               "data-starting-style" => "the enter transition's first frame (the presence " \
+                                        "helper's two-frame trick)",
+               "data-ending-style" => "held through the exit transition before the native " \
+                                      "close()"
+             },
+             vars: {
+               "--drawer-swipe-movement-x" => "px dragged toward a left/right dismissal " \
+                                              "(controller-written during swipes)",
+               "--drawer-swipe-movement-y" => "px dragged toward an up/down dismissal " \
+                                              "(controller-written during swipes)",
+               "--drawer-swipe-progress" => "0..1 fraction of the dismiss travel (the backdrop " \
+                                            "fade rides it)",
+               "--drawer-swipe-strength" => "remaining-travel factor set on release - scales " \
+                                            "the exit duration so a mostly-swiped drawer " \
+                                            "closes fast"
+             }
+        part "drawer-swipe-handle", "The grab pill (show_swipe_handle: true, aria-hidden) - a " \
+                                    "drag may always start on it"
+        part "drawer-header", "Title block at the top of the popup"
+        part "drawer-title", "The heading - the drawer's accessible name (required slot)"
+        part "drawer-description", "Muted copy under the title, wired to aria-describedby"
+        part "drawer-body", "The scrollable content region between header and footer"
+        part "drawer-footer", "Action row pinned to the bottom of the popup"
+
+        # Enforces the inherited title contract plus snap-point validity.
+        # @api private
+        def before_render
+          super
+          validate_snap_points! if snap_points.present?
+        end
+
+        # The parent's show_close_button does not apply: a Drawer has no
+        # corner X (it closes by swipe, backdrop, or footer actions), so
+        # the inherited option is hidden from introspection. A projected
+        # option the template ignores would be a contract lie.
+        # @api private
+        def self.option_attributes
+          super - %i[show_close_button]
+        end
+
+        # The <dialog> IS the drawer popup: the chrome + swipe wiring land
+        # here. The swipe vars are written to this element by the controller
+        # and ::backdrop inherits them (the overlay fade rides along).
+        # @api private
+        def dialog_attributes
+          attrs = {
+            # Non-modal show() skips the top layer, so the UA :modal
+            # positioning (fixed + inset:0) must be re-stated explicitly -
+            # the direction margins and over-constraint sizing then work
+            # exactly as they do in the top layer.
+            "class" => css(:content, class: [Style.direction(direction),
+                                             (css(:nonmodal) unless modal)].compact.join(" ")),
+            "data-slot" => "drawer-content",
+            "data-swipe-direction" => direction,
+            "data-closed" => "",
+            "aria-labelledby" => title_id
+          }.merge(stimulus_attributes_for(:content))
+          # The attribute drives the dictionary's full-height sizing; the
+          # controller reads the value for the offset physics.
+          attrs["data-snap-points"] = "" if snap_points.present?
+          attrs["aria-describedby"] = description_id if description?
+          attrs
+        end
+
+        private
+
+        def validate_snap_points!
+          unless direction == :down
+            raise ArgumentError, "Drawer snap_points: is a bottom-sheet recipe - direction: :down only"
+          end
+
+          valid = snap_points.is_a?(Array) && snap_points.any? && snap_points.all? do |point|
+            (point.is_a?(Numeric) && point.positive? && point <= 1) ||
+              (point.is_a?(String) && point.match?(SNAP_POINT_LENGTH))
+          end
+          return if valid
+
+          raise ArgumentError, "Drawer snap_points: entries are fractions in (0, 1] or CSS " \
+                               'px/rem lengths ("31rem", "400px"), ascending'
+        end
+
+        # Host-facing close descriptor (no template consumer) - the
+        # explicit click event preserved from the pre-declaration shape.
+        def close_action
+          stimulus_action(:close, on: :click)
+        end
+
+        def snap_points_json = snap_points.to_json
+
+        private :dialog_attributes
+      end
+    end
+  end
+end