rift-ds 1.13.0 → 1.14.0

package/README.md

@@ -13,7 +13,7 @@ An open source React design system built for AI products and coding agents: comp
 
 ## Why Rift DS
 
-- **<!-- component-count -->155<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. Every one forwards a ref and your own attributes to its element, state you can own works controlled or uncontrolled (a modal opens when your app says so, by design), and every word a component writes has a prop you can localise. The build checks the first two on every component, and the words wherever they sit in markup. React and React DOM are the only required peer dependencies.
+- **<!-- component-count -->159<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. Every one forwards a ref and your own attributes to its element, state you can own works controlled or uncontrolled (a modal opens when your app says so, by design), and every word a component writes has a prop you can localise. The build checks the first two on every component, and the words wherever they sit in markup. React and React DOM are the only required peer dependencies.
 - **AI patterns, the whole chat and templates, ready to use.** Composer, streaming chat thread, tool calls, reasoning and thread panel are in the box, the complete AI chat ships assembled as one widget that one command scaffolds, and the docs site has complete template screens built from them.
 - **Fully themeable.** The shipped themes are complete looks to start from, each in light and dark. One `data-brand` attribute applies a theme, and a few CSS overrides make your own.
 - **Ready for coding agents.** One command installs the agent skills, and a public MCP endpoint serves every component's props, so your agent builds with the library as it actually is. No key, no account.
