@charcuterie/ui 4.25.0 → 4.26.1

package/src/CommandPalette/useCommandPaletteHotkeys.ts

@@ -0,0 +1,158 @@
+import { useLatestRef } from "@charcuterie/logic"
+import { useEffect } from "react"
+
+export type CommandPaletteHotkeysOptions = {
+  /** Off while the palette is open, or on a page that should not take the keys. Default `true`. */
+  isEnabled?: boolean
+  /**
+   * A printable key typed outside an editable field opens the palette
+   * with that character as the query. Default `true`.
+   */
+  isOpenedByTyping?: boolean
+  /** Receives the text the palette should open with: `""`, or the character typed. */
+  onOpen: (initialQuery: string) => void
+}
+
+/**
+ * Elements that keep their keys: anything you type into, and the
+ * widgets with their own type-to-find (a focused `Listbox` or `Menu`
+ * jumps to the option you type, and stealing that key breaks it).
+ */
+const TYPEAHEAD_OWNER_SELECTOR = [
+  "input",
+  "textarea",
+  "select",
+  "[contenteditable]:not([contenteditable='false'])",
+  "[role='combobox']",
+  "[role='grid']",
+  "[role='listbox']",
+  "[role='menu']",
+  "[role='menubar']",
+  "[role='searchbox']",
+  "[role='textbox']",
+  "[role='tree']",
+  "[role='treegrid']",
+].join(",")
+
+/** Input types that take no text, so a letter typed on one is free to open the palette. */
+const NON_TEXT_INPUT_TYPES = new Set([
+  "button",
+  "checkbox",
+  "color",
+  "file",
+  "image",
+  "radio",
+  "range",
+  "reset",
+  "submit",
+])
+
+export const getIsTypingTarget = (
+  target: EventTarget | null,
+): boolean => {
+  if (!(target instanceof Element)) {
+    return false
+  }
+
+  if (
+    target instanceof HTMLInputElement &&
+    NON_TEXT_INPUT_TYPES.has(target.type)
+  ) {
+    return false
+  }
+
+  return (
+    (target instanceof HTMLElement &&
+      target.isContentEditable) ||
+    target.closest(TYPEAHEAD_OWNER_SELECTOR) !== null
+  )
+}
+
+/**
+ * The global keys that open a command palette, as an opt-in hook.
+ *
+ * - **`Ctrl K`, `Ctrl Space`** (or `⌘` on a Mac) open it from
+ *   anywhere, a text field included — the chord types nothing.
+ * - **`/`** opens it when focus is not somewhere that types, and
+ *   the slash itself is not typed.
+ * - **Any printable key** does the same and becomes the query, so
+ *   the page is a search box without a click (`isOpenedByTyping`).
+ *
+ * It is a hook, not something `CommandPalette` does on mount,
+ * because a document-wide key listener is a page-level decision: an
+ * app with two palettes, or a page where letters already mean
+ * something (a board with its own shortcuts), must be able to say
+ * no. See
+ * `docs/decisions/2026-10-16-command-palette-hotkeys-are-an-opt-in-hook.md`.
+ *
+ * A key another handler already claimed (`defaultPrevented`), a key
+ * pressed during IME composition, and a key with `Alt` held are all
+ * left alone.
+ */
+export const useCommandPaletteHotkeys = ({
+  isEnabled = true,
+  isOpenedByTyping = true,
+  onOpen,
+}: CommandPaletteHotkeysOptions): void => {
+  const onOpenRef = useLatestRef(onOpen)
+
+  useEffect(() => {
+    if (!isEnabled) {
+      return
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (
+        event.defaultPrevented ||
+        event.isComposing ||
+        event.altKey
+      ) {
+        return
+      }
+
+      const isChord = event.ctrlKey || event.metaKey
+
+      if (isChord) {
+        if (
+          !event.shiftKey &&
+          (event.key.toLowerCase() === "k" ||
+            event.key === " ")
+        ) {
+          event.preventDefault()
+          onOpenRef.current("")
+        }
+
+        return
+      }
+
+      if (getIsTypingTarget(event.target)) {
+        return
+      }
+
+      if (event.key === "/") {
+        event.preventDefault()
+        onOpenRef.current("")
+
+        return
+      }
+
+      // `key` is the character for a printable key and a name
+      // ("Enter", "ArrowDown") for everything else; a space is
+      // printable but presses the focused button.
+      if (
+        isOpenedByTyping &&
+        [...event.key].length === 1 &&
+        /\S/u.test(event.key)
+      ) {
+        event.preventDefault()
+        onOpenRef.current(event.key)
+      }
+    }
+
+    document.addEventListener("keydown", handleKeyDown)
+
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown)
+    }
+  }, [isEnabled, isOpenedByTyping, onOpenRef])
+}

package/src/TableViewport/TableViewport.mdx

