rift-ds 1.13.0 → 1.15.0

package/behaviors/shortcut-keys.js

@@ -0,0 +1,129 @@
+const KEY_ALIASES = {
+  esc: "escape",
+  return: "enter",
+  up: "arrowup",
+  down: "arrowdown",
+  left: "arrowleft",
+  right: "arrowright",
+  del: "delete",
+  plus: "+",
+  " ": "space",
+  cmd: "meta",
+  command: "meta",
+  option: "alt",
+  control: "ctrl"
+};
+const MODIFIERS = /* @__PURE__ */ new Set(["mod", "ctrl", "meta", "alt", "shift"]);
+const parseStep = (text) => {
+  const step = { key: "", mod: false, ctrl: false, meta: false, alt: false, shift: false };
+  for (const raw of text.toLowerCase().split("+")) {
+    const part = KEY_ALIASES[raw] ?? raw;
+    if (MODIFIERS.has(part)) step[part] = true;
+    else step.key = part;
+  }
+  return step;
+};
+const parseShortcut = (shortcut) => shortcut.trim().split(/\s+/).filter(Boolean).map(parseStep);
+const detectPlatform = () => {
+  if (typeof navigator === "undefined") return "other";
+  const nav = navigator;
+  const name = nav.userAgentData?.platform || nav.platform || nav.userAgent || "";
+  return /mac|iphone|ipad|ipod/i.test(name) ? "apple" : "other";
+};
+const APPLE_LABELS = {
+  mod: "⌘",
+  meta: "⌘",
+  ctrl: "⌃",
+  alt: "⌥",
+  shift: "⇧",
+  enter: "↩",
+  escape: "Esc",
+  backspace: "⌫",
+  delete: "⌦",
+  tab: "⇥",
+  space: "Space"
+};
+const OTHER_LABELS = {
+  mod: "Ctrl",
+  meta: "Meta",
+  ctrl: "Ctrl",
+  alt: "Alt",
+  shift: "Shift",
+  enter: "Enter",
+  escape: "Esc",
+  backspace: "Backspace",
+  delete: "Del",
+  tab: "Tab",
+  space: "Space"
+};
+const SHARED_LABELS = {
+  arrowup: "↑",
+  arrowdown: "↓",
+  arrowleft: "←",
+  arrowright: "→",
+  home: "Home",
+  end: "End",
+  pageup: "PgUp",
+  pagedown: "PgDn"
+};
+const APPLE_ORDER = ["ctrl", "alt", "shift", "mod", "meta"];
+const OTHER_ORDER = ["mod", "ctrl", "meta", "alt", "shift"];
+function shortcutKeys(shortcut, platform, labels = {}) {
+  const table = { ...SHARED_LABELS, ...platform === "apple" ? APPLE_LABELS : OTHER_LABELS };
+  const legend = (name) => labels[name] ?? table[name] ?? (/^f\d+$/.test(name) ? name.toUpperCase() : name.length === 1 ? name.toUpperCase() : name);
+  return parseShortcut(shortcut).map((step) => {
+    const order = platform === "apple" ? APPLE_ORDER : OTHER_ORDER;
+    const mods = order.filter((mod) => step[mod]);
+    const unique = mods.filter((mod, i) => !mods.slice(0, i).some((m) => legend(m) === legend(mod)));
+    return [...unique.map(legend), legend(step.key)];
+  });
+}
+function formatShortcut(shortcut, platform, labels = {}) {
+  return shortcutKeys(shortcut, platform, labels).map((keys) => keys.join(platform === "apple" ? "" : "+")).join(" ");
+}
+const ARIA_KEYS = {
+  ctrl: "Control",
+  meta: "Meta",
+  alt: "Alt",
+  shift: "Shift",
+  escape: "Escape",
+  enter: "Enter",
+  space: "Space",
+  tab: "Tab",
+  backspace: "Backspace",
+  delete: "Delete",
+  arrowup: "ArrowUp",
+  arrowdown: "ArrowDown",
+  arrowleft: "ArrowLeft",
+  arrowright: "ArrowRight",
+  home: "Home",
+  end: "End",
+  pageup: "PageUp",
+  pagedown: "PageDown"
+};
+function shortcutAria(shortcut, platform) {
+  const steps = parseShortcut(shortcut);
+  if (steps.length !== 1) return void 0;
+  const [step] = steps;
+  const names = [
+    step.ctrl || step.mod && platform === "other" ? "Control" : null,
+    step.meta || step.mod && platform === "apple" ? "Meta" : null,
+    step.alt ? "Alt" : null,
+    step.shift ? "Shift" : null,
+    ARIA_KEYS[step.key] ?? (step.key.length === 1 ? step.key.toUpperCase() : step.key)
+  ].filter(Boolean);
+  return names.join("+");
+}
+function shortcutAriaAnyPlatform(shortcut) {
+  const forms = [shortcutAria(shortcut, "apple"), shortcutAria(shortcut, "other")].filter(Boolean);
+  return forms.length > 0 ? [...new Set(forms)].join(" ") : void 0;
+}
+export {
+  KEY_ALIASES,
+  detectPlatform,
+  formatShortcut,
+  parseShortcut,
+  shortcutAria,
+  shortcutAriaAnyPlatform,
+  shortcutKeys
+};

