lostcoords-ui 0.5.0 → 0.7.0

data/app/helpers/lostcoords/ui/choice_helper.rb

@@ -6,7 +6,7 @@ module Lostcoords::Ui
     CHOICE_LABEL = "lc-choice inline-flex min-w-0 items-start gap-related text-body text-foreground cursor-pointer has-disabled:cursor-not-allowed has-disabled:opacity-60"
 
     # card: true draws the whole label as a selectable tile, for plan or theme pickers.
-    CHOICE_CARD = "flex w-full rounded-2xl lc-squircle border border-transparent bg-(--lc-tile-bg,var(--muted)) p-content " \
+    CHOICE_CARD = "flex w-full rounded-2xl lc-squircle border border-transparent bg-tile p-content " \
       "transition-[background-color,border-color] duration-(--lc-motion-quick) ease-(--lc-ease-out) hover:bg-accent " \
       "has-checked:border-primary has-checked:bg-primary-soft has-focus-visible:outline-2 has-focus-visible:outline-offset-2 " \
       "has-focus-visible:outline-(--ring,color-mix(in_oklab,var(--primary)_50%,transparent))"
@@ -42,15 +42,18 @@ module Lostcoords::Ui
       lc_choice("switch", label, hint, false, name, unchecked_value, { type: "checkbox", role: "switch", name: name, value: value, checked: checked, class: lc_switch_class }, attributes)
     end
 
-    # A fieldset of checkboxes, radios or switches with a legend, hint and error.
-    def lc_choice_group(legend:, hint: nil, error: nil, **attributes, &block)
+    # A fieldset of checkboxes, radios or switches with a legend, hint and error. With an id, the
+    # fieldset's aria-describedby points at the hint and error, as lc_field does for its control.
+    def lc_choice_group(legend:, id: nil, hint: nil, error: nil, **attributes, &block)
       lc_label!(legend, :legend)
       errors = Array(error).compact_blank
-      tag.fieldset(**lc_attributes({ class: lc_field_class(extra: "m-0 min-w-0 border-0 p-0"), aria: { invalid: (true if errors.any?) }, data: { slot: "choice-group" } }, attributes)) do
+      described = [ ("#{id}-hint" if id && hint.present?), ("#{id}-error" if id && errors.any?) ].compact.presence&.join(" ")
+      defaults = { id: id, class: lc_field_class(extra: "m-0 min-w-0 border-0 p-0"), aria: { invalid: (true if errors.any?), describedby: described }, data: { slot: "choice-group", invalid: (true if errors.any?) } }
+      tag.fieldset(**lc_attributes(defaults, attributes)) do
         safe_join([
-          tag.legend(legend, class: lc_field_label_class(extra: "p-0")),
+          tag.legend(legend, class: lc_field_label_class(extra: "p-0"), data: { slot: "choice-group-legend" }),
           tag.div(class: "flex flex-col gap-related", &block),
-          *lc_field_messages(nil, hint, errors)
+          *lc_field_messages(id, hint, errors)
         ])
       end
     end
@@ -64,7 +67,7 @@ module Lostcoords::Ui
       end
 
       # Shared with Lostcoords::Ui::FormBuilder, which renders its own inputs.