@@ -10,6 +10,8 @@ its rows and uses the page's vertical scroll. Expand table opens a full-window `
 The dialog body is the only scroll surface; headers and the first column stay visible.
 Escape and Close return focus to the trigger. Only one table is mounted, so links and IDs
 are never duplicated. The inline height and horizontal position survive expansion.
+Expansion fades and zooms in; dismissal reverses the animation before returning to the
+document. Reduced-motion and zero-duration profiles skip the animation.
 
 Apps provide the semantic table, its column count, and its accessible label. Sanitizing
 Markdown HTML and delegating document links remain the app's responsibilities. Use

package/src/TableViewport/TableViewport.test.tsx

@@ -1,6 +1,6 @@
 import { composeStories } from "@storybook/react"
 import { expect, userEvent, waitFor } from "storybook/test"
-import { test } from "vitest"
+import { test, vi } from "vitest"
 import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
 import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
@@ -26,6 +26,8 @@ test("long inline comparisons grow with the page and expand without duplicate ta
     role: "dialog",
     name: "Printer comparison",
   })
+  for (const animation of dialog.getAnimations())
+    animation.finish()
   await expect(
     document.querySelectorAll("table").length,
   ).toBe(1)
@@ -56,3 +58,89 @@ test("long inline comparisons grow with the page and expand without duplicate ta
     canvas.getByRole("table"),
   ).toBeInTheDocument()
 })
+
+test("keeps the table and focus trap until the reverse animation completes", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+  const trigger = canvas.getByRole("button", {
+    name: "Expand table",
+  })
+  const pane = canvas.getByRole("region", {
+    name: "Printer comparison",
+  })
+  pane.scrollLeft = 120
+  const scrollLeft = pane.scrollLeft
+  const height = pane.getBoundingClientRect().height
+  await userEvent.click(trigger)
+  const dialog = body.getByRole("dialog", {
+    name: "Printer comparison",
+  })
+  const [animation] = dialog.getAnimations()
+  await expect(animation).toBeDefined()
+  animation.pause()
+  animation.currentTime =
+    Number(animation.effect?.getTiming().duration) / 2
+  await expect(
+    Number(getComputedStyle(dialog).opacity),
+  ).toBeGreaterThan(0)
+  await expect(
+    Number(getComputedStyle(dialog).opacity),
+  ).toBeLessThan(1)
+  await expect(pane.getBoundingClientRect().height).toBe(
+    height,
+  )
+  await userEvent.keyboard("{Escape}")
+  await animation.ready
+  animation.pause()
+  await expect(animation.playbackRate).toBe(-1)
+  await expect(body.getByRole("dialog")).toBe(dialog)
+  await expect(
+    document.querySelectorAll("table"),
+  ).toHaveLength(1)
+  // A second dismiss during exit must not reverse back into an opening.
+  await userEvent.click(
+    body.getByRole("button", { name: "Close" }),
+  )
+  await expect(animation.playbackRate).toBe(-1)
+  animation.finish()
+  await waitFor(() =>
+    expect(body.queryByRole("dialog")).toBeNull(),
+  )
+  await waitFor(() =>
+    expect(document.activeElement).toBe(trigger),
+  )
+  await waitFor(() =>
+    expect(pane.scrollLeft).toBe(scrollLeft),
+  )
+  await expect(
+    canvas.getByRole("table"),
+  ).toBeInTheDocument()
+})
+
+test("reduced motion opens and closes immediately without a table animation", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+  const matchMedia = window.matchMedia.bind(window)
+  const media = vi
+    .spyOn(window, "matchMedia")
+    .mockImplementation((query) =>
+      query === "(prefers-reduced-motion: reduce)"
+        ? { ...matchMedia(query), matches: true }
+        : matchMedia(query),
+    )
+  try {
+    await userEvent.click(
+      canvas.getByRole("button", { name: "Expand table" }),
+    )
+    const dialog = body.getByRole("dialog", {
+      name: "Printer comparison",
+    })
+    await expect(dialog.getAnimations()).toHaveLength(0)
+    await userEvent.click(
+      body.getByRole("button", { name: "Close" }),
+    )
+    await waitFor(() =>
+      expect(body.queryByRole("dialog")).toBeNull(),
+    )
+  } finally {
+    media.mockRestore()
+  }
+})

package/src/TableViewport/TableViewport.tsx

@@ -1,5 +1,10 @@
 import type { CSSProperties, ReactNode } from "react"
