@galaxy-io/dls 1.6.1 → 2.0.1

package/dist/inputs/internal/fieldFrame.d.ts

@@ -0,0 +1,34 @@
+/** @internal The DLS hairline width, for frames that draw or subtract it in `calc()`. */
+export declare const HAIRLINE_WIDTH = "0.5px";
+/** @internal The surface set a field frame rests on (the values of every input's `variant`). */
+export declare enum FieldSurface {
+    /** `background.base` fill. */
+    BASE = "BASE",
+    /** `background.primary` fill. The default. */
+    PRIMARY = "PRIMARY",
+    /** `background.secondary` fill. */
+    SECONDARY = "SECONDARY",
+    /** `background.tertiary` fill. */
+    TERTIARY = "TERTIARY"
+}
+/** @internal Rest look per surface: the fill and the `border.primary` hairline color. */
+export declare const FIELD_SURFACE_TO_REST_MAP: Record<FieldSurface, string>;
+/** @internal `isGhost` at rest: no fill and no hairline. Interpolate after the variant map, which it replaces. */
+export declare const FIELD_GHOST_REST = "background: transparent; border-color: transparent;";
+/**
+ * @internal Hover on an editable field (every surface, and a ghost field): the hairline steps up to
+ * `border.hovered`, stronger than `border.primary` in both themes (Constitution III.6).
+ */
+export declare const FIELD_HOVER: string;
+/**
+ * @internal The error hairline, declarations only: `border.error`, and the 1px inset focus line
+ * (`FIELD_FOCUS`) red too. Put it inside the frame's rest, hover and focus selectors.
+ */
+export declare const FIELD_ERROR: string;
+/**
+ * @internal Disabled: the variant's resting fill and hairline are kept (`border.disabled` is not
+ * used on frames); the field reads as disabled through `text.disabled` and the cursor.
+ */
+export declare const FIELD_DISABLED = "cursor: not-allowed;";
+/** @internal Stretch to the parent's width (the frame, and the `Field` wrapper when there is one). */
+export declare const FIELD_FILL_WIDTH = "display: flex; width: 100%;";

package/dist/inputs/internal/fieldFrame.js

