poetry-ui 0.0.2

data/app/components/poetry/ui/command/dialog_component.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Command
+      # The Command palette inside a modal dialog - the app-wide "press
+      # Cmd+K" search. The native <dialog> focus trap does the overlay
+      # work; the dialog's title and description are screen-reader-only
+      # (localized defaults name the dialog), so the visible surface is
+      # the palette itself.
+      #
+      # The global hotkey is OPT-IN (hotkey: "meta+k") and toggles the
+      # dialog from anywhere; the trigger button remains the visible way
+      # in. Items use Command's contract: act on poetry:command:select.
+      #
+      # @example
+      #   render Poetry::Ui::Command::DialogComponent.new(hotkey: "meta+k") do |dialog|
+      #     dialog.with_trigger(variant: :outline) { "Open palette" }
+      #     dialog.with_item(value: "settings") { "Settings" }
+      #   end
+      class DialogComponent < Poetry::Core::Component
+        # The palette surface delegates to the embedded Command - callers
+        # use the same slot API as bare poetry_command.
+        delegate :with_item, :with_group, :with_separator, :with_empty, :with_loading, to: :command
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "App-wide palettes use poetry_command_dialog with hotkey: ('meta+k') - never a hand-wired " \
+          "window keydown listener around poetry_dialog.",
+          "Open it with with_trigger(...) too - the hotkey is an accelerator, not the only way in.",
+          "The sr-only title/description default to the source strings - override title:/description: " \
+          "rather than removing them (they are the dialog's accessible name).",
+          "Item wiring is Command's: act on poetry:command:select; close the dialog in the listener if " \
+          "the action should dismiss the palette.",
+          "The close X is off by default (keyboard-first: Esc, the backdrop, or picking an item closes it) " \
+          "and appears with dismissible: false; show_close_button: true forces it - it seats in the input " \
+          "row, never over it."
+        ].freeze
+
+        renders_one :trigger,
+                    doc: "The trigger is a poetry Button wired to open - the Dialog pattern: with_trigger(variant: " \
+                         ":outline) { \"Open palette\" }.",
+                    renders: lambda { |**options, &block|
+                      options[:data] = { action: stimulus_action(:open) }.merge(options[:data] || {})
+                      Button::Component.new(**options, &block)
+                    }
+
+        # The SHARED dialog controller (zero new JS) - hotkey included.
+        use_stimulus do
+          on :root do
+            controller :dialog do
+              register
+              value :dismissible
+              value :hotkey, if: -> { hotkey.present? }
+            end
+          end
+          on :content do
+            controller :dialog do
+              target :dialog
+              action :close, on: :cancel
+              action :backdrop_close, on: :click
+            end
+          end
+          on :trigger do
+            controller(:dialog) { action :open }
+          end
+          on :close do
+            controller(:dialog) { action :close }
+          end
+        end
+
+        option :title, :string, default: -> { I18n.t("poetry.command.dialog_title") },
+                                doc: "The dialog's sr-only accessible name (localized default) - override rather " \
+                                     "than remove."
+        option :description, :string, default: -> { I18n.t("poetry.command.dialog_description") },
+                                      doc: "The sr-only description wired to aria-describedby (localized default)."
+        option :hotkey, :string,
+               doc: "A global shortcut (\"meta+k\") that toggles the palette from anywhere; an accelerator, not the " \
+                    "only way in."
+        option :dismissible, :boolean, default: true, doc: "Backdrop clicks close the palette; false keeps it open."
+        option :show_close_button, :boolean,
+               default: -> { !dismissible },
+               doc: "The close X, seated in the input row. Off by default while backdrop clicks close the " \
+                    "palette (Esc, the backdrop, or picking an item all close it); on when dismissible: " \
+                    "false so a pointer has a way out. Pass true to always show it."
+        option :filter, :boolean, default: true, doc: "Passed through to the embedded Command: client-side filtering."
+        option :loop, :boolean, default: false, doc: "Passed through: wraps arrow-key highlight movement at the ends."
+        option :placeholder, :string, doc: "Passed through: the filter input's placeholder text."
+        option :list_label, :string, doc: "Passed through: the listbox's accessible name."
+        option :value, :string, doc: "Passed through: seats the initial highlight on this item value."
+        option :id, :string, doc: "Passed through: the embedded palette's base DOM id."
+
+        part "command-dialog", "Root wrapper around the trigger and the <dialog> - the " \
+                               "palette's own chrome; the embedded Command inside carries its " \
+                               "own part contract"
+        # The dialog-* parts below are Dialog's panel chrome REUSED (same
+        # controller, own template) - declared here because this component
+        # renders them itself, retuned for the palette.
+        part "dialog-content", "The <dialog> panel (Dialog's chrome retuned to overflow-hidden " \
+                               "p-0) - positioning, animation, and the open state ride here",
+             states: {
+               "data-open" => "panel is open (the dialog controller flips the pair at runtime)",
+               "data-closed" => "panel is closed or animating out (the server-rendered state)"
+             }
+        part "dialog-header", "Dialog's title block, sr-only here - the palette owns the " \
+                              "visible surface"
+        part "dialog-title", "The sr-only heading - the dialog's accessible name (defaults to " \
+                             "the source string)"
+        part "dialog-description", "The sr-only description wired to aria-describedby"
+
+        # data-component self-id: "command-dialog", not the path-derived
+        # "dialog" (which would shadow Dialog's own self-identification).
+        # @api private
+        def self.component_title
+          "command-dialog"
+        end
+
+        # The embedded Command. Its sizing inside the dialog is the theme's
+        # own (the default theme's .cn-command-dialog rule carries the
+        # classic h-12 chain; the styled ports keep their well and rows).
+        # @api private
+        def command
+          @command ||= begin
+            options = {
+              filter: filter, loop: loop, value: value,
+              "aria-label" => I18n.t("poetry.command.input_label")
+            }
+            options[:placeholder] = placeholder if placeholder.present?
+            options[:list_label] = list_label if list_label.present?
+            options[:id] = id if id.present?
+            Component.new(**options).tap do |palette|
+              palette.input_trailing = -> { close_button } if show_close_button
+            end
+          end
+        end
+
+        # The close X: Dialog's ghost icon-sm button, seated in the input row
+        # by the embedded Command (static beats the themed absolute offset).
+        # Rendered in THIS component's view context when the row renders.
+        # @api private
+        def close_button
+          classes = Poetry::Ui::Dialog::Style.css(:close, class: Style.css(:dialog_close))
+          render(Poetry::Ui::Button::Component.new(variant: :ghost, size: :"icon-sm",
+                                                   label: t("poetry.dialog.close"),
+                                                   class: classes, data: { action: close_action })) do
+            render(Poetry::Ui::Icon::Component.new(name: :x))
+          end
+        end
+
+        # The sr-only title's id - the dialog's aria-labelledby target.
+        # @api private
+        def title_id
+          "#{instance_id}-title"
+        end
+
+        # The sr-only description's id - the aria-describedby target.
+        # @api private
+        def description_id
+          "#{instance_id}-description"
+        end
+
+        # Attributes for the root wrapper.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "command-dialog" }
+              .merge(stimulus_attributes_for(:root))
+              .merge(component_data_attributes)
+          )
+        end
+
+        # Dialog's content chrome retuned for the palette (overflow-hidden
+        # p-0 win on conflicts); labelled/described by the sr-only header.
+        # @api private
+        def dialog_attributes
+          {
+            "class" => Poetry::Ui::Dialog::Style.css(:content, class: Style.css(:dialog_content)),
+            "data-slot" => "dialog-content",
+            "data-closed" => "",
+            "aria-labelledby" => title_id,
+            "aria-describedby" => description_id
+          }.merge(stimulus_attributes_for(:content))
+        end
+
+        # Validated action descriptor for the template's close button.
+        # @api private
+        def close_action
+          stimulus_action(:close)
+        end
+
+        private
+
+        # (Descriptor strings resolve through the declared elements above,
+        # never through hand-written wiring.)
+
+        # Server-stable unique id for the aria wiring (two palettes on one
+        # page must not share label ids).
+        def instance_id
+          @instance_id ||= poetry_instance_id("poetry-command-dialog")
+        end
+
+        private :command, :close_button, :title_id, :description_id, :root_attributes, :dialog_attributes, :close_action
+      end
+    end
+  end
+end