-      def lc_choice_label(slot, label, hint, input, card: false, **attributes, &block)
+      def lc_choice_label(slot, label, hint, input, card: false, errors: [], error_id: nil, **attributes, &block)
         extra = capture(&block) if block
         tag.label(**lc_attributes({ class: lc_choice_label_class(card: card), data: { slot: slot, card: (true if card) } }, attributes)) do
           safe_join([
@@ -73,6 +76,7 @@ module Lostcoords::Ui
               safe_join([
                 tag.span(label, class: ("text-label" if card)),
                 (tag.span(hint, class: "text-small text-muted-foreground") if hint.present?),
+                (tag.span(safe_join(errors, tag.br), id: error_id, class: "text-small text-destructive", data: { slot: "field-error" }) if errors.any?),
                 (tag.span(extra, class: "flex min-w-0 flex-col pt-tight") if extra.present?)
               ].compact)
             end

data/app/helpers/lostcoords/ui/collapsible_helper.rb

@@ -0,0 +1,9 @@
+module Lostcoords::Ui
+  module CollapsibleHelper
+    def lc_collapsible(title:, open: false, **attributes, &block)
+      lc_label!(title, :title)
+      defaults = { class: lc_card_class(extra: "lc-collapsible"), open: open, data: { slot: "collapsible", controller: "lc-collapsible", action: "click->lc-collapsible#toggle" } }
+      render "lostcoords/ui/components/lc_collapsible", title: title, attributes: lc_attributes(defaults, attributes), content: (capture(&block) if block)
+    end
+  end
+end

data/app/helpers/lostcoords/ui/dialog_helper.rb

@@ -14,13 +14,18 @@ module Lostcoords::Ui
     }.freeze
 
     def lc_dialog_class(kind = :modal, extra: nil)
-      lc_tw("lc-squircle", lc_dialog_kinds.fetch(kind), extra)
+      lc_tw("lc-squircle", DIALOGS.fetch(lc_option!(:kind, kind, DIALOGS.keys)), extra)
     end
 
-    private
-
-    def lc_dialog_kinds
-      DIALOGS
+    # Yields a builder with footer and close parts.
+    def lc_dialog(id:, title:, description: nil, trigger: lc_t("lostcoords.ui.dialog.trigger"), kind: :modal, detents: "fit", **attributes, &block)
+      lc_label!(id, :id)
+      lc_label!(title, :title)
+      lc_label!(trigger, :trigger)
+      defaults = { class: lc_dialog_class(kind), aria: { describedby: ("#{id}-description" if description.present?) }, data: lc_sheet_data({ slot: "dialog" }, detents: detents) }
+      required = { id: id, aria: { labelledby: "#{id}-title" }, data: { lc_dialog_target: "dialog" } }
+      render "lostcoords/ui/components/lc_dialog", id: id, title: title, description: description, trigger: trigger,
+        attributes: lc_attributes(defaults, attributes, required), content: (capture(Parts::Dialog.new(self, id), &block) if block)
     end
   end
 end

data/app/helpers/lostcoords/ui/emoji_picker_helper.rb

@@ -6,6 +6,12 @@ module Lostcoords::Ui
   module EmojiPickerHelper
     include TranslationHelper
 
+    def lc_emoji_picker(form:, field:, label:, catalog_url:, value: nil, quick: [], recent: [], recent_scope: nil, auto_submit: false, **attributes)
+      lc_label!(label, :label)
+      lc_label!(catalog_url, :catalog_url)
+      render "lostcoords/ui/components/emoji_picker", form: form, field: field, label: label, catalog_url: catalog_url, value: value, quick: quick, recent: recent, recent_scope: recent_scope, auto_submit: auto_submit, attributes: attributes
+    end
+
     SEARCH_NAMES_PATH = Lostcoords::Ui.root.join("config/emoji_search_names.yml")
     SEARCH_NAMES_JA_PATH = Lostcoords::Ui.root.join("config/emoji_search_names_ja.yml")
     SEARCH_ALIASES_PATH = Lostcoords::Ui.root.join("config/emoji_search_aliases.yml")

data/app/helpers/lostcoords/ui/feedback_helper.rb

@@ -9,13 +9,13 @@ module Lostcoords::Ui
       lg: "size-8 border-[3px]"
     }.freeze
 
-    SKELETON_BASE = "block rounded-xl bg-muted animate-pulse"
+    SKELETON_BASE = "block rounded-xl bg-tile animate-pulse"
 
     EMPTY_STATE_BASE =
       "flex flex-col items-center gap-content text-center " \
       "py-section px-content"
 
-    ALERT_BASE = "flex items-start gap-related py-heading px-content rounded-2xl lc-squircle bg-muted text-foreground text-label"
+    ALERT_BASE = "flex items-start gap-related py-heading px-content rounded-2xl lc-squircle bg-tile text-foreground text-label"
     ALERT_ICONS = {
       neutral: [ "information-circle", "text-muted-foreground" ],
       primary: [ "information-circle", "text-primary" ],

data/app/helpers/lostcoords/ui/form_helper.rb

@@ -1,18 +1,19 @@
 module Lostcoords::Ui
   module FormHelper
     TOGGLE_GROUP_BASE =
-      "inline-flex items-center gap-1 rounded-2xl bg-muted p-1 lc-squircle"
+      "inline-flex items-center gap-1 rounded-2xl bg-track p-1 lc-squircle"
 
     TOGGLE_GROUP_ITEM_BASE =
       "lc-press inline-flex items-center justify-center gap-1.5 whitespace-nowrap " \
       "h-control-sm rounded-xl border-0 bg-transparent " \
       "px-3 font-sans text-label cursor-pointer no-underline " \
-      "text-muted-foreground hover:text-foreground " \
+      "text-muted-foreground not-disabled:hover:text-foreground " \
       "aria-selected:bg-background aria-selected:text-foreground " \
+      "aria-checked:bg-background aria-checked:text-foreground " \
       "aria-pressed:bg-background aria-pressed:text-foreground " \
       "aria-[current]:not-aria-[current=false]:bg-background aria-[current]:not-aria-[current=false]:text-foreground " \
       "transition-[background-color,color,box-shadow,transform] duration-(--lc-motion-quick) ease-(--lc-ease-out) " \
-      "disabled:opacity-40 disabled:pointer-events-none " \
+      "disabled:cursor-not-allowed disabled:text-[color-mix(in_oklab,var(--foreground)_38%,transparent)] " \
       "[&_svg]:size-[1.1em] [&_svg]:shrink-0"
 
     TOGGLE_GROUP_ITEM_ACTIVE = "bg-background text-foreground hover:text-foreground"

data/app/helpers/lostcoords/ui/glass_helper.rb

@@ -19,7 +19,7 @@ module Lostcoords::Ui
       "dark:max-md:[--lc-glass-fill:color-mix(in_oklab,var(--muted)_92%,transparent)]"
 
     def lc_glass_class(shape: :bar, thick: false, extra: nil)
-      lc_tw("lc-glass", GLASS_SHAPES.fetch(shape.to_sym, GLASS_SHAPES[:bar]), (GLASS_THICK if thick), extra)
+      lc_tw("lc-glass", GLASS_SHAPES.fetch(lc_option!(:shape, shape, GLASS_SHAPES.keys)), (GLASS_THICK if thick), extra)
     end
   end
 end

data/app/helpers/lostcoords/ui/menu_helper.rb

@@ -27,7 +27,7 @@ module Lostcoords::Ui
     }.freeze
 
     def lc_popover_class(align: :end, extra: nil)