@@ -0,0 +1,64 @@
+import { t } from "../../theme/tokens/t.js";
+//#region src/inputs/internal/fieldFrame.ts
+/**
+* @internal The field-frame look every framed input shares (Input, TextAreaInput, SelectInput,
+* TagInput, PinInput, DurationInput, DateInput, ColorInput, FileInput, SliderInput, ...): the
+* resting fill and hairline per surface variant, the ghost rest, the hover hairline, the error
+* hairline, the disabled cursor and the fill-width box. Private on purpose (an `internal/` module:
+* built, never a package export).
+*
+* Each export is a CSS-text fragment (a plain string, evaluated at build time by wyw), like the
+* mixins in `styles/mixins`: interpolate it inside the component's own `css` block instead of
+* re-declaring the rules. They are deliberately **not** `css` classes. The stylesheet lists a
+* module's CSS after the CSS of the modules it imports (`scripts/css-order.mjs`), so a class
+* declared here would land *before* every component's `styled` Root; the Root's own
+* `border: 0.5px solid transparent`, `display: inline-flex` and `cursor: text` would then win over
+* the fill, the hairline, `fillWidth` and the disabled cursor at equal specificity. Interpolating
+* keeps each class where the component declares it, so the cascade order is unchanged.
+*
+* A component keeps its public `<Component>Variant` enum (the surface set) and a full
+* `<COMPONENT>_VARIANT_TO_CSS_MAP: Record<<Component>Variant, string>` of `css` blocks whose bodies
+* are these fragments, keyed through `FieldSurface`.
+*/
+/** @internal The DLS hairline width, for frames that draw or subtract it in `calc()`. */
+var HAIRLINE_WIDTH = "0.5px";
+/** @internal The surface set a field frame rests on (the values of every input's `variant`). */
+var FieldSurface = /* @__PURE__ */ function(FieldSurface) {
+	/** `background.base` fill. */
+	FieldSurface["BASE"] = "BASE";
+	/** `background.primary` fill. The default. */
+	FieldSurface["PRIMARY"] = "PRIMARY";
+	/** `background.secondary` fill. */
+	FieldSurface["SECONDARY"] = "SECONDARY";
+	/** `background.tertiary` fill. */
+	FieldSurface["TERTIARY"] = "TERTIARY";
+	return FieldSurface;
+}({});
+/** @internal Rest look per surface: the fill and the `border.primary` hairline color. */
+var FIELD_SURFACE_TO_REST_MAP = {
+	["BASE"]: `background: ${t.color.background.base}; border-color: ${t.color.border.primary};`,
+	["PRIMARY"]: `background: ${t.color.background.primary}; border-color: ${t.color.border.primary};`,
+	["SECONDARY"]: `background: ${t.color.background.secondary}; border-color: ${t.color.border.primary};`,
+	["TERTIARY"]: `background: ${t.color.background.tertiary}; border-color: ${t.color.border.primary};`
+};
+/** @internal `isGhost` at rest: no fill and no hairline. Interpolate after the variant map, which it replaces. */
+var FIELD_GHOST_REST = "background: transparent; border-color: transparent;";
+/**
+* @internal Hover on an editable field (every surface, and a ghost field): the hairline steps up to
+* `border.hovered`, stronger than `border.primary` in both themes (Constitution III.6).
+*/
+var FIELD_HOVER = `&:hover { border-color: ${t.color.border.hovered}; }`;
+/**
+* @internal The error hairline, declarations only: `border.error`, and the 1px inset focus line
+* (`FIELD_FOCUS`) red too. Put it inside the frame's rest, hover and focus selectors.
+*/
+var FIELD_ERROR = `border-color: ${t.color.border.error}; outline-color: ${t.color.border.error};`;
+/**
+* @internal Disabled: the variant's resting fill and hairline are kept (`border.disabled` is not
+* used on frames); the field reads as disabled through `text.disabled` and the cursor.
+*/
+var FIELD_DISABLED = "cursor: not-allowed;";
+/** @internal Stretch to the parent's width (the frame, and the `Field` wrapper when there is one). */
+var FIELD_FILL_WIDTH = "display: flex; width: 100%;";
+//#endregion
+export { FIELD_DISABLED, FIELD_ERROR, FIELD_FILL_WIDTH, FIELD_GHOST_REST, FIELD_HOVER, FIELD_SURFACE_TO_REST_MAP, FieldSurface, HAIRLINE_WIDTH };

package/dist/inputs/internal/fieldWiring.d.ts

@@ -0,0 +1,50 @@
+import { type FieldContextValue } from "../../hooks/useField.js";
+/** @internal What a control gives the wiring: its own props, as destructured. */
+export interface FieldWiringOptions {
+    /** The control's own `id` prop. */
+    id: string | undefined;
+    /** The control's `ariaLabel` prop. */
+    ariaLabel: string | undefined;
+    /** A pass-through `aria-label` (from `...rest`). */
+    ariaLabelAttribute?: string | undefined;
+    /** A pass-through `aria-labelledby` (from `...rest`). */
+    ariaLabelledBy?: string | undefined;
+    /** The app's `aria-describedby`, appended after the Field's and the control's own ids. */
+    ariaDescribedBy: string | undefined;
+    /**
+     * Ids of the control's own descriptive parts (a prefix, a counter), in order; `false` skips one.
+     * A function receives the resolved control id, for part ids derived from it.
+     */
+    describedByIds?: readonly (string | false)[] | ((controlId: string) => readonly (string | false)[]);
+    /** The control's `error` message; a non-empty one marks it invalid. */
+    error?: string | undefined;
+    /**
+     * The control's `isError`.
+     * @default false
+     */
+    isError?: boolean;
+    /**
+     * The control's `isRequired`.
+     * @default false
+     */
+    isRequired?: boolean;
+}
+/** @internal The wiring a control applies to its root or `<input>`. */
+export interface FieldWiring {
+    /** The nearest Field's context, or `null` outside a Field. */
+    field: FieldContextValue | null;
+    /** The id the control carries: the Field's `controlId`, else the control's `id`, else generated. */
+    controlId: string;
+    /** Space-separated `aria-describedby`, or `undefined` when there is nothing to point at. */
+    describedBy: string | undefined;
+    /** `aria-invalid`: a non-empty `error`, `isError`, or the Field's `isError`. */
+    isInvalid: boolean;
+    /** `aria-required`: the control's `isRequired` or the Field's. */
+    isRequired: boolean;
+    /** True when something names the control (the Field's label, `ariaLabel`, `aria-label`, `aria-labelledby`). */
+    hasName: boolean;
+}
+/** @internal Joins the ids that are set into one `aria-describedby` value; `undefined` when none. */
+export declare function joinIds(ids: readonly (string | false | undefined)[]): string | undefined;
+/** @internal Reads the nearest Field and merges it with the control's own props (see the module doc). */
+export declare function useFieldWiring({ id, ariaLabel, ariaLabelAttribute, ariaLabelledBy, ariaDescribedBy, describedByIds, error, isError, isRequired, }: FieldWiringOptions): FieldWiring;

