lostcoords-ui 0.5.0 → 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

@@ -4,12 +4,15 @@ import ConfirmDialog from "lostcoords/ui/controllers/lc_confirm_dialog_controlle
 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"
 
@@ -20,12 +23,15 @@ const controllers = {
   "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,
 }

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

@@ -15,7 +15,7 @@
   <% 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->lc-emoji-picker#select"
@@ -24,10 +24,10 @@
     </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-lc-emoji-picker-target="trigger"
       data-action="click->lc-emoji-picker#toggle"
@@ -40,7 +40,7 @@
     </button>
 
     <div
-      class="emoji-picker__popover <%= popover_class %>"
+      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"
@@ -48,17 +48,17 @@
       aria-label="<%= label %>"
       hidden
     >
-      <span class="emoji-picker__handle" data-lc-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"
@@ -72,10 +72,10 @@
           >
         </div>
 
-        <div class="emoji-picker__tones" data-lc-emoji-picker-target="tones">
+        <div class="lc-emoji-picker__tones" data-lc-emoji-picker-target="tones">
           <button
             type="button"
-            class="emoji-picker__tone-toggle"
+            class="lc-emoji-picker__tone-toggle"
             data-lc-emoji-picker-target="toneToggle"
             data-action="click->lc-emoji-picker#toggleTones"
             aria-haspopup="true"
@@ -83,11 +83,11 @@
             aria-label="<%= lc_t("lostcoords.ui.emoji_picker.skin_tone") %>"
           >✋</button>
 
-          <div class="emoji-picker__tone-menu <%= popover_class %>" data-lc-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->lc-emoji-picker#selectTone"
@@ -98,11 +98,11 @@
         </div>
       </div>
 
-      <nav class="emoji-picker__tabs" data-lc-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"
+            class="lc-emoji-picker__tab"
             data-lc-emoji-picker-target="tab"
             data-target-section="recent"
             data-action="click->lc-emoji-picker#jumpTo"
@@ -113,7 +113,7 @@
         <% lc_emoji_picker_groups.each do |group| %>
           <button
             type="button"
-            class="emoji-picker__tab"
+            class="lc-emoji-picker__tab"
             data-lc-emoji-picker-target="tab"
             data-target-section="<%= group[:key] %>"
             data-action="click->lc-emoji-picker#jumpTo"
@@ -122,20 +122,20 @@
         <% end %>
       </nav>
 
-      <div class="emoji-picker__body" data-lc-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-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-lc-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-lc-emoji-picker-target="resultsCount">0</span>
           </header>
 
-          <div class="emoji-picker__grid" data-lc-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-lc-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-lc-emoji-picker-target="preview">
-        <span class="emoji-picker__preview-emoji" data-lc-emoji-picker-target="previewEmoji"><%= selected %></span>
-        <span class="emoji-picker__preview-name" data-lc-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

@@ -5,7 +5,7 @@
       <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-10 rounded-full bg-muted">
+  <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">

data/lib/lostcoords/ui/action_view.rb

@@ -8,5 +8,6 @@ require_relative "icons"
 require_relative "parts"
 require_relative "form_builder"
 require_relative "helpers"
+require_relative "stylesheets"
 
 Lostcoords::Ui.load_translations!

data/lib/lostcoords/ui/builders.rb

@@ -10,8 +10,8 @@ module Lostcoords::Ui
 
       def component?
         !name.to_s.end_with?("_class") &&
-          !%i[lc_tw lc_sheet_data lc_alert_icon].include?(name) &&
-          helper != "EmojiPickerHelper"
+          !%i[lc_tw lc_sheet_data lc_shortcut_data lc_alert_icon].include?(name) &&
+          (helper != "EmojiPickerHelper" || name == :lc_emoji_picker)
       end
     end
 

data/lib/lostcoords/ui/form_builder.rb

@@ -33,6 +33,11 @@ module Lostcoords::Ui
       super(method, choices, options, control_options(method, html_options, "select", @template.lc_select_class(size: size)), &block)
     end
 
+    SELECT_OPTIONS = %i[include_blank prompt selected disabled].freeze
+
+    alias_method :rails_check_box, :check_box
+    private :rails_check_box
+
     def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
       super(method, control_options(method, options, "checkbox-input", @template.lc_checkbox_class), checked_value, unchecked_value)
     end
@@ -44,13 +49,14 @@ module Lostcoords::Ui
 
     # A checkbox drawn as a switch, with its label beside it.
     def switch(method, label: nil, hint: nil, checked_value: "1", unchecked_value: "0", **options)
-      input = check_box(method, { role: "switch", class: @template.lc_switch_class(extra: options.delete(:class)), data: { slot: "switch-input" } }.merge(options), checked_value, unchecked_value)
+      input = rails_check_box(method, control_options(method, { role: "switch" }.merge(options), "switch-input", @template.lc_switch_class, described: true), checked_value, unchecked_value)
       choice_label(method, label, hint, "switch", input)
     end
 
     # A checkbox with its label beside it.
     def choice(method, label: nil, hint: nil, checked_value: "1", unchecked_value: "0", **options)