-      lc_glass_class(shape: :menu, extra: lc_tw(POPOVER_BASE, MENU_POPOVER_ALIGN.fetch(align), extra))
+      lc_glass_class(shape: :menu, extra: lc_tw(POPOVER_BASE, MENU_POPOVER_ALIGN.fetch(lc_option!(:align, align, MENU_POPOVER_ALIGN.keys)), extra))
     end
 
     def lc_menu_popover_class(align: :end, extra: nil)
@@ -35,7 +35,42 @@ module Lostcoords::Ui
     end
 
     def lc_menu_option_class(tone: :default, extra: nil)
-      lc_tw(MENU_OPTION_BASE, MENU_OPTION_TONES.fetch(tone), extra)
+      lc_tw(MENU_OPTION_BASE, MENU_OPTION_TONES.fetch(lc_option!(:tone, tone, MENU_OPTION_TONES.keys)), extra)
+    end
+
+    def lc_menu(id:, label: lc_t("lostcoords.ui.menu.label"), align: :end, **attributes, &block)
+      align = lc_option!(:align, align, MENU_POPOVER_ALIGN.keys)
+      lc_render_panel(id, label, nil, "lc-menu", "menu", lc_menu_popover_class(align: align), lc_attributes({ data: { slot: "menu" } }, attributes), &block)
+    end
+
+    def lc_popover(id:, label: lc_t("lostcoords.ui.popover.trigger"), title: nil, align: :end, trigger_variant: :secondary, **attributes, &block)
+      title = title.presence
+      align = lc_option!(:align, align, MENU_POPOVER_ALIGN.keys)
+      classes = lc_popover_class(align: align, extra: "data-open:flex flex-col gap-content p-inset z-(--lc-z-popover) min-w-64 max-w-[calc(100vw-2rem)]")
+      lc_render_panel(id, label, title, "lc-popover", "dialog", classes, lc_attributes({ data: { slot: "popover" } }, attributes), trigger_variant: trigger_variant, &block)
+    end
+
+    def lc_menu_option(label = nil, href: nil, tone: :default, **attributes, &block)
+      tone = lc_option!(:tone, tone, MENU_OPTION_TONES.keys)
+      content = tag.span(block ? capture(&block) : label, class: "col-span-3")
+      defaults = { class: lc_menu_option_class(tone: tone), role: "menuitem", data: { slot: "menu-item", action: "click->lc-menu#close" } }
+      if href
+        raise ArgumentError, "Links cannot be disabled; use a menu button instead" if attributes[:disabled] || attributes["disabled"]
+
+        tag.a(content, **lc_attributes(defaults.merge(href: href), attributes))
+      else
+        tag.button(content, **lc_attributes(defaults.merge(type: "button"), attributes))
+      end
+    end
+
+    private
+    def lc_render_panel(id, label, title, controller, role, classes, attributes, trigger_variant: :secondary, &block)
+      lc_label!(id, :id)
+      lc_label!(label, :label)
+      required = { id: id, role: role, aria: { labelledby: "#{id}-#{title ? 'title' : 'trigger'}" }, data: { "#{controller}_target" => "popover" } }
+      required[:tabindex] = -1 if role == "dialog"
+      merged = lc_attributes({ class: classes }, attributes, required)
+      render "lostcoords/ui/components/lc_floating_panel", id: id, label: label, title: title, controller: controller, role: role, trigger_variant: trigger_variant, attributes: merged, content: (capture(&block) if block)
     end
   end
 end

data/app/helpers/lostcoords/ui/navigation_helper.rb

@@ -99,10 +99,20 @@ module Lostcoords::Ui
       end
     end
 
+    TABS_ORIENTATIONS = {
+      horizontal: { root: "flex min-w-0 flex-col gap-content", list: "max-w-full overflow-x-auto lc-scroll-fade-x" },
+      vertical: { root: "flex min-w-0 flex-row items-start gap-content", list: "shrink-0 flex-col items-stretch [&>[role=tab]]:justify-start" }
+    }.freeze
+
     # Yields a builder; each `tabs.panel "Label" do … end` adds a tab and its panel.
-    def lc_tabs(id:, label:, selected: nil, **attributes, &block)
+    # orientation: :vertical stacks the tabs beside the panels and moves them with Arrow Up and Down.
+    # activation: :manual moves focus with the arrows and selects with Enter or Space.
+    def lc_tabs(id:, label:, selected: nil, orientation: :horizontal, activation: :automatic, **attributes, &block)
       lc_label!(id, :id)
       lc_label!(label, :label)
+      orientation = lc_option!(:orientation, orientation, TABS_ORIENTATIONS.keys)
+      activation = lc_option!(:activation, activation, %i[automatic manual])
+      layout = TABS_ORIENTATIONS.fetch(orientation)
       tabs = Parts::Tabs.new(self)
       capture(tabs, &block) if block
       raise ArgumentError, "lc_tabs needs at least one panel" if tabs.panels.empty?