@@ -25,18 +25,25 @@ Everything deep lives on the docs site: **[rift-ds.com](https://rift-ds.com/)**,
 
 ## Install
 
+In a Next.js app router project (a fresh `create-next-app` included), three commands give you a themed first page:
+
 ```bash
 npm install rift-ds
+npx rift-ds init app
+npx rift-ds init block dashboard
 ```
 
-Import the token stylesheet once, then use components:
+`init app` adds a root wrapper that routes every link through Next's `Link`, the script that applies the visitor's colour mode before first paint, and the base theme's font, then prints your root layout: make `app/layout.tsx` that, and drop the `globals.css` import `create-next-app` added. `init block dashboard` adds a dashboard inside an app shell (the sidebar, the top bar and the page header), laid out for a desktop and a phone; the other blocks are on the [blocks page](https://rift-ds.com/docs/blocks). Neither overwrites a file, and the files are yours to change.
+
+In any other React app, import the token stylesheet and the base sheet once, then use components:
 
 ```tsx
 import 'rift-ds/tokens/tokens.css';
+import 'rift-ds/tokens/base.css'; // the reset and page every component is tuned against
 import { Button, Card, Badge } from 'rift-ds';
 ```
 
-React 19+ is a peer dependency. The package is ESM-only and resolved via `exports` subpaths: use a bundler that handles CSS and font imports from `node_modules` (Vite, Next.js, webpack) and set TypeScript's `moduleResolution` to `"bundler"` or `"nodenext"`. The Recharts-backed charts live behind `rift-ds/charts`, so the optional `recharts` peer dependency is only needed if you use them. The chat widget's subpaths bring their own optional peers (`react-markdown` and `remark-gfm` for the panel, `@anthropic-ai/sdk` for the server handlers, `@upstash/ratelimit` and `@upstash/redis` for the guardrails), needed only if you use them. Prefer owning the source? Pull single components through the shadcn CLI (`npx shadcn@latest add https://rift-ds.com/r/button.json`, with details in the [get-started guide](https://rift-ds.com/docs/get-started)), or clone this repo and build on it directly; all of it is MIT.
+React 19+ is a peer dependency. The package's own runtime dependencies, TanStack Table and TanStack Virtual (the headless engine under `DataTable` and the windowing behind its long tables), install with it. The package is ESM-only and resolved via `exports` subpaths: use a bundler that handles CSS and font imports from `node_modules` (Vite, Next.js, webpack) and set TypeScript's `moduleResolution` to `"bundler"` or `"nodenext"`. The Recharts-backed charts live behind `rift-ds/charts`, so the optional `recharts` peer dependency is only needed if you use them. The chat widget's subpaths bring their own optional peers (`react-markdown` and `remark-gfm` for the panel, `@anthropic-ai/sdk` for the server handlers, `@upstash/ratelimit` and `@upstash/redis` for the guardrails), needed only if you use them. Prefer owning the source? Pull single components through the shadcn CLI (`npx shadcn@latest add https://rift-ds.com/r/button.json`, with details in the [get-started guide](https://rift-ds.com/docs/get-started)), or clone this repo and build on it directly; all of it is MIT.
 
 ## The chat widget
 
@@ -100,13 +107,13 @@ import 'rift-ds/tokens/presets/presets.css';
 
 ## Components
 
-<!-- component-count -->155<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->159<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bento tile · Bento tile art · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Question card · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bento tile · Bento tile art · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Command palette trigger · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Question card · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Table toolbar · Tabs · Tag input · Textarea · Theme picker · Theme toggle · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>
@@ -118,6 +125,7 @@ Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · A
 - **Next.js 16**: the documentation site
 - **Storybook 10**: component explorer
 - **Vitest + Playwright + axe**: every Storybook story runs as a render test in headless Chromium, with an accessibility audit on each
+- **TanStack Table + TanStack Virtual**: the headless engine and the windowing under `DataTable`, the package's runtime dependencies
 - **CSS custom properties**: all theming via semantic tokens, no CSS-in-JS
 
 The [overview](https://rift-ds.com/overview) shows the generate-and-validate pipeline behind the docs.

package/behaviors/ScrollRegion.d.ts

@@ -0,0 +1,8 @@
+import { CSSProperties, ReactNode } from 'react';
+export declare function ScrollRegion({ className, style, children, onNode, }: {
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+    /** Hands the scrolling element to its owner (a virtualised table scrolls its rows inside it). */
+    onNode?: (node: HTMLDivElement | null) => void;
+}): import("react").JSX.Element;

package/behaviors/ScrollRegion.js

@@ -0,0 +1,51 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useRef, useCallback, useId, useState, useEffect } from "react";
+function ScrollRegion({
+  className,
+  style,
+  children,
+  onNode
+}) {
+  const ref = useRef(null);
+  const setNode = useCallback(
+    (node) => {
+      ref.current = node;
+      onNode?.(node);
+    },
+    [onNode]
+  );
+  const captionId = useId();
+  const [overflows, setOverflows] = useState(false);
+  const [labelledBy, setLabelledBy] = useState();
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    const caption = node.querySelector("caption");
+    if (caption) {
+      if (!caption.id) caption.id = captionId;
+      setLabelledBy(caption.id);
+    }
+    const measure = () => setOverflows(node.scrollWidth > node.clientWidth + 1);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    if (node.firstElementChild) observer.observe(node.firstElementChild);
+    return () => observer.disconnect();
+  }, [captionId]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: setNode,
+      className,
+      style,
+      role: overflows ? "region" : void 0,
+      "aria-labelledby": overflows ? labelledBy : void 0,
+      tabIndex: overflows ? 0 : void 0,
+      children
+    }
+  );
+}
+export {
+  ScrollRegion
+};

package/behaviors/devWarning.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Development-only console warnings, the way React writes its own: the
+ * check reads `process.env.NODE_ENV`, which every bundler replaces at build
+ * time, so a production bundle drops the warning and a page with no
+ * bundler (and no `process`) stays silent rather than throwing. Each
+ * message prints once per page load, however many instances trip it.
+ */
+/** Warns once, in development only. */
+export declare function warnOnce(message: string): void;

package/behaviors/devWarning.js

