@cl-light-ds/ui 0.4.0 → 0.6.0

package/src/components/toggle-group/ToggleGroup.astro

@@ -98,6 +98,22 @@
  *   </ToggleGroupItem>
  * </ToggleGroup>
  *
+ * ### Segmented Variant
+ *
+ * `variant="segmented"` is the outline look with the pressed item filled
+ * `muted` in `foreground` text, also on hover: a view switcher, where one item
+ * is always the current view. The fill follows the group's own pressed state
+ * (`aria-pressed`), so drive it with `defaultValue` or `toggle-group:set`.
+ *
+ * <ToggleGroup variant="segmented" defaultValue="card" aria-label="Collection view">
+ *   <ToggleGroupItem value="card" aria-label="Card view">
+ *     <LayoutGridIcon />
+ *   </ToggleGroupItem>
+ *   <ToggleGroupItem value="list" aria-label="List view">
+ *     <ListIcon />
+ *   </ToggleGroupItem>
+ * </ToggleGroup>
+ *
  * ### Sizes
  *
  * <div class="flex flex-col gap-4">
@@ -181,7 +197,8 @@ import type { HTMLAttributes } from "astro/types";
 import { cn } from "@cl-light-ds/ui/lib/utils";
 
 interface Props extends Omit<HTMLAttributes<"div">, "class"> {
-  variant?: "default" | "outline";
+  /** `"segmented"`: outline, with the pressed item `muted` in `foreground` text (C26). */
+  variant?: "default" | "outline" | "segmented";
   size?: "xs" | "default" | "sm" | "lg";
   spacing?: number;
   defaultValue?: string | string[];
@@ -218,7 +235,7 @@ const {
   data-default-value={Array.isArray(defaultValue) ? defaultValue.join(",") : defaultValue}
   data-multiple={multiple ? "true" : undefined}
   class={cn(
-    "rounded-lg data-[spacing=0]:data-[variant=outline]:shadow-xs",
+    "rounded-lg data-[spacing=0]:data-[variant=outline]:shadow-xs data-[spacing=0]:data-[variant=segmented]:shadow-xs",
     "group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] data-vertical:flex-col data-vertical:items-stretch",
     className
   )}

package/src/components/toggle-group/ToggleGroupItem.astro

@@ -40,6 +40,16 @@ const {
     "group-data-vertical/toggle-group:group-data-[spacing=0]/toggle-group:group-data-[variant=outline]/toggle-group:border-t-0",
     "group-data-horizontal/toggle-group:group-data-[spacing=0]/toggle-group:group-data-[variant=outline]/toggle-group:first:border-s",
     "group-data-vertical/toggle-group:group-data-[spacing=0]/toggle-group:group-data-[variant=outline]/toggle-group:first:border-t",
+    // C26 — segmented: the outline's shared borders, and the pressed item
+    // `muted` in `foreground` text, also on hover. The pressed colours use a
+    // plain ancestor selector (Tailwind's group-data-* wraps the group in
+    // :where(), adding no weight) so they outrank the shared pressed and hover
+    // backgrounds.
+    "group-data-horizontal/toggle-group:group-data-[spacing=0]/toggle-group:group-data-[variant=segmented]/toggle-group:border-s-0",
+    "group-data-vertical/toggle-group:group-data-[spacing=0]/toggle-group:group-data-[variant=segmented]/toggle-group:border-t-0",
+    "group-data-horizontal/toggle-group:group-data-[spacing=0]/toggle-group:group-data-[variant=segmented]/toggle-group:first:border-s",
+    "group-data-vertical/toggle-group:group-data-[spacing=0]/toggle-group:group-data-[variant=segmented]/toggle-group:first:border-t",
+    "[[data-slot=toggle-group][data-variant=segmented]_&]:aria-pressed:bg-muted [[data-slot=toggle-group][data-variant=segmented]_&]:aria-pressed:text-foreground",
     className
   )}
   {...rest}

package/src/components/tooltip/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to the `Tooltip` component family (`Tooltip`, `TooltipTrigger`, `TooltipContent`) are documented in this file.
 
+## Date 15th Oct 2026
+## Handover gaps: Tooltip on these pages (C22, gap G2)
+
+### Fixed
+
+- **`TooltipTrigger asChild` binds your control, not the wrapper.** The handover recorded Tooltip as "doesn't work on these pages" (G2, workspace G10). That note dates from when the screens were static (no JavaScript), so no tooltip could work. Retested with 1.1.2 in the storybook and in a test page shaped like the screen (sticky top bar, `WorkspaceCard` with its stretched link, `ToggleGroup` view switcher, `FavoriteToggle`, a `Dialog`): hover shows the tooltip everywhere, on top of everything (portal, `z-50`), including in a dialog and over a sticky bar. What really failed, for every `asChild` trigger (the usual way to put a tooltip on a DS `Button`):
+  - **Keyboard:** the runtime listens for `focus` on whatever carries `data-slot="tooltip-trigger"`. With `asChild` that was the wrapper `<div>`, and `focus` doesn't bubble, so tabbing to the button never opened the tooltip.
+  - **Screen readers:** `aria-describedby` went on the wrapper `<div>`, not on the focused control.
+  - **Position:** the tooltip centred on the wrapper. In a grid cell, a flex column or a dialog body the wrapper stretches to the full width, so the tooltip sat off to one side (163px off in a 448px dialog).
+- `Tooltip`'s script now hands the slot to the wrapper's first child while binding, then gives the child its own `data-slot` back (the runtime keeps the element). Keyboard focus opens the tooltip, `aria-describedby` is on the control, and the tooltip centres on it. Markup and props are unchanged.
+- A **disabled** child (`:disabled` when the page loads) keeps the wrapper as trigger, as before: a disabled button fires no pointer events, so this keeps hovering it showing the tooltip.
+
+### Notes
+
+- Like the other overlays, tooltips bind once, when the page loads. A tooltip added to the page later needs `create()` from `@data-slot/tooltip`, and is bound to its wrapper.
+- The screens can now use `Tooltip` on icon-only controls, keeping their `aria-label`s.
+
+
+## Handover gaps: triggers don't submit forms (C29, gap G18)
+
+### Docs
+
+- `TooltipTrigger` already renders `type="button"` unless you pass a `type`; no change.
+- **`asChild`:** the wrapper is a `<div>`, not a button, so it can't set a type. Inside a `<form>`, give your child `type="button"` (now in the prop's JSDoc).
+
+
 ## 2026-09-18 — Figma alignment (ClickLearn Lightning Design Library, node `5275-137`)
 
 Figma documents Tooltip across four pages: Contents (6 side/align positions — already fully covered by the existing `side`/`align` props), Variants (Default, Outline), Sizes (Small, Large), and the top-level Component page.