@@ -111,7 +121,9 @@ module Lostcoords::Ui
       raise ArgumentError, "selected tab #{selected.inspect} has no panel" unless tabs.panels.any? { |panel| panel.value == selected }
 
       key = ->(panel) { "#{id}-#{panel.value.gsub(/[^\w-]+/, '-')}" }
-      list = tag.div(role: "tablist", aria: { label: label }, class: lc_toggle_group_class(extra: "max-w-full overflow-x-auto lc-scroll-fade-x"), data: { slot: "tabs-list" }) do
+      ids = tabs.panels.map(&key)
+      raise ArgumentError, "tab values #{tabs.panels.map(&:value).inspect} produce duplicate ids" unless ids.uniq.size == ids.size
+      list = tag.div(role: "tablist", aria: { label: label, orientation: (orientation if orientation == :vertical) }, class: lc_toggle_group_class(extra: layout[:list]), data: { slot: "tabs-list" }) do
         safe_join(tabs.panels.map do |panel|
           active = panel.value == selected
           tag.button(panel.label, type: "button", role: "tab", id: "#{key.(panel)}-tab", tabindex: (active ? 0 : -1),
@@ -121,9 +133,10 @@ module Lostcoords::Ui
       end
       panels = tabs.panels.map do |panel|
         tag.div(panel.content, **lc_attributes({ role: "tabpanel", id: "#{key.(panel)}-panel", tabindex: 0, hidden: (panel.value != selected),
-          aria: { labelledby: "#{key.(panel)}-tab" }, class: "min-w-0 rounded-lg outline-offset-4", data: { slot: "tabs-panel", lc_tabs_target: "panel" } }, panel.attributes))
+          aria: { labelledby: "#{key.(panel)}-tab" }, class: lc_tw("min-w-0 rounded-lg outline-offset-4", ("flex-1" if orientation == :vertical)), data: { slot: "tabs-panel", lc_tabs_target: "panel" } }, panel.attributes))
       end
-      tag.div(**lc_attributes({ id: id, class: "flex min-w-0 flex-col gap-content", data: { slot: "tabs", controller: "lc-tabs" } }, attributes)) do
+      data = { slot: "tabs", controller: "lc-tabs", lc_tabs_activation_value: (activation.to_s if activation == :manual) }.compact
+      tag.div(**lc_attributes({ id: id, class: layout[:root], data: data }, attributes)) do
         safe_join([ list, *panels ])
       end
     end

data/app/helpers/lostcoords/ui/render_attributes_helper.rb

@@ -1,7 +1,10 @@
 module Lostcoords::Ui
   module RenderAttributesHelper
     private
-      def lc_attributes(defaults, attributes)
+      # required: attributes the component needs to work, merged last so a caller can't override them.
+      def lc_attributes(defaults, attributes, required = nil)
+        return lc_attributes(lc_attributes(defaults, attributes), required) if required
+
         defaults = lc_normalize_attributes(defaults)
         attributes = lc_normalize_attributes(attributes)
         merged = defaults.merge(attributes)
@@ -36,6 +39,19 @@ module Lostcoords::Ui
         normalized
       end
 
+      def lc_label!(value, name)
+        raise ArgumentError, "#{name} must not be blank" if value.blank?
+      end
+
+      # The hint and error paragraphs under a field or choice group. With an id, controls can point
+      # aria-describedby at them.
+      def lc_field_messages(id, hint, errors)
+        [
+          (tag.p(hint, id: ("#{id}-hint" if id), class: "m-0 text-small text-muted-foreground", data: { slot: "field-description" }) if hint.present?),
+          (tag.p(safe_join(errors, tag.br), id: ("#{id}-error" if id), class: "m-0 text-small text-destructive", role: "alert", data: { slot: "field-error" }) if errors.any?)
+        ].compact
+      end
+
       def lc_option!(name, value, allowed)
         normalized = value.to_sym if value.is_a?(String) || value.is_a?(Symbol)
         return normalized if allowed.include?(normalized)

data/app/helpers/lostcoords/ui/sheet_helper.rb

@@ -2,7 +2,11 @@ module Lostcoords::Ui
   module SheetHelper
     # Makes a <dialog> an iOS sheet on phones (lc-sheet controller), keeping the dialog's own
     # controllers. detents: "fit", "medium large" or "large".
+    SHEET_DETENTS = [ "fit", "medium large", "large" ].freeze
+
     def lc_sheet_data(data = {}, detents: "fit")