-      choice_label(method, label, hint, "checkbox", check_box(method, options, checked_value, unchecked_value))
+      input = rails_check_box(method, control_options(method, options, "checkbox-input", @template.lc_checkbox_class, described: true), checked_value, unchecked_value)
+      choice_label(method, label, hint, "checkbox", input)
     end
 
     def label(method, text = nil, options = {}, &block)
@@ -68,17 +74,22 @@ module Lostcoords::Ui
       end
       variant = options.delete(:variant) || :primary
       size = options.delete(:size) || :md
-      super(value, options.merge(class: @template.lc_button_class(variant: variant, size: size, extra: options[:class])))
+      data = { slot: "button", variant: variant, size: size }.merge(options.delete(:data) || {})
+      super(value, options.merge(class: @template.lc_button_class(variant: variant, size: size, extra: options[:class]), data: data))
     end
 
     # Label, control, hint and the attribute's errors in one field. `as:` names the control helper;
-    # a block renders a custom control and receives its attributes to splat with `**control`.
-    def field(method, label: nil, hint: nil, as: :text_field, **options, &block)
+    # `as: :select` takes `choices:` and Rails' select options such as `include_blank:`. A block renders
+    # a custom control and receives its attributes to splat with `**control`.
+    def field(method, label: nil, hint: nil, as: :text_field, choices: nil, **options, &block)
       @template.lc_field(label: label || human_name(method), id: field_id(method), hint: hint, error: errors_for(method)) do |control|
-        if block
-          @template.capture(control, &block)
+        next @template.capture(control, &block) if block
+
+        attributes = @template.send(:lc_attributes, options.except(*SELECT_OPTIONS), control.to_hash.except(:id))
+        if as.to_sym == :select
+          select(method, choices, options.slice(*SELECT_OPTIONS), attributes)
         else
-          public_send(as, method, **options, **control.to_hash.except(:id))
+          public_send(as, method, attributes.merge(options.slice(*SELECT_OPTIONS)))
         end
       end
     end
@@ -88,16 +99,18 @@ module Lostcoords::Ui
         options[:size].is_a?(Symbol) || options[:size].is_a?(String) && options[:size].match?(/\A[a-z]+\z/) ? options.delete(:size).to_sym : :md
       end
 
-      def control_options(method, options, slot, classes)
+      # described: points aria-describedby at the error a choice label renders, as lc_field does for its control.
+      def control_options(method, options, slot, classes, described: false)
         options = options.dup
         aria = (options.delete(:aria) || {}).dup
         aria[:invalid] = true if errors_for(method).any? && !aria.key?(:invalid)
+        aria[:describedby] = [ aria[:describedby], "#{field_id(method)}-error" ].compact.join(" ") if described && errors_for(method).any?
         data = { slot: slot }.merge(options.delete(:data) || {})
         options.merge(class: @template.lc_tw(classes, options[:class]), aria: aria, data: data)
       end
 
       def choice_label(method, text, hint, slot, input)
-        @template.send(:lc_choice_label, slot, text || human_name(method), hint, input, for: field_id(method))
+        @template.send(:lc_choice_label, slot, text || human_name(method), hint, input, errors: errors_for(method), error_id: "#{field_id(method)}-error", for: field_id(method))
       end
 
       def errors_for(method)

data/lib/lostcoords/ui/stylesheets.rb

@@ -0,0 +1,25 @@
+require "fileutils"
+require "pathname"
+
+module Lostcoords::Ui
+  # The Tailwind entries a host can import: the document defaults, core.css and one file per opt-in component.
+  module Stylesheets
+    ROOT = Pathname(File.expand_path("../../../app/assets/tailwind/lostcoords/ui", __dir__))
+
+    def self.entries
+      [ ROOT.join("base.css"), ROOT.join("core.css"), *ROOT.glob("components/*.css").sort ]
+    end
+
+    # tailwindcss-rails gives an engine one generated import, of engine.css. These proxies give every
+    # entry a stable path in the host, such as builds/tailwind/lostcoords_ui/components/dialog.css.
+    def self.write(builds)
+      directory = Pathname(builds).join("lostcoords_ui")
+      FileUtils.rm_rf(directory)
+      entries.each do |entry|
+        path = directory.join(entry.relative_path_from(ROOT))
+        FileUtils.mkdir_p(path.dirname)
+        path.write("/* Generated by lostcoords-ui before every Tailwind build; do not edit. */\n@import \"#{entry}\";\n")
+      end
+    end
+  end
+end

data/lib/lostcoords/ui/version.rb

@@ -1,5 +1,5 @@
 module Lostcoords
   module Ui
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/tasks/lostcoords_ui.rake

@@ -13,3 +13,14 @@ namespace :lostcoords do
     end
   end
 end
+
+# Runs with tailwindcss-rails' own engines step, before every tailwindcss:build and tailwindcss:watch.
+# Apps without tailwindcss-rails import the gem's stylesheets by path instead.
+if defined?(Tailwindcss::Engines)
+  namespace :tailwindcss do
+    task :engines do
+      require "lostcoords/ui/stylesheets"
+      Lostcoords::Ui::Stylesheets.write(Rails.root.join("app/assets/builds/tailwind"))
+    end
+  end
+end