package/dist/inputs/internal/fieldWiring.js

@@ -0,0 +1,38 @@
+import { useField } from "../../hooks/useField.js";
+import { isFilled } from "./predicates.js";
+import { useId } from "react";
+//#region src/inputs/internal/fieldWiring.ts
+/**
+* @internal The `useField()` consumer contract (`hooks/useField`), computed once for every input:
+* the control id (the Field's wins over the control's own `id`, then a generated one), the merged
+* `aria-describedby` (the Field's ids, the control's own part ids, then the app's), the invalid and
+* required flags (the control's own props or the Field's), and whether the control has an
+* accessible name (the Field's label, `ariaLabel`, or a pass-through `aria-label` /
+* `aria-labelledby`). Private on purpose (an `internal/` module: built, never a package export).
+*/
+/** @internal Joins the ids that are set into one `aria-describedby` value; `undefined` when none. */
+function joinIds(ids) {
+	const present = ids.filter((candidate) => typeof candidate === "string" && candidate !== "");
+	return present.length > 0 ? present.join(" ") : void 0;
+}
+/** @internal Reads the nearest Field and merges it with the control's own props (see the module doc). */
+function useFieldWiring({ id, ariaLabel, ariaLabelAttribute, ariaLabelledBy, ariaDescribedBy, describedByIds = [], error, isError = false, isRequired = false }) {
+	const field = useField();
+	const generatedId = useId();
+	const controlId = field?.controlId ?? id ?? generatedId;
+	const ownIds = typeof describedByIds === "function" ? describedByIds(controlId) : describedByIds;
+	return {
+		field,
+		controlId,
+		describedBy: joinIds([
+			field?.describedBy,
+			...ownIds,
+			ariaDescribedBy
+		]),
+		isInvalid: isFilled(error) || isError || field?.isError === true,
+		isRequired: isRequired || field?.isRequired === true,
+		hasName: field?.labelId !== void 0 || isFilled(ariaLabel) || isFilled(ariaLabelledBy) || isFilled(ariaLabelAttribute)
+	};
+}
+//#endregion
+export { joinIds, useFieldWiring };

package/dist/inputs/internal/innerButton.d.ts

@@ -0,0 +1,2 @@
+/** @internal Apply to an in-field Button's `className` on the X_SMALL rung only. */
+export declare const X_SMALL_INNER_BUTTON_CSS: import("@linaria/core").LinariaClassName;

package/dist/inputs/internal/innerButton.js

@@ -0,0 +1,24 @@
+/* empty css                      */
+//#region src/inputs/internal/innerButton.ts
+/**
+* @internal The in-field button on the X_SMALL rung, private to the DLS (an `internal/` module:
+* built, never a package export).
+*
+* A field puts a `ButtonSize.X_SMALL` button (20px) inside its frame: the clear button of Input,
+* SelectInput / MultiSelectInput, DateInput and ColorInput, CopyInput's copy, PasswordInput's
+* reveal and NumberInput's steppers. From SMALL up the frame leaves 2–6px around it, but an
+* X_SMALL frame is 20px itself, so the button's hover fill would cover the whole frame and run
+* over its hairline. On that rung the button is a 16px square instead: the frame height minus
+* 2px on each side, so the fill sits inside the frame with the same 2px gap SMALL has.
+*
+* The icon stays Button's 13px glyph in its 14px `IconSlot`, which lands on whole pixels in the
+* 16px box (1px in from each edge). The focus ring is drawn on the button's own edge
+* (`outline-offset: -1px`) rather than 1px outside it, so it stays inside the frame too.
+*
+* Doubled class, so it beats Button's size and icon-only rules (one class each) and its
+* `FOCUS_RING` offset whatever the stylesheet order.
+*/
+/** @internal Apply to an in-field Button's `className` on the X_SMALL rung only. */
+var X_SMALL_INNER_BUTTON_CSS = "gx-innerButton-X_SMALL_INNER_BUTTON_CSS-x1ep0pcd";
+//#endregion
+export { X_SMALL_INNER_BUTTON_CSS };

