poetry-ui 0.0.2

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Drawer
+      # The Drawer preview: the bottom sheet with its grab handle (the
+      # gesture's discoverability affordance), and a right-edge panel.
+      # Previews render CLOSED (the trigger page, the Dialog convention);
+      # the dommy tier drives the open/swipe behavior.
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(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.with_footer do
+              embed(Poetry::Ui::Button::Component.new.with_content("Submit"))
+            end
+            "Drag the handle down to dismiss."
+          end
+        end
+
+        def right_edge
+          render_component(direction: :right) do |drawer|
+            drawer.with_trigger { "Open panel" }
+            drawer.with_title { "Filters" }
+            "Swipe right to dismiss."
+          end
+        end
+
+        def top_sheet
+          render_component(direction: :up) do |drawer|
+            drawer.with_trigger { "Open notice" }
+            drawer.with_title { "Service notice" }
+            "Swipe up to dismiss."
+          end
+        end
+
+        def left_edge
+          render_component(direction: :left) do |drawer|
+            drawer.with_trigger { "Open navigation" }
+            drawer.with_title { "Navigate" }
+            "Swipe left to dismiss."
+          end
+        end
+
+        # modal: false keeps the page interactive behind the drawer -
+        # Esc rides its own keydown exit (a non-modal dialog never fires
+        # cancel).
+        def non_modal
+          render_component(modal: false) do |drawer|
+            drawer.with_trigger { "Open player" }
+            drawer.with_title { "Now playing" }
+            "The page stays interactive behind this drawer."
+          end
+        end
+
+        # snap_points: the swipe physics settle at fractional heights.
+        def with_snap_points
+          render_component(snap_points: [0.4, 1]) do |drawer|
+            drawer.with_trigger { "Open details" }
+            drawer.with_title { "Details" }
+            "Drag the handle - the sheet settles at 40% or full height."
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Drawer
+      # Re-expressed through the cn-* theme layer, still the
+      # native-dialog swipe spine. The ENTIRE swipe mechanism stays inline
+      # (transform vars, swipe-progress backdrop math, starting/ending
+      # transforms, the direction margin geometry + closed-transform vars)
+      # - a swapped theme can restyle surfaces but never break the gesture.
+      # Margins stay dictionary-side ON BOTH content and directions so the
+      # merger keeps collapsing m-0 against the side margins exactly as
+      # before (the split-side conflict rule, applied by keeping the
+      # conflict on the inline side this time). Corners/edges/surface ride
+      # the theme. Snap points landed 2026-08-01; nested-stack visuals
+      # and bleed stay deferred.
+      class Style < Poetry::Core::Style
+        # open:flex, not flex: never defeat the UA's dialog:not([open])
+        # display:none (the Dialog browser-pass lesson).
+        # Scrim color + blur are theme-owned: each
+        # themes/<name>.css carries backdrop:bg-* / backdrop-blur-* on
+        # .cn-drawer-content. Only the swipe machinery (transition +
+        # opacity calc) stays structural here.
+        # No `relative`: the top layer discards it and the UA reasserts
+        # `absolute`, pinning the drawer to the DOCUMENT edge (it scrolls
+        # off-screen below the fold). The UA `:modal` rule keeps it
+        # viewport-fixed so the direction auto-margins pin it to the viewport
+        # edge; the swipe transform rides on top.
+        element :content,
+                "cn-drawer-content m-0 open:flex min-h-0 flex-col " \
+                "outline-none select-none will-change-transform " \
+                "transition-[transform,opacity] duration-450 ease-[cubic-bezier(0.22,1,0.36,1)] " \
+                "transform-[translate3d(var(--translate-x,0px),var(--translate-y,0px),0)] " \
+                "data-swiping:duration-0 " \
+                "data-starting-style:transform-(--closed-transform) " \
+                "data-ending-style:transform-(--closed-transform) " \
+                "data-ending-style:duration-[calc(var(--drawer-swipe-strength,1)*400ms)] " \
+                "backdrop:transition-opacity backdrop:duration-450 " \
+                "backdrop:opacity-[calc(1-var(--drawer-swipe-progress,0))] " \
+                "data-swiping:backdrop:transition-none"
+
+        # The dismiss-direction geometry: top-layer edge margins + the
+        # direction's closed transform, with the controller's positive
+        # movement mapped onto the axis (negative directions invert it).
+        # The corner/edge treatment rides cn-drawer-direction-*.
+        # --drawer-inset (theme-owned; upstream's "floats the drawer from
+        # the viewport edges", default 0px = flush) gaps every non-anchored
+        # edge: the anchored side swaps its 0-margin for the inset, the
+        # cross axis swaps its explicit size (w-full/h-full) for auto so
+        # the UA's inset:0 over-constraint fills viewport-minus-margins
+        # (identical to the full size at 0px), and the closed transform
+        # travels the extra inset so the exit still clears the viewport.
+        # rhea/mira/luma/maia ship --spacing(2), like their source styles.
+        variant :direction, {
+          # down/up wear h-fit, never h-auto: the UA :modal sets top:0 AND
+          # bottom:0, and an abspos box with both insets and height:auto
+          # SOLVES height to fill (CSS2 10.6.4) - h-auto blew every bottom
+          # sheet up to its max-h cap. fit-content restores the UA's own
+          # content sizing; the auto margin still bottom-anchors. The
+          # x-axis directions keep h-auto: there fill IS the intent, the
+          # edge panel runs the full viewport.
+          down: "cn-drawer-direction-down mt-auto mb-(--drawer-inset,0px) mx-(--drawer-inset,0px) " \
+                "h-fit w-auto max-w-none max-h-[calc(100dvh-6rem)] " \
+                "data-snap-points:h-dvh data-snap-points:max-h-none " \
+                "[--closed-transform:translate3d(0,calc(100%+var(--drawer-inset,0px)+2px),0)] " \
+                "[--translate-y:calc(var(--drawer-snap-point-offset,0px)+var(--drawer-swipe-movement-y,0px))]",
+          up: "cn-drawer-direction-up mb-auto mt-(--drawer-inset,0px) mx-(--drawer-inset,0px) " \
+              "h-fit w-auto max-w-none max-h-[calc(100dvh-6rem)] " \
+              "[--closed-transform:translate3d(0,calc(-100%-var(--drawer-inset,0px)-2px),0)] " \
+              "[--translate-y:calc(-1*var(--drawer-swipe-movement-y,0px))]",
+          left: "cn-drawer-direction-left mr-auto ml-(--drawer-inset,0px) my-(--drawer-inset,0px) " \
+                "h-auto max-h-none w-3/4 sm:max-w-sm " \
+                "[--closed-transform:translate3d(calc(-100%-var(--drawer-inset,0px)-2px),0,0)] " \
+                "[--translate-x:calc(-1*var(--drawer-swipe-movement-x,0px))]",
+          right: "cn-drawer-direction-right ml-auto mr-(--drawer-inset,0px) my-(--drawer-inset,0px) " \
+                 "h-auto max-h-none w-3/4 sm:max-w-sm " \
+                 "[--closed-transform:translate3d(calc(100%+var(--drawer-inset,0px)+2px),0,0)] " \
+                 "[--translate-x:var(--drawer-swipe-movement-x,0px)]"
+        }
+
+        # The grab pill (touch-none keeps the browser from stealing the
+        # drag for scroll); the pill's look rides the theme rule.
+        element :handle, "cn-drawer-swipe-handle relative z-10 mx-auto flex h-3 w-full shrink-0 " \
+                         "cursor-grab touch-none items-center justify-center active:cursor-grabbing " \
+                         "after:block after:shrink-0"
+
+        element :header, "cn-drawer-header flex shrink-0 flex-col"
+        # Non-modal show() skips the top layer; the UA :modal positioning
+        # must be restated (dictionary-resident so safelists ship it).
+        element :nonmodal, "fixed inset-0 z-50"
+        element :footer, "cn-drawer-footer mt-auto flex shrink-0 flex-col"
+        element :title, "cn-drawer-title"
+        element :description, "cn-drawer-description text-balance"
+        element :body, "cn-drawer-body flex min-h-0 flex-1 flex-col overflow-y-auto overscroll-contain"
+
+        # The direction's edge classes for the <dialog> element (the Sheet
+        # resolver pattern: variants render at the dictionary root, and the
+        # Drawer's visual root is the :content element).
+        def self.direction(value)
+          resolver.variants.fetch(:direction).fetch(value.to_sym)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= trigger %>
+  <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(content_attributes).to_attributes) do %>
+    <% items.each do |item| %><%= item %><% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The DropdownMenu family - the button-triggered action menu.
+    module DropdownMenu
+      # The closed vocabulary for the side placement axis.
+      SIDES = %i[top right bottom left].freeze
+      # The closed vocabulary for the align placement axis.
+      ALIGNS = %i[start center end].freeze
+      # The closed vocabulary for the dir (reading direction) axis.
+      DIRS = %i[ltr rtl].freeze
+
+      # The shared menus item union wearing this family's identity -
+      # SLOT_BUILDERS is added in a reopen at the bottom of the file,
+      # once the family classes it names exist.
+      module ItemSlots
+        extend ActiveSupport::Concern
+        include Poetry::Ui::Menus::ItemSlots
+      end
+
+      # A dropdown menu: a button that opens a popup list of actions
+      # (role=menu), composed from items, checkbox items, radio groups,
+      # labels, separators, groups, and nested submenus. Reach for it
+      # when one control offers several actions; choosing a form VALUE
+      # belongs to Select or Combobox instead.
+      #
+      # Requires with_trigger (the menu button) and at least one item.
+      # Arrow-key navigation, typeahead, and focus containment activate
+      # when the menu opens; the closed menu renders inert and hidden.
+      #
+      # @example A menu button with actions
+      #   render Poetry::Ui::DropdownMenu::Component.new do |menu|
+      #     menu.with_trigger(variant: :outline) { "Open" }
+      #     menu.with_item { "Rename" }
+      #     menu.with_item(variant: :destructive) { "Delete" }
+      #   end
+      class Component < Poetry::Core::Component
+        include Poetry::Ui::ComposableTrigger
+
+        include ItemSlots
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          ComposableTrigger::AGENT_RULE,
+          "Use poetry_dropdown_menu - never hand-roll role=menu popups with Tailwind.",
+          "Items are ACTIONS. Choosing a form VALUE is a Select/Combobox - do not fake it with radio items.",
+          "Navigation items pass with_item(href:) (external: for a new tab); a form action (sign-out, a " \
+          "DELETE) passes with_item(submit:, method:). The item renders AS the anchor / submit button " \
+          "(role=menuitem on the <a> or <button>) - one interactive element - so NEVER nest a link_to or " \
+          "button_to inside an item.",
+          "Icon-only triggers MUST have an accessible name (the composed Button's label: rule).",
+          "Never write the state attributes (data-popup-open / data-checked / data-unchecked) without " \
+          "their aria twin (aria-expanded / aria-checked) - the controller writes both; agents patching " \
+          "DOM must too.",
+          "Destructive items use variant: :destructive AND still confirm irreversible actions via a dialog.",
+          "shortcut: is a visual hint only - it does NOT bind the key; wire a real hotkey separately or omit it.",
+          "Do not nest interactive elements inside items (a menuitem IS the interactive unit).",
+          "Keep submenus <= 2 levels; prefer grouping + separators over deep nesting.",
+          "Critical actions must exist somewhere reachable without JS (menus are JS-required interaction)."
+        ].freeze
+
+        # Slot-to-component map: with_trigger renders a Button, so callers
+        # get Button's full option and slot contract on the trigger.
+        SLOT_RENDERS = { trigger: Button::Component }.freeze
+
+        renders_one :trigger,
+                    doc: "The menu button - a poetry Button (options forward to it, e.g. variant: :outline). The " \
+                         "slot owns the aria-haspopup/expanded/ controls wiring regardless of the composed content, " \
+                         "so composition cannot drop the aria.",
+                    renders: lambda { |**options, &block|
+                      wiring = {
+                        "id" => trigger_id, "data-slot" => "dropdown-menu-trigger",
+                        "aria-haspopup" => "menu", "aria-expanded" => open.to_s, "aria-controls" => content_id
+                      }.merge(stimulus_attributes_for(:trigger))
+                      # Trigger state: bare data-popup-open while open, NO attribute
+                      # while closed (absence IS the state).
+                      wiring["data-popup-open"] = "" if open
+                      composed_trigger(wiring, options, &block) || begin
+                        options[:disabled] = true if disabled && !options.key?(:disabled)
+                        Button::Component.new(**wiring, **options, &block)
+                      end
+                    }
+
+        # The content's layer behaviors (focus containment, dismissal,
+        # roving focus) are attached by the menu controller on open rather
+        # than declared statically here - a statically-connected focus
+        # trap on a hidden menu would steal focus at page load.
+        use_stimulus do
+          on :root do
+            controller :menu do
+              register
+              value :open
+              value :modal
+              value :loop
+            end
+            controller :popper do
+              register
+              value :side
+              value :align
+              value :side_offset
+              value :align_offset
+              value :avoid_collisions
+            end
+          end
+          on :trigger do
+            controller :menu do
+              action :toggle, on: :click
+              action :trigger_keydown, on: :keydown
+            end
+            controller(:popper) { target :anchor }
+          end
+          on :content do
+            controller(:popper) { target :content }
+          end
+          # Anatomy-rendered wiring, declared here so the contract covers
+          # the whole family surface (items + submenus render via the
+          # escape hatch in the anatomy classes).
+          on :item do
+            controller(:menu) { action :activate, on: :click }
+          end
+          on :sub_trigger do
+            controller :menu do
+              action :sub_enter, on: :pointerenter
+              action :sub_leave, on: :pointerleave
+              action :open_sub, on: :click
+            end
+            controller(:popper) { target :anchor }
+          end
+        end
+
+        option :open, :boolean, default: false, doc: "Renders the menu already open on page load."
+        option :modal, :boolean, default: true,
+                                 doc: "While open, pointer interaction outside the menu is blocked; false keeps the " \
+                                      "rest of the page interactive."
+        option :side, :symbol, default: :bottom,
+                               doc: "Which side of the trigger the menu opens on (flips on collision)."
+        option :align, :symbol, default: :center, doc: "The menu's alignment against the trigger's edge."
+        option :side_offset, :integer, default: 4, doc: "Gap in pixels between the trigger and the menu."
+        option :align_offset, :integer, default: 0, doc: "Pixel shift along the alignment edge."
+        option :avoid_collisions, :boolean, default: true,
+                                            doc: "Flips/shifts placement to keep the menu inside the viewport."
+        option :loop, :boolean, default: false, doc: "Arrow-key navigation wraps from the last item back to the first."
+        option :dir, :symbol, doc: "Reading direction; :rtl flips submenu sides and indicators."
+        option :disabled, :boolean, default: false, doc: "Disables the menu trigger button."
+
+        validates :side, inclusion: { in: SIDES }
+        validates :align, inclusion: { in: ALIGNS }
+        validates :dir, inclusion: { in: DIRS }, allow_nil: true
+
+        # (dropdown-menu-trigger rides the composed Button, so that element
+        # belongs to Button's anatomy, not this contract.)
+        part "dropdown-menu", "Root wrapper hosting the menu + popper controllers around the trigger " \
+                              "and content"
+        part "dropdown-menu-content", "The role=menu popup panel - positioning, animation, and the " \
+                                      "open state ride here",
+             states: {
+               "data-open" => "menu is open (presence flips the pair at runtime)",
+               "data-closed" => "menu is closed or animating out (the server-rendered state)",
+               "data-side" => { condition: "the placement side (popper re-writes it after collision flips)",
+                                values: %w[top right bottom left] },
+               "data-align" => { condition: "the alignment against the trigger (popper re-resolves it)",
+                                 values: %w[start center end] }
+             },
+             vars: {
+               "--transform-origin" => "popper's anchor-facing animation origin",
+               "--available-width" => "popper: viewport space left for the panel (post-flip)",
+               "--available-height" => "popper: viewport space left for the panel (post-flip)",
+               "--anchor-width" => "popper: the trigger's measured width",
+               "--anchor-height" => "popper: the trigger's measured height"
+             }
+        part "dropdown-menu-group", "role=group semantic grouping between separators"
+        part "dropdown-menu-label", "Non-interactive heading for a run of items",
+             states: {
+               "data-inset" => "indented to align with checkbox/radio item text (inset: true)"
+             }
+        part "dropdown-menu-item", "One role=menuitem action row",
+             states: {
+               "data-variant" => "default or destructive (the danger treatment)",
+               "data-inset" => "indented to align with checkbox/radio item text (inset: true)",
+               "data-disabled" => "item is disabled (always written together with aria-disabled)"
+             }
+        part "dropdown-menu-checkbox-item", "A role=menuitemcheckbox toggle row",
+             states: {
+               "data-checked" => "checked (the controller re-writes the pair with aria-checked on " \
+                                 "activation)",
+               "data-unchecked" => "unchecked",
+               "data-disabled" => "item is disabled (always written together with aria-disabled)",
+               "data-close-on-select" => "per-item override of the menu's close-on-select default " \
+                                         "(\"false\" keeps the menu open)"
+             }
+        part "dropdown-menu-radio-group", "role=group scoping one single-select value",
+             states: {
+               "data-value" => "the selected radio value (the controller re-writes it on change)"
+             }
+        part "dropdown-menu-radio-item", "A role=menuitemradio row inside a radio group",
+             states: {
+               "data-checked" => "the selected radio (the controller re-writes the pair with aria-checked)",
+               "data-unchecked" => "not selected",
+               "data-value" => "the radio's value",
+               "data-disabled" => "item is disabled (always written together with aria-disabled)"
+             }
+        part "dropdown-menu-checkbox-item-indicator",
+             "The check glyph inside checkbox items (aria-hidden; the item carries the checked state)"
+        part "dropdown-menu-radio-item-indicator",
+             "The circle glyph inside radio items (aria-hidden; the item carries the checked state)"
+        part "dropdown-menu-separator", "role=separator rule between groups"
+        part "dropdown-menu-shortcut", "The trailing keybinding HINT - aria-hidden, never binds the key"
+        part "dropdown-menu-sub", "A submenu scope - hosts its own popper around the sub trigger/" \
+                                  "content pair"
+        part "dropdown-menu-sub-trigger", "The role=menuitem row opening its submenu",
+             states: {
+               "data-popup-open" => "its submenu is open (written with aria-expanded; absence is the " \
+                                    "closed state)",
+               "data-inset" => "indented to align with checkbox/radio item text (inset: true)"
+             }
+        part "dropdown-menu-sub-content", "The nested role=menu panel - its own popper content on the " \
+                                          "same presence machinery",
+             states: {
+               "data-open" => "submenu is open (presence flips the pair at runtime)",
+               "data-closed" => "submenu is closed (the server-rendered state)",
+               "data-side" => { condition: "the placement side (right/left by direction; popper resolves " \
+                                           "it at runtime)",
+                                values: %w[top right bottom left] },
+               "data-align" => { condition: "the alignment against the sub-trigger (popper resolves it " \
+                                            "at runtime)",
+                                 values: %w[start center end] }
+             },
+             vars: {
+               "--transform-origin" => "popper's anchor-facing animation origin",
+               "--available-width" => "popper: viewport space left for the panel (post-flip)",
+               "--available-height" => "popper: viewport space left for the panel (post-flip)",
+               "--anchor-width" => "popper: the sub-trigger's measured width",
+               "--anchor-height" => "popper: the sub-trigger's measured height"
+             }
+
+        # Enforces the required slots before render.
+        # @api private
+        def before_render
+          raise ArgumentError, "DropdownMenu requires with_trigger (the menu button)" unless trigger?
+          raise ArgumentError, "DropdownMenu requires at least one item" unless items?
+        end
+
+        # The trigger element's server-stable id.
+        # @api private
+        def trigger_id
+          "#{instance_id}-trigger"
+        end
+
+        # The content element's server-stable id (aria-controls target).
+        # @api private
+        def content_id
+          "#{instance_id}-content"
+        end
+
+        # The root wrapper's attributes.
+        # @api private
+        def root_attributes
+          root = { "data-slot" => "dropdown-menu" }
+          root["dir"] = dir.to_s if dir
+          html_attributes.merge_if_not_set(
+            root.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # The role=menu panel's attributes.
+        # @api private
+        def content_attributes
+          attrs = {
+            "id" => content_id, "role" => "menu", "aria-orientation" => "vertical",
+            "aria-labelledby" => trigger_id, "tabindex" => "-1",
+            "data-slot" => "dropdown-menu-content", (open ? "data-open" : "data-closed") => "",
+            # Initial placement, re-resolved live by popper on open.
+            "data-side" => side, "data-align" => align,
+            "class" => css(:content)
+          }.merge(stimulus_attributes_for(:content))
+          attrs["hidden"] = true unless open
+          attrs
+        end
+
+        private
+
+        def menu_dir
+          dir
+        end
+
+        # Server-stable unique id pair for the aria wiring (two menus on
+        # one page must not share ids); portal-safe (the controller
+        # resolves content via aria-controls, not a Stimulus target).
+        def instance_id
+          @instance_id ||= poetry_instance_id("poetry-dropdown-menu")
+        end
+
+        private :trigger_id, :content_id, :root_attributes, :content_attributes
+      end
+
+      # role=group semantic grouping between separators - the shared kernel
+      # anatomy wearing this family identity.
+      #
+      # @api private
+      class Group < Poetry::Ui::Menus::Group
+        include ItemSlots
+      end
+
+      # role=group scoping the single-select value for its radio items -
+      # the shared kernel anatomy wearing this family identity.
+      #
+      # @api private
+      class RadioGroup < Poetry::Ui::Menus::RadioGroup
+      end
+
+      # A submenu scope (recursive item union on its own popper) - the
+      # shared kernel anatomy wearing this family identity.
+      #
+      # @api private
+      class Sub < Poetry::Ui::Menus::Sub
+        include ItemSlots
+      end
+
+      # The builder classes behind lambda-wrapped slot types: a lambda
+      # hides its return class from introspection, so the owner declares
+      # it and the registry walker recurses into the builder's own call
+      # surface (with_sub yields a Sub with its own items).
+      module ItemSlots
+        # Nested-slot recursion map for the registry projection.
+        SLOT_BUILDERS = { sub: Sub, group: Group, radio_group: RadioGroup }.freeze
+      end
+
+      class Component
+        # The slots before_render enforces, stated statically for render-free checks.
+        REQUIRED_SLOTS = { trigger: "the menu button", item: "at least one item" }.freeze
+      end
+
+      class Group
+        # The slots before_render enforces, stated statically for render-free checks.
+        REQUIRED_SLOTS = { item: "at least one item" }.freeze
+      end
+
+      class RadioGroup
+        # The slots before_render enforces, stated statically for render-free checks.
+        REQUIRED_SLOTS = { radio_item: "at least one radio item" }.freeze
+      end
+
+      class Sub
+        # The slots before_render enforces, stated statically for render-free checks.
+        REQUIRED_SLOTS = { trigger: "the sub-menu item", item: "at least one item" }.freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module DropdownMenu
+      # The DropdownMenu preview matrix: the ported demo composition plus
+      # both item variants, both toggle kinds, inset, disabled, a 2-deep
+      # sub, RTL, and the server-rendered open state.
+      class Preview < Poetry::Core::Preview::Base
+        # The dropdown-menu-demo port: Button trigger, label, grouped items
+        # with shortcuts, a submenu, a disabled item, a destructive tail.
+        def default
+          render_component(align: :start) do |menu|
+            menu.with_trigger(variant: :outline) { "Open" }
+            menu.with_label { "My Account" }
+            menu.with_group do |group|
+              group.with_item(shortcut: "⇧⌘P") { "Profile" }
+              group.with_item(shortcut: "⌘B") { "Billing" }
+              group.with_item(shortcut: "⌘S") { "Settings" }
+            end
+            menu.with_separator
+            menu.with_sub do |sub|
+              sub.with_trigger { "Invite users" }
+              sub.with_item { "Email" }
+              sub.with_item { "Message" }
+              sub.with_sub do |nested|
+                nested.with_trigger { "More..." }
+                nested.with_item { "Import from CSV" }
+              end
+            end
+            menu.with_separator
+            menu.with_item(disabled: true) { "API" }
+            menu.with_item(variant: :destructive, shortcut: "⇧⌘Q") { "Log out" }
+          end
+        end
+
+        # dropdown-menu-checkboxes parity: toggles keep the menu open.
+        def checkboxes
+          render_component(align: :start) do |menu|
+            menu.with_trigger(variant: :outline) { "View" }
+            menu.with_label { "Appearance" }
+            menu.with_separator
+            menu.with_checkbox_item(checked: true, close_on_select: false) { "Status Bar" }
+            menu.with_checkbox_item(checked: false, close_on_select: false, disabled: true) { "Activity Bar" }
+            menu.with_checkbox_item(checked: false, close_on_select: false) { "Panel" }
+          end
+        end
+
+        # dropdown-menu-radio-group parity: one checked value per group.
+        def radio_group
+          render_component(align: :start) do |menu|
+            menu.with_trigger(variant: :outline) { "Panel Position" }
+            menu.with_label { "Panel Position" }
+            menu.with_separator
+            menu.with_radio_group(value: "bottom") do |group|
+              group.with_radio_item(value: "top") { "Top" }
+              group.with_radio_item(value: "bottom") { "Bottom" }
+              group.with_radio_item(value: "right") { "Right" }
+            end
+          end
+        end
+
+        # inset aligns flush items with the checkbox/radio gutter.
+        def inset_and_disabled
+          render_component do |menu|
+            menu.with_trigger(variant: :outline) { "Edit" }
+            menu.with_label(inset: true) { "Actions" }
+            menu.with_item(inset: true) { "Undo" }
+            menu.with_item(inset: true, disabled: true) { "Redo" }
+            menu.with_separator
+            menu.with_checkbox_item(checked: true, close_on_select: false) { "Autosave" }
+          end
+        end
+
+        # The submenu side flips under RTL (chevron mirrors via ml-auto).
+        def rtl
+          render_component(dir: :rtl) do |menu|
+            menu.with_trigger(variant: :outline) { "فتح" }
+            menu.with_item { "الملف الشخصي" }
+            menu.with_sub do |sub|
+              sub.with_trigger { "المزيد" }
+              sub.with_item { "استيراد" }
+            end
+          end
+        end
+
+        # Server-rendered open state (controllable-state: the attributes
+        # are the store; the controller reconciles on connect).
+        def open
+          render_component(open: true, align: :start) do |menu|
+            menu.with_trigger(variant: :outline) { "Open" }
+            menu.with_label { "My Account" }
+            menu.with_item { "Profile" }
+            menu.with_separator
+            menu.with_item(variant: :destructive) { "Delete" }
+          end
+        end
+      end
+    end
+  end
+end