data/app/components/poetry/ui/command/dialog_preview.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Command
+      # The CommandDialog preview - the trigger-opened palette (the modal
+      # behaviors live in the browser pass; previews cover markup).
+      class DialogPreview < Poetry::Core::Preview::Base
+        def default
+          render_component do |palette|
+            palette.with_trigger(variant: :outline) { "Open command palette" }
+            palette.with_group(heading: "Suggestions") do |group|
+              group.with_item(value: "calendar") { "Calendar" }
+              group.with_item(value: "emoji") { "Search Emoji" }
+            end
+            palette.with_group(heading: "Settings") do |group|
+              group.with_item(value: "profile", shortcut: "⌘P") { "Profile" }
+            end
+          end
+        end
+
+        def close_button
+          render_component(show_close_button: true) do |palette|
+            palette.with_trigger(variant: :outline) { "Open with a close button" }
+            palette.with_item(value: "calendar") { "Calendar" }
+            palette.with_item(value: "emoji") { "Search Emoji" }
+          end
+        end
+
+        def with_hotkey
+          render_component(hotkey: "meta+k") do |palette|
+            palette.with_trigger(variant: :outline) { "⌘K" }
+            palette.with_item(value: "calendar") { "Calendar" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Command
+      # The Command preview matrix: the ported command-demo composition
+      # (inline, groups + shortcuts + keywords), the ⌘K dialog variant,
+      # the zero-match empty state, disabled items, the filter:false
+      # server mode, an initial value: highlight, and RTL.
+      class Preview < Poetry::Core::Preview::Base
+        # The command-demo port: grouped commands with shortcuts; Calendar
+        # carries keywords ("schedule" finds it), Calculator is disabled.
+        # Type to filter live; a non-matching query shows the empty part
+        # and announces "0 results".
+        def default
+          render_component(placeholder: "Type a command or search...",
+                           "aria-label": "Command palette",
+                           class: "rounded-lg border shadow-md") do |command|
+            command.with_group(heading: "Suggestions") do |group|
+              group.with_item(value: "calendar", keywords: %w[schedule dates]) { "Calendar" }
+              group.with_item(value: "emoji") { "Search Emoji" }
+              group.with_item(value: "calculator", disabled: true) { "Calculator" }
+            end
+            command.with_separator
+            command.with_group(heading: "Settings") do |group|
+              group.with_item(value: "profile", shortcut: "⌘P") { "Profile" }
+              group.with_item(value: "billing", shortcut: "⌘B") { "Billing" }
+              group.with_item(value: "settings", shortcut: "⌘S") { "Settings" }
+            end
+          end
+        end
+
+        # command-dialog parity: the ⌘K palette - the trigger button (and
+        # the opt-in meta+k hotkey) open the Dialog; focus lands in the
+        # input; Esc closes via the platform dialog.
+        def dialog
+          render(Poetry::Ui::Command::DialogComponent.new(hotkey: "meta+k",
+                                                          placeholder: "Type a command or search...")) do |palette|
+            palette.with_trigger(variant: :outline) { "Open command palette (⌘K)" }
+            palette.with_group(heading: "Suggestions") do |group|
+              group.with_item(value: "calendar") { "Calendar" }
+              group.with_item(value: "emoji") { "Search Emoji" }
+            end
+            palette.with_separator
+            palette.with_group(heading: "Settings") do |group|
+              group.with_item(value: "profile", shortcut: "⌘P") { "Profile" }
+              group.with_item(value: "settings", shortcut: "⌘S") { "Settings" }
+            end
+          end
+        end
+
+        # The zero-match state: type any non-matching query ("zzz") - every
+        # item hides, the custom empty part shows, and the status region
+        # announces "0 results". The pinned group survives via
+        # always_render (the source's forceMount).
+        def zero_match
+          render_component("aria-label": "Jump to", placeholder: "Search pages…",
+                           class: "rounded-lg border shadow-md") do |command|
+            command.with_empty { "Nothing matches - try fewer letters." }
+            command.with_item(value: "dashboard") { "Dashboard" }
+            command.with_item(value: "reports") { "Reports" }
+            command.with_group(heading: "Recent", always_render: true) do |group|
+              group.with_item(value: "readme", always_render: true) { "README.md" }
+            end
+          end
+        end
+
+        # Disabled items: skipped by arrows and the filter re-seat; the
+        # first ENABLED item takes the server-rendered initial highlight.
+        def disabled_items
+          render_component("aria-label": "Actions", class: "rounded-lg border shadow-md") do |command|
+            command.with_item(value: "cut", disabled: true) { "Cut" }
+            command.with_item(value: "copy") { "Copy" }
+            command.with_item(value: "paste", disabled: true) { "Paste" }
+            command.with_item(value: "delete") { "Delete" }
+          end
+        end
+
+        # An initial value: highlight, server-rendered (data-highlighted +
+        # the input's aria-activedescendant point at Billing before any JS).
+        def valued
+          render_component(value: "billing", "aria-label": "Settings",
+                           class: "rounded-lg border shadow-md") do |command|
+            command.with_item(value: "profile") { "Profile" }
+            command.with_item(value: "billing") { "Billing" }
+            command.with_item(value: "notifications") { "Notifications" }
+          end
+        end
+
+        # filter: false - the SERVER-DRIVEN mode (the source's shouldFilter=false):
+        # typing never hides items client-side; the host re-renders the
+        # list (Turbo frame ?q=) and Command keeps highlight + activation +
+        # the count announcement. The loading part is the host-toggled
+        # pending affordance.
+        def server_mode
+          render_component(filter: false, "aria-label": "Search records",
+                           placeholder: "Search customers…",
+                           class: "rounded-lg border shadow-md") do |command|
+            command.with_loading { "Searching…" }
+            command.with_item(value: "acme") { "Acme Corp" }
+            command.with_item(value: "globex") { "Globex" }
+            command.with_item(value: "initech") { "Initech" }
+          end
+        end
+
+        # dir=rtl: the search icon leads via flex order, the shortcut's
+        # ms-auto keeps it on the reading-order end (the logical-property
+        # fix over the source's ml-auto).
+        def rtl
+          render_component(dir: :rtl, "aria-label": "الأوامر", list_label: "الأوامر",
+                           placeholder: "ابحث عن أمر…", class: "rounded-lg border shadow-md") do |command|
+            command.with_group(heading: "اقتراحات") do |group|
+              group.with_item(value: "calendar", shortcut: "⌘C") { "التقويم" }
+              group.with_item(value: "search") { "بحث" }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Command
+      # Re-expressed through the cn-* theme layer. The two deliberate
+      # source deltas (data-[highlighted] over data-[selected=true]; the
+      # ms-auto RTL shortcut) now live in the theme rules. The
+      # CommandDialog's overflow-hidden/p-0 stays INLINE (the source's
+      # structural pair, carried on the component in every style); its
+      # classic h-12 sizing chain is the DEFAULT theme's .cn-command-dialog
+      # rule - the styled sources carry no chain, so the dictionary must
+      # not either (an inline utility would override all nine themes).
+      class Style < Poetry::Core::Style
+        base "cn-command flex flex-col overflow-hidden size-full"
+
+        element :input_wrapper, "cn-command-input-wrapper flex items-center"
+
+        # h-10 input inside the h-9 wrapper is source-exact (it clips
+        # identically in source; the dialog chain retunes both to h-12) -
+        # do not "fix" it to h-9/h-9.
+        element :input, "cn-command-input flex w-full outline-hidden " \
+                        "disabled:cursor-not-allowed disabled:opacity-50"
+
+        element :list, "cn-command-list overflow-x-hidden overflow-y-auto"
+
+        element :empty, "cn-command-empty"
+
+        # POETRY ADDITION: the async-pending affordance (host-toggled).
+        element :loading, "py-6 text-center text-sm"
+
+        element :group, "cn-command-group overflow-hidden"
+
+        # The source's group-heading descendant chain, landed on the part.
+        element :heading, "cn-command-group-heading"
+
+        # group/command-item: bare marker, no CSS - the vega shortcut
+        # re-color (group-data-selected/command-item) keys on it.
+        element :item, "cn-command-item group/command-item relative flex cursor-default items-center " \
+                       "outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 " \
+                       "data-disabled:opacity-50 data-disabled:pointer-events-none"
+
+        # POETRY ADDITION: the label wrapper is layout-transparent - it
+        # mirrors the item's own row (preflight blockifies svg, so a bare
+        # span would stack an icon above its text).
+        element :item_text, "flex min-w-0 items-center gap-2"
+
+        element :shortcut, "cn-command-shortcut"
+
+        element :separator, "cn-command-separator"
+
+        # POETRY ADDITION: the polite result-count live region.
+        element :status, "sr-only"
+
+        # Visually-hidden text fragments (the loading part's sr copy).
+        element :sr_only, "sr-only"
+
+        # The source's inline SearchIcon classes, named per part.
+        element :search_icon, "cn-command-input-icon"
+
+        # CommandDialog: the DialogContent override - the themes' radius
+        # retune hook plus the source's structural pair (overflow-hidden
+        # p-0), inline so it beats every theme's cn-dialog-content padding
+        # (the ports that repeat p-0 in their rule are the source's own
+        # duplicates; three ports do not, and relied on this pair).
+        element :dialog_content, "cn-command-dialog overflow-hidden p-0"
+
+        # CommandDialog: the close X seats in the input row as its trailing
+        # flex item - never laid over the input, centered by the row in
+        # every theme. static beats the themed cn-dialog-close absolute
+        # offset (utilities win), shrink-0 keeps the icon button whole
+        # beside the w-full input; size and hover stay the theme's ghost
+        # icon-sm. Dictionary-held so the safelist harvests it.
+        element :dialog_close, "static shrink-0"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/composable_trigger.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Gives an including overlay component a composable trigger:
+    # with_trigger(compose: true) yields the trigger's wiring to the
+    # block, and the block's output IS the trigger. Without compose: the
+    # classic path renders (a composed Button). compose: must be passed
+    # explicitly - the slot cannot infer intent from the block itself.
+    #
+    # The wiring hash is flat and symbol-keyed: the Stimulus behavior the
+    # overlay needs on its trigger, plus id/aria/slot where the overlay's
+    # trigger anatomy carries them - popper-positioned overlays (popover,
+    # hover card, tooltip, dropdown) hand over their full trigger anatomy,
+    # the modal family (dialog, alert, sheet, drawer) hands only the open
+    # action. data-component stays the caller's either way, so the
+    # composed control keeps its own name. Splat the wiring onto a
+    # WIRING-FREE control: a receiver with its own data-action would end
+    # up with two attributes and the first parsed wins.
+    #
+    # @example Composing your own control as the trigger
+    #   <% menu.with_trigger(compose: true) do |wiring| %>
+    #     <%= poetry_sidebar_menu_button(size: :lg, **wiring) do %>...<% end %>
+    #   <% end %>
+    module ComposableTrigger
+      # The compose-mode bullet shared by every includer's AGENT_RULES -
+      # projected into the registry, llms.txt, and the agent surface.
+      AGENT_RULE =
+        "with_trigger(compose: true) { |wiring| ... } composes YOUR control as the trigger: " \
+        "the block is yielded the trigger wiring (the Stimulus behavior the overlay needs; " \
+        "poppers add id/aria and their trigger slot, modals hand only the open action) - " \
+        "splat it onto a wiring-free control (poetry_sidebar_menu_button, a plain tag); " \
+        "without compose: the classic composed Button renders."
+
+      private
+
+      # The custom-trigger markup when compose: true, or nil for the
+      # default path. Other slot options don't combine with compose -
+      # style the composed control itself.
+      def composed_trigger(wiring, options = {}, &block)
+        return nil unless options.delete(:compose)
+        raise ArgumentError, "compose: true requires a block taking |wiring|" unless block
+
+        if options.any?
+          raise ArgumentError,
+                "with_trigger options #{options.keys.inspect} don't combine with compose: " \
+                "true - put styling on the composed control itself"
+        end
+
+        attrs = { data: {} }
+        wiring.except(:type, "type").each do |key, value|
+          name = key.to_s
+          if name.start_with?("data-")
+            attrs[:data][name.delete_prefix("data-").to_sym] = value
+          else
+            attrs[name.to_sym] = value
+          end
+        end
+        yield(attrs)
+      end
+    end
+  end
+end

data/app/components/poetry/ui/context_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 %>