package/src/components/tooltip/Tooltip.astro

@@ -351,7 +351,35 @@ const {
 <script>
   import { createTooltip } from "@data-slot/tooltip";
 
-  document
-    .querySelectorAll('[data-slot="tooltip"]')
-    .forEach((el) => createTooltip(el));
+  /*
+   * `TooltipTrigger asChild` renders a wrapper <div data-slot="tooltip-trigger">
+   * around your control, and @data-slot/tooltip binds to whatever carries that
+   * slot. Bound to the wrapper, the tooltip never opened on keyboard focus
+   * (focus doesn't bubble to the div), put aria-describedby on the div instead
+   * of the control, and centred on the div, which stretches in grid/flex
+   * columns (C22). So bind the child: give it the slot while binding, then give
+   * its own data-slot back (the runtime keeps the element, not the selector).
+   * A disabled child fires no pointer events, so it keeps the wrapper as its
+   * trigger, as before: hovering a disabled control still shows its tooltip.
+   */
+  const bind = (root: Element) => {
+    const wrapper = root.querySelector<HTMLElement>('[data-slot="tooltip-trigger"][data-as-child]');
+    const child = wrapper?.firstElementChild as HTMLElement | null | undefined;
+    if (!wrapper || !child || wrapper.closest('[data-slot="tooltip"]') !== root || child.matches(":disabled")) {
+      createTooltip(root);
+      return;
+    }
+    const childSlot = child.getAttribute("data-slot");
+    wrapper.setAttribute("data-slot", "tooltip-trigger-wrapper");
+    child.setAttribute("data-slot", "tooltip-trigger");
+    try {
+      createTooltip(root);
+    } finally {
+      if (childSlot === null) child.removeAttribute("data-slot");
+      else child.setAttribute("data-slot", childSlot);
+      wrapper.setAttribute("data-slot", "tooltip-trigger");
+    }
+  };
+
+  document.querySelectorAll('[data-slot="tooltip"]').forEach(bind);
 </script>

package/src/components/tooltip/TooltipTrigger.astro

@@ -4,7 +4,11 @@ import type { HTMLAttributes } from "astro/types";
 
 interface Props extends HTMLAttributes<"button"> {
   class?: string;
-  /** Radix-like: render wrapper so the child can be the interactive element */
+  /**
+   * Radix-like: render wrapper so the child can be the interactive element.
+   * The wrapper is not a button, so the child sets its own type: give a
+   * `<button>`/`<Button>` child `type="button"` inside a `<form>` or it submits it.
+   */
   asChild?: boolean;
 }
 

package/src/lib/command-search.ts

@@ -0,0 +1,78 @@
+/**
+ * Helpers for the `CommandSearch` component
+ * (`@cl-light-ds/ui/components/command-search`).
+ *
+ * ```ts
+ * import { setCommandSearchResults } from "@cl-light-ds/ui/lib/command-search";
+ *
+ * // mode="remote": search on your side, then hand the results back.
+ * palette.addEventListener("command-search:search", async (event) => {
+ *   const { query } = event.detail;
+ *   setCommandSearchResults(palette, await api.search(query), { query });
+ * });
+ * ```
+ */
+
+export interface CommandSearchResultItem {
+  /** Unique value, sent with `command-search:select`. */
+  value: string;
+  /** The row's text. */
+  label: string;
+  /** Muted text on the right, e.g. the workspace it is in. */
+  description?: string;
+  /** Navigate here when chosen. */
+  href?: string;
+  disabled?: boolean;
+}
+
+export interface CommandSearchResultGroup {
+  heading: string;
+  items: CommandSearchResultItem[];
+  /** Total matches, when more exist than `items` holds. Defaults to `items.length`. */
+  count?: number;
+  /**
+   * Show at most this many of `items`; the count stays `count ?? items.length`.
+   * Defaults to `CommandSearch`'s `limit`; 0 for no limit.
+   */
+  limit?: number;
+}
+
+type Target = string | HTMLElement | undefined;
+
+const findRoot = (target: Target): HTMLElement | null => {
+  if (typeof document === "undefined") return null;
+  if (target instanceof HTMLElement) return target;
+  if (typeof target === "string") return document.getElementById(target);
+  return document.querySelector<HTMLElement>("[data-command-search]");
+};
+
+/** Open the palette (empty, focused). Defaults to the first on the page. */
+export function openCommandSearch(target?: Target) {
+  findRoot(target)?.dispatchEvent(
+    new CustomEvent("dialog:set", { detail: { open: true } }),
+  );
+}
+
+/** Close the palette. */
+export function closeCommandSearch(target?: Target) {
+  findRoot(target)?.dispatchEvent(
+    new CustomEvent("dialog:set", { detail: { open: false } }),
+  );
+}
+
+/**
+ * End a search in `mode="remote"`: render these groups as the results (or,
+ * with no groups, keep the rows you have put in the list yourself). `query`
+ * guards against stale answers: results for an older query are ignored.
+ */
+export function setCommandSearchResults(
+  target: Target,
+  groups?: CommandSearchResultGroup[],
+  options: { query?: string } = {},
+) {
+  findRoot(target)?.dispatchEvent(
+    new CustomEvent("command-search:results", {
+      detail: { groups, query: options.query },
+    }),
+  );
+}

package/src/lib/dialog-focus.ts

@@ -0,0 +1,73 @@
+/**
+ * Focus inside popovers that open in a dialog.
+ *
+ * The popover runtime moves an open popover's content to <body> (a positioner),
+ * so it is outside the dialog: the dialog's focus trap sees focus there as
+ * "escaped" and pulls it back, and Tab from the popover's trigger skips the
+ * popover. A popover opened from a dialog acts as a nested modal instead:
+ *
+ * - Tab from its trigger goes into the popover (Shift+Tab to its last control);
+ * - Tab and Shift+Tab go round the popover's own controls;
+ * - Escape (the popover's own) closes it and returns to the trigger.
+ *
+ * The popover is tied to its dialog through its trigger (`aria-controls`).
+ * Installed once by Dialog; runs before the dialog's trap (window, capture).
+ */
+
+const TABBABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+let installed = false;
+
+/** The open popover whose trigger is in an open dialog and which holds or triggers `el`. */
+function popoverFor(el: Element): { content: HTMLElement; fromTrigger: boolean } | null {
+  const content = el.closest<HTMLElement>('[data-slot="popover-content"]');
+  if (content) return !content.hidden && inOpenDialog(triggerOf(content)) ? { content, fromTrigger: false } : null;
+
+  const trigger = el.closest<HTMLElement>('[aria-controls][aria-expanded="true"]');
+  const target = trigger && document.getElementById(trigger.getAttribute("aria-controls")!);
+  if (target?.dataset.slot === "popover-content" && !target.hidden && inOpenDialog(trigger)) {
+    return { content: target, fromTrigger: true };
+  }
+  return null;
+}
+
+function triggerOf(content: HTMLElement) {
+  return content.id ? document.querySelector(`[aria-controls="${CSS.escape(content.id)}"]`) : null;
+}
+
+function inOpenDialog(el: Element | null) {
+  return !!el?.closest('[data-slot="dialog-content"][data-open]');
+}
+
+export function trapTabInPopoversInDialogs() {
+  if (installed) return;
+  installed = true;
+
+  window.addEventListener(
+    "keydown",
+    (event) => {
+      if (event.key !== "Tab" || event.defaultPrevented) return;
+      const active = document.activeElement;
+      const found = active && popoverFor(active);
+      if (!found) return;
+
+      const tabbables = Array.from(found.content.querySelectorAll<HTMLElement>(TABBABLE)).filter(
+        (el) => !el.closest("[hidden]") && el.getClientRects().length > 0,
+      );
+      if (tabbables.length === 0) return;
+
+      event.preventDefault();
+      event.stopPropagation();
+      const at = found.fromTrigger ? -1 : tabbables.indexOf(active as HTMLElement);
+      const next =
+        at === -1
+          ? event.shiftKey
+            ? tabbables.length - 1
+            : 0
+          : (at + (event.shiftKey ? -1 : 1) + tabbables.length) % tabbables.length;
+      tabbables[next].focus();
+    },
+    true,
+  );
+}

package/src/lib/dropdown-menu-radio-groups.ts

@@ -0,0 +1,79 @@
+/**
+ * Several radio groups in one DropdownMenu.
+ *
+ * The @data-slot/dropdown-menu runtime holds a single radio value per menu, so a
+ * second group (Sort by + Order) would untick the first. A *named*
+ * DropdownMenuRadioGroup is run on the runtime's checkbox values instead: its
+ * items are registered as checkbox items, exactly one is kept checked, and they
+ * are still announced as radios (`menuitemradio`).
+ *
+ * The group's value is mirrored on the group (`data-value`) and announced with
+ * `dropdown-menu:group-value-change` ({ name, value, previousValue }) on the root.
+ */
+
+type Menu = { values: string[]; set(detail: { values?: string[] }): void };
+
+const GROUP = '[data-slot="dropdown-menu-radio-group"][data-name]';
+const ITEM = '[data-slot="dropdown-menu-radio-item"]';
+const GROUPED_ITEM = "[data-radio-group-item]";
+
+/** Before the runtime starts: turn named groups' items into checkbox items. */
+export function prepareRadioGroups(root: HTMLElement) {
+  const defaults: string[] = [];
+  for (const group of root.querySelectorAll<HTMLElement>(GROUP)) {
+    const items = Array.from(group.querySelectorAll<HTMLElement>(ITEM));
+    const initial =
+      group.dataset.defaultValue ?? items.find((item) => item.hasAttribute("data-default-checked"))?.dataset.value;
+    for (const item of items) {
+      item.dataset.slot = "dropdown-menu-checkbox-item";
+      item.setAttribute("data-radio-group-item", group.dataset.name!);
+      item.toggleAttribute("data-default-checked", item.dataset.value === initial);
+    }
+    if (initial) {
+      defaults.push(initial);
+      group.dataset.value = initial;
+    }
+  }
+  // Root defaults win over item defaults in the runtime, so merge ours in.
+  if (defaults.length && root.dataset.defaultValues) {
+    const values = JSON.parse(root.dataset.defaultValues) as string[];
+    root.dataset.defaultValues = JSON.stringify([...values, ...defaults.filter((v) => !values.includes(v))]);
+  }
+}
+
+/** After the runtime starts: keep one item per group checked. */
+export function bindRadioGroups(root: HTMLElement, menu: Menu) {
+  const items = Array.from(root.querySelectorAll<HTMLElement>(GROUPED_ITEM));
+  if (items.length === 0) return;
+  // The runtime re-sets checkbox items' role when the menu opens; keep them radios.
+  const asRadio = () => {
+    for (const item of items) if (item.getAttribute("role") !== "menuitemradio") item.setAttribute("role", "menuitemradio");
+  };
+  asRadio();
+  const roles = new MutationObserver(asRadio);
+  for (const item of items) roles.observe(item, { attributeFilter: ["role"] });
+
+  // Picking the checked item again would untick it: a radio can't be unset.
+  root.addEventListener("dropdown-menu:select", (event) => {
+    const item = (event as CustomEvent<{ item: HTMLElement | null }>).detail.item;
+    if (item?.hasAttribute("data-radio-group-item") && item.hasAttribute("data-checked")) event.preventDefault();
+  });
+
+  root.addEventListener("dropdown-menu:values-change", (event) => {
+    const { item, checked } = (event as CustomEvent<{ item: HTMLElement | null; checked: boolean }>).detail;
+    const name = item?.getAttribute("data-radio-group-item");
+    if (!item || !name || !checked) return;
+    const siblings = items.filter((other) => other !== item && other.getAttribute("data-radio-group-item") === name);
+    const drop = new Set(siblings.map((other) => other.dataset.value));
+    menu.set({ values: menu.values.filter((value) => !drop.has(value)) });
+
+    const group = item.closest<HTMLElement>(GROUP);
+    const previousValue = group?.dataset.value ?? null;
+    if (group) group.dataset.value = item.dataset.value;
+    root.dispatchEvent(
+      new CustomEvent("dropdown-menu:group-value-change", {
+        detail: { name, value: item.dataset.value, previousValue },
+      }),
+    );
+  });
+}

package/src/lib/loading-overlay.ts

@@ -0,0 +1,174 @@
+/**
+ * Controller for the `LoadingOverlay` component
+ * (`@cl-light-ds/ui/components/loading-overlay`). Works on the overlay's markup
+ * directly, so it can be called from any script, before or after the
+ * component's own script has run.
+ *
+ * ```ts
+ * import { showLoadingOverlay, revealLoadingOverlay, hideLoadingOverlay } from "@cl-light-ds/ui/lib/loading-overlay";
+ *
+ * showLoadingOverlay({ title: "Opening workspace…", lines: ["Loading your recordings…", "Fetching guides and assets…"] });
+ * await work();
+ * await revealLoadingOverlay(); // fade the dimming away to what is behind it
+ * ```
+ *
+ * The same is available as events on the overlay element:
+ * `loading-overlay:show` (detail: the show options), `loading-overlay:hide`,
+ * `loading-overlay:reveal` (detail: `{ duration }`), `loading-overlay:behind`
+ * (detail: `{ show }`). It fires `loading-overlay:change` (`{ open }`).
+ */
+
+export interface LoadingOverlayShowOptions {
+  /** Big title, e.g. "Opening workspace…". Defaults to the component's `title`. */
+  title?: string;
+  /** Status lines shown in turn under the title. Defaults to the component's `lines`. */
+  lines?: string[];
+  /** ms between status lines. Defaults to the component's `interval` (900). */
+  interval?: number;
+  /** Start again after the last line instead of staying on it. */
+  loop?: boolean;
+  /**
+   * Fade in the `behind` slot's content under the dimming: `true` at once, a
+   * number of ms to wait first, `false` not at all (default).
+   */
+  behind?: boolean | number;
+  /** Which overlay: its id or element. Defaults to the first on the page. */
+  overlay?: string | HTMLElement;
+}
+
+type Target = string | HTMLElement | undefined;
+
+interface RunState {
+  lineTimer?: number;
+  behindTimer?: number;
+  hideTimer?: number;
+  returnFocus?: HTMLElement | null;
+}
+
+const ROOT = '[data-slot="loading-overlay"]';
+const runs = new WeakMap<HTMLElement, RunState>();
+
+const findOverlay = (overlay: Target): HTMLElement | null => {
+  if (typeof document === "undefined") return null;
+  if (overlay instanceof HTMLElement) return overlay;
+  if (typeof overlay === "string") return document.getElementById(overlay);
+  return document.querySelector<HTMLElement>(ROOT);
+};
+
+const part = (root: HTMLElement, name: string) =>
+  root.querySelector<HTMLElement>(`[data-slot="loading-overlay-${name}"]`);
+
+const readLines = (root: HTMLElement): string[] => {
+  try {
+    const lines = JSON.parse(root.dataset.lines ?? "[]");
+    return Array.isArray(lines) ? lines.map(String) : [];
+  } catch {
+    return [];
+  }
+};
+
+const stop = (root: HTMLElement) => {
+  const run = runs.get(root);
+  if (!run) return run;
+  window.clearInterval(run.lineTimer);
+  window.clearTimeout(run.behindTimer);
+  window.clearTimeout(run.hideTimer);
+  return run;
+};
+
+const emit = (root: HTMLElement, open: boolean) =>
+  root.dispatchEvent(new CustomEvent("loading-overlay:change", { detail: { open } }));
+
+/** Show the overlay (or restart it with new text). */
+export function showLoadingOverlay(options: LoadingOverlayShowOptions = {}) {
+  const root = findOverlay(options.overlay);
+  if (!root) return;
+  const wasOpen = !root.hidden;
+  const previous = stop(root);
+  const run: RunState = {
+    returnFocus: wasOpen
+      ? previous?.returnFocus
+      : (document.activeElement as HTMLElement | null),
+  };
+  runs.set(root, run);
+
+  const title = part(root, "title");
+  const status = part(root, "status");
+  if (title && options.title !== undefined) title.textContent = options.title;
+  const lines = options.lines ?? readLines(root);
+  const interval = options.interval ?? (Number(root.dataset.interval) || 900);
+  const loop = options.loop ?? root.dataset.loop === "true";
+  let at = 0;
+  if (status) {
+    status.textContent = lines[0] ?? "";
+    status.hidden = lines.length === 0;
+  }
+  if (lines.length > 1) {
+    run.lineTimer = window.setInterval(() => {
+      at = loop ? (at + 1) % lines.length : Math.min(at + 1, lines.length - 1);
+      if (status) status.textContent = lines[at];
+    }, interval);
+  }
+
+  root.dataset.reveal = "off";
+  root.dataset.behind = "off";
+  const behind = options.behind ?? false;
+  if (behind !== false) {
+    run.behindTimer = window.setTimeout(
+      () => setLoadingOverlayBehind(true, root),
+      behind === true ? 0 : behind,
+    );
+  }
+
+  root.hidden = false;
+  root.setAttribute("aria-busy", "true");
+  // Keyboard focus moves off whatever is now covered.
+  root.focus({ preventScroll: true });
+  if (!wasOpen) emit(root, true);
+}
+
+/** Fade the `behind` slot's content in (or out) under the dimming. */
+export function setLoadingOverlayBehind(show: boolean, overlay?: Target) {
+  const root = findOverlay(overlay);
+  if (root && !root.hidden) root.dataset.behind = show ? "on" : "off";
+}
+
+/** Hide the overlay at once. */
+export function hideLoadingOverlay(overlay?: Target) {
+  const root = findOverlay(overlay);
+  if (!root || root.hidden) return;
+  const run = stop(root);
+  runs.delete(root);
+  root.hidden = true;
+  root.removeAttribute("aria-busy");
+  root.dataset.reveal = "off";
+  root.dataset.behind = "off";
+  if (root.contains(document.activeElement) && run?.returnFocus?.isConnected)
+    run.returnFocus.focus({ preventScroll: true });
+  emit(root, false);
+}
+
+/**
+ * Fade the dimming, spinner and text away, revealing what is behind (the
+ * page, or the `behind` slot), then hide. Resolves once hidden.
+ */
+export function revealLoadingOverlay(
+  options: { duration?: number; overlay?: Target } = {},
+): Promise<void> {
+  const root = findOverlay(options.overlay);
+  if (!root || root.hidden) return Promise.resolve();
+  const run = runs.get(root) ?? {};
+  window.clearInterval(run.lineTimer);
+  window.clearTimeout(run.hideTimer);
+  runs.set(root, run);
+  const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const duration = reduced ? 0 : (options.duration ?? 700);
+  root.dataset.reveal = "on";
+  root.removeAttribute("aria-busy");
+  return new Promise((resolve) => {
+    run.hideTimer = window.setTimeout(() => {
+      hideLoadingOverlay(root);
+      resolve();
+    }, duration);
+  });
+}

package/src/lib/scroll-lock.ts

@@ -0,0 +1,97 @@
+/**
+ * Page scroll lock for dialogs and menus that leaves the scrollbar where it is.
+ *
+ * The @data-slot runtimes lock scroll by setting `overflow: hidden` and
+ * `scrollbar-gutter: stable` on <html>. The reserved gutter isn't covered by a
+ * dialog's overlay (a white band down the right edge), and on a page with no
+ * scrollbar the gutter appears from nowhere and the page jumps sideways. So the
+ * components pass `lockScroll: false` to the runtime and lock here instead:
+ * nothing about the layout changes; the wheel, touch and the page-scrolling keys
+ * just don't scroll the page while a lock is held. Anything under the pointer
+ * that can scroll by itself (a long list in the dialog) still does, and a
+ * dragged scrollbar is put back.
+ */
+
+let holds = 0;
+let savedY = 0;
+let installed = false;
+
+/** Whether something between `target` and the page can scroll by `dy` itself. */
+function scrollsItself(target: EventTarget | null, dy: number) {
+  for (
+    let el = target instanceof Element ? target : null;
+    el && el !== document.body && el !== document.documentElement;
+    el = el.parentElement
+  ) {
+    const { overflowY } = getComputedStyle(el);
+    if (!/(auto|scroll)/.test(overflowY)) continue;
+    if (el.scrollHeight <= el.clientHeight) continue;
+    if (dy < 0 ? el.scrollTop > 0 : el.scrollTop + el.clientHeight < el.scrollHeight) return true;
+  }
+  return false;
+}
+
+function install() {
+  if (installed) return;
+  installed = true;
+
+  window.addEventListener(
+    "wheel",
+    (event) => {
+      if (holds > 0 && !scrollsItself(event.target, event.deltaY)) event.preventDefault();
+    },
+    { passive: false },
+  );
+
+  let touchY = 0;
+  window.addEventListener("touchstart", (event) => (touchY = event.touches[0]?.clientY ?? 0), {
+    passive: true,
+  });
+  window.addEventListener(
+    "touchmove",
+    (event) => {
+      const dy = touchY - (event.touches[0]?.clientY ?? touchY);
+      if (holds > 0 && !scrollsItself(event.target, dy)) event.preventDefault();
+    },
+    { passive: false },
+  );
+
+  window.addEventListener("keydown", (event) => {
+    if (holds === 0 || !["PageUp", "PageDown", "Home", "End", " "].includes(event.key)) return;
+    const target = event.target as HTMLElement;
+    if (target.closest("input, textarea, select, button, [contenteditable]")) return;
+    const dy = event.key === "PageUp" || event.key === "Home" ? -1 : 1;
+    if (!scrollsItself(target, dy)) event.preventDefault();
+  });
+
+  window.addEventListener("scroll", () => {
+    if (holds > 0 && window.scrollY !== savedY) window.scrollTo(window.scrollX, savedY);
+  });
+}
+
+/** Take a lock. Locks nest: the page scrolls again once every lock is released. */
+export function holdScrollLock() {
+  install();
+  if (holds === 0) savedY = window.scrollY;
+  holds += 1;
+}
+
+export function releaseScrollLock() {
+  holds = Math.max(0, holds - 1);
+}
+
+/**
+ * Hold the lock while `root` is open. `event` is the runtime's open-change event
+ * (its detail has `open`); `isOpen` reads the state for roots that start open.
+ */
+export function lockScrollWhileOpen(root: HTMLElement, event: string, isOpen: () => boolean) {
+  let open = false;
+  const set = (next: boolean) => {
+    if (next === open) return;
+    open = next;
+    if (next) holdScrollLock();
+    else releaseScrollLock();
+  };
+  root.addEventListener(event, (e) => set(Boolean((e as CustomEvent<{ open?: boolean }>).detail?.open)));
+  set(isOpen());
+}