@leavepulse/ui 0.21.0 → 0.22.0

package/dist/composables/useRovingFocus.js

@@ -0,0 +1,160 @@
+import { ref, computed, toValue, watch } from "vue";
+const TYPEAHEAD_RESET_MS = 700;
+function useRovingFocus(items, options = {}) {
+  const {
+    orientation = "vertical",
+    loop = true,
+    typeahead = true,
+    onActivate,
+    onEscape
+  } = options;
+  const activeId = ref();
+  const containerEl = ref(null);
+  const enabled = computed(() => toValue(items).filter((item) => !item.disabled));
+  watch(
+    enabled,
+    (list) => {
+      if (list.length === 0) {
+        activeId.value = void 0;
+        return;
+      }
+      if (!activeId.value || !list.some((item) => item.id === activeId.value)) {
+        activeId.value = list[0].id;
+      }
+    },
+    { immediate: true }
+  );
+  function indexOfActive() {
+    return enabled.value.findIndex((item) => item.id === activeId.value);
+  }
+  function focus(id) {
+    if (id) activeId.value = id;
+  }
+  function move(delta) {
+    const list = enabled.value;
+    if (list.length === 0) return;
+    const from = indexOfActive();
+    if (from === -1) {
+      focus(list[0].id);
+      return;
+    }
+    let next = from + delta;
+    if (next < 0) next = loop ? list.length - 1 : 0;
+    if (next >= list.length) next = loop ? 0 : list.length - 1;
+    focus(list[next].id);
+  }
+  function first() {
+    focus(enabled.value[0]?.id);
+  }
+  function last() {
+    focus(enabled.value.at(-1)?.id);
+  }
+  let typed = "";
+  let typedAt = 0;
+  function typeaheadTo(character) {
+    const now = Date.now();
+    typed = now - typedAt > TYPEAHEAD_RESET_MS ? character : typed + character;
+    typedAt = now;
+    const list = enabled.value;
+    const needle = typed.toLowerCase();
+    const repeated = typed.length > 1 && [...typed].every((c) => c === typed[0]);
+    const query = repeated ? typed[0].toLowerCase() : needle;
+    const from = indexOfActive();
+    const offset = repeated || typed.length === 1 ? 1 : 0;
+    for (let step = 0; step < list.length; step += 1) {
+      const item = list[(from + offset + step) % list.length];
+      if (item.label?.toLowerCase().startsWith(query)) {
+        focus(item.id);
+        return;
+      }
+    }
+  }
+  function onKeydown(event) {
+    const vertical = orientation === "vertical" || orientation === "both";
+    const horizontal = orientation === "horizontal" || orientation === "both";
+    switch (event.key) {
+      case "ArrowDown":
+        if (!vertical) return;
+        event.preventDefault();
+        move(1);
+        return;
+      case "ArrowUp":
+        if (!vertical) return;
+        event.preventDefault();
+        move(-1);
+        return;
+      case "ArrowRight":
+        if (!horizontal) return;
+        event.preventDefault();
+        move(1);
+        return;
+      case "ArrowLeft":
+        if (!horizontal) return;
+        event.preventDefault();
+        move(-1);
+        return;
+      case "Home":
+        event.preventDefault();
+        first();
+        return;
+      case "End":
+        event.preventDefault();
+        last();
+        return;
+      case "Enter":
+      case " ":
+        if (!activeId.value) return;
+        event.preventDefault();
+        onActivate?.(activeId.value);
+        return;
+      case "Escape":
+        if (!onEscape) return;
+        event.preventDefault();
+        onEscape();
+        return;
+    }
+    if (typeahead && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey && event.key !== " ") {
+      event.preventDefault();
+      typeaheadTo(event.key);
+    }
+  }
+  watch(activeId, (id) => {
+    if (!id || typeof document === "undefined") return;
+    const container = containerEl.value;
+    if (!container || !container.contains(document.activeElement)) return;
+    const target = container.querySelector(
+      `[data-roving-id="${CSS.escape(id)}"]`
+    );
+    target?.focus();
+  });
+  function setContainer(el) {
+    containerEl.value = el;
+  }
+  const containerProps = computed(() => ({
+    ref: (el) => setContainer(el instanceof HTMLElement ? el : null),
+    onKeydown
+  }));
+  function itemProps(id) {
+    const active = activeId.value === id;
+    return {
+      tabindex: active ? 0 : -1,
+      "data-active": active ? "" : void 0,
+      "data-roving-id": id,
+      onFocus: () => focus(id)
+    };
+  }
+  return {
+    activeId,
+    focus,
+    move,
+    first,
+    last,
+    onKeydown,
+    setContainer,
+    containerProps,
+    itemProps
+  };
+}
+export {
+  useRovingFocus
+};

