lostcoords-ui 0.5.0 → 0.6.0

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)
@@ -39,7 +38,7 @@ module Lostcoords::Ui
     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
+      tag.div(**lc_attributes(defaults, attributes, { role: "group", 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
@@ -49,7 +48,7 @@ module Lostcoords::Ui
       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))
+      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 +56,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)
+  }
+}

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

@@ -1,5 +1,9 @@
 import { FloatingPanel } from "lostcoords/ui/helpers/floating_panel"
-import { focusFirstMenuItem, navigateMenu } from "lostcoords/ui/helpers/menu_keys"
+import {
+  focusFirstMenuItem,
+  focusLastMenuItem,
+  navigateMenu,
+} from "lostcoords/ui/helpers/menu_keys"
 
 // The phone dock's action stack lays itself out over the fixed nav, so it
 // passes lift: false and stays in place instead of lifting into the top layer.
@@ -9,15 +13,33 @@ export default class extends FloatingPanel {
     this.focusOutHandler = this.handleFocusOut.bind(this)
     this.pointerDownHandler = this.handlePointerDown.bind(this)
     this.keydownHandler = (event) => navigateMenu(event, this.popoverTarget)
+    this.triggerKeydownHandler = this.handleTriggerKeydown.bind(this)
     this.focusOutSuppressed = false
     this.focusOutSuppressionTimer = null
   }
 
+  connect() {
+    super.connect()
+    this.triggerTarget.addEventListener("keydown", this.triggerKeydownHandler)
+  }
+
   disconnect() {
+    this.triggerTarget.removeEventListener("keydown", this.triggerKeydownHandler)
     this.clearFocusOutSuppression()
     super.disconnect()
   }
 
+  // Arrow Down opens the menu on its first item, Arrow Up on its last.
+  handleTriggerKeydown(event) {
+    if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return
+    if (event.altKey || event.ctrlKey || event.metaKey) return
+
+    event.preventDefault()
+    this.open()
+    if (event.key === "ArrowDown") focusFirstMenuItem(this.popoverTarget)
+    else focusLastMenuItem(this.popoverTarget)
+  }
+
   toggle(event) {
     event.preventDefault()
     event.stopPropagation()

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

@@ -1,4 +1,5 @@
 import { Controller } from "@hotwired/stimulus"
+import { navigate } from "lostcoords/ui/helpers/roving_focus"
 
 export default class extends Controller {
   static targets = ["option", "input"]
@@ -28,21 +29,12 @@ export default class extends Controller {
     this.changed(option)
   }
 
+  // All four arrows move and select, wrapping at the ends; Left and Right
+  // follow the text direction.
   navigate(event) {
-    const current = this.options.indexOf(event.target)
-    if (current < 0) return
-    const next = {
-      ArrowRight: (current + 1) % this.options.length,
-      ArrowDown: (current + 1) % this.options.length,
-      ArrowLeft: (current - 1 + this.options.length) % this.options.length,
-      ArrowUp: (current - 1 + this.options.length) % this.options.length,
-      Home: 0,
-      End: this.options.length - 1,
-    }[event.key]
-    if (next === undefined) return
-    event.preventDefault()
-    const option = this.options[next]
-    option.focus()
+    const option = navigate(event, this.optionTargets, { orientation: "both", wrap: true })
+    if (!option) return
+
     this.apply(option)
     this.changed(option)
   }

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

@@ -340,7 +340,7 @@ export default class extends Controller {
       this.releaseScroll = holdDocumentScroll()
       const lockedTop = -parseFloat(document.body.style.top || "0")
       root.style.setProperty("--lc-sheet-page-origin", `${window.scrollY + lockedTop}px`)
-      root.dataset.sheetPage = ""
+      root.dataset.lcSheetPage = ""
       this.ownsPage = true
     }
     root.style.setProperty("--lc-sheet-page-p", p.toFixed(3))
@@ -361,7 +361,7 @@ export default class extends Controller {
     if (!this.ownsPage) return
     this.ownsPage = false
     const root = document.documentElement
-    delete root.dataset.sheetPage
+    delete root.dataset.lcSheetPage
     for (const name of ["p", "scale", "origin", "transition"])
       root.style.removeProperty(`--lc-sheet-page-${name}`)
     this.releaseScroll()

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

@@ -0,0 +1,45 @@
+import { Controller } from "@hotwired/stimulus"
+import { isEditable } from "lostcoords/ui/helpers/roving_focus"
+import { ariaKeyShortcuts, registerShortcut } from "lostcoords/ui/helpers/shortcuts"
+
+// Binds page-wide keys to the element: a field takes focus and selects its
+// text, anything else is clicked. The element announces its keys through
+// aria-keyshortcuts. See helpers/shortcuts.js for the key syntax.
+export default class extends Controller {
+  static values = { keys: String }
+
+  // Stimulus keeps values across a reconnect (a moved or permanent element)
+  // without calling keysValueChanged again, so connect registers too.
+  connect() {
+    this.register()
+  }
+
+  keysValueChanged() {
+    if (this.connected) this.register()
+  }
+
+  register() {
+    this.connected = true
+    this.unregister?.()
+    this.unregister = null
+    if (!this.keysValue) return
+
+    this.element.setAttribute("aria-keyshortcuts", ariaKeyShortcuts(this.keysValue))
+    this.unregister = registerShortcut(this.element, this.keysValue, () => this.run())
+  }
+
+  disconnect() {
+    this.connected = false
+    this.unregister?.()
+    this.unregister = null
+  }
+
+  run() {
+    if (isEditable(this.element)) {
+      this.element.focus()
+      this.element.select?.()
+    } else {
+      this.element.click()
+    }
+  }
+}