package/dist/inputs/internal/ownField.d.ts

@@ -0,0 +1,45 @@
+import type { CSSProperties } from "react";
+import type { FieldProps, FieldSize } from "../Field.js";
+/** @internal What the input hands the shell: its own props, as destructured. */
+export interface OwnFieldOptions {
+    /** The component's display name, for the development warning. */
+    componentName: string;
+    /** The input's `label`. */
+    label: string | undefined;
+    /** The input's `error`. */
+    error: string | undefined;
+    /** The input's `isRequired`, forwarded to the Field (the asterisk and `aria-required`). */
+    isRequired: boolean;
+    /** The Field rung, from the component's own `<COMPONENT>_SIZE_TO_FIELD_SIZE_MAP`. */
+    size: FieldSize;
+    /** The input's `id`, forwarded to the Field (the control's id, the label's `htmlFor`). */
+    id: string | undefined;
+    /** The input's `className`; on the Field when one renders, otherwise the frame's. */
+    className: string | undefined;
+    /** The input's `style`; on the Field when one renders, otherwise the frame's. */
+    style: CSSProperties | undefined;
+    /** A class placed before `className` on the Field (the component's fill-width class, when `fillWidth`). */
+    rootClassName?: string | false;
+    /** Forwarded as the Field's own `fillWidth` prop (ToggleInput's Field stretches itself). */
+    fillWidth?: boolean;
+    /**
+     * `false` when the input never renders its own Field (ColorInput with a custom trigger).
+     * @default true
+     */
+    isEnabled?: boolean;
+}
+/** @internal The props of the Field an input renders for itself. */
+export type OwnFieldProps = Pick<FieldProps, "label" | "error" | "isRequired" | "size" | "fillWidth" | "id" | "className" | "style">;
+/**
+ * @internal The Field props when the input must render its own Field (standalone, with a `label`
+ * or an `error`), or `null` when the frame renders alone (no label and no error, or inside an
+ * app's Field). Warns once, in development, when an input inside a Field also has its own `label`.
+ */
+export declare function useOwnField({ componentName, label, error, isRequired, size, id, className, style, rootClassName, fillWidth, isEnabled, }: OwnFieldOptions): OwnFieldProps | null;
+/**
+ * @internal The frame's `style`, only when the frame is the root (an own Field takes it otherwise).
+ * Spread onto the frame: `{...rootStyle(isRoot, style)}`.
+ */
+export declare function rootStyle(isRoot: boolean, style: CSSProperties | undefined): {
+    style?: CSSProperties;
+};

package/dist/inputs/internal/ownField.js

