@leavepulse/ui 0.20.9 → 0.22.0

package/src/components/LpModal.vue

@@ -32,8 +32,18 @@ const props = withDefaults(
      * regions (e.g. multi-pane catalogues) — the panes scroll, not the modal.
      */
     fillBody?: boolean
+    /**
+     * Where the keyboard lands when the dialog opens. Default `"auto"` picks
+     * the first meaningful control in the body — a field to type in, or failing
+     * that the primary action — instead of the close button, which is what
+     * happens if the DOM order is left to decide.
+     *
+     * `"none"` leaves reka's own behaviour alone; pass a CSS selector to name
+     * the element yourself.
+     */
+    autoFocus?: "auto" | "none" | string
   }>(),
-  { size: "md" },
+  { size: "md", autoFocus: "auto" },
 )
 
 defineEmits<{ (e: "update:open", value: boolean): void }>()
@@ -89,6 +99,58 @@ const bodyPad = computed(() =>
 // reka renders a real element but exposes it as a component instance, so the
 // panel is reached through $el.
 const panelRef = ref<ComponentPublicInstance | null>(null)
+
+/**
+ * Controls that are worth landing on when the dialog opens, in order of
+ * preference. A field the user is going to type in wins over a button, since
+ * typing is the reason most dialogs exist.
+ */
+const AUTO_FOCUS_ORDER = [
+  "input:not([type=hidden]):not([disabled]):not([readonly])",
+  "textarea:not([disabled]):not([readonly])",
+  "select:not([disabled])",
+  "[data-lp-autofocus]",
+  "button:not([disabled]):not([data-lp-dialog-close])",
+  "[href]",
+  "[tabindex]:not([tabindex='-1'])",
+]
+
+/**
+ * reka focuses the first tabbable node, which in this layout is the close
+ * button in the header — the one control nobody opens a dialog to press. Worse,
+ * a dialog opened by mouse gets a programmatic focus, and `:focus-visible` does
+ * not match programmatic focus, so the ring never drew and the keyboard looked
+ * dead even though it worked.
+ *
+ * Both are fixed here: pick a meaningful target, and mark it so the ring shows.
+ */
+function onOpenAutoFocus(event: Event) {
+  if (props.autoFocus === "none") return
+  const panel = panelRef.value?.$el
+  if (!(panel instanceof HTMLElement)) return
+
+  const selectors =
+    props.autoFocus === "auto" ? AUTO_FOCUS_ORDER : [props.autoFocus]
+  for (const selector of selectors) {
+    const target = panel.querySelector<HTMLElement>(selector)
+    if (!target || target.hasAttribute("disabled")) continue
+    event.preventDefault()
+    // `focus-visible` is the browser's own heuristic and cannot be forced, so
+    // the ring is driven off an attribute the kit owns. Removed as soon as the
+    // element loses focus, leaving normal focus-visible behaviour in charge.
+    target.setAttribute("data-lp-focus-ring", "")
+    target.addEventListener(
+      "blur",
+      () => target.removeAttribute("data-lp-focus-ring"),
+      { once: true },
+    )
+    target.focus()
+    if (target instanceof HTMLInputElement && target.type === "text") {
+      target.select()
+    }
+    return
+  }
+}
 const tweening = ref(false)
 const resizing = ref(false)
 
@@ -248,6 +310,7 @@ onBeforeUnmount(() => {
         :class="[widthClass, tweening ? 'transition-[height] duration-fast ease-[var(--ease-emphasized)] motion-reduce:transition-none' : '']"
         :style="width ? { width } : undefined"
         v-bind="describedByAttrs"
+        @open-auto-focus="onOpenAutoFocus"
       >
         <header v-if="title || $slots.title" class="flex shrink-0 items-start justify-between gap-4 p-5 pb-3">
           <div class="flex flex-col gap-1">
@@ -258,7 +321,10 @@ onBeforeUnmount(() => {
               {{ description }}
             </DialogDescription>
           </div>
+          <!-- Marked so the auto-focus pass skips it: it is first in the DOM
+               and last in usefulness. Still reachable by Tab and Escape. -->
           <DialogClose
+            data-lp-dialog-close
             class="group flex shrink-0 items-center rounded-md p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
             aria-label="Close"
           >

package/src/components/LpScrollArea.vue

@@ -92,15 +92,32 @@ function measureEdges(el: HTMLElement) {
   atBottom.value = el.scrollTop + el.clientHeight >= el.scrollHeight - 1
 }
 
+/**
+ * reka hard-codes `tabindex="0"` on the viewport so a scrollable region can be
+ * reached and scrolled by keyboard. That is right when there IS something to
+ * scroll and wrong when there isn't: in a dialog whose body fits, the first Tab
+ * landed on the box itself, nothing moved on screen, and the shortcut read as
+ * broken. The attribute is set after `$attrs`, so a prop cannot override it —
+ * it has to come off the element.
+ *
+ * Kept in sync with content size rather than set once: a list that fills in
+ * later becomes scrollable without anything else changing.
+ */
+function syncViewportFocusable(el: HTMLElement) {
+  const scrollable = el.scrollHeight > el.clientHeight || el.scrollWidth > el.clientWidth
+  if (scrollable) el.setAttribute("tabindex", "0")
+  else el.removeAttribute("tabindex")
+}
+
 function onViewportScroll(event: Event) {
   if (props.fade) measureEdges(event.target as HTMLElement)
   emit("scroll", event)
 }
 
-// Scrolling is not the only thing that changes which edges hide content: a list
-// that fills in, a panel that resizes, or content short enough to need no fade
-// at all never fire a scroll event. Watched only when `fade` is on, since
-// nothing else here depends on the measurements.
+// Scrolling is not the only thing that changes what we measure: a list that
+// fills in, a panel that resizes, or content short enough to need no fade at
+// all never fire a scroll event. Runs regardless of `fade` — the focusable
+// state has to track content size even where the fade is off.
 let edgeResize: ResizeObserver | undefined
 let edgeMutation: MutationObserver | undefined
 
@@ -115,9 +132,12 @@ watch(
   [viewportEl, () => props.fade],
   ([el, enabled]) => {
     stopEdgeWatch()
-    if (!el || !enabled) return
+    if (!el) return
 
-    const remeasure = () => measureEdges(el)
+    const remeasure = () => {
+      if (enabled) measureEdges(el)
+      syncViewportFocusable(el)
+    }
     remeasure()
 
     if (typeof ResizeObserver !== "undefined") {

package/src/components/LpShortcutsDialog.vue

@@ -0,0 +1,127 @@
+<script setup lang="ts">
+/*
+ * A keyboard reference, conventionally opened with F1.
+ *
+ * Shortcuts are passed in as data rather than read off a live binding list: a
+ * binding knows its key but not what to call it, and in most apps half of them
+ * are only mounted in the section they belong to — a reference that lists what
+ * happens to be active is not a reference.
+ *
+ * Combos are written the way they read ("Ctrl+Shift+M", "←→↑↓") and split on
+ * "+" into one <kbd> each.
+ */
+import LpModal from "./LpModal.vue"
+import { appleModifierLabel } from "../composables/useHotkeys"
+
+export interface ShortcutEntry {
+  /** Rendered one <kbd> per "+"-separated key, so write it the way it reads. */
+  combo: string
+  label: string
+}
+
+export interface ShortcutGroup {
+  title: string
+  entries: ShortcutEntry[]
+}
+
+const props = withDefaults(
+  defineProps<{
+    open?: boolean
+    groups: ShortcutGroup[]
+    title?: string
+    description?: string
+  }>(),
+  { open: false, title: "Keyboard shortcuts" },
+)
+
+const emit = defineEmits<{ (e: "update:open", value: boolean): void }>()
+</script>
+
+<template>
+  <LpModal
+    :open="props.open"
+    size="lg"
+    :title="props.title"
+    :description="props.description"
+    @update:open="(value: boolean) => emit('update:open', value)"
+  >
+    <div class="shortcut-groups">
+      <section v-for="group in props.groups" :key="group.title" class="shortcut-group">
+        <h3>{{ group.title }}</h3>
+        <dl>
+          <div v-for="entry in group.entries" :key="entry.combo" class="shortcut-row">
+            <dt>{{ entry.label }}</dt>
+            <dd>
+              <kbd v-for="(key, index) in entry.combo.split('+')" :key="`${key}-${index}`">
+                {{ appleModifierLabel(key.trim()) }}
+              </kbd>
+            </dd>
+          </div>
+        </dl>
+      </section>
+    </div>
+  </LpModal>
+</template>
+
+<style scoped>
+/* Two columns where there is room: the list is long enough that one column
+   pushes the last group off a laptop screen. */
+.shortcut-groups {
+  display: grid;
+  gap: 18px;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+}
+
+.shortcut-group h3 {
+  margin: 0 0 6px;
+  color: var(--color-muted);
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.shortcut-group dl {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  margin: 0;
+}
+
+.shortcut-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 5px 0;
+}
+
+.shortcut-row dt {
+  color: var(--color-ink);
+  font-size: 0.82rem;
+  min-width: 0;
+}
+
+.shortcut-row dd {
+  display: flex;
+  flex-shrink: 0;
+  gap: 3px;
+  margin: 0;
+}
+
+kbd {
+  display: inline-flex;
+  min-width: 20px;
+  align-items: center;
+  justify-content: center;
+  padding: 2px 6px;
+  border: 1px solid var(--color-line-strong);
+  border-bottom-width: 2px;
+  border-radius: 5px;
+  background: color-mix(in srgb, var(--color-ink) 6%, transparent);
+  color: var(--color-muted-strong);
+  font-family: inherit;
+  font-size: 0.7rem;
+  line-height: 1.5;
+}
+</style>

package/src/components/LpTable.vue

@@ -4,6 +4,7 @@ import LpCheckbox from "./LpCheckbox.vue"
 import LpContextMenu, { type ContextMenuItemDef } from "./LpContextMenu.vue"
 import LpIcon from "./LpIcon.vue"
 import LpScrollArea from "./LpScrollArea.vue"
+import { useRovingFocus } from "../composables/useRovingFocus"
 
 export interface TableColumn<Row> {
   key: string
@@ -134,6 +135,54 @@ function toggleRow(key: RowKey, checked: boolean) {
 
 const colSpan = computed(() => props.columns.length + (props.selectable ? 1 : 0))
 
+/*
+ * Keyboard navigation over the rows. A table is one Tab stop, not one per row:
+ * a few hundred rows would otherwise be a few hundred Tab presses, which is the
+ * same as having no keyboard support at all.
+ *
+ * Typeahead matches the FIRST column, which in practice is the name — the thing
+ * a person looking for a row would type. Rows are addressed by their key so the
+ * cursor survives a re-sort.
+ */
+const rovingItems = computed(() =>
+  displayRows.value.map((row, index) => ({
+    id: String(keyFor(row, index)),
+    label: String(row[props.columns[0]?.key ?? ""] ?? ""),
+  })),
+)
+
+const rowByKey = computed(() => {
+  const map = new Map<string, T>()
+  displayRows.value.forEach((row, index) => map.set(String(keyFor(row, index)), row))
+  return map
+})
+
+const roving = useRovingFocus(rovingItems, {
+  onActivate: (id) => {
+    const row = rowByKey.value.get(id)
+    if (!row) return
+    // Space ticks the box where the table has one, since that is what a
+    // selectable list is for; Enter always means "open this row".
+    emit("rowClick", row)
+  },
+})
+
+function onRowKeydown(event: KeyboardEvent) {
+  // Space ticks rather than activates when the table is selectable — the
+  // standard split for a multi-select list.
+  if (event.key === " " && props.selectable && roving.activeId.value) {
+    event.preventDefault()
+    const key = roving.activeId.value
+    const row = rowByKey.value.get(key)
+    if (row) {
+      const rowKey = keyFor(row, displayRows.value.indexOf(row))
+      toggleRow(rowKey, !selectedSet.value.has(rowKey))
+    }
+    return
+  }
+  roving.onKeydown(event)
+}
+
 // With stickyHeader, the overlay scrollbar would otherwise run up under the
 // pinned header. Measure the header height and inset the bar by it so the bar
 // starts below the header. Tracked live (density/content can change it).
@@ -213,7 +262,11 @@ const barInsetTop = computed(() =>
           </th>
         </tr>
       </thead>
-      <tbody>
+      <!-- The keydown lives on the rows, not here: only a focused row should
+           steer, and a stray key from a control inside a cell must not move the
+           cursor. The container is bound only so the composable can find rows
+           to focus. -->
+      <tbody :ref="(el) => roving.setContainer(el as HTMLElement | null)">
         <tr v-if="displayRows.length === 0">
           <td :colspan="colSpan" class="px-4 py-10 text-center text-muted">
             <LpIcon :name="emptyIcon" :size="22" class="mx-auto mb-2 opacity-60" />
@@ -230,9 +283,11 @@ const barInsetTop = computed(() =>
           :items="menuFor(row)"
         >
           <tr
-            class="border-b border-line/60 transition-colors last:border-0 hover:bg-surface-soft/60"
+            class="border-b border-line/60 outline-none transition-colors last:border-0 hover:bg-surface-soft/60 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring data-[active]:bg-surface-soft/40"
             :class="selectedSet.has(keyFor(row, index)) ? 'bg-brand-soft/40' : ''"
+            v-bind="roving.itemProps(String(keyFor(row, index)))"
             @click="emit('rowClick', row)"
+            @keydown="onRowKeydown"
           >
             <td v-if="selectable" class="w-px px-4 py-3" @click.stop>
               <LpCheckbox

package/src/components/LpTooltip.vue

@@ -1,4 +1,28 @@
 <script setup lang="ts">
+/*
+ * Tooltip for controls whose meaning is not written on them — an icon button,
+ * a truncated value, a disabled action that owes an explanation.
+ *
+ * Why not the native `title` attribute: it is drawn by the operating system, so
+ * it looks different on every platform and cannot be themed; it waits about a
+ * second before appearing; it cannot wrap or hold markup; and screen-reader
+ * support for it is inconsistent — it is often ignored outright.
+ *
+ * Accessibility contract, which is the part that is easy to get wrong:
+ *
+ *   `label` — the tip IS the control's name (an icon button). The text is put
+ *     on the TRIGGER as aria-label, so a screen reader announces "Delete,
+ *     button" rather than "button". reka only ever wires aria-describedby,
+ *     which describes a control that already has a name — it cannot name a
+ *     nameless one, so naming has to happen here.
+ *
+ *   default — the tip merely ADDS to a control that already has a name. reka's
+ *     own aria-describedby carries it, and the name is announced first.
+ *
+ * Either way the trigger keeps a real accessible name, which is what `title`
+ * alone could not guarantee. reka opens the tip on keyboard focus as well as
+ * hover and closes it on Escape, satisfying WCAG 1.4.13.
+ */
 import {
   TooltipContent,
   TooltipPortal,
@@ -8,19 +32,47 @@ import {
 } from "reka-ui"
 import { PANEL_SURFACE, TOOLTIP_ANIM } from "./dropdown"
 
-defineProps<{ content?: string; sideOffset?: number }>()
+withDefaults(
+  defineProps<{
+    content?: string
+    sideOffset?: number
+    /** Which edge to prefer; flips automatically when there is no room. */
+    side?: "top" | "right" | "bottom" | "left"
+    /**
+     * The tip names the control rather than describing it — for a trigger with
+     * no visible text of its own. Sets the accessible name instead of only
+     * adding a description.
+     */
+    label?: boolean
+    /** Milliseconds before the tip appears on hover. */
+    delay?: number
+    /**
+     * Show on any focus, not just keyboard focus. Off by default: a tip that
+     * pops up after every mouse click on the trigger is noise.
+     */
+    showOnPointerFocus?: boolean
+  }>(),
+  { delay: 200, side: "top" },
+)
 </script>
 
 <template>
-  <TooltipProvider :delay-duration="200">
-    <TooltipRoot>
-      <TooltipTrigger as-child>
+  <TooltipProvider :delay-duration="delay">
+    <TooltipRoot :ignore-non-keyboard-focus="!showOnPointerFocus">
+      <!-- `as-child` merges these onto the caller's own element, so the label
+           lands on the real button rather than on a wrapper. -->
+      <TooltipTrigger as-child :aria-label="label ? content : undefined">
         <slot />
       </TooltipTrigger>
       <TooltipPortal>
         <TooltipContent
+          :side="side"
           :side-offset="sideOffset ?? 6"
-          :class="[PANEL_SURFACE, TOOLTIP_ANIM, 'z-(--z-tooltip) px-2.5 py-1.5 text-xs text-ink']"
+          :class="[
+            PANEL_SURFACE,
+            TOOLTIP_ANIM,
+            'z-(--z-tooltip) max-w-[min(20rem,90vw)] px-2.5 py-1.5 text-xs text-ink',
+          ]"
         >
           <slot name="content">{{ content }}</slot>
         </TooltipContent>

package/src/composables/useHotkeys.ts

@@ -0,0 +1,131 @@
+import { onBeforeUnmount, onMounted, type MaybeRefOrGetter, toValue } from "vue"
+
+/*
+ * One keydown listener over a registry of bindings, so a shortcut is declared
+ * next to the action it runs instead of growing another window-level handler.
+ *
+ * Three things every hand-rolled shortcut handler tends to get wrong, and the
+ * reason this is worth sharing rather than rewriting per app:
+ *
+ *   layout — a binding names its key twice over. `key` is what the layout
+ *     produced, `code` is the physical position, and either matching counts. On
+ *     a Cyrillic layout Ctrl+K arrives as `key: "л"` with `code: "KeyK"`, and a
+ *     user pressing the key printed "K" expects it to work either way.
+ *
+ *   IME — a composing input delivers every keystroke as its own event, so
+ *     acting on them fires shortcuts mid-word.
+ *
+ *   text entry — a shortcut that steals a key from someone typing is a bug,
+ *     except for the few that mean something in a field (Escape, a palette).
+ *
+ * Modifier note: Ctrl and Meta are one modifier here, since macOS binds ⌘ where
+ * the rest bind Ctrl. Label the difference in the UI, not in the binding.
+ */
+
+export interface HotkeyBinding {
+  /** Layout-produced key, compared case-insensitively ("l", "f2", "escape"). */
+  key: string
+  /**
+   * Physical key position ("KeyL", "F2", "Digit1"). Matches on its own, which
+   * is what makes non-Latin layouts work.
+   */
+  code?: string
+  /** Ctrl on Windows/Linux, ⌘ on macOS — the two are treated as one. */
+  ctrl?: boolean
+  shift?: boolean
+  alt?: boolean
+  /**
+   * Runs even while a text field has focus. Only for shortcuts that mean
+   * something there — Escape, and the palette the user reaches from anywhere.
+   */
+  allowInInput?: boolean
+  /**
+   * Returning `false` declines the key: the event keeps its default and the
+   * search moves on. This is what lets a binding defer to a layer that owns the
+   * key better than it does — Escape belongs to whichever overlay is on top,
+   * and swallowing it here would close all of them.
+   */
+  handler: () => void | boolean
+}
+
+/**
+ * Whether this machine prints ⌘ where the rest print Ctrl. Read once: the
+ * keyboard does not change under a running window, and the check is only ever
+ * used to pick a label.
+ */
+export const isAppleKeyboard =
+  typeof navigator !== "undefined"
+  && /Mac|iPhone|iPad|iPod/.test(navigator.platform || "")
+
+/**
+ * The symbol to print for a modifier on this platform. Bindings treat Ctrl and
+ * Meta as one modifier, so only the label may differ — never the binding.
+ */
+export function appleModifierLabel(key: string): string {
+  if (!isAppleKeyboard) return key
+  if (key === "Ctrl") return "⌘"
+  if (key === "Alt") return "⌥"
+  return key
+}
+
+const TEXT_INPUT_TYPES = new Set([
+  "text",
+  "search",
+  "email",
+  "number",
+  "password",
+  "tel",
+  "url",
+])
+
+/**
+ * Whether the event lands in something the user is typing into. Checked off the
+ * event target rather than `document.activeElement` so it stays right inside a
+ * dialog's focus trap.
+ */
+function isTextEntry(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false
+  if (target.isContentEditable) return true
+  if (target instanceof HTMLTextAreaElement) return true
+  if (target instanceof HTMLInputElement) {
+    return TEXT_INPUT_TYPES.has(target.type)
+  }
+  return false
+}
+
+function matches(event: KeyboardEvent, binding: HotkeyBinding): boolean {
+  const ctrlHeld = event.ctrlKey || event.metaKey
+  if (ctrlHeld !== Boolean(binding.ctrl)) return false
+  if (event.shiftKey !== Boolean(binding.shift)) return false
+  if (event.altKey !== Boolean(binding.alt)) return false
+  return (
+    event.key.toLowerCase() === binding.key.toLowerCase()
+    || (binding.code !== undefined && event.code === binding.code)
+  )
+}
+
+/**
+ * Bind a list of hotkeys for as long as the calling component is mounted.
+ *
+ * The list is read on every keystroke rather than captured once, so bindings
+ * may come and go with the state that owns them — a getter is the point, not a
+ * formality.
+ */
+export function useHotkeys(bindings: MaybeRefOrGetter<HotkeyBinding[]>) {
+  function onKeydown(event: KeyboardEvent) {
+    if (event.isComposing) return
+    const inTextEntry = isTextEntry(event.target)
+    for (const binding of toValue(bindings)) {
+      if (inTextEntry && !binding.allowInInput) continue
+      if (!matches(event, binding)) continue
+      // Claimed only once the handler has run and not declined, so a binding
+      // that stands down leaves the key untouched for whoever handles it next.
+      if (binding.handler() === false) continue
+      event.preventDefault()
+      return
+    }
+  }
+
+  onMounted(() => window.addEventListener("keydown", onKeydown))
+  onBeforeUnmount(() => window.removeEventListener("keydown", onKeydown))
+}