package/dist/index.d.ts

@@ -113,6 +113,8 @@ export { useHotkeys, isAppleKeyboard, appleModifierLabel } from './composables/u
 export type { HotkeyBinding } from './composables/useHotkeys';
 export { useInputFilter } from './composables/useInputFilter';
 export type { UseInputFilterOptions } from './composables/useInputFilter';
+export { useRovingFocus } from './composables/useRovingFocus';
+export type { RovingItem, UseRovingFocusOptions } from './composables/useRovingFocus';
 export { useSettled } from './composables/useSettled';
 export type { UseSettledOptions } from './composables/useSettled';
 export { useTilt } from './composables/useTilt';

package/dist/index.js

@@ -1,9 +1,9 @@
 import { _ } from "./chunks/LayoutCanvas-Dd20boUG.js";
-import { _ as _2 } from "./chunks/LpAddressInput-B411MOJa.js";
+import { _ as _2 } from "./chunks/LpAddressInput-Dah7asXy.js";
 import { _ as _3 } from "./chunks/LpMapPicker-DFKrd1Ne.js";
 import { OSM_TILES, createNominatimProvider, emptyAddress, formatAddress, project, tileUrl, unproject } from "./components/address.js";
 import { _ as _4 } from "./chunks/LpAlert-BAYHDSS1.js";
-import { _ as _5 } from "./chunks/LpAppShell-CfM7fdr3.js";
+import { _ as _5 } from "./chunks/LpAppShell-DGZv907S.js";
 import { _ as _6 } from "./chunks/LpAutocomplete-DIgXmtCA.js";
 import { _ as _7 } from "./chunks/LpAvatar-B1Ez0ZAx.js";
 import { _ as _8 } from "./chunks/LpBadge-CXzBPnwO.js";
@@ -14,15 +14,15 @@ import { _ as _12 } from "./chunks/LpCard-BmrTvWOe.js";
 import { _ as _13 } from "./chunks/LpCheckbox-BO0zuuPh.js";
 import { _ as _14 } from "./chunks/LpCodeBlock-CSiOSPs8.js";
 import { default as default2 } from "./components/LpCommandPalette.vue.js";
-import { _ as _15 } from "./chunks/LpConfirmDialog-D8pBGPOI.js";
+import { _ as _15 } from "./chunks/LpConfirmDialog-CkMzeKdp.js";
 import { _ as _16 } from "./chunks/LpContextMenu-D0mzXqA7.js";
 import { _ as _17 } from "./chunks/LpDatePicker-dY2q4dr4.js";
 import { _ as _18 } from "./chunks/LpDisclosure-DP6yfgfM.js";
 import { _ as _19 } from "./chunks/LpDivider-CUX46KR0.js";
-import { _ as _20 } from "./chunks/LpDrawer-B4cNj39a.js";
+import { _ as _20 } from "./chunks/LpDrawer-DAJN5rGK.js";
 import { _ as _21 } from "./chunks/LpDropdownMenu-DJpoqRCb.js";
 import { _ as _22 } from "./chunks/LpEmptyState-CrfyRJUG.js";
-import { _ as _23 } from "./chunks/LpFileTree-d9nXtSVo.js";
+import { _ as _23 } from "./chunks/LpFileTree-DWx77B1F.js";
 import { ancestorIds, checkStateOf, checkedCount, computeStats, fileIcon, formatModified, formatSize, sortNodes, subtreeIds, subtreeSize } from "./components/fileTree.js";
 import { _ as _24 } from "./chunks/LpFormField-Bn-ZwC6z.js";
 import { _ as _25 } from "./chunks/LpIcon-CCnX5_2j.js";
@@ -31,9 +31,9 @@ import { _ as _27 } from "./chunks/LpInput-BauZRyzm.js";
 import { _ as _28 } from "./chunks/LpLightbox-Ci35Y_xP.js";
 import { fileNameOf } from "./components/lightbox.js";
 import { _ as _29 } from "./chunks/LpLink-DHwOEp4e.js";
