@lovett/ui 0.0.10 → 0.1.0

package/src/lib/focus.ts

@@ -0,0 +1,74 @@
+/**
+ * Tabbable-element query shared by the focus-managing surfaces (Modal's
+ * trap, Popover's focus-on-open). Extracted from modal.tsx.
+ *
+ * Deliberately attribute-only — no geometry check. `offsetWidth` /
+ * `getClientRects()` are always zero in jsdom, so a visibility filter would
+ * empty this list under test and silently disable the trap in exactly the
+ * environment that verifies it.
+ */
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'iframe',
+  'summary',
+  '[contenteditable="true"]',
+  '[tabindex]',
+].join(',')
+
+export function tabbablesWithin(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+    (el) =>
+      el.tabIndex >= 0 &&
+      !el.hasAttribute('inert') &&
+      el.getAttribute('aria-hidden') !== 'true' &&
+      !el.closest('[hidden]') &&
+      // `inert` is INHERITED by the subtree in a browser, so a control inside
+      // an inert ancestor cannot take focus — a trap that hands it focus
+      // anyway simply stops moving. The detail surface collapses a pane by
+      // making it inert rather than unmounting it (its scroll and its drafts
+      // have to survive), which is the case that made this ancestor check
+      // load-bearing rather than tidy.
+      !el.closest('[inert]'),
+  )
+}
+
+/**
+ * Keep Tab inside `container`.
+ *
+ * `Popover` is non-modal by design: it moves focus in and hands it back, but
+ * Tab walks straight out of it into the page behind. For a surface that is a
+ * self-contained panel of controls — the Display popover, the filter picker —
+ * that reads as the panel losing focus mid-use, so those surfaces wrap the
+ * cycle themselves. Call from a `keydown` handler on the container.
+ *
+ * Does nothing unless the key is Tab, and nothing when the container holds
+ * fewer than two tabbables (a single control has nowhere to cycle to and
+ * preventing default there would trap the user on it).
+ */
+export function handleTabTrap(
+  event: { key: string; shiftKey: boolean; preventDefault: () => void },
+  container: HTMLElement | null,
+): void {
+  if (event.key !== 'Tab' || !container) return
+  const tabbables = tabbablesWithin(container)
+  if (tabbables.length < 2) return
+  const first = tabbables[0]
+  const last = tabbables[tabbables.length - 1]
+  if (!first || !last) return
+  const active = document.activeElement
+  if (event.shiftKey && (active === first || !container.contains(active))) {
+    event.preventDefault()
+    last.focus()
+    return
+  }
+  if (!event.shiftKey && active === last) {
+    event.preventDefault()
+    first.focus()
+  }
+}

package/src/lib/layer-stack.ts