@@ -0,0 +1,16 @@
+const isDevelopment = (() => {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+})();
+const warned = /* @__PURE__ */ new Set();
+function warnOnce(message) {
+  if (!isDevelopment || warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[rift-ds] ${message}`);
+}
+export {
+  warnOnce
+};

package/behaviors/useAnchoredPosition.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Anchored positioning: the one way every popup in the library places itself
+ * against the control that opened it (menus, listboxes, pickers, popovers,
+ * hover cards, tooltips).
+ *
+ * The panel stays where it is in the DOM, so it keeps the trigger's stacking
+ * context and any theme scoped above it, but is `position: fixed`, placed
+ * from the anchor's rectangle. A fixed panel is not clipped by an ancestor's
+ * `overflow`, which is what lets a menu inside a table's scroll wrapper, a
+ * rail or a card show whole. Portals would escape the same way but would
+ * leave the theme scope; floating-ui would solve it at the cost of a
+ * dependency. This is the approach Tooltip proved first.
+ *
+ * On every placement it:
+ * - puts the panel on the preferred side, flipping to the opposite side when
+ *   the preferred one has too little room and the opposite has more;
+ * - shifts it along the edge to stay inside its box, a margin clear of the
+ *   edge (`--gap-200` unless the component says otherwise);
+ * - optionally caps its height to the room on the side it took (a list then
+ *   scrolls inside rather than running off the screen);
+ * - optionally sets its minimum width to the anchor's, so a listbox is never
+ *   narrower than the control that opened it, and always publishes the
+ *   anchor's width as `--ds-anchor-width` for a panel that should match it
+ *   exactly;
+ * - marks the side it landed on as `data-side` (and `data-align`), so the
+ *   entrance can grow from the anchor whichever way the panel flipped;
+ * - hides it (an inline `visibility: hidden`, flagged `data-anchor-hidden`)
+ *   while the anchor is scrolled wholly out of view, so a panel never hangs
+ *   at the screen's edge over nothing.
+ *
+ * The placement outlives the open state on purpose: a panel that eases out
+ * when it closes keeps its place for the exit instead of snapping back into
+ * flow mid-fade.
+ *
+ * It re-places on scroll (any scroll container, captured), on resize, and
+ * when the panel or the anchor changes size, once per animation frame, and
+ * writes straight to the DOM: placement never costs a React render, the same
+ * reasoning the gesture rule gives (design.md, the playground's resize
+ * record).
+ *
+ * The room a panel has is the viewport's. An ancestor with a transform,
+ * filter, backdrop filter, perspective or containment (a Dialog panel's
+ * entrance scale, the chat panel's blur) becomes the fixed panel's
+ * containing block, which moves the
+ * coordinates it is placed in; only when that ancestor also clips its
+ * overflow does the room narrow to its box.
+ */
+export type AnchoredSide = 'top' | 'bottom' | 'left' | 'right';
+export type AnchoredAlign = 'start' | 'center' | 'end';
+export type AnchoredPlacement = {
+    /** The side the panel took after flipping. */
+    side: AnchoredSide;
+    /** The panel's position in the box, in px from the box's top left. */
+    x: number;
+    y: number;
+    /** The panel's size as placed. */
+    width: number;
+    height: number;
+    /** The anchor's rectangle, in the same coordinates. */
+    anchor: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+};
+export type AnchoredPositionOptions = {
+    /** Whether the panel is showing. Placement runs only while true. */
+    open: boolean;
+    /** The control the panel is anchored to. */
+    anchorRef: React.RefObject<HTMLElement | null>;
+    /** The panel being placed. */
+    panelRef: React.RefObject<HTMLElement | null>;
+    /** The preferred side. Default `bottom`. */
+    side?: AnchoredSide;
+    /** Where along that side the panel lines up with the anchor. Default `start`. */
+    align?: AnchoredAlign;
+    /**
+     * The custom property that holds the gap between anchor and panel, read
+     * where it resolves so it is never restated as a number. Default
+     * `--gap-200`.
+     */
+    gapProperty?: string;
+    /**
+     * The custom property that holds the margin a panel keeps from the box's
+     * edge when it shifts to stay inside. Default `--gap-200`, so a panel never
+     * sits tighter to the screen's edge than that, whatever its trigger gap.
+     */
+    edgeProperty?: string;
+    /** Whether the panel may flip to the opposite side. Default true. */
+    flip?: boolean;
+    /** Cap the panel's height to the room on its side, for a list that scrolls inside. Default false. */
+    fitHeight?: boolean;
+    /** Set the panel's minimum width to the anchor's. Default false. */
+    matchWidth?: boolean;
+    /** Called after every placement, for a detail the panel draws itself (an arrow). */
+    onPlace?: (placement: AnchoredPlacement) => void;
+    /**
+     * Which of several anchors is open, for a component that shows one panel
+     * at a time against different controls (FilterBar's chips): a change
+     * re-reads the refs and places afresh. Leave undefined for one anchor.
+     */
+    target?: string | number | null;
+};
+/**
+ * The nearest ancestor a fixed-position descendant is placed from instead of
+ * the viewport. Null means the viewport.
+ */
+export declare function fixedContainingBlock(element: HTMLElement): HTMLElement | null;
+/** Places `panelRef` against `anchorRef` while `open`. See the module comment. */
+export declare function useAnchoredPosition({ open, anchorRef, panelRef, side, align, gapProperty, edgeProperty, flip, fitHeight, matchWidth, onPlace, target, }: AnchoredPositionOptions): void;

package/behaviors/useAnchoredPosition.js

@@ -0,0 +1,153 @@
+"use client";
+import { useRef, useLayoutEffect } from "react";
+function fixedContainingBlock(element) {
+  for (let node = element.parentElement; node; node = node.parentElement) {
+    const style = getComputedStyle(node);
+    const read = (property) => style.getPropertyValue(property).trim();
+    if (read("transform") !== "none" || read("filter") !== "none" || read("backdrop-filter") !== "none" || read("perspective") !== "none" || /\b(layout|paint|strict|content)\b/.test(read("contain")) || /\b(transform|filter|perspective)\b/.test(read("will-change"))) {
+      return node;
+    }
+  }
+  return null;
+}
+const clamp = (value, min, max) => max < min ? min : Math.min(Math.max(value, min), max);
+const OPPOSITE = {
+  top: "bottom",
+  bottom: "top",
+  left: "right",
+  right: "left"
+};
+function useAnchoredPosition({
+  open,
+  anchorRef,
+  panelRef,
+  side = "bottom",
+  align = "start",
+  gapProperty = "--gap-200",
+  edgeProperty = "--gap-200",
+  flip = true,
+  fitHeight = false,
+  matchWidth = false,
+  onPlace,
+  target
+}) {
+  const onPlaceRef = useRef(onPlace);
+  useLayoutEffect(() => {
+    onPlaceRef.current = onPlace;
+  });
+  useLayoutEffect(() => {
+    if (!open) return;
+    const anchor = anchorRef.current;
+    const panel = panelRef.current;
+    if (!anchor || !panel) return;
+    panel.style.position = "fixed";
+    panel.style.inset = "auto";
+    panel.style.margin = "0";
+    const place = () => {
+      const block = fixedContainingBlock(panel);
+      const blockBox = block ? block.getBoundingClientRect() : null;
+      const origin = blockBox ? { left: blockBox.left + block.clientLeft, top: blockBox.top + block.clientTop } : { left: 0, top: 0 };
+      const bounds = {
+        left: 0,
+        top: 0,
+        right: document.documentElement.clientWidth,
+        bottom: document.documentElement.clientHeight
+      };
+      if (block && blockBox) {
+        const style = getComputedStyle(block);
+        if (style.overflowX !== "visible") {
+          bounds.left = Math.max(bounds.left, origin.left);
+          bounds.right = Math.min(bounds.right, origin.left + block.clientWidth);
+        }
+        if (style.overflowY !== "visible") {
+          bounds.top = Math.max(bounds.top, origin.top);
+          bounds.bottom = Math.min(bounds.bottom, origin.top + block.clientHeight);
+        }
+      }
+      const a = anchor.getBoundingClientRect();
+      const panelStyle = getComputedStyle(panel);
+      const gap = parseFloat(panelStyle.getPropertyValue(gapProperty)) || 0;
+      const edge = parseFloat(panelStyle.getPropertyValue(edgeProperty)) || 0;
+      panel.style.setProperty("--ds-anchor-width", `${a.width}px`);
+      if (matchWidth) panel.style.minWidth = `${a.width}px`;
+      if (fitHeight) panel.style.maxHeight = "";
+      const width = panel.offsetWidth;
+      let height = panel.offsetHeight;
+      const room = {
+        top: a.top - bounds.top - gap - edge,
+        bottom: bounds.bottom - a.bottom - gap - edge,
+        left: a.left - bounds.left - gap - edge,
+        right: bounds.right - a.right - gap - edge
+      };
+      const vertical = side === "top" || side === "bottom";
+      const need = vertical ? height : width;
+      let chosen = side;
+      if (flip && room[side] < need && room[OPPOSITE[side]] > room[side]) {
+        chosen = OPPOSITE[side];
+      }
+      if (fitHeight && vertical && height > room[chosen]) {
+        height = Math.max(room[chosen], 0);
+        panel.style.maxHeight = `${height}px`;
+      }
+      let x;
+      let y;
+      if (chosen === "top" || chosen === "bottom") {
+        y = chosen === "bottom" ? a.bottom + gap : a.top - gap - height;
+        x = align === "center" ? a.left + a.width / 2 - width / 2 : align === "end" ? a.right - width : a.left;
+      } else {
+        x = chosen === "right" ? a.right + gap : a.left - gap - width;
+        y = align === "center" ? a.top + a.height / 2 - height / 2 : align === "end" ? a.bottom - height : a.top;
+      }
+      x = clamp(x, bounds.left + edge, bounds.right - edge - width);
+      y = clamp(y, bounds.top + edge, bounds.bottom - edge - height);
+      panel.style.left = `${x - origin.left}px`;
+      panel.style.top = `${y - origin.top}px`;
+      panel.dataset.side = chosen;
+      panel.dataset.align = align;
+      const offscreen = a.bottom < bounds.top || a.top > bounds.bottom || a.right < bounds.left || a.left > bounds.right;
+      if (offscreen) {
+        panel.dataset.anchorHidden = "";
+        panel.style.visibility = "hidden";
+      } else if ("anchorHidden" in panel.dataset) {
+        delete panel.dataset.anchorHidden;
+        panel.style.removeProperty("visibility");
+      }
+      onPlaceRef.current?.({
+        side: chosen,
+        x: x - origin.left,
+        y: y - origin.top,
+        width,
+        height,
+        anchor: { left: a.left - origin.left, top: a.top - origin.top, width: a.width, height: a.height }
+      });
+    };
+    let frame = 0;
+    const schedule = () => {
+      if (frame) return;
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        place();
+      });
+    };
+    place();
+    window.addEventListener("scroll", schedule, true);
+    window.addEventListener("resize", schedule);
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+    observer?.observe(panel);
+    observer?.observe(anchor);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("scroll", schedule, true);
+      window.removeEventListener("resize", schedule);
+      observer?.disconnect();
+      if ("anchorHidden" in panel.dataset) {
+        delete panel.dataset.anchorHidden;
+        panel.style.removeProperty("visibility");
+      }
+    };
+  }, [open, target, anchorRef, panelRef, side, align, gapProperty, edgeProperty, flip, fitHeight, matchWidth]);
+}
+export {
+  fixedContainingBlock,
+  useAnchoredPosition
+};

package/behaviors/useFocusScope.d.ts

@@ -30,8 +30,15 @@ type FocusScopeOptions = {
     active: boolean;
     /** Wrap Tab / Shift+Tab within the scope. Default true. */
     trap?: boolean;
-    /** Restore focus to the previously focused element on deactivate. Default true. */
-    restoreFocus?: boolean;
+    /**
+     * Restore focus on deactivate. Default true: the previously focused
+     * element, or its nearest visible stand-in. A function names the target
+     * instead, read at the moment of closing, for a host that knows better
+     * than the opener: a table whose row deleted itself from this dialog
+     * sends focus to the next row rather than the table's first control. A
+     * function that returns null falls back to the default.
+     */
+    restoreFocus?: boolean | (() => HTMLElement | null);
     /**
      * Where initial focus lands. Defaults to the first visible real control,
      * then the first focusable of any kind, then the container itself.

package/behaviors/useFocusScope.js

@@ -81,7 +81,11 @@ function useFocusScope(ref, options) {
         inertScopes.splice(index, 1);
         applyInert();
       }
-      if (optionsRef.current.restoreFocus !== false && previousFocus) {
+      const restore = optionsRef.current.restoreFocus;
+      const chosen = typeof restore === "function" ? restore() : null;
+      if (chosen) {
+        chosen.focus();
+      } else if (restore !== false && previousFocus) {
         restoreTarget(previousFocus)?.focus();
       }
     };