@spunto/design-system 0.15.1 → 0.17.0

package/src/components/command-menu.tsx

@@ -0,0 +1,630 @@
+"use client"
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ComponentProps,
+  type ReactElement,
+  type ReactNode,
+  type RefObject,
+} from "react"
+import { Autocomplete } from "@base-ui/react/autocomplete"
+import { Popover } from "@base-ui/react/popover"
+import { SearchIcon } from "lucide-react"
+
+import { cn } from "../utils"
+import { highlightMatch, type CommandFilter, type CommandFilterItem } from "./command-shared"
+import { Kbd } from "./kbd"
+import { Skeleton } from "./skeleton"
+import { Spinner } from "./spinner"
+import { useOverlayContainer } from "./spunto-provider"
+
+// ---------------------------------------------------------------------------
+// Why this exists next to CommandPalette
+//
+// `CommandPalette` is a *dialog*: it traps focus, which is exactly right for ⌘K
+// and exactly wrong for a "/" menu inside an editor. There, the caret must stay
+// in the block the user is typing in — the moment focus moves, the insertion
+// point is lost and the menu has nothing left to insert into.
+//
+// So this is a separate component rather than a `modal={false}` flag on the
+// palette: the contract isn't "same thing, less dimming", it's the opposite one.
+// Nothing here ever moves focus (Base UI `Popover` with `initialFocus={false}`,
+// `finalFocus={false}`, no backdrop, non-modal), the menu is anchored to whatever
+// the caller points at (an element, a ref, or a virtual element — a caret rect),
+// and the keys it needs (↑ ↓ ↵ esc) are taken on `document` in the **capture**
+// phase, so they never reach the field underneath. Everything else — every
+// printable character, Home/End, the caret keys we don't claim — flows to the
+// field as if no menu were open.
+//
+// Two ways to drive the query, and they're the two real shapes of this UI:
+//   - the caller owns the text (the "/" menu: `query={afterTheSlash}`), or
+//   - the menu owns it, by rendering a `CommandMenuInput` inside the popup
+//     (a filter dropdown hanging off a button; add `autoFocus` if that field
+//     should take focus — it's opt-in, and still not a trap).
+//
+// Presentational, like the palette: `loading` is a prop, results are children,
+// a server-side search is `onQueryChange` + `filter={null}`.
+// ---------------------------------------------------------------------------
+
+/** Same shape as the palette's — a filter written for one works on the other. */
+export type CommandMenuFilterItem = CommandFilterItem
+export type CommandMenuFilter = CommandFilter
+
+/** How every part finds the rendered items: they're the only thing carrying this slot. */
+const ITEM_SELECTOR = "[data-slot='command-menu-item']"
+
+interface MenuContextValue {
+  query: string
+  loading: boolean
+  activeValue: string | null
+  setActiveValue: (value: string) => void
+  setQuery: (value: string) => void
+  matches: (item: CommandFilterItem) => boolean
+  close: () => void
+  listId: string
+}
+
+const MenuContext = createContext<MenuContextValue | null>(null)
+
+function useMenu(part: string): MenuContextValue {
+  const ctx = useContext(MenuContext)
+  if (!ctx) throw new Error(`<${part}> must be rendered inside <CommandMenu>.`)
+  return ctx
+}
+
+// --- root -------------------------------------------------------------------
+
+export interface CommandMenuProps {
+  /** Controlled open state — the caller decides (typing "/", clicking a button…). */
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /**
+   * What the menu hangs off: an element, a ref, a getter, or a **virtual element**
+   * (`{ getBoundingClientRect() }`) — which is how a caret becomes an anchor.
+   */
+  anchor?: Popover.Positioner.Props["anchor"]
+  /**
+   * The field that keeps the focus. Purely for accessibility: while the menu is
+   * open, it gets `aria-expanded`, `aria-controls` and a live `aria-activedescendant`
+   * pointing at the highlighted item, so a screen reader announces the highlight
+   * without focus ever moving. Keyboard interception doesn't need it.
+   */
+  inputRef?: RefObject<HTMLElement | null>
+  /** Controlled query. Leave it out to let a `CommandMenuInput` own it. */
+  query?: string
+  defaultQuery?: string
+  /** Fires on every keystroke of a `CommandMenuInput` — the hook for a server-side search. */
+  onQueryChange?: (query: string) => void
+  /**
+   * Local filtering. Default: accent- and case-insensitive "contains" over the
+   * item's label, keywords and value. `null` filters nothing (results already
+   * come filtered), or pass your own predicate.
+   */
+  filter?: CommandMenuFilter | null
+  /** Draws the input spinner, shows `CommandMenuLoading`, silences `CommandMenuEmpty`. */
+  loading?: boolean
+  /** Where the popup sits relative to the anchor. */
+  side?: Popover.Positioner.Props["side"]
+  align?: Popover.Positioner.Props["align"]
+  sideOffset?: number
+  alignOffset?: number
+  /** Accessible name of the listbox. */
+  label?: string
+  className?: string
+  children?: ReactNode
+}
+
+/**
+ * Inline command menu — the palette's parts, anchored, and without a focus trap.
+ *
+ * ```tsx
+ * <CommandMenu open={open} onOpenChange={setOpen} anchor={caretRect} inputRef={editorRef} query={query}>
+ *   <CommandMenuList>
+ *     <CommandMenuEmpty>Aucun bloc</CommandMenuEmpty>
+ *     <CommandMenuGroup heading="Blocs">
+ *       <CommandMenuItem icon={<Heading1 />} onSelect={() => insert("h1")}>Titre 1</CommandMenuItem>
+ *     </CommandMenuGroup>
+ *   </CommandMenuList>
+ * </CommandMenu>
+ * ```
+ */
+function CommandMenu({
+  open,
+  onOpenChange,
+  anchor,
+  inputRef,
+  query: queryProp,
+  defaultQuery = "",
+  onQueryChange,
+  filter,
+  loading = false,
+  side = "bottom",
+  align = "start",
+  sideOffset = 6,
+  alignOffset = 0,
+  label = "Menu de commandes",
+  className,
+  children,
+}: CommandMenuProps) {
+  const container = useOverlayContainer()
+  const listId = useId()
+  const popupRef = useRef<HTMLDivElement | null>(null)
+  const [uncontrolled, setUncontrolled] = useState(defaultQuery)
+  const [activeValue, setActiveValue] = useState<string | null>(null)
+  const query = queryProp ?? uncontrolled
+  const { contains } = Autocomplete.useFilter({ sensitivity: "base" })
+
+  const setQuery = useCallback(
+    (next: string) => {
+      if (queryProp === undefined) setUncontrolled(next)
+      onQueryChange?.(next)
+    },
+    [queryProp, onQueryChange]
+  )
+
+  const close = useCallback(() => onOpenChange(false), [onOpenChange])
+
+  // Every rendered item, in DOM order. The DOM is the source of truth here for
+  // the same reason it is in the palette: items filter themselves out by
+  // rendering nothing, so any list we kept in state would describe the previous
+  // keystroke.
+  const items = useCallback(
+    () => Array.from(popupRef.current?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []),
+    []
+  )
+
+  // Keep a highlight on something that still exists. Runs after *every* commit
+  // (no dep array) because what changed is the rendered list, not a value we
+  // hold — the functional update makes it a no-op once it has settled.
+  useEffect(() => {
+    if (!open) return
+    const values = items().map((el) => el.dataset.value ?? "")
+    setActiveValue((prev) => (prev && values.includes(prev) ? prev : (values[0] ?? null)))
+  })
+
+  useEffect(() => {
+    if (!open) setActiveValue(null)
+  }, [open])
+
+  // Follow the highlight when it moves out of view. `nearest` so an already
+  // visible item doesn't make the list jump.
+  useEffect(() => {
+    if (!open || !activeValue) return
+    popupRef.current
+      ?.querySelector<HTMLElement>(`${ITEM_SELECTOR}[data-active='true']`)
+      ?.scrollIntoView({ block: "nearest" })
+  }, [open, activeValue])
+
+  // The keys the menu claims, taken on `document` in the capture phase so they
+  // are consumed before the focused field (or React's delegated handlers) ever
+  // sees them. Deliberately short: ↵ is only claimed when there *is* something
+  // to activate, so "/" + a query with no result still inserts a line break.
+  useEffect(() => {
+    if (!open) return
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.defaultPrevented) return
+      const claim = () => {
+        event.preventDefault()
+        event.stopPropagation()
+      }
+      if (event.key === "Escape") {
+        claim()
+        close()
+        return
+      }
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        const all = items()
+        if (all.length === 0) return
+        claim()
+        const values = all.map((el) => el.dataset.value ?? "")
+        const at = activeValue ? values.indexOf(activeValue) : -1
+        const step = event.key === "ArrowDown" ? 1 : -1
+        const next = (at + step + values.length) % values.length
+        setActiveValue(values[next])
+        return
+      }
+      if (event.key === "Enter") {
+        const active = popupRef.current?.querySelector<HTMLElement>(`${ITEM_SELECTOR}[data-active='true']`)
+        if (!active) return
+        claim()
+        // A click, not a stored callback: it also does the right thing when the
+        // item rendered itself as a link.
+        active.click()
+      }
+    }
+    document.addEventListener("keydown", onKeyDown, true)
+    return () => document.removeEventListener("keydown", onKeyDown, true)
+  }, [open, activeValue, items, close])
+
+  // Combobox semantics for the field that kept the focus. Written to the DOM
+  // rather than handed back as props: the caller's field is often a
+  // contenteditable deep in an editor, not something we can spread props onto.
+  useEffect(() => {
+    const el = inputRef?.current
+    if (!el) return
+    if (!open) {
+      el.removeAttribute("aria-expanded")
+      el.removeAttribute("aria-controls")
+      el.removeAttribute("aria-activedescendant")
+      return
+    }
+    el.setAttribute("aria-expanded", "true")
+    el.setAttribute("aria-controls", listId)
+    const active = popupRef.current?.querySelector<HTMLElement>(`${ITEM_SELECTOR}[data-active='true']`)
+    if (active?.id) el.setAttribute("aria-activedescendant", active.id)
+    else el.removeAttribute("aria-activedescendant")
+    return () => {
+      el.removeAttribute("aria-expanded")
+      el.removeAttribute("aria-controls")
+      el.removeAttribute("aria-activedescendant")
+    }
+  }, [open, activeValue, inputRef, listId])
+
+  const ctx: MenuContextValue = {
+    query,
+    loading,
+    activeValue,
+    setActiveValue,
+    setQuery,
+    close,
+    listId,
+    matches: (item) => {
+      if (!query.trim()) return true
+      if (filter === null) return true
+      if (filter) return filter(item, query)
+      return [item.label, item.value ?? "", ...item.keywords].some((text) => text && contains(text, query))
+    },
+  }
+
+  return (
+    <Popover.Root open={open} onOpenChange={(next) => onOpenChange(next)}>
+      <Popover.Portal container={container ?? undefined}>
+        <Popover.Positioner
+          data-slot="command-menu-positioner"
+          className="z-50 outline-none"
+          anchor={anchor}
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+          alignOffset={alignOffset}
+        >
+          <Popover.Popup
+            ref={popupRef}
+            data-slot="command-menu"
+            // The whole point: opening and closing leave the focus alone.
+            initialFocus={false}
+            finalFocus={false}
+            // A pointer press inside the menu would blur the field the caret
+            // lives in before the click ever lands. Cancel the default, keep the
+            // caret, let `click` do the work.
+            onMouseDown={(event) => event.preventDefault()}
+            className={cn(
+              "flex max-h-[min(20rem,var(--available-height))] w-[min(20rem,var(--available-width))] flex-col overflow-hidden rounded-xl border border-border bg-popover text-popover-foreground shadow-lg shadow-black/[0.08] outline-none",
+              "origin-[var(--transform-origin)] transition-[transform,opacity] duration-150 data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              className
+            )}
+            aria-label={label}
+          >
+            <MenuContext.Provider value={ctx}>{children}</MenuContext.Provider>
+          </Popover.Popup>
+        </Popover.Positioner>
+      </Popover.Portal>
+    </Popover.Root>
+  )
+}
+
+// --- input ------------------------------------------------------------------
+
+export interface CommandMenuInputProps
+  extends Omit<ComponentProps<"input">, "value" | "defaultValue" | "onChange" | "size"> {
+  /** Left-hand icon. Defaults to a magnifier; pass `null` for none. */
+  icon?: ReactNode
+}
+
+/**
+ * Optional search row *inside* the popup, for a menu that owns its own query
+ * (a filter dropdown on a button). Leave it out when the caller's field is the
+ * query — the "/" menu case. It doesn't take focus unless you pass `autoFocus`.
+ */
+function CommandMenuInput({ className, placeholder = "Rechercher…", icon, ...props }: CommandMenuInputProps) {
+  const { loading, query, setQuery } = useMenu("CommandMenuInput")
+  return (
+    <div
+      data-slot="command-menu-input"
+      className={cn("flex h-9 shrink-0 items-center gap-2 border-b border-border px-2.5", className)}
+    >
+      {icon !== null && (
+        <span className="shrink-0 text-muted-foreground [&_svg]:size-4" aria-hidden>
+          {icon ?? <SearchIcon className="size-4" />}
+        </span>
+      )}
+      <input
+        // `any-pointer-coarse:text-base` — below 16px, iOS zooms the page on focus.
+        className="h-full min-w-0 flex-1 bg-transparent text-sm text-foreground outline-none placeholder:text-muted-foreground any-pointer-coarse:text-base"
+        placeholder={placeholder}
+        aria-label={props["aria-label"] ?? placeholder}
+        value={query}
+        onChange={(event) => setQuery(event.target.value)}
+        {...props}
+      />
+      {loading && <Spinner size="xs" className="shrink-0 text-muted-foreground" />}
+    </div>
+  )
+}
+
+// --- list -------------------------------------------------------------------
+
+/**
+ * The scrollable listbox. Wrap the groups, items, `CommandMenuEmpty` and
+ * `CommandMenuLoading` in it — the empty state keys off `:has()` on this
+ * element, so it only works from inside.
+ */
+function CommandMenuList({ className, children, ...props }: ComponentProps<"div">) {
+  const { loading, listId } = useMenu("CommandMenuList")
+  const ref = useRef<HTMLDivElement>(null)
+  const [count, setCount] = useState(0)
+
+  // Counting the rendered items is the one thing CSS can't do for us, and the
+  // announcement below needs it. Reading the DOM after the commit is cheaper
+  // (and more accurate) than making every item report in.
+  useEffect(() => {
+    const rendered = ref.current?.querySelectorAll(ITEM_SELECTOR).length ?? 0
+    setCount((prev) => (prev === rendered ? prev : rendered))
+  })
+
+  return (
+    <div
+      ref={ref}
+      data-slot="command-menu-list"
+      className={cn("group/cmd-menu min-h-0 flex-1 overflow-y-auto overscroll-contain p-1.5", className)}
+      {...props}
+    >
+      <div id={listId} role="listbox" aria-label="Résultats">
+        {children}
+      </div>
+      {/* Must stay mounted to announce reliably — only its text changes. */}
+      <div role="status" aria-live="polite" className="sr-only">
+        {loading ? "Recherche en cours…" : count === 0 ? "Aucun résultat" : `${count} résultat${count > 1 ? "s" : ""}`}
+      </div>
+    </div>
+  )
+}
+
+// --- group / separator ------------------------------------------------------
+
+export interface CommandMenuGroupProps extends ComponentProps<"div"> {
+  heading?: ReactNode
+}
+
+/**
+ * A titled block of items. It hides itself when none of its items survived the
+ * filter — through `:has()` rather than a JS count, so the heading never flashes
+ * for a frame above an empty group.
+ */
+function CommandMenuGroup({ heading, className, children, ...props }: CommandMenuGroupProps) {
+  const headingId = useId()
+  return (
+    <div
+      data-slot="command-menu-group"
+      role="group"
+      aria-labelledby={heading != null ? headingId : undefined}
+      className={cn("hidden has-[[data-slot=command-menu-item]]:block", className)}
+      {...props}
+    >
+      {heading != null && (
+        <div
+          id={headingId}
+          className="px-2 pt-1.5 pb-1 text-[0.6875rem] font-medium tracking-wide text-muted-foreground uppercase select-none"
+        >
+          {heading}
+        </div>
+      )}
+      {children}
+    </div>
+  )
+}
+
+/** A thin rule between groups. Static — it doesn't disappear with its neighbours. */
+function CommandMenuSeparator({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="command-menu-separator"
+      role="separator"
+      className={cn("-mx-1.5 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+// --- item -------------------------------------------------------------------
+
+/** Props handed to the app's link component. Spread them all. */
+export type CommandMenuLinkProps = ComponentProps<"a"> & { href: string }
+export type CommandMenuLinkRender = (props: CommandMenuLinkProps) => ReactElement
+
+export interface CommandMenuItemProps extends Omit<ComponentProps<"div">, "onSelect"> {
+  /** Leading icon (a `lucide-react` glyph, an avatar, a status dot…). */
+  icon?: ReactNode
+  /** Secondary text, right-aligned. */
+  meta?: ReactNode
+  /** Second line under the label. */
+  description?: ReactNode
+  /** Shortcut cap on the right, e.g. `"mod+n"`. */
+  shortcut?: string
+  /** Extra search terms, never displayed. */
+  keywords?: string[]
+  /**
+   * Text the filter matches on. Defaults to the children when they're a plain
+   * string — pass it explicitly as soon as they aren't.
+   */
+  label?: string
+  /** Stable identity for the item. Also matched by the filter. */
+  value?: string
+  disabled?: boolean
+  /** Turns the item into a link. Enter and click both navigate. */
+  href?: string
+  /**
+   * Escape hatch for app-specific rendering. `link` gets every prop the item put
+   * on the node plus `href`, and must return an anchor-ish node (`next/link`, a
+   * router link…). The package never imports `next/link`.
+   */
+  render?: { link?: CommandMenuLinkRender }
+  /** Fires on click *and* on Enter while highlighted. */
+  onSelect?: () => void
+  /**
+   * Whether selecting closes the menu.
+   * @default true
+   */
+  closeOnSelect?: boolean
+}
+
+/**
+ * One entry. Renders nothing when it doesn't match the query — that's the whole
+ * filtering mechanism, and what keeps a long list cheap once the user types.
+ */
+function CommandMenuItem({
+  icon,
+  meta,
+  description,
+  shortcut,
+  keywords = [],
+  label: labelProp,
+  value,
+  disabled,
+  href,
+  render,
+  onSelect,
+  closeOnSelect = true,
+  className,
+  children,
+  ...props
+}: CommandMenuItemProps) {
+  const { matches, close, query, activeValue, setActiveValue } = useMenu("CommandMenuItem")
+  const autoId = useId()
+  const label = labelProp ?? (typeof children === "string" ? children : undefined)
+
+  if (!matches({ label: label ?? "", keywords, value })) return null
+
+  const itemValue = value ?? label ?? autoId
+  const active = activeValue === itemValue
+
+  const content = (
+    <>
+      {icon != null && (
+        <span
+          className={cn(
+            "flex size-5 shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4",
+            active && "text-foreground"
+          )}
+          aria-hidden
+        >
+          {icon}
+        </span>
+      )}
+      <span className="min-w-0 flex-1">
+        <span className="block truncate">{label != null ? highlightMatch(label, query) : children}</span>
+        {description != null && <span className="block truncate text-xs text-muted-foreground">{description}</span>}
+      </span>
+      {meta != null && <span className="shrink-0 truncate text-xs text-muted-foreground tabular-nums">{meta}</span>}
+      {shortcut && <Kbd keys={shortcut} className="shrink-0" />}
+    </>
+  )
+
+  const shared = {
+    id: autoId,
+    role: "option" as const,
+    "aria-selected": active,
+    "aria-disabled": disabled || undefined,
+    "data-slot": "command-menu-item",
+    "data-value": itemValue,
+    "data-active": active || undefined,
+    "data-disabled": disabled || undefined,
+    onMouseEnter: () => {
+      if (!disabled) setActiveValue(itemValue)
+    },
+    onClick: () => {
+      if (disabled) return
+      onSelect?.()
+      if (closeOnSelect) close()
+    },
+    className: cn(
+      "flex scroll-my-1.5 cursor-default items-center gap-2 rounded-lg px-2 py-1.5 text-sm text-foreground no-underline outline-none select-none",
+      active && "bg-accent text-accent-foreground",
+      disabled && "pointer-events-none opacity-50",
+      className
+    ),
+  }
+
+  if (href) {
+    const linkRender = render?.link ?? ((linkProps: CommandMenuLinkProps) => <a {...linkProps} />)
+    return linkRender({ ...shared, ...(props as ComponentProps<"a">), href, children: content })
+  }
+
+  return (
+    <div {...shared} {...props}>
+      {content}
+    </div>
+  )
+}
+
+// --- empty / loading --------------------------------------------------------
+
+/**
+ * Shown only when no item survived the filter, and never while `loading` (a
+ * pending search isn't an empty result). Must live inside `CommandMenuList`.
+ */
+function CommandMenuEmpty({ className, children = "Aucun résultat", ...props }: ComponentProps<"div">) {
+  const { loading } = useMenu("CommandMenuEmpty")
+  if (loading) return null
+  return (
+    <div
+      data-slot="command-menu-empty"
+      role="presentation"
+      className={cn(
+        "px-3 py-6 text-center text-sm text-muted-foreground group-has-[[data-slot=command-menu-item]]/cmd-menu:hidden",
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
+
+export interface CommandMenuLoadingProps extends ComponentProps<"div"> {
+  /** Number of skeleton rows. @default 3 */
+  rows?: number
+}
+
+/** Skeleton rows while an async search is in flight. Renders nothing unless the root is `loading`. */
+function CommandMenuLoading({ rows = 3, className, ...props }: CommandMenuLoadingProps) {
+  const { loading } = useMenu("CommandMenuLoading")
+  if (!loading) return null
+  return (
+    <div data-slot="command-menu-loading" role="presentation" className={cn("space-y-1", className)} {...props}>
+      {Array.from({ length: rows }, (_, i) => (
+        <div key={i} className="flex items-center gap-2 px-2 py-1.5">
+          <Skeleton className="size-4 shrink-0 rounded" />
+          <Skeleton className="h-3" style={{ width: `${45 - i * 8}%` }} />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export {
+  CommandMenu,
+  CommandMenuInput,
+  CommandMenuList,
+  CommandMenuGroup,
+  CommandMenuSeparator,
+  CommandMenuItem,
+  CommandMenuEmpty,
+  CommandMenuLoading,
+}