lostcoords-ui 0.4.1 → 0.6.0

data/app/javascript/lostcoords/ui/helpers/shortcuts.js

@@ -0,0 +1,162 @@
+import { topModalElement } from "lostcoords/ui/helpers/dismiss_stack"
+import { isEditable } from "lostcoords/ui/helpers/roving_focus"
+
+// Page-wide keyboard shortcuts. A shortcut is written as keys joined by "+",
+// with "mod" for ⌘ on Apple platforms and Ctrl elsewhere: "mod+k", "/",
+// "shift+?", "alt+n". Several shortcuts for one element are separated by spaces.
+//
+// A shortcut without mod, ctrl or alt never fires while focus is in a text
+// field, so typing "/" in a field types it. While a modal dialog is open, only
+// elements inside it respond. When two visible elements claim the same keys,
+// the first in document order wins and the page logs a warning.
+
+const bindings = new Set()
+const warned = new Set()
+
+export const isApple = /mac|iphone|ipad|ipod/i.test(
+  navigator.userAgentData?.platform || navigator.platform || navigator.userAgent,
+)
+
+export function parseShortcuts(text) {
+  return text
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((combo) => {
+      const parts = combo.toLowerCase().split("+")
+      const key = parts.pop() || "+"
+      const modifiers = new Set(parts)
+      return {
+        text: combo,
+        key,
+        mod: modifiers.has("mod"),
+        ctrl: modifiers.has("ctrl"),
+        meta: modifiers.has("meta"),
+        alt: modifiers.has("alt"),
+        shift: modifiers.has("shift"),
+      }
+    })
+}
+
+export function matchesShortcut(shortcut, event) {
+  const meta = shortcut.meta || (shortcut.mod && isApple)
+  const ctrl = shortcut.ctrl || (shortcut.mod && !isApple)
+  if (event.metaKey !== meta || event.ctrlKey !== ctrl || event.altKey !== shortcut.alt)
+    return false
+
+  // Option on a Mac turns letters into other characters (Option+N is a dead key),
+  // so alt shortcuts on letters and digits match the physical key.
+  if (shortcut.alt && /^[a-z0-9]$/.test(shortcut.key))
+    return event.shiftKey === shortcut.shift && event.code === physicalKey(shortcut.key)
+
+  const key = event.key.toLowerCase()
+  // Shifted punctuation such as "?" already reports the shifted key.
+  if (key.length === 1 && !/[a-z0-9]/.test(key)) return key === shortcut.key
+  return event.shiftKey === shortcut.shift && key === shortcut.key
+}
+
+const physicalKey = (key) => (/\d/.test(key) ? `Digit${key}` : `Key${key.toUpperCase()}`)
+
+// Shift shows unless the key is a symbol it already produces, such as "?".
+const showsShift = (shortcut) => shortcut.shift && !/^[^a-z0-9]$/.test(shortcut.key)
+
+const KEY_NAMES = {
+  escape: "Esc",
+  arrowup: "↑",
+  arrowdown: "↓",
+  arrowleft: "←",
+  arrowright: "→",
+  enter: "↵",
+}
+
+// "mod+k" reads "⌘ K" on Apple platforms and "Ctrl K" elsewhere.
+export function formatShortcut(text) {
+  return parseShortcuts(text)
+    .map((shortcut) => {
+      const keys = []
+      if (shortcut.ctrl || (shortcut.mod && !isApple)) keys.push(isApple ? "⌃" : "Ctrl")
+      if (shortcut.alt) keys.push(isApple ? "⌥" : "Alt")
+      if (showsShift(shortcut)) keys.push(isApple ? "⇧" : "Shift")
+      if (shortcut.meta || (shortcut.mod && isApple)) keys.push(isApple ? "⌘" : "Meta")
+      keys.push(
+        KEY_NAMES[shortcut.key] ||
+          (shortcut.key.length === 1 ? shortcut.key.toUpperCase() : shortcut.key),
+      )
+      return keys.join(" ")
+    })
+    .join(" / ")
+}
+
+// The aria-keyshortcuts value: "mod+k" becomes "Meta+K" or "Control+K".
+export function ariaKeyShortcuts(text) {
+  return parseShortcuts(text)
+    .map((shortcut) => {
+      const keys = []
+      if (shortcut.ctrl || (shortcut.mod && !isApple)) keys.push("Control")
+      if (shortcut.alt) keys.push("Alt")
+      if (shortcut.shift) keys.push("Shift")
+      if (shortcut.meta || (shortcut.mod && isApple)) keys.push("Meta")
+      keys.push(
+        shortcut.key.length === 1
+          ? shortcut.key.toUpperCase()
+          : shortcut.key[0].toUpperCase() + shortcut.key.slice(1),
+      )
+      return keys.join("+")
+    })
+    .join(" ")
+}
+
+// Registers element for the shortcuts in text; run is called when one fires.
+// Returns a function that removes the binding.
+export function registerShortcut(element, text, run) {
+  const binding = { element, shortcuts: parseShortcuts(text), run }
+  if (bindings.size === 0) document.addEventListener("keydown", handleKeydown)
+  bindings.add(binding)
+
+  return () => {
+    bindings.delete(binding)
+    if (bindings.size === 0) document.removeEventListener("keydown", handleKeydown)
+  }
+}
+
+function handleKeydown(event) {
+  if (event.defaultPrevented || event.isComposing || event.repeat) return
+
+  const typing = isEditable(event.target)
+  const matches = [...bindings].filter(
+    (binding) =>
+      binding.shortcuts.some(
+        (shortcut) =>
+          matchesShortcut(shortcut, event) &&
+          !(typing && !shortcut.mod && !shortcut.ctrl && !shortcut.meta && !shortcut.alt),
+      ) && available(binding.element),
+  )
+  if (matches.length === 0) return
+
+  matches.sort((a, b) =>
+    a.element.compareDocumentPosition(b.element) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1,
+  )
+  if (matches.length > 1) warnConflict(event, matches)
+
+  event.preventDefault()
+  matches[0].run(event)
+}
+
+function available(element) {
+  if (!element.isConnected || element.disabled || element.closest("[inert]")) return false
+  if (element.getClientRects().length === 0) return false
+
+  const modal = topModalElement()
+  return !modal || modal.contains(element)
+}
+
+function warnConflict(event, matches) {
+  const key = `${event.ctrlKey}${event.metaKey}${event.altKey}${event.shiftKey}${event.key}`
+  if (warned.has(key)) return
+
+  warned.add(key)
+  console.warn(
+    `lostcoords-ui: ${matches.length} elements share the shortcut ${event.key}; the first one runs.`,
+    matches.map((binding) => binding.element),
+  )
+}