@@ -0,0 +1,58 @@
+import { useDevWarning } from "./devWarn.js";
+import { useField } from "../../hooks/useField.js";
+import { isFilled } from "./predicates.js";
+import { cx } from "@linaria/core";
+//#region src/inputs/internal/ownField.tsx
+/**
+* @internal The own-Field shell every labelled input shares. A standalone input with `label` or
+* `error` renders a `Field` around its frame; inside an app's Field it never wraps itself again
+* and reads the Field's wiring instead (`useField()`). The shell also decides where `className`
+* and `style` go: on the Field when the input renders one, otherwise on the frame (the root).
+* Private on purpose (an `internal/` module: built, never a package export).
+*
+* ```tsx
+* const Input = forwardRef<HTMLInputElement, InputProps>(function Input(props, ref) {
+*   const ownField = useOwnField({ componentName: "Input", ..., size: INPUT_SIZE_TO_FIELD_SIZE_MAP[size] });
+*   if (ownField !== null) {
+*     return (
+*       <Field {...ownField}>
+*         <InputFrame inputProps={props} forwardedRef={ref} isRoot={false} />
+*       </Field>
+*     );
+*   }
+*   return <InputFrame inputProps={props} forwardedRef={ref} isRoot />;
+* });
+* ```
+*/
+/**
+* @internal The Field props when the input must render its own Field (standalone, with a `label`
+* or an `error`), or `null` when the frame renders alone (no label and no error, or inside an
+* app's Field). Warns once, in development, when an input inside a Field also has its own `label`.
+*/
+function useOwnField({ componentName, label, error, isRequired, size, id, className, style, rootClassName, fillWidth, isEnabled = true }) {
+	const field = useField();
+	const hasLabel = isFilled(label);
+	const hasError = isFilled(error);
+	useDevWarning(isEnabled && field !== null && hasLabel, `[@galaxy-io/dls] ${componentName} inside a Field ignores its own \`label\`. Put the label on the Field only.`);
+	if (!isEnabled || field !== null || !hasLabel && !hasError) return null;
+	const fieldClassName = cx(rootClassName, className);
+	return {
+		...hasLabel ? { label } : {},
+		...hasError ? { error } : {},
+		isRequired,
+		size,
+		...fillWidth === void 0 ? {} : { fillWidth },
+		...id === void 0 ? {} : { id },
+		...fieldClassName === "" ? {} : { className: fieldClassName },
+		...style === void 0 ? {} : { style }
+	};
+}
+/**
+* @internal The frame's `style`, only when the frame is the root (an own Field takes it otherwise).
+* Spread onto the frame: `{...rootStyle(isRoot, style)}`.
+*/
+function rootStyle(isRoot, style) {
+	return isRoot && style !== void 0 ? { style } : {};
+}
+//#endregion
+export { rootStyle, useOwnField };

package/dist/inputs/internal/predicates.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @internal The two predicates every input uses to decide whether a string prop or a slot renders.
+ * Private on purpose (an `internal/` module: built, never a package export).
+ */
+import type { ReactNode } from "react";
+/** @internal True for a non-empty string (`label`, `error`, `prefix`, an `aria-*` id list). */
+export declare function isFilled(text: string | undefined): text is string;
+/** @internal True when a slot value would render something (`leading`, `trailing`, `description`). */
+export declare function hasContent(node: ReactNode): boolean;

package/dist/inputs/internal/predicates.js

@@ -0,0 +1,11 @@
+//#region src/inputs/internal/predicates.ts
+/** @internal True for a non-empty string (`label`, `error`, `prefix`, an `aria-*` id list). */
+function isFilled(text) {
+	return text !== void 0 && text !== "";
+}
+/** @internal True when a slot value would render something (`leading`, `trailing`, `description`). */
+function hasContent(node) {
+	return node !== void 0 && node !== null && node !== false && node !== "";
+}
+//#endregion
+export { hasContent, isFilled };

package/dist/inputs/internal/useComboboxPopover.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @internal The plumbing a field that opens a panel shares (SelectInput, DateInput, ColorInput):
+ * an open setter that drops repeated requests before React renders, the focus return after a
+ * press outside the panel, and the retried focus into a panel that mounts in a portal a render
+ * after it opens. Private on purpose (an `internal/` module: built, never a package export).
+ */
+import { type MutableRefObject, type RefObject } from "react";
+/** @internal The deduped open setter and the latest requested state, for handlers that run before React renders. */
+export interface DedupedOpen {
+    /** Opens or closes, ignoring a request that matches the latest requested state. */
+    setOpen: (next: boolean) => void;
+    /** The latest requested state (`isShown`, or a pending request not yet rendered). */
+    isShownRef: RefObject<boolean>;
+}
+/**
+ * @internal An open setter that ignores a request matching the latest requested state. An outside
+ * press and the blur it causes both ask to close before React renders: the second is dropped.
+ * Every accepted request re-renders, so the tracked state returns to the real `isShown` even when
+ * a controlled caller ignores the request.
+ */
+export declare function useDedupedOpen(isShown: boolean, setOpenState: (isOpen: boolean) => void): DedupedOpen;
+/** @internal Where focus returns after an outside press, and what counts as inside. */
+export interface RestoreFocusOptions {
+    /** Whether the panel is shown; the listener is only installed while it is. */
+    isShown: boolean;
+    /** The element focus returns to (the combobox control or the custom trigger); also the document source. */
+    focusRef: RefObject<HTMLElement | null>;
+    /** A press inside any of these (the field, the trigger, the panel) is not an outside press. */
+    insideRefs: readonly RefObject<HTMLElement | null>[];
+    /** Focus returns only when, as the press began, the active element was inside one of these. */
+    focusScopeRefs: readonly RefObject<HTMLElement | null>[];
+}
+/**
+ * @internal A press outside closes the panel (Popover), which does not return focus. When focus was
+ * inside the scope as the press began and the press lands on nothing focusable, the browser moves
+ * focus to the body; once the press settles (`pointerup`, then a frame), focus returns to
+ * `focusRef`. Any other field that took focus keeps it.
+ */
+export declare function useRestoreFocusAfterOutsidePress(options: RestoreFocusOptions): void;
+/**
+ * @internal Focuses `findTarget()` before paint while `shouldFocusRef` asks for it and the panel is
+ * shown. The portal mounts a render later than the panel's first commit, so a missing target is
+ * retried for up to `retryFrames` animation frames. Runs after every render, like the code it
+ * replaces; the ref is cleared once the target is focused.
+ */
+export declare function useRetriedFocus(shouldFocusRef: MutableRefObject<boolean>, isShown: boolean, findTarget: () => HTMLElement | null, retryFrames: number): void;