-import { useRef, useState } from "react"
+import {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react"
 import { Button } from "../Button/Button.tsx"
 import { Dialog } from "../Dialog/Dialog.tsx"
 import { toClassName } from "../toClassName.ts"
@@ -23,12 +28,87 @@ export const TableViewport = ({
   const [inlineHeight, setInlineHeight] = useState(0)
   const scrollRef = useRef<HTMLElement>(null)
   const scrollPosition = useRef(0)
+  const expansion = useRef<Animation | null>(null)
+  const isClosing = useRef(false)
+  useLayoutEffect(() => {
+    // Restore after React has actually returned the table to this pane.
+    // A frame scheduled from the animation's promise can run before that commit
+    // on a busy renderer, when the empty pane clamps scrollLeft back to zero.
+    if (!isExpanded && scrollRef.current)
+      scrollRef.current.scrollLeft = scrollPosition.current
+  }, [isExpanded])
+  const animateExpansion = useCallback(
+    (node: HTMLDivElement | null) => {
+      const dialog = node?.closest<HTMLElement>(
+        '[role="dialog"]',
+      )
+      if (
+        !dialog ||
+        matchMedia("(prefers-reduced-motion: reduce)")
+          .matches
+      )
+        return
+
+      const style = getComputedStyle(dialog)
+      const duration = Number.parseFloat(
+        style.getPropertyValue("--duration-slow"),
+      )
+      // Zero-duration profiles (including ePaper) remove motion entirely.
+      if (!(duration > 0)) return
+
+      const animation = dialog.animate(
+        [
+          {
+            opacity: 0,
+            transform: "translateY(0.75rem) scale(0.98)",
+          },
+          { opacity: 1, transform: "none" },
+        ],
+        {
+          duration,
+          easing:
+            style
+              .getPropertyValue("--easing-standard")
+              .trim() || "ease-out",
+          fill: "both",
+        },
+      )
+      expansion.current = animation
+      // Unmounting a document can cancel an unfinished enter or exit.
+      void animation.finished.catch(() => {})
+      return () => {
+        animation.cancel()
+        expansion.current = null
+      }
+    },
+    [],
+  )
+  const close = () => {
+    if (isClosing.current) return
+    isClosing.current = true
+    const finish = () => {
+      setIsExpanded(false)
+      isClosing.current = false
+    }
+    const animation = expansion.current
+    if (
+      !animation ||
+      matchMedia("(prefers-reduced-motion: reduce)").matches
+    ) {
+      finish()
+      return
+    }
+    // Reversing also handles Escape during the opening animation without a jump.
+    animation.reverse()
+    void animation.finished.then(finish, () => {})
+  }
   const contentStyle = {
     "--table-min-inline-size": `${Math.max(1, columnCount) * 14}rem`,
   } as CSSProperties
   const content = (
     <div
       className="charcuterie-table-content"
+      ref={isExpanded ? animateExpansion : undefined}
       style={contentStyle}
     >
       {children}
@@ -70,14 +150,7 @@ export const TableViewport = ({
         heading={label}
         isVisible={isExpanded}
         size="full"
-        onClose={() => {
-          setIsExpanded(false)
-          requestAnimationFrame(() => {
-            if (scrollRef.current)
-              scrollRef.current.scrollLeft =
-                scrollPosition.current
-          })
-        }}
+        onClose={close}
       >
         {isExpanded ? content : null}
       </Dialog>

package/src/index.ts

@@ -130,6 +130,20 @@ export type {
 export { ColorSchemeToggle } from "./ColorSchemeToggle/ColorSchemeToggle.tsx"
 export type { ComboboxProps } from "./Combobox/Combobox.tsx"
 export { Combobox } from "./Combobox/Combobox.tsx"
+export type { CommandPaletteProps } from "./CommandPalette/CommandPalette.tsx"
+export { CommandPalette } from "./CommandPalette/CommandPalette.tsx"
+export type {
+  CommandPaletteGroup,
+  CommandPaletteItem,
+  CommandPalettePrefix,
+} from "./CommandPalette/commandPaletteSections.ts"
+export type {
+  UseCommandPaletteOptions,
+  UseCommandPaletteResult,
+} from "./CommandPalette/useCommandPalette.ts"
+export { useCommandPalette } from "./CommandPalette/useCommandPalette.ts"
+export type { CommandPaletteHotkeysOptions } from "./CommandPalette/useCommandPaletteHotkeys.ts"
+export { useCommandPaletteHotkeys } from "./CommandPalette/useCommandPaletteHotkeys.ts"
 export type { ComparisonChartProps } from "./ComparisonChart/ComparisonChart.tsx"
 export { ComparisonChart } from "./ComparisonChart/ComparisonChart.tsx"
 export type {

package/src/sourceRules.test.ts

@@ -626,7 +626,8 @@ test("the barrel is the only place components are re-exported", async () => {
   // GroupedList owns rows under group headings; castkit, tally-marks
   // and whereabouts each drew it by hand. `GroupedListRow.tsx` is its
   // member and stays out of this count by the `<Name>/<Name>.tsx` rule.
-  expect(componentNames.length).toBe(78)
+  // CommandPalette composes Modal and SearchInput into the launcher.
+  expect(componentNames.length).toBe(79)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)