+      detents = lc_option!(:detents, detents, SHEET_DETENTS.map(&:to_sym)).to_s
+      data = data.to_h.symbolize_keys
       data.merge(
         controller: [ data[:controller], "lc-sheet" ].compact.join(" "),
         lc_sheet_detents_value: detents

data/app/helpers/lostcoords/ui/structures_helper.rb

@@ -1,7 +1,6 @@
 module Lostcoords::Ui
   module StructuresHelper
     INPUT_TYPES = %i[text search email password tel url number date time datetime-local month week].freeze
-    SHEET_DETENTS = [ "fit", "medium large", "large" ].freeze
 
     def lc_input(name: nil, value: nil, type: :text, size: :md, **attributes)
       type = lc_option!(:type, type, INPUT_TYPES)
@@ -36,10 +35,12 @@ module Lostcoords::Ui
       end
     end
 
+    # One choice from a few options, as a segmented control. Arrows move and select, like native radios,
+    # so it is a radiogroup of radio buttons to assistive technology.
     def lc_toggle_group(label:, name: nil, value: nil, **attributes, &block)
       lc_label!(label, :label)
-      defaults = { class: lc_toggle_group_class, role: "group", aria: { label: label }, data: { slot: "toggle-group", controller: "lc-selection", action: "click->lc-selection#select keydown->lc-selection#navigate", lc_selection_value_value: value } }
-      tag.div(**lc_attributes(lc_attributes(defaults, attributes), { role: "group", aria: { label: label } })) do
+      defaults = { class: lc_toggle_group_class, role: "radiogroup", aria: { label: label }, data: { slot: "toggle-group", controller: "lc-selection", action: "click->lc-selection#select keydown->lc-selection#navigate", lc_selection_value_value: value } }
+      tag.div(**lc_attributes(defaults, attributes, { role: "radiogroup", aria: { label: label } })) do
         safe_join([ (hidden_field_tag(name, value, data: { lc_selection_target: "input" }) if name), (capture(&block) if block) ].compact)
       end
     end
@@ -47,9 +48,9 @@ module Lostcoords::Ui
     def lc_toggle_group_item(label = nil, value: nil, selected: false, **attributes, &block)
       value ||= label
       lc_label!(value, :value)
-      defaults = { class: lc_toggle_group_item_class, type: "button", aria: { pressed: selected }, data: { slot: "toggle-group-item", lc_selection_target: "option", value: value } }
-      required = { type: "button", data: { lc_selection_target: "option", value: value } }
-      tag.button(block ? capture(&block) : label, **lc_attributes(lc_attributes(defaults, attributes), required))
+      defaults = { class: lc_toggle_group_item_class, aria: { checked: selected }, data: { slot: "toggle-group-item" } }
+      required = { type: "button", role: "radio", data: { lc_selection_target: "option", value: value } }
+      tag.button(block ? capture(&block) : label, **lc_attributes(defaults, attributes, required))
     end
 
     def lc_toggle(label = nil, active: false, ghost: false, size: :md, **attributes, &block)
@@ -57,94 +58,5 @@ module Lostcoords::Ui
       defaults = { class: lc_toggle_class(ghost: ghost, size: size), type: "button", aria: { pressed: active }, data: { slot: "toggle", controller: "lc-toggle", action: "click->lc-toggle#toggle" } }
       tag.button(block ? capture(&block) : label, **lc_attributes(defaults, attributes).merge(type: "button"))
     end
-
-    # Yields a builder with footer and close parts.
-    def lc_dialog(id:, title:, description: nil, trigger: lc_t("lostcoords.ui.dialog.trigger"), kind: :modal, detents: "fit", **attributes, &block)
-      kind = lc_option!(:kind, kind, DialogHelper::DIALOGS.keys)
-      detents = detents.to_s
-      raise ArgumentError, "detents must be one of #{SHEET_DETENTS.join(', ')}" unless SHEET_DETENTS.include?(detents)
-      defaults = { class: lc_dialog_class(kind), aria: { describedby: ("#{id}-description" if description.present?) }, data: lc_sheet_data({ slot: "dialog" }, detents: detents) }
-      lc_render_dialog(id, title, description, trigger, defaults, attributes, &block)
-    end
-
-    def lc_menu(id:, label: lc_t("lostcoords.ui.menu.label"), align: :end, **attributes, &block)
-      align = lc_option!(:align, align, MenuHelper::MENU_POPOVER_ALIGN.keys)
-      lc_render_panel(id, label, nil, "lc-menu", "menu", lc_menu_popover_class(align: align), lc_attributes({ data: { slot: "menu" } }, attributes), &block)
-    end
-
-    def lc_popover(id:, label: lc_t("lostcoords.ui.popover.trigger"), title: nil, align: :end, trigger_variant: :secondary, **attributes, &block)
-      title = title.presence
-      align = lc_option!(:align, align, MenuHelper::MENU_POPOVER_ALIGN.keys)
-      classes = lc_popover_class(align: align, extra: "data-open:flex flex-col gap-content p-inset z-(--lc-z-popover) min-w-64 max-w-[calc(100vw-2rem)]")
-      lc_render_panel(id, label, title, "lc-popover", "dialog", classes, lc_attributes({ data: { slot: "popover" } }, attributes), trigger_variant: trigger_variant, &block)
-    end
-
-    def lc_menu_option(label = nil, href: nil, tone: :default, **attributes, &block)
-      tone = lc_option!(:tone, tone, MenuHelper::MENU_OPTION_TONES.keys)
-      content = tag.span(block ? capture(&block) : label, class: "col-span-3")
-      defaults = { class: lc_menu_option_class(tone: tone), role: "menuitem", data: { slot: "menu-item", action: "click->lc-menu#close" } }
-      if href
-        raise ArgumentError, "Links cannot be disabled; use a menu button instead" if attributes[:disabled] || attributes["disabled"]
-
-        tag.a(content, **lc_attributes(defaults.merge(href: href), attributes))
-      else
-        tag.button(content, **lc_attributes(defaults.merge(type: "button"), attributes))
-      end
-    end
-
-    def lc_toast(message = nil, tone: :success, timeout: 4000, **attributes, &block)
-      tone = lc_option!(:tone, tone, FeedbackHelper::ALERT_ICONS.keys)
-      raise ArgumentError, "timeout must be a nonnegative integer" unless timeout.is_a?(Integer) && timeout >= 0
-
-      defaults = { class: lc_glass_class(shape: :hud, extra: "flex items-center gap-related px-content py-heading text-label font-semibold transition-opacity data-leaving:opacity-0"), role: tone == :destructive ? "alert" : "status", data: { slot: "toast", tone: tone, controller: "lc-toast", action: "click->lc-toast#dismiss", lc_toast_timeout_value: timeout } }
-      tag.div(**lc_attributes(defaults, attributes)) do
-        safe_join([ lc_alert_icon(tone: tone), tag.span(block ? capture(&block) : message) ])
-      end
-    end
-
-    def lc_collapsible(title:, open: false, **attributes, &block)
-      lc_label!(title, :title)
-      defaults = { class: lc_card_class(extra: "lc-collapsible"), open: open, data: { slot: "collapsible", controller: "lc-collapsible", action: "click->lc-collapsible#toggle" } }
-      render "lostcoords/ui/components/lc_collapsible", title: title, attributes: lc_attributes(defaults, attributes), content: (capture(&block) if block)
-    end
-
-    def lc_emoji_picker(form:, field:, label:, catalog_url:, value: nil, quick: [], recent: [], recent_scope: nil, auto_submit: false, **attributes)
-      lc_label!(label, :label)
-      lc_label!(catalog_url, :catalog_url)
-      render "lostcoords/ui/components/emoji_picker", form: form, field: field, label: label, catalog_url: catalog_url, value: value, quick: quick, recent: recent, recent_scope: recent_scope, auto_submit: auto_submit, attributes: attributes
-    end
-
-    private
-      # The hint and error paragraphs under a field or choice group. With an id, controls can point
-      # aria-describedby at them.
-      def lc_field_messages(id, hint, errors)
-        [
-          (tag.p(hint, id: ("#{id}-hint" if id), class: "m-0 text-small text-muted-foreground", data: { slot: "field-description" }) if hint.present?),
-          (tag.p(safe_join(errors, tag.br), id: ("#{id}-error" if id), class: "m-0 text-small text-destructive", role: "alert", data: { slot: "field-error" }) if errors.any?)
-        ].compact
-      end
-
-
-    def lc_label!(value, name)
-      raise ArgumentError, "#{name} must not be blank" if value.blank?
-    end
-
-    def lc_render_dialog(id, title, description, trigger, defaults, attributes, &block)
-      lc_label!(id, :id)
-      lc_label!(title, :title)
-      lc_label!(trigger, :trigger)
-      required = { id: id, aria: { labelledby: "#{id}-title" }, data: (defaults[:data] || {}).merge(lc_dialog_target: "dialog") }
-      merged = lc_attributes(lc_attributes(defaults, attributes), required)
-      render "lostcoords/ui/components/lc_dialog", id: id, title: title, description: description, trigger: trigger, attributes: merged, content: (capture(Parts::Dialog.new(self, id), &block) if block)
-    end
-
-    def lc_render_panel(id, label, title, controller, role, classes, attributes, trigger_variant: :secondary, &block)
-      lc_label!(id, :id)
-      lc_label!(label, :label)
-      required = { id: id, role: role, aria: { labelledby: "#{id}-#{title ? 'title' : 'trigger'}" }, data: { "#{controller}_target" => "popover" } }
-      required[:tabindex] = -1 if role == "dialog"
-      merged = lc_attributes(lc_attributes({ class: classes }, attributes), required)
-      render "lostcoords/ui/components/lc_floating_panel", id: id, label: label, title: title, controller: controller, role: role, trigger_variant: trigger_variant, attributes: merged, content: (capture(&block) if block)
-    end
   end
 end

data/app/helpers/lostcoords/ui/toast_helper.rb

@@ -0,0 +1,22 @@
+module Lostcoords::Ui
+  module ToastHelper
+    # Render toasts inside lc_toast_region, the live region that announces them. A destructive toast
+    # is also an alert, so it interrupts.
+    def lc_toast(message = nil, tone: :success, timeout: 4000, **attributes, &block)
+      tone = lc_option!(:tone, tone, FeedbackHelper::ALERT_ICONS.keys)
+      raise ArgumentError, "timeout must be a nonnegative integer" unless timeout.is_a?(Integer) && timeout >= 0
+
+      defaults = { class: lc_glass_class(shape: :hud, extra: "flex items-center gap-related px-content py-heading text-label font-semibold transition-opacity data-leaving:opacity-0"), role: ("alert" if tone == :destructive), data: { slot: "toast", tone: tone, controller: "lc-toast", action: "click->lc-toast#dismiss", lc_toast_timeout_value: timeout } }
+      tag.div(**lc_attributes(defaults, attributes)) do
+        safe_join([ lc_alert_icon(tone: tone), tag.span(block ? capture(&block) : message) ])
+      end
+    end
+
+    # Fixed corner that holds toasts. Render it once in the layout and append toasts to it, from flash
+    # or a Turbo Stream; it shows in the top layer, above dialogs and sticky chrome.
+    def lc_toast_region(**attributes, &block)
+      defaults = { class: "lc-toast-region", role: "status", aria: { live: "polite" }, data: { slot: "toast-region", controller: "lc-toast-region" } }
+      tag.div(**lc_attributes(defaults, attributes)) { capture(&block) if block }
+    end
+  end
+end

data/app/helpers/lostcoords/ui/{overlay_helper.rb → tooltip_helper.rb}

@@ -1,5 +1,5 @@
 module Lostcoords::Ui
-  module OverlayHelper
+  module TooltipHelper
     TOOLTIP_SIDES = %i[top bottom].freeze
 
     # Yields attributes for the trigger; splat them with `**tip` so the trigger is described by the tooltip.
@@ -9,8 +9,8 @@ module Lostcoords::Ui
       lc_label!(id, :id)
       side = lc_option!(:side, side, TOOLTIP_SIDES)
       trigger = capture({ aria: { describedby: id } }, &block) if block
-      tag.span(**lc_attributes({ class: "lc-tooltip relative inline-flex", data: { slot: "tooltip", side: side, controller: "lc-tooltip", action: "keydown@window->lc-tooltip#dismiss mouseleave->lc-tooltip#reset focusout->lc-tooltip#reset" } }, attributes)) do
-        safe_join([ trigger, tag.span(text, id: id, role: "tooltip", class: "lc-tooltip__content", data: { slot: "tooltip-content" }) ].compact)
+      tag.span(**lc_attributes({ class: "lc-tooltip relative inline-flex", data: { slot: "tooltip", side: side, controller: "lc-tooltip", action: "mouseenter->lc-tooltip#show focusin->lc-tooltip#show mouseleave->lc-tooltip#hide focusout->lc-tooltip#hide" } }, attributes)) do
+        safe_join([ trigger, tag.span(text, id: id, role: "tooltip", class: "lc-tooltip__content", data: { slot: "tooltip-content", lc_tooltip_target: "content" }) ].compact)
       end
     end
   end

data/app/helpers/lostcoords/ui/typography_helper.rb

@@ -3,6 +3,10 @@ module Lostcoords::Ui
     HEADING_SIZES = { display: "text-display", title: "text-title", heading: "text-heading", subheading: "text-subheading" }.freeze
     TEXT_SIZES = { body: "text-body", small: "text-small", label: "text-label", caption: "text-caption" }.freeze
     TEXT_TONES = { default: "text-foreground", muted: "text-muted-foreground" }.freeze
+    KBD_BASE = "lc-kbd inline-flex items-center rounded-md bg-tile px-1.5 font-sans text-caption leading-5 whitespace-nowrap text-muted-foreground"
+    KBD_NAMES = { "mod" => "Ctrl", "ctrl" => "Ctrl", "alt" => "Alt", "shift" => "Shift", "meta" => "Meta", "escape" => "Esc", "enter" => "↵",
+                  "arrowup" => "↑", "arrowdown" => "↓", "arrowleft" => "←", "arrowright" => "→" }.freeze
+    KBD_MODIFIERS = %w[mod ctrl alt shift meta].freeze
 
     def lc_heading_class(size: :heading, trim: false, extra: nil)
       size = lc_option!(:size, size, HEADING_SIZES.keys)
@@ -15,6 +19,10 @@ module Lostcoords::Ui
       lc_tw("lc-text m-0", TEXT_SIZES.fetch(size), TEXT_TONES.fetch(tone), ("lc-trim" if trim), extra)
     end
 
+    def lc_kbd_class(extra: nil)
+      lc_tw(KBD_BASE, extra)
+    end
+
     def lc_heading(content = nil, level: 2, size: :heading, trim: false, **attributes, &block)
       raise ArgumentError, "Invalid level: #{level.inspect}. Expected an integer from 1 to 6" unless (1..6).include?(level) && level.is_a?(Integer)
 
@@ -24,5 +32,27 @@ module Lostcoords::Ui
     def lc_text(content = nil, size: :body, tone: :default, trim: false, **attributes, &block)
       tag.p(content, **lc_attributes({ class: lc_text_class(size: size, tone: tone, trim: trim) }, attributes), &block)
     end
+
+    # A key hint, such as lc_kbd("mod+k"). "mod" renders Ctrl and reads ⌘ on Apple platforms once JS runs.
+    def lc_kbd(keys, **attributes)
+      lc_label!(keys, :keys)
+      text = keys.split.map do |combo|
+        *modifiers, key = combo.downcase.split(/\+(?!\z)/)
+        names = modifiers.map { |modifier| KBD_MODIFIERS.include?(modifier) ? KBD_NAMES.fetch(modifier) : raise(ArgumentError, "Unknown modifier #{modifier.inspect} in #{keys.inspect}. Expected one of: #{KBD_MODIFIERS.join(', ')}") }
+        # A symbol such as ? already implies Shift; a letter or digit keeps it.
+        names.delete("Shift") if key.match?(/\A[^[:alnum:]]\z/)
+        [ *names, KBD_NAMES.fetch(key) { key.length == 1 ? key.upcase : key.capitalize } ].join(" ")
+      end.join(" / ")
+      tag.kbd(text, **lc_attributes({ class: lc_kbd_class, data: { controller: "lc-kbd", lc_kbd_keys_value: keys } }, attributes))
+    end
+
+    # Data for the element a page-wide shortcut focuses (fields) or clicks (anything else):
+    # lc_button "Search", data: lc_shortcut_data("mod+k"). Shortcuts without mod, ctrl or alt
+    # don't fire while typing in a field; inside an open modal, only its own shortcuts do.
+    def lc_shortcut_data(keys, data = {})
+      lc_label!(keys, :keys)
+      data = data.to_h.symbolize_keys
+      data.merge(controller: [ data[:controller], "lc-shortcut" ].compact.join(" "), lc_shortcut_keys_value: keys)
+    end
   end
 end

data/app/javascript/lostcoords/ui/controllers/lc_collapsible_controller.js

@@ -3,7 +3,7 @@ import { prefersReducedMotion } from "lostcoords/ui/helpers/viewport"
 
 // Animates a <details> both ways and keeps what it reveals on screen. Only
 // user toggles go through here: programmatic opens (validation) already scroll
-// to the field they care about. Durations live in ui/disclosure.css.
+// to the field they care about. Durations live in ui/collapsible.css.
 export default class extends Controller {
   // Where the panel's height can't ease to `auto` in CSS (Safari), ease the
   // <details> itself between measured heights.

data/app/javascript/lostcoords/ui/controllers/lc_emoji_picker_controller.js

@@ -1,4 +1,7 @@
 import { CatalogPicker } from "lostcoords/ui/helpers/catalog_picker"
+import { registerDismissable } from "lostcoords/ui/helpers/dismiss_stack"
+import { menuItems, navigateMenu } from "lostcoords/ui/helpers/menu_keys"
+import { navigate } from "lostcoords/ui/helpers/roving_focus"
 import { prefersReducedMotion } from "lostcoords/ui/helpers/viewport"
 
 const TONE_MODIFIERS = ["", "\u{1F3FB}", "\u{1F3FC}", "\u{1F3FD}", "\u{1F3FE}", "\u{1F3FF}"]
@@ -25,7 +28,7 @@ export default class extends CatalogPicker {
   }
 
   static optionKey = "emoji"
-  static catalogClass = "emoji-picker__catalog"
+  static catalogClass = "lc-emoji-picker__catalog"
   static previewTargets = ["previewEmoji", "previewName"]
 
   connect() {
@@ -36,6 +39,7 @@ export default class extends CatalogPicker {
   }
 
   disconnect() {
+    this.unregisterTones?.()
     this.clearPopover()
     super.disconnect()
   }
@@ -151,13 +155,33 @@ export default class extends CatalogPicker {
     })
   }
 
+  navigateTabs(event) {
+    navigate(event, this.tabTargets, { orientation: "horizontal", wrap: true })
+  }
+
+  // Escape closes the tone menu before the picker around it.
   toggleTones(event) {
     event.preventDefault()
     event.stopPropagation()
-    const open = this.toneMenuTarget.hidden
-    this.toneMenuTarget.hidden = !open
-    this.toneToggleTarget.setAttribute("aria-expanded", String(open))
-    if (open) this.syncTones()
+    if (!this.toneMenuTarget.hidden) return this.closeTones()
+
+    this.toneMenuTarget.hidden = false
+    this.toneToggleTarget.setAttribute("aria-expanded", "true")
+    this.syncTones()
+    this.unregisterTones = registerDismissable({
+      element: this.toneMenuTarget,
+      type: "popover",
+      close: () => this.closeTones(),
+      restoreFocus: () => this.toneToggleTarget.focus({ preventScroll: true }),
+    })
+    if (event.detail === 0) {
+      const items = menuItems(this.toneMenuTarget)
+      ;(items.find((item) => item.getAttribute("aria-current") === "true") || items[0])?.focus()
+    }
+  }
+
+  navigateTones(event) {
+    navigateMenu(event, this.toneMenuTarget, { orientation: "both" })
   }
 
   selectTone(event) {
@@ -174,7 +198,11 @@ export default class extends CatalogPicker {
 
   closeTones() {
     if (!this.hasToneMenuTarget) return
+    this.unregisterTones?.()
+    this.unregisterTones = null
+    const hadFocus = this.toneMenuTarget.contains(document.activeElement)
     this.toneMenuTarget.hidden = true
+    if (hadFocus) this.toneToggleTarget.focus({ preventScroll: true })
     this.toneToggleTarget.setAttribute("aria-expanded", "false")
   }
 
@@ -255,7 +283,7 @@ export default class extends CatalogPicker {
   renderRecent(emojis) {
     if (!this.hasRecentTarget) return
 
-    const grid = this.recentTarget.querySelector(".emoji-picker__grid")
+    const grid = this.recentTarget.querySelector(".lc-emoji-picker__grid")
     const count = this.recentTarget.querySelector(".count")
     if (!grid) return
 

data/app/javascript/lostcoords/ui/controllers/lc_kbd_controller.js

@@ -0,0 +1,12 @@
+import { Controller } from "@hotwired/stimulus"
+import { formatShortcut } from "lostcoords/ui/helpers/shortcuts"
+
+// Shows a key hint in the platform's own notation: "mod+k" reads ⌘ K on
+// Apple platforms. The server renders the Ctrl form, which stays without JS.
+export default class extends Controller {
+  static values = { keys: String }
+
+  keysValueChanged() {
+    if (this.keysValue) this.element.textContent = formatShortcut(this.keysValue)
+  }
+}