package/dist/inputs/internal/useComboboxPopover.js

@@ -0,0 +1,92 @@
+import { useIsomorphicLayoutEffect } from "../../hooks/useIsomorphicLayoutEffect.js";
+import { useCallback, useEffect, useReducer, useRef } from "react";
+//#region src/inputs/internal/useComboboxPopover.ts
+/**
+* @internal The plumbing a field that opens a panel shares (SelectInput, DateInput, ColorInput):
+* an open setter that drops repeated requests before React renders, the focus return after a
+* press outside the panel, and the retried focus into a panel that mounts in a portal a render
+* after it opens. Private on purpose (an `internal/` module: built, never a package export).
+*/
+/**
+* @internal An open setter that ignores a request matching the latest requested state. An outside
+* press and the blur it causes both ask to close before React renders: the second is dropped.
+* Every accepted request re-renders, so the tracked state returns to the real `isShown` even when
+* a controlled caller ignores the request.
+*/
+function useDedupedOpen(isShown, setOpenState) {
+	const isShownRef = useRef(isShown);
+	isShownRef.current = isShown;
+	const [, rerender] = useReducer((count) => count + 1, 0);
+	return {
+		setOpen: useCallback((next) => {
+			if (next === isShownRef.current) return;
+			isShownRef.current = next;
+			setOpenState(next);
+			rerender();
+		}, [setOpenState]),
+		isShownRef
+	};
+}
+/**
+* @internal A press outside closes the panel (Popover), which does not return focus. When focus was
+* inside the scope as the press began and the press lands on nothing focusable, the browser moves
+* focus to the body; once the press settles (`pointerup`, then a frame), focus returns to
+* `focusRef`. Any other field that took focus keeps it.
+*/
+function useRestoreFocusAfterOutsidePress(options) {
+	const { isShown } = options;
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	useEffect(() => {
+		const doc = optionsRef.current.focusRef.current?.ownerDocument;
+		if (!isShown || doc === void 0) return;
+		const restore = () => {
+			if (doc.activeElement === null || doc.activeElement === doc.body) optionsRef.current.focusRef.current?.focus({ preventScroll: true });
+		};
+		const handlePointerDown = (event) => {
+			const target = event.target;
+			if (target === null) return;
+			const { insideRefs, focusScopeRefs } = optionsRef.current;
+			if (insideRefs.some((ref) => ref.current?.contains(target) === true)) return;
+			const active = doc.activeElement;
+			if (!(active !== null && active !== doc.body && focusScopeRefs.some((ref) => ref.current?.contains(active) === true))) return;
+			const settle = () => doc.defaultView?.requestAnimationFrame(restore);
+			doc.addEventListener("pointerup", settle, {
+				once: true,
+				capture: true
+			});
+		};
+		doc.addEventListener("pointerdown", handlePointerDown, true);
+		return () => doc.removeEventListener("pointerdown", handlePointerDown, true);
+	}, [isShown]);
+}
+/**
+* @internal Focuses `findTarget()` before paint while `shouldFocusRef` asks for it and the panel is
+* shown. The portal mounts a render later than the panel's first commit, so a missing target is
+* retried for up to `retryFrames` animation frames. Runs after every render, like the code it
+* replaces; the ref is cleared once the target is focused.
+*/
+function useRetriedFocus(shouldFocusRef, isShown, findTarget, retryFrames) {
+	useIsomorphicLayoutEffect(() => {
+		if (!shouldFocusRef.current || !isShown) return;
+		const tryFocus = () => {
+			const target = findTarget();
+			if (target === null) return false;
+			shouldFocusRef.current = false;
+			target.focus({ preventScroll: true });
+			return true;
+		};
+		if (tryFocus()) return;
+		let tries = 0;
+		let frame = 0;
+		const retry = () => {
+			if (!shouldFocusRef.current || tryFocus()) return;
+			tries += 1;
+			if (tries < retryFrames) frame = requestAnimationFrame(retry);
+		};
+		frame = requestAnimationFrame(retry);
+		return () => cancelAnimationFrame(frame);
+	});
+}
+//#endregion
+export { useDedupedOpen, useRestoreFocusAfterOutsidePress, useRetriedFocus };