-import { _ as _30 } from "./chunks/LpLogViewer-BXPBUV21.js";
-import { _ as _31 } from "./chunks/LpModal-DKFdzKwV.js";
-import { _ as _32 } from "./chunks/LpNotificationBell-Nges4kJk.js";
+import { _ as _30 } from "./chunks/LpLogViewer-B1aLUVdz.js";
+import { _ as _31 } from "./chunks/LpModal-CNAFRgCU.js";
+import { _ as _32 } from "./chunks/LpNotificationBell-HSGo1pcf.js";
 import { _ as _33 } from "./chunks/LpNumberField-C5ar-OwE.js";
 import { _ as _34 } from "./chunks/LpOtpInput-DqaT0Z75.js";
 import { _ as _35 } from "./chunks/LpPagination-CeGuNe_q.js";
@@ -44,18 +44,18 @@ import { _ as _38 } from "./chunks/LpPopover-8268UmlC.js";
 import { _ as _39 } from "./chunks/LpProgress-BhI0IbjC.js";
 import { _ as _40 } from "./chunks/LpRadio-CL-pI0_O.js";
 import { _ as _41 } from "./chunks/LpRadioGroup-B4yDTmi6.js";
-import { _ as _42 } from "./chunks/LpScrollArea-Du8tW8c5.js";
+import { _ as _42 } from "./chunks/LpScrollArea-D8xyKXcF.js";
 import { _ as _43 } from "./chunks/LpSegmented-BmpanyAo.js";
 import { _ as _44 } from "./chunks/LpSelect-D5mU4cZO.js";
 import { _ as _45 } from "./chunks/LpServiceNode-Dc-Ut5RS.js";
 import { default as default3 } from "./components/LpShortcutsDialog.vue.js";
-import { _ as _46 } from "./chunks/LpSidebar-Bd0148dd.js";
+import { _ as _46 } from "./chunks/LpSidebar-JvMaaYsy.js";
 import { _ as _47 } from "./chunks/LpSkeleton-eSFIo4kD.js";
 import { _ as _48 } from "./chunks/LpSlider-B1SF3pRV.js";
 import { _ as _49 } from "./chunks/LpStat-CdbEFOvn.js";
 import { _ as _50 } from "./chunks/LpStepper-5dFTrW21.js";
 import { _ as _51 } from "./chunks/LpSwitch-v6fnccSM.js";
-import { _ as _52 } from "./chunks/LpTable-BBKlNR9j.js";
+import { _ as _52 } from "./chunks/LpTable-DTj52qlg.js";
 import { _ as _53 } from "./chunks/LpTableOfContents-CjvxPMpU.js";
 import { _ as _54 } from "./chunks/LpTabs-Cefe_lys.js";
 import { _ as _55 } from "./chunks/LpTextarea-CRAkhemZ.js";
@@ -63,7 +63,7 @@ import { p as presets, a as parseTheme, s as serializeTheme } from "./chunks/LpT
 import { D, _ as _56, N, T, b, c, d, e, f, g, i, l, h, j, n, r, t, k, m, u, v } from "./chunks/LpThemeSwitcher-B_kj0T2b.js";
 import { _ as _57 } from "./chunks/LpTilt-DuyKbpkA.js";
 import { _ as _58 } from "./chunks/LpToaster-gDB1EaU3.js";
-import { _ as _59 } from "./chunks/LpTooltip-CIwoRCag.js";
+import { _ as _59 } from "./chunks/LpTooltip-D1hbjQWG.js";
 import { _ as _60 } from "./chunks/LpTopologyCanvas-DVwyQfKa.js";
 import { _ as _61 } from "./chunks/LpUptimeBar-CB366k0O.js";
 import { deserializeLayout, serializeLayout } from "./layout/tree.js";
@@ -72,6 +72,7 @@ import { blockTitle, defineBlocks } from "./layout/registry.js";
 import { useLayout } from "./layout/useLayout.js";
 import { appleModifierLabel, isAppleKeyboard, useHotkeys } from "./composables/useHotkeys.js";
 import { useInputFilter } from "./composables/useInputFilter.js";
+import { useRovingFocus } from "./composables/useRovingFocus.js";
 import { useSettled } from "./composables/useSettled.js";
 import { useTilt } from "./composables/useTilt.js";
 import { useZoomPan } from "./composables/useZoomPan.js";
@@ -236,6 +237,7 @@ export {
   useHotkeys,
   useInputFilter,
   useLayout,
+  useRovingFocus,
   useSettled,
   u as useTheme,
   useTilt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leavepulse/ui",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "description": "LeavePulse token-driven Vue component kit.",
   "repository": {

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/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>