@@ -0,0 +1,215 @@
+/**
+ * Dismiss-layer stack — the ONE "topmost layer wins" registry shared by
+ * Modal, DropdownMenu and Popover (and, next, ContextMenu / Select /
+ * Combobox / Tooltip / CommandPalette).
+ *
+ * Extracted from modal.tsx's module-level `openPanels` array so every
+ * dismissable surface participates in the same order. Before this, a
+ * DropdownMenu opened from inside a Modal answered Escape at the same time
+ * the Modal did — two document listeners, one keypress, both closed. Now a
+ * single document `keydown` listener dispatches Escape to the top of the
+ * stack ONLY, then stops propagation so window-level handlers (the chat
+ * conversation drawer's Escape, lens hotkey maps) do not treat a consumed
+ * Escape as theirs — which is what DropdownMenu's own listener already did.
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager:
+ * every picker, sheet and palette needs one dismiss order). First consumer
+ * is the workspace app: Modal (51 files), DropdownMenu (137 call sites) and
+ * Popover all register here.
+ *
+ * Two kinds. A `modal` layer also owns a focus trap, and that trap must not
+ * switch off because a `popover` opened above it — so Modal asks
+ * `isTopOfKind()` for Tab handling while Escape always goes to `isTop()`.
+ * Order is push order, which under React is effect order: a surface that
+ * mounts or opens later sits above one that opened earlier.
+ *
+ * Usage (a dismissable surface):
+ *
+ *   const layer = useLayer({
+ *     enabled: open,
+ *     kind: 'popover',
+ *     elementRef: contentRef,
+ *     onEscape: () => setOpen(false),
+ *   })
+ *   useOutsideClick([triggerRef, contentRef], () => setOpen(false), {
+ *     enabled: open,
+ *     layer, // clicks inside a layer stacked ABOVE this one are not "outside"
+ *   })
+ *
+ * `useEscapeKey(handler, { enabled })` is the one-liner for anything that
+ * only needs Escape.
+ */
+
+import { useEffect, useMemo, useRef, type RefObject } from 'react'
+
+export type LayerKind = 'modal' | 'popover'
+
+export interface LayerHandle {
+  /** True while no layer of ANY kind sits above this one. */
+  isTop(): boolean
+  /** True while no layer of the SAME kind sits above this one. */
+  isTopOfKind(): boolean
+  /**
+   * True when `node` is inside the element of a layer stacked above this
+   * one — a nested Select's listbox, a Combobox inside a Popover. Outside-
+   * click handlers treat those as inside.
+   */
+  containsInLayerAbove(node: Node): boolean
+}
+
+interface LayerRecord {
+  /**
+   * MUTABLE, and the one field that is.
+   *
+   * A surface whose kind CHANGES while it is open must not lose its place in
+   * the stack over it. The item detail is the case that found this: its three
+   * modes are one element tree, and `panel` is non-modal while `full` and
+   * `modal` are, so switching mode flips this from 'modal' to 'popover'. When
+   * `kind` was an effect dependency, that flip popped and re-pushed the
+   * layer — landing the detail ABOVE a dropdown menu that was already open,
+   * so the next Escape closed the whole detail instead of the menu inside it.
+   * (Switching mode is done FROM that menu, so it was the common path, not an
+   * edge case.)
+   *
+   * Updating in place keeps push order meaning what it says: the order things
+   * OPENED, not the order they last changed shape.
+   */
+  kind: LayerKind
+  readonly element: () => HTMLElement | null
+  readonly onEscape: (event: KeyboardEvent) => void
+}
+
+const stack: LayerRecord[] = []
+let listening = false
+
+function onDocumentKeyDown(event: KeyboardEvent): void {
+  if (event.key !== 'Escape') return
+  const top = stack[stack.length - 1]
+  if (!top) return
+  // Consumed here. Window-level listeners (hotkey maps, drawers) must not
+  // see an Escape that closed a layer — same contract DropdownMenu's own
+  // listener had before the stack existed.
+  event.stopPropagation()
+  top.onEscape(event)
+}
+
+function pushLayer(record: LayerRecord): () => void {
+  stack.push(record)
+  if (!listening) {
+    document.addEventListener('keydown', onDocumentKeyDown)
+    listening = true
+  }
+  return () => {
+    const at = stack.lastIndexOf(record)
+    if (at !== -1) stack.splice(at, 1)
+    if (stack.length === 0 && listening) {
+      document.removeEventListener('keydown', onDocumentKeyDown)
+      listening = false
+    }
+  }
+}
+
+export interface UseLayerOptions {
+  /** Register while true; pop when it turns false or the owner unmounts. */
+  enabled: boolean
+  kind: LayerKind
+  /**
+   * The surface's root element. Read lazily, so a ref that is filled in
+   * after the layer registers (portal content) still resolves.
+   */
+  elementRef?: RefObject<HTMLElement | null>
+  /** Called when this layer is topmost and Escape is pressed. */
+  onEscape: (event: KeyboardEvent) => void
+}
+
+/**
+ * Register a dismiss layer for as long as `enabled` holds. `onEscape` is
+ * read through a ref, so an inline arrow does not re-register the layer
+ * (and does not reorder it) on every render.
+ */
+export function useLayer(options: UseLayerOptions): LayerHandle {
+  const { enabled, kind, elementRef, onEscape } = options
+
+  const onEscapeRef = useRef(onEscape)
+  useEffect(() => {
+    onEscapeRef.current = onEscape
+  })
+
+  // Read through a ref for the same reason `onEscape` is: so that changing it
+  // updates the layer rather than reordering the stack. See `LayerRecord.kind`.
+  const kindRef = useRef(kind)
+  kindRef.current = kind
+
+  const recordRef = useRef<LayerRecord | null>(null)
+
+  useEffect(() => {
+    if (!enabled) return
+    const record: LayerRecord = {
+      kind: kindRef.current,
+      element: () => elementRef?.current ?? null,
+      onEscape: (event) => onEscapeRef.current(event),
+    }
+    recordRef.current = record
+    const pop = pushLayer(record)
+    return () => {
+      pop()
+      if (recordRef.current === record) recordRef.current = null
+    }
+  }, [enabled, elementRef])
+
+  // A kind change updates the record IN PLACE, keeping its position.
+  useEffect(() => {
+    const record = recordRef.current
+    if (record !== null) record.kind = kind
+  }, [kind])
+
+  return useMemo<LayerHandle>(
+    () => ({
+      isTop: () => {
+        const record = recordRef.current
+        return record !== null && stack[stack.length - 1] === record
+      },
+      isTopOfKind: () => {
+        const record = recordRef.current
+        if (!record) return false
+        for (let i = stack.length - 1; i >= 0; i--) {
+          const layer = stack[i]
+          if (layer === record) return true
+          if (layer?.kind === record.kind) return false
+        }
+        return false
+      },
+      containsInLayerAbove: (node) => {
+        const record = recordRef.current
+        if (!record) return false
+        const at = stack.indexOf(record)
+        if (at === -1) return false
+        for (let i = at + 1; i < stack.length; i++) {
+          if (stack[i]?.element()?.contains(node)) return true
+        }
+        return false
+      },
+    }),
+    [],
+  )
+}
+
+export interface UseEscapeKeyOptions {
+  /** Default true. */
+  enabled?: boolean
+  /** Default `popover`. */
+  kind?: LayerKind
+}
+
+/**
+ * Escape-only participant in the layer stack. Fires `onEscape` only while
+ * this is the topmost layer; a layer that opens later takes over until it
+ * closes.
+ */
+export function useEscapeKey(
+  onEscape: (event: KeyboardEvent) => void,
+  options: UseEscapeKeyOptions = {},
+): LayerHandle {
+  const { enabled = true, kind = 'popover' } = options
+  return useLayer({ enabled, kind, onEscape })
+}

package/src/lib/refs.ts

@@ -0,0 +1,31 @@
+/**
+ * Ref plumbing for primitives that must hand one DOM node to several
+ * owners — the caller's forwarded ref, the component's own ref, and a
+ * positioning hook's callback ref.
+ *
+ * `assignRef` writes a node into any React ref shape. `composeRefs` returns
+ * ONE callback ref that fans out to all of them; memoize the result
+ * (`useMemo` on the inputs) so React does not detach/re-attach on every
+ * render.
+ */
+
+import type { Ref, RefCallback } from 'react'
+
+export function assignRef<T>(ref: Ref<T> | undefined, node: T | null): void {
+  if (!ref) return
+  if (typeof ref === 'function') {
+    // React 19 callback refs may return a cleanup; we call with `null` on
+    // detach instead, which every consumer of this package already handles.
+    ref(node)
+    return
+  }
+  ref.current = node
+}
+
+export function composeRefs<T>(
+  ...refs: ReadonlyArray<Ref<T> | undefined>
+): RefCallback<T> {
+  return (node) => {
+    for (const ref of refs) assignRef(ref, node)
+  }
+}