package/dist/json/JsonViewer.d.ts

@@ -0,0 +1,62 @@
+import { type AriaAttributes, type CSSProperties } from "react";
+/** Row rung: the same two rungs, with the same row geometry, as `TreeSize`. */
+export declare enum JsonViewerSize {
+    /** Tree's SMALL row: 24px, mono `body_sm`, 10px caret, 14px per level; `SMALL` search field, `X_SMALL` copy buttons. */
+    SMALL = "SMALL",
+    /** Tree's MEDIUM row: 28px, mono `body_md`, 12px caret, 16px per level; `MEDIUM` search field, `SMALL` copy buttons. The default. */
+    MEDIUM = "MEDIUM"
+}
+/** A JSON value: what `JSON.parse` returns. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Every JsonViewer prop except the accessible-name pair (`ariaLabel` / `aria-labelledby`). */
+interface JsonViewerBaseProps extends AriaAttributes {
+    /** The value to show, already parsed. Keys keep their insertion order. */
+    data: JsonValue;
+    /**
+     * How many levels start expanded: `0` shows only the top-level rows collapsed, `1` opens the top-level objects and arrays, `Infinity` opens everything.
+     * @default 1
+     */
+    defaultExpandedDepth?: number;
+    /**
+     * Show a search field above the rows. Matching keys and values are highlighted and their ancestors expand.
+     * @default false
+     */
+    canSearch?: boolean;
+    /**
+     * Show a footer with the focused row's path and buttons to copy the path and the row's value as JSON.
+     * @default false
+     */
+    canCopy?: boolean;
+    /**
+     * Row rung: Tree's 24 / 28px rows, with the rung's text, caret and indent. The search field and footer buttons follow it.
+     * @default JsonViewerSize.MEDIUM
+     */
+    size?: JsonViewerSize;
+    /** DOM id on the root `<div>`. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root `<div>`. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root `<div>`. */
+    className?: string;
+    /** Inline style on the root `<div>`; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** Named by `ariaLabel`. */
+interface JsonViewerNamedProps {
+    /** Accessible name of the tree. Required unless `aria-labelledby` names it. */
+    ariaLabel: string;
+}
+/** Named by a visible heading through `aria-labelledby` (forwarded to the `role="tree"` element). */
+interface JsonViewerLabelledByProps {
+    /** Accessible name of the tree. Required unless `aria-labelledby` names it. */
+    ariaLabel?: undefined;
+    /** Id of the element that names the tree (a visible heading). */
+    "aria-labelledby": string;
+}
+/** JsonViewer props. The tree needs a name: `ariaLabel`, or `aria-labelledby` pointing at a heading. */
+export type JsonViewerProps = JsonViewerBaseProps & (JsonViewerNamedProps | JsonViewerLabelledByProps);
+/** Collapsible, type-colored JSON with search and path copy. */
+declare const JsonViewer: import("react").ForwardRefExoticComponent<JsonViewerProps & import("react").RefAttributes<HTMLDivElement>>;
+export default JsonViewer;