data/app/javascript/lostcoords/ui/helpers/top_layer.js

@@ -6,17 +6,48 @@
 // The panel's stylesheet still decides where it sits. The caller makes the
 // panel visible in place, liftToTopLayer measures that designed spot relative
 // to its trigger, then re-pins it there as a fixed top-layer popover, follows
-// the trigger on scroll and resize, and flips above when it would leave the
-// viewport. Browsers without the Popover API keep the in-place panel.
+// the trigger on scroll and resize, and flips to the other side when it would
+// leave the viewport. Browsers without the Popover API keep the in-place panel.
+//
+// Every top-layer call in the library goes through this file: showTopLayer and
+// hideTopLayer for elements that place themselves, liftToTopLayer for panels
+// pinned to a trigger, and onPageLeave to close them before Turbo caches a page.
 
 const MARGIN = 8
+const PAGE_LEAVES = ["turbo:before-cache", "turbo:before-visit", "turbo:before-render"]
+
+export const supportsTopLayer = () => typeof HTMLElement.prototype.showPopover === "function"
+
+// showPopover and hidePopover throw when the element is disconnected or already
+// in that state; both are no-ops here instead.
+export function showTopLayer(element) {
+  if (!supportsTopLayer() || !element.isConnected) return false
+  if (!element.hasAttribute("popover")) element.setAttribute("popover", "manual")
+  if (!element.matches(":popover-open")) element.showPopover()
+  return true
+}
+
+export function hideTopLayer(element) {
+  if (supportsTopLayer() && element.matches(":popover-open")) element.hidePopover()
+}
+
+// Calls close before Turbo snapshots or leaves the page, so a cached page never
+// keeps an open overlay. Returns a function that removes the listeners.
+export function onPageLeave(close) {
+  for (const type of PAGE_LEAVES) document.addEventListener(type, close)
+  window.addEventListener("pagehide", close)
+  return () => {
+    for (const type of PAGE_LEAVES) document.removeEventListener(type, close)
+    window.removeEventListener("pagehide", close)
+  }
+}
 const PLACEMENT = ["position", "inset", "top", "left", "margin", "translate", "inlineSize"]
 
 const lifts = new WeakMap()
 const pinned = new WeakSet()
 
 export function liftToTopLayer(panel, trigger) {
-  if (typeof panel.showPopover !== "function") return () => {}
+  if (!supportsTopLayer() || !panel.isConnected) return () => {}
 
   lifts.get(panel)?.()
   if (pinned.has(panel)) reset(panel)
@@ -25,10 +56,12 @@ export function liftToTopLayer(panel, trigger) {
   const placed = panel.getBoundingClientRect()
   const offsetX = placed.left - anchor.left
   const offsetY = placed.top - anchor.top
-  const gap = placed.top - anchor.bottom
+  // A panel above its trigger flips below when it would leave the top edge; any
+  // other panel flips above when it would leave the bottom.
+  const above = placed.bottom <= anchor.top + 1
+  const gap = above ? anchor.top - placed.bottom : placed.top - anchor.bottom
 
-  panel.setAttribute("popover", "manual")
-  panel.showPopover()
+  showTopLayer(panel)
   Object.assign(panel.style, {
     position: "fixed",
     inset: "auto",
@@ -48,8 +81,13 @@ export function liftToTopLayer(panel, trigger) {
     const right = document.documentElement.clientWidth - MARGIN
 
     let top = a.top + offsetY
-    const flipped = a.top - gap - height
-    if (top + height > maxBottom - MARGIN && flipped >= minTop + MARGIN) top = flipped
+    if (above) {
+      const flipped = a.bottom + gap
+      if (top < minTop + MARGIN && flipped + height <= maxBottom - MARGIN) top = flipped
+    } else {
+      const flipped = a.top - gap - height
+      if (top + height > maxBottom - MARGIN && flipped >= minTop + MARGIN) top = flipped
+    }
     top = Math.max(minTop + MARGIN, Math.min(top, maxBottom - MARGIN - height))
 
     panel.style.left = `${Math.max(MARGIN, Math.min(a.left + offsetX, right - width))}px`
@@ -77,7 +115,7 @@ export function liftToTopLayer(panel, trigger) {
     Promise.allSettled(panel.getAnimations().map((animation) => animation.finished)).then(() => {
       if (!lifts.has(panel)) reset(panel)
     })
-    if (panel.matches(":popover-open")) panel.hidePopover()
+    hideTopLayer(panel)
   }
   lifts.set(panel, release)
   return release
@@ -85,7 +123,7 @@ export function liftToTopLayer(panel, trigger) {
 
 function reset(panel) {
   pinned.delete(panel)
-  if (panel.matches(":popover-open")) panel.hidePopover()
+  hideTopLayer(panel)
   panel.removeAttribute("popover")
   for (const property of PLACEMENT) panel.style[property] = ""
 }

data/app/javascript/lostcoords/ui/index.js

@@ -0,0 +1,57 @@
+import CodeBlock from "lostcoords/ui/controllers/lc_code_block_controller"
+import Collapsible from "lostcoords/ui/controllers/lc_collapsible_controller"
+import ConfirmDialog from "lostcoords/ui/controllers/lc_confirm_dialog_controller"
+import Copy from "lostcoords/ui/controllers/lc_copy_controller"
+import Dialog from "lostcoords/ui/controllers/lc_dialog_controller"
+import EmojiPicker from "lostcoords/ui/controllers/lc_emoji_picker_controller"
+import Kbd from "lostcoords/ui/controllers/lc_kbd_controller"
+import Menu from "lostcoords/ui/controllers/lc_menu_controller"
+import Popover from "lostcoords/ui/controllers/lc_popover_controller"
+import Selection from "lostcoords/ui/controllers/lc_selection_controller"
+import Sheet from "lostcoords/ui/controllers/lc_sheet_controller"
+import Shortcut from "lostcoords/ui/controllers/lc_shortcut_controller"
+import Tabs from "lostcoords/ui/controllers/lc_tabs_controller"
+import Toast from "lostcoords/ui/controllers/lc_toast_controller"
+import ToastRegion from "lostcoords/ui/controllers/lc_toast_region_controller"
+import Toggle from "lostcoords/ui/controllers/lc_toggle_controller"
+import Tooltip from "lostcoords/ui/controllers/lc_tooltip_controller"
+
+const controllers = {
+  "lc-confirm-dialog": ConfirmDialog,
+  "lc-collapsible": Collapsible,
+  "lc-code-block": CodeBlock,
+  "lc-copy": Copy,
+  "lc-dialog": Dialog,
+  "lc-emoji-picker": EmojiPicker,
+  "lc-kbd": Kbd,
+  "lc-menu": Menu,
+  "lc-popover": Popover,
+  "lc-selection": Selection,
+  "lc-sheet": Sheet,
+  "lc-shortcut": Shortcut,
+  "lc-tabs": Tabs,
+  "lc-toast": Toast,
+  "lc-toast-region": ToastRegion,
+  "lc-toggle": Toggle,
+  "lc-tooltip": Tooltip,
+}
+const registrations = new WeakMap()
+
+export function registerControllers(application, { only = Object.keys(controllers) } = {}) {
+  if (!Array.isArray(only)) throw new TypeError("only must be an array of controller identifiers")
+  for (const identifier of only) {
+    if (!Object.hasOwn(controllers, identifier)) {
+      throw new Error(`Unknown lostcoords-ui controller: ${identifier}`)
+    }
+  }
+  let registered = registrations.get(application)
+  if (!registered) {
+    registered = new Set()
+    registrations.set(application, registered)
+  }
+  for (const identifier of only) {
+    if (registered.has(identifier)) continue
+    application.register(identifier, controllers[identifier])
+    registered.add(identifier)
+  }
+}

data/app/views/lostcoords/ui/components/_emoji_picker.html.erb

@@ -7,30 +7,30 @@
   tone_modifiers = [ "", "🏻", "🏼", "🏽", "🏾", "🏿" ]
   tone_names = %w[default light medium_light medium medium_dark dark] %>
 
-<%= tag.div(**lc_attributes({ class: lc_tw("emoji-picker", picker_class), data: { controller: "emoji-picker", emoji_picker_auto_submit_value: auto_submit, emoji_picker_catalog_url_value: catalog_url, emoji_picker_recent_scope_value: recent_scope } }, attributes)) do %>
+<%= tag.div(**lc_attributes({ class: lc_tw("lc-emoji-picker", picker_class), data: { controller: "lc-emoji-picker", lc_emoji_picker_auto_submit_value: auto_submit, lc_emoji_picker_catalog_url_value: catalog_url, lc_emoji_picker_recent_scope_value: recent_scope } }, attributes)) do %>
   <%= form.hidden_field field,
       value: selected,
-      data: { emoji_picker_target: "input" } %>
+      data: { lc_emoji_picker_target: "input" } %>
 
   <% quick.each do |emoji| %>
     <button
       type="button"
-      class="emoji-picker__choice"
+      class="lc-emoji-picker__choice"
       aria-current="<%= emoji == selected %>"
       data-emoji="<%= emoji %>"
-      data-action="click->emoji-picker#select"
+      data-action="click->lc-emoji-picker#select"
     >
       <%= emoji %>
     </button>
   <% end %>
 
-  <div class="emoji-picker__more">
+  <div class="lc-emoji-picker__more">
     <button
       type="button"
-      class="emoji-picker__trigger <%= trigger_class %>"
+      class="lc-emoji-picker__trigger <%= trigger_class %>"
       aria-current="<%= !selected_is_quick %>"
-      data-emoji-picker-target="trigger"
-      data-action="click->emoji-picker#toggle"
+      data-lc-emoji-picker-target="trigger"
+      data-action="click->lc-emoji-picker#toggle"
       data-default-label="＋"
       data-value="<%= selected %>"
       aria-label="<%= label %>"
@@ -40,25 +40,25 @@
     </button>
 
     <div
-      class="emoji-picker__popover <%= popover_class %>"
-      data-emoji-picker-target="popover"
-      data-controller="sheet"
-      data-action="click->emoji-picker#select pointerover->emoji-picker#preview focusin->emoji-picker#preview sheet:dismiss->emoji-picker#close"
+      class="lc-emoji-picker__popover <%= popover_class %>"
+      data-lc-emoji-picker-target="popover"
+      data-controller="lc-sheet"
+      data-action="click->lc-emoji-picker#select pointerover->lc-emoji-picker#preview focusin->lc-emoji-picker#preview lc-sheet:dismiss->lc-emoji-picker#close"
       role="dialog"
       aria-label="<%= label %>"
       hidden
     >
-      <span class="emoji-picker__handle" data-sheet-target="handle" aria-hidden="true"></span>
+      <span class="lc-emoji-picker__handle" data-lc-sheet-target="handle" aria-hidden="true"></span>
 
-      <div class="emoji-picker__search">
-        <div class="emoji-picker__search-field">
-          <svg class="emoji-picker__search-icon" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+      <div class="lc-emoji-picker__search">
+        <div class="lc-emoji-picker__search-field">
+          <svg class="lc-emoji-picker__search-icon" viewBox="0 0 20 20" fill="none" aria-hidden="true">
             <circle cx="9" cy="9" r="6" stroke="currentColor" stroke-width="1.6" />
             <path d="m14 14 3.5 3.5" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" />
           </svg>
 
           <input
-            class="emoji-picker__search-input"
+            class="lc-emoji-picker__search-input"
             type="search"
             inputmode="search"
             autocomplete="off"
@@ -67,30 +67,30 @@
             enterkeyhint="search"
             aria-label="<%= lc_t("lostcoords.ui.emoji_picker.search_label") %>"
             placeholder="<%= lc_t("lostcoords.ui.emoji_picker.search_placeholder") %>"
-            data-emoji-picker-target="searchInput"
-            data-action="input->emoji-picker#filter keydown->emoji-picker#onSearchKeydown"
+            data-lc-emoji-picker-target="searchInput"
+            data-action="input->lc-emoji-picker#filter keydown->lc-emoji-picker#onSearchKeydown"
           >
         </div>
 
-        <div class="emoji-picker__tones" data-emoji-picker-target="tones">
+        <div class="lc-emoji-picker__tones" data-lc-emoji-picker-target="tones">
           <button
             type="button"
-            class="emoji-picker__tone-toggle"
-            data-emoji-picker-target="toneToggle"
-            data-action="click->emoji-picker#toggleTones"
+            class="lc-emoji-picker__tone-toggle"
+            data-lc-emoji-picker-target="toneToggle"
+            data-action="click->lc-emoji-picker#toggleTones"
             aria-haspopup="true"
             aria-expanded="false"
             aria-label="<%= lc_t("lostcoords.ui.emoji_picker.skin_tone") %>"
           >✋</button>
 
-          <div class="emoji-picker__tone-menu <%= popover_class %>" data-emoji-picker-target="toneMenu" role="menu" hidden>
+          <div class="lc-emoji-picker__tone-menu <%= popover_class %>" data-lc-emoji-picker-target="toneMenu" data-action="keydown->lc-emoji-picker#navigateTones" role="menu" aria-label="<%= lc_t("lostcoords.ui.emoji_picker.skin_tone") %>" hidden>
             <% tone_modifiers.each_with_index do |modifier, index| %>
               <button
                 type="button"
-                class="emoji-picker__tone"
+                class="lc-emoji-picker__tone"
                 role="menuitemradio"
                 data-tone-index="<%= index %>"
-                data-action="click->emoji-picker#selectTone"
+                data-action="click->lc-emoji-picker#selectTone"
                 aria-label="<%= lc_t("lostcoords.ui.emoji_picker.skin_tones.#{tone_names[index]}") %>"
               >✋<%= modifier %></button>
             <% end %>
@@ -98,14 +98,14 @@
         </div>
       </div>
 
-      <nav class="emoji-picker__tabs" data-emoji-picker-target="tabs" aria-label="<%= lc_t("lostcoords.ui.emoji_picker.categories_nav") %>">
+      <nav class="lc-emoji-picker__tabs" data-lc-emoji-picker-target="tabs" data-action="keydown->lc-emoji-picker#navigateTabs" aria-label="<%= lc_t("lostcoords.ui.emoji_picker.categories_nav") %>">
         <% if recent.any? %>
           <button
             type="button"
-            class="emoji-picker__tab"
-            data-emoji-picker-target="tab"
+            class="lc-emoji-picker__tab"
+            data-lc-emoji-picker-target="tab"
             data-target-section="recent"
-            data-action="click->emoji-picker#jumpTo"
+            data-action="click->lc-emoji-picker#jumpTo"
             aria-label="<%= lc_t("lostcoords.ui.emoji_picker.recently_used") %>"
           >🕘</button>
         <% end %>
@@ -113,29 +113,29 @@
         <% lc_emoji_picker_groups.each do |group| %>
           <button
             type="button"
-            class="emoji-picker__tab"
-            data-emoji-picker-target="tab"
+            class="lc-emoji-picker__tab"
+            data-lc-emoji-picker-target="tab"
             data-target-section="<%= group[:key] %>"
-            data-action="click->emoji-picker#jumpTo"
+            data-action="click->lc-emoji-picker#jumpTo"
             aria-label="<%= group[:name] %>"
           ><%= group[:icon] %></button>
         <% end %>
       </nav>
 
-      <div class="emoji-picker__body" data-emoji-picker-target="body">
+      <div class="lc-emoji-picker__body" data-lc-emoji-picker-target="body" data-action="keydown->lc-emoji-picker#navigateGrid focusin->lc-emoji-picker#trackGridFocus">
         <% if recent.any? %>
           <section
-            class="emoji-picker__recent"
+            class="lc-emoji-picker__recent"
             data-section="recent"
             aria-label="<%= lc_t('lostcoords.ui.emoji_picker.recently_used') %>"
-            data-emoji-picker-target="recent"
+            data-lc-emoji-picker-target="recent"
           >
-            <header class="emoji-picker__category-head">
+            <header class="lc-emoji-picker__category-head">
               <h3><%= lc_t("lostcoords.ui.emoji_picker.recently_used") %></h3>
               <span class="count"><%= recent.size %></span>
             </header>
 
-            <div class="emoji-picker__grid">
+            <div class="lc-emoji-picker__grid">
               <% recent.each do |emoji| %>
                 <button
                   type="button"
@@ -153,23 +153,23 @@
           </section>
         <% end %>
 
-        <section class="emoji-picker__results" data-emoji-picker-target="results" aria-label="<%= lc_t('lostcoords.ui.emoji_picker.search_results') %>" hidden>
-          <header class="emoji-picker__category-head">
+        <section class="lc-emoji-picker__results" data-lc-emoji-picker-target="results" aria-label="<%= lc_t('lostcoords.ui.emoji_picker.search_results') %>" hidden>
+          <header class="lc-emoji-picker__category-head">
             <h3><%= lc_t("lostcoords.ui.emoji_picker.search_results") %></h3>
-            <span class="count" data-emoji-picker-target="resultsCount">0</span>
+            <span class="count" data-lc-emoji-picker-target="resultsCount">0</span>
           </header>
 
-          <div class="emoji-picker__grid" data-emoji-picker-target="resultsGrid"></div>
+          <div class="lc-emoji-picker__grid" data-lc-emoji-picker-target="resultsGrid"></div>
         </section>
 
-        <p class="emoji-picker__empty" data-emoji-picker-target="empty" hidden>
+        <p class="lc-emoji-picker__empty" data-lc-emoji-picker-target="empty" hidden>
           <%= lc_t("lostcoords.ui.emoji_picker.no_results") %>
         </p>
       </div>
 
-      <footer class="emoji-picker__preview" data-emoji-picker-target="preview">
-        <span class="emoji-picker__preview-emoji" data-emoji-picker-target="previewEmoji"><%= selected %></span>
-        <span class="emoji-picker__preview-name" data-emoji-picker-target="previewName"><%= lc_emoji_picker_search_name(selected) %></span>
+      <footer class="lc-emoji-picker__preview" data-lc-emoji-picker-target="preview">
+        <span class="lc-emoji-picker__preview-emoji" data-lc-emoji-picker-target="previewEmoji"><%= selected %></span>
+        <span class="lc-emoji-picker__preview-name" data-lc-emoji-picker-target="previewName"><%= lc_emoji_picker_search_name(selected) %></span>
       </footer>
     </div>
   </div>

data/app/views/lostcoords/ui/components/_emoji_picker_grid.html.erb

@@ -1,15 +1,15 @@
 <% lc_emoji_picker_groups.each do |group| %>
   <section
-    class="emoji-picker__category"
+    class="lc-emoji-picker__category"
     data-section="<%= group[:key] %>"
     aria-label="<%= group[:name] %>"
   >
-    <header class="emoji-picker__category-head">
+    <header class="lc-emoji-picker__category-head">
       <h3><%= group[:name] %></h3>
       <span class="count"><%= group[:emojis].size %></span>
     </header>
 
-    <div class="emoji-picker__grid">
+    <div class="lc-emoji-picker__grid">
       <% group[:emojis].each do |emoji| %>
         <button
           type="button"

data/app/views/lostcoords/ui/components/_lc_code_block.html.erb

@@ -0,0 +1,18 @@
+<%# locals: (id:, language:, title:, label:, content:, truncated:, max_lines:, attributes:) %>
+<%= tag.div(**attributes) do %>
+  <% if title %>
+    <div class="flex h-10 items-center ps-inset pe-16 pt-inset">
+      <span class="truncate font-mono text-xs text-muted-foreground"><%= title %></span>
+    </div>
+  <% end %>
+  <div class="lc-code-block-copy absolute end-2 top-2 z-raised rounded-full bg-muted">
+    <%= lc_copy_button source: "#{id}-content", icon_only: true, variant: :ghost, size: :sm, aria: { label: lc_t("lostcoords.ui.code_block.copy", label: label) } %>
+  </div>
+  <div class="relative">
+    <pre id="<%= id %>-content" class="m-0 overflow-x-auto ps-inset pe-16 pb-inset font-mono text-[0.8125rem] text-muted-foreground [tab-size:2] <%= title ? 'pt-2 [--lc-code-block-padding:--spacing(7)]' : 'pt-inset [--lc-code-block-padding:--spacing(10)]' %> <%= 'max-h-[calc(var(--lc-code-block-lines)*1lh+var(--lc-code-block-padding))] overflow-y-hidden group-data-expanded/code-block:max-h-none' if truncated %>" style="<%= "--lc-code-block-lines: #{max_lines}" if truncated %>" tabindex="0" role="region" aria-label="<%= label %>"><%= tag.code(content, data: { language: language }) %></pre>
+    <% if truncated %><div class="pointer-events-none absolute inset-x-0 bottom-0 h-12 bg-linear-to-t from-muted to-transparent group-data-expanded/code-block:hidden" aria-hidden="true"></div><% end %>
+  </div>
+  <% if truncated %>
+    <%= lc_button lc_t("lostcoords.ui.code_block.expand"), variant: :ghost, size: :sm, class: "w-full rounded-none", aria: { expanded: false, controls: "#{id}-content" }, data: { action: "lc-code-block#toggle", lc_code_block_target: "toggle", expand_label: lc_t("lostcoords.ui.code_block.expand"), collapse_label: lc_t("lostcoords.ui.code_block.collapse") } %>
+  <% end %>
+<% end %>

data/app/views/lostcoords/ui/components/_lc_collapsible.html.erb

@@ -0,0 +1,5 @@
+<%# locals: (title:, attributes:, content:) %>
+<%= tag.details(**attributes) do %>
+  <summary class="cursor-pointer text-label font-semibold"><%= title %></summary>
+  <div class="pt-heading"><%= content %></div>
+<% end %>

data/app/views/lostcoords/ui/components/_lc_dialog.html.erb

@@ -1,12 +1,15 @@
-<%# locals: (id:, title:, trigger:, attributes:, content:) %>
-<div data-controller="modal">
-  <button type="button" class="<%= lc_button_class(variant: :secondary) %>" aria-haspopup="dialog" aria-controls="<%= id %>" data-action="modal#open"><%= trigger %></button>
+<%# locals: (id:, title:, description:, trigger:, attributes:, content:) %>
+<div data-controller="lc-dialog">
+  <button type="button" class="<%= lc_button_class(variant: :secondary) %>" aria-haspopup="dialog" aria-controls="<%= id %>" data-action="lc-dialog#open" data-slot="dialog-trigger"><%= trigger %></button>
   <%= tag.dialog(**attributes) do %>
-    <div class="flex flex-col gap-5 p-5">
-      <div class="flex items-center justify-between gap-4">
-        <h2 id="<%= id %>-title" class="text-xl font-semibold"><%= title %></h2>
-        <button type="button" class="<%= lc_icon_button_class(size: :sm) %>" aria-label="Close <%= title %>" data-action="modal#close"><%= lc_icon "x-mark", options: { "aria-hidden": true } %></button>
-      </div>
+    <div class="flex flex-col gap-inset p-inset" data-slot="dialog-content">
+      <header class="flex items-start justify-between gap-content" data-slot="dialog-header">
+        <div class="flex min-w-0 flex-col gap-tight">
+          <h2 id="<%= id %>-title" class="<%= lc_heading_class(size: :subheading) %>" data-slot="dialog-title"><%= title %></h2>
+          <% if description.present? %><p id="<%= id %>-description" class="<%= lc_text_class(size: :small, tone: :muted) %>" data-slot="dialog-description"><%= description %></p><% end %>
+        </div>
+        <button type="button" class="<%= lc_icon_button_class(size: :sm, shape: :circle, extra: "-me-related -mt-tight") %>" aria-label="<%= lc_t("lostcoords.ui.dialog.close", title: title) %>" data-action="lc-dialog#close"><%= lc_icon "x-mark", options: { "aria-hidden": true } %></button>
+      </header>
       <%= content %>
     </div>
   <% end %>

data/app/views/lostcoords/ui/components/_lc_floating_panel.html.erb

@@ -0,0 +1,8 @@
+<%# locals: (id:, label:, title:, controller:, role:, trigger_variant:, attributes:, content:) %>
+<%= tag.div(class: "relative inline-flex", data: { controller: controller }) do %>
+  <%= lc_button label, variant: trigger_variant, id: "#{id}-trigger", aria: { haspopup: role, expanded: false, controls: id }, data: { "#{controller}_target" => "trigger", action: "#{controller}#toggle" } %>
+  <%= tag.div(**attributes) do %>
+    <% if title %><h2 id="<%= id %>-title" class="<%= lc_heading_class(size: :subheading) %>"><%= title %></h2><% end %>
+    <%= content %>
+  <% end %>
+<% end %>

data/config/importmap.rb

@@ -1,3 +1,11 @@
-# Keys match the host's own helpers/ and controllers/ pins, so imports and stimulus-loading resolve the same way.
+# Everything lives under lostcoords/ui/*. Controllers are also pinned under the host's controllers/* key,
+# so eagerLoadControllersFrom("controllers", application) registers them as lc-* identifiers. A host file
+# with the same name, such as app/javascript/controllers/lc_dialog_controller.js, replaces the gem's.
+pin "lostcoords/ui", to: "lostcoords/ui/index.js", preload: false
 pin_all_from Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/controllers"), under: "controllers", to: "lostcoords/ui/controllers", preload: false
-pin_all_from Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/helpers"), under: "helpers", to: "lostcoords/ui/helpers", preload: false
+pin_all_from Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/helpers"), under: "lostcoords/ui/helpers", to: "lostcoords/ui/helpers", preload: false
+# pin_all_from keeps one mapping per directory, so the namespaced controller keys are pinned one by one.
+Dir[Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/controllers/*.js")].each do |path|
+  name = File.basename(path, ".js")
+  pin "lostcoords/ui/controllers/#{name}", to: "lostcoords/ui/controllers/#{name}.js", preload: false
+end