package/behaviors/shortcuts.d.ts

@@ -0,0 +1,75 @@
+import { Shortcut, ShortcutPlatform } from './shortcut-keys';
+export { detectPlatform, formatShortcut, parseShortcut, shortcutAria, shortcutKeys, type Shortcut, type ShortcutKeyLabels, type ShortcutPlatform, } from './shortcut-keys';
+/**
+ * Keyboard shortcuts: the one document keydown listener every app-level key
+ * binding goes through, the grammar a shortcut is written in, and the way it
+ * is drawn on each platform.
+ *
+ * A shortcut is a string: steps separated by spaces, each step modifiers and
+ * a key joined by `+`. `mod+k` is ⌘K on Apple platforms and Ctrl+K
+ * elsewhere; `shift+?`, `alt+arrowup`, `escape`; `g i` is G then I. Keys are
+ * a character or a name (enter, escape, space, tab, backspace, delete, the
+ * arrows, home, end, pageup, pagedown, f1 to f12, plus).
+ *
+ * Who hears a key, in order:
+ * - Nothing does while an IME is composing, or once a component has handled
+ *   the key itself (`event.preventDefault()`), so a list's own arrow keys or
+ *   an input's own Escape never also fire a shortcut. Escape is the layer
+ *   stack's while any overlay is open (useLayer), so an `escape` shortcut
+ *   is for closing something that is not a library overlay.
+ * - Nothing does while focus is in a text field, unless the shortcut opts in
+ *   with `allowInInput` (a palette's Cmd+K should work from a search box).
+ * - A `global` shortcut always does.
+ * - A `scope`d shortcut does while focus is inside its element, or while
+ *   nothing has focus and the element sits on the surface in front (the open
+ *   modal, else the page). Lightbox's arrows are scoped to its panel.
+ * - Any other shortcut belongs to the page: it does only while no modal is
+ *   open and focus is not inside an open overlay (a menu, a popover), the
+ *   same topmost-only rule the layer stack applies to Escape.
+ * When several match, the longest sequence wins, then the shortcut
+ * registered last. A matched key's default is prevented.
+ *
+ * Exactly one document listener exists while any shortcut is registered, and
+ * none otherwise. scripts/validate-overlay-listeners.mjs holds every other
+ * document key listener in the library and the site to this module.
+ */
+export interface ShortcutOptions {
+    /** What the shortcut does, in a few words, for a help list built from `useRegisteredShortcuts`. */
+    description?: string;
+    /** The heading a help list files the shortcut under, such as "Navigation". */
+    group?: string;
+    /** Whether the shortcut is live. Default true. */
+    enabled?: boolean;
+    /** Fires only while focus is inside this element (see the module's rules). */
+    scope?: React.RefObject<HTMLElement | null>;
+    /** Fires whatever is open or focused, outside text fields. Default false. */
+    global?: boolean;
+    /** Fires while focus is in a text field too. Default false. */
+    allowInInput?: boolean;
+}
+/**
+ * The platform shortcuts are drawn for. The server and the first client
+ * render both say `other`, then the client settles on its own, so drawing a
+ * shortcut never breaks hydration.
+ */
+export declare function usePlatform(): ShortcutPlatform;
+/**
+ * Binds a shortcut (or several, as an array) to `handler` while the component
+ * is mounted and `enabled` is not false. The handler and options are read at
+ * key time, so passing new ones each render never re-registers the shortcut.
+ */
+export declare function useShortcut(shortcut: Shortcut | Shortcut[], handler: (event: KeyboardEvent) => void, options?: ShortcutOptions): void;
+/** A live shortcut as a help list reads it. */
+export interface RegisteredShortcut {
+    /** The shortcuts that run it, in the grammar. */
+    shortcuts: Shortcut[];
+    /** What it does, from the binding's `description`. */
+    description: string;
+    /** Its heading, from the binding's `group`. */
+    group?: string;
+}
+/**
+ * Every live shortcut that has a description, in registration order, for a
+ * "keyboard shortcuts" help dialog. Updates as shortcuts mount and unmount.
+ */
+export declare function useRegisteredShortcuts(): RegisteredShortcut[];

package/behaviors/shortcuts.js

@@ -0,0 +1,160 @@
+"use client";
+import { useSyncExternalStore, useRef, useEffect } from "react";
+import { MOTION_SHORTCUT_SEQUENCE_MS } from "../tokens/motion.js";
+import { warnOnce } from "./devWarning.js";
+import { activeModalPanel } from "./useFocusScope.js";
+import { hasOpenLayer, openLayerContains } from "./useLayer.js";
+import { detectPlatform, parseShortcut, KEY_ALIASES } from "./shortcut-keys.js";
+import { formatShortcut, shortcutAria, shortcutKeys } from "./shortcut-keys.js";
+const noSubscription = () => () => {
+};
+function usePlatform() {
+  return useSyncExternalStore(noSubscription, detectPlatform, () => "other");
+}
+const eventKey = (event) => {
+  const key = event.key.toLowerCase();
+  return KEY_ALIASES[key] ?? key;
+};
+const codeKey = (event) => {
+  const match = /^(?:Key([A-Z])|Digit(\d))$/.exec(event.code ?? "");
+  return match ? (match[1] ?? match[2]).toLowerCase() : null;
+};
+const matchesStep = (step, event, platform) => {
+  const ctrl = step.ctrl || step.mod && platform === "other";
+  const meta = step.meta || step.mod && platform === "apple";
+  if (event.ctrlKey !== ctrl || event.metaKey !== meta || event.altKey !== step.alt) return false;
+  const symbol = step.key.length === 1 && !/[a-z0-9]/.test(step.key);
+  if (!symbol && event.shiftKey !== step.shift) return false;
+  return eventKey(event) === step.key || codeKey(event) === step.key;
+};
+const isTextField = (target) => {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  if (target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) return true;
+  if (target instanceof HTMLInputElement) {
+    return !["checkbox", "radio", "button", "submit", "reset", "range", "color", "file", "image"].includes(target.type);
+  }
+  return false;
+};
+const registrations = [];
+let version = 0;
+const listeners = /* @__PURE__ */ new Set();
+const notify = () => {
+  version += 1;
+  for (const listener of listeners) listener();
+};
+let recent = [];
+const eligible = (registration, target) => {
+  const options = registration.optionsRef.current;
+  if (options.enabled === false) return false;
+  if (isTextField(target) && !options.allowInInput) return false;
+  if (options.global) return true;
+  const modal = activeModalPanel();
+  const node = target instanceof Node ? target : null;
+  const unfocused = !node || node === document.body || node === document.documentElement;
+  const scope = options.scope?.current;
+  if (scope) {
+    if (!unfocused) return scope.contains(node);
+    return modal ? modal.contains(scope) : !openLayerContains(scope);
+  }
+  if (modal) return false;
+  return unfocused || !openLayerContains(node);
+};
+const handleKeyDown = (event) => {
+  if (event.isComposing || event.defaultPrevented) return;
+  if (event.key === "Escape" && hasOpenLayer()) return;
+  if (["Shift", "Control", "Alt", "Meta"].includes(event.key)) return;
+  const now = event.timeStamp || performance.now();
+  const last = recent[recent.length - 1];
+  if (last && now - last.at > MOTION_SHORTCUT_SEQUENCE_MS) recent = [];
+  recent = [...recent.slice(-3), { event, at: now }];
+  const platform = detectPlatform();
+  let best = null;
+  registrations.forEach((registration2, index) => {
+    if (!eligible(registration2, event.target)) return;
+    for (const steps of registration2.steps) {
+      if (steps.length > recent.length) continue;
+      const tail = recent.slice(recent.length - steps.length);
+      if (!steps.every((step, i) => matchesStep(step, tail[i].event, platform))) continue;
+      if (!best || steps.length > best.length || steps.length === best.length && index > best.index) {
+        best = { registration: registration2, length: steps.length, index };
+      }
+    }
+  });
+  if (!best) return;
+  const { registration } = best;
+  event.preventDefault();
+  recent = [];
+  registration.handlerRef.current(event);
+};
+const register = (registration) => {
+  for (const shortcut of registration.shortcuts) {
+    const scope = registration.optionsRef.current.scope;
+    const clash = registrations.find(
+      (other) => other.optionsRef.current.enabled !== false && other.optionsRef.current.scope === scope && other.shortcuts.includes(shortcut)
+    );
+    if (clash && registration.optionsRef.current.enabled !== false) {
+      warnOnce(`The shortcut "${shortcut}" is registered twice in one scope; the one registered last wins.`);
+    }
+  }
+  registrations.push(registration);
+  if (registrations.length === 1) document.addEventListener("keydown", handleKeyDown);
+  notify();
+  return () => {
+    const index = registrations.indexOf(registration);
+    if (index !== -1) registrations.splice(index, 1);
+    if (registrations.length === 0) {
+      document.removeEventListener("keydown", handleKeyDown);
+      recent = [];
+    }
+    notify();
+  };
+};
+function useShortcut(shortcut, handler, options = {}) {
+  const handlerRef = useRef(handler);
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    handlerRef.current = handler;
+    optionsRef.current = options;
+  });
+  const shortcuts = Array.isArray(shortcut) ? shortcut : [shortcut];
+  const key = shortcuts.join("\0");
+  const enabled = options.enabled !== false;
+  useEffect(() => {
+    if (!enabled) return;
+    const list = key.split("\0");
+    return register({ shortcuts: list, steps: list.map(parseShortcut), handlerRef, optionsRef });
+  }, [key, enabled]);
+}
+const subscribe = (listener) => {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+};
+let snapshot = { version: -1, list: [] };
+const readRegistered = () => {
+  if (snapshot.version !== version) {
+    snapshot = {
+      version,
+      list: registrations.filter((r) => r.optionsRef.current.enabled !== false && r.optionsRef.current.description).map((r) => ({
+        shortcuts: r.shortcuts,
+        description: r.optionsRef.current.description ?? "",
+        group: r.optionsRef.current.group
+      }))
+    };
+  }
+  return snapshot.list;
+};
+const EMPTY = [];
+function useRegisteredShortcuts() {
+  return useSyncExternalStore(subscribe, readRegistered, () => EMPTY);
+}
+export {
+  detectPlatform,
+  formatShortcut,
+  parseShortcut,
+  shortcutAria,
+  shortcutKeys,
+  usePlatform,
+  useRegisteredShortcuts,
+  useShortcut
+};

package/behaviors/useAnchoredPosition.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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';
+/** A side a caller can ask for: a screen side, or `start` / `end` of the reading direction. */
+export type AnchoredSideRequest = AnchoredSide | 'start' | 'end';
+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`. `start` and `end` resolve against
+     * the anchor's reading direction at placement time (`start` is the left
+     * in English, the right in Arabic); the placement reports the screen side
+     * it took.
+     */
+    side?: AnchoredSideRequest;
+    /**
+     * Where along that side the panel lines up with the anchor. Default
+     * `start`. On the top and bottom sides `start` and `end` follow the
+     * anchor's reading direction, so a menu lines up with its trigger's
+     * leading edge in either. The panel's `data-align` reports the screen
+     * alignment it took (`start` is the left edge), like `data-side`.
+     */
+    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: sideRequest, align: alignRequest, gapProperty, edgeProperty, flip, fitHeight, matchWidth, onPlace, target, }: AnchoredPositionOptions): void;

package/behaviors/useAnchoredPosition.js

@@ -0,0 +1,158 @@
+"use client";
+import { useRef, useLayoutEffect } from "react";
+import { isRtl } from "./direction.js";
+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: sideRequest = "bottom",
+  align: alignRequest = "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 rtl = isRtl(anchor);
+      const side = sideRequest === "start" ? rtl ? "right" : "left" : sideRequest === "end" ? rtl ? "left" : "right" : sideRequest;
+      const flipsAlign = rtl && (side === "top" || side === "bottom") && alignRequest !== "center";
+      const align = flipsAlign ? alignRequest === "start" ? "end" : "start" : alignRequest;
+      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, sideRequest, alignRequest, 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.
@@ -40,5 +47,11 @@ type FocusScopeOptions = {
     /** Make everything outside the scope inert while active. Default true. */
     inertOutside?: boolean;
 };
+/**
+ * The panel of the topmost modal scope that isolates the page, or null when
+ * none is open. Keyboard shortcuts read it: while a modal is open, only the
+ * shortcuts that live inside it (or are global) may fire.
+ */
+export declare const activeModalPanel: () => HTMLElement | null;
 export declare function useFocusScope(ref: React.RefObject<HTMLElement | null>, options: FocusScopeOptions): void;
 export {};