@galaxy-io/dls 1.6.1 → 2.0.0

package/dist/feedback/Spinner.d.ts

@@ -0,0 +1,63 @@
+import { type AriaAttributes, type CSSProperties, type ReactNode } from "react";
+/** Canonical rungs; the member names the control rung the spinner sits in. */
+export declare enum SpinnerSize {
+    /** 20px rung: 12px ring, `caption` label. */
+    X_SMALL = "X_SMALL",
+    /** 24px rung: 12px ring, `body_sm` label. */
+    SMALL = "SMALL",
+    /** 32px rung: 14px ring, `body_md` label. The default. */
+    MEDIUM = "MEDIUM",
+    /** 36px rung: 14px ring, `body_lg` label. */
+    LARGE = "LARGE",
+    /** 40px rung: 16px ring, `body_lg` label. */
+    X_LARGE = "X_LARGE"
+}
+/** Color role of the ring and label (Constitution V-A color set, neutral subset). */
+export declare enum SpinnerVariant {
+    /** `text.primary`. */
+    PRIMARY = "PRIMARY",
+    /** `text.secondary`. The default: loading is quiet, auxiliary chrome. */
+    SECONDARY = "SECONDARY",
+    /** `text.tertiary`. */
+    TERTIARY = "TERTIARY",
+    /** The host's color (`currentColor`); used inside Button, Chip and Toast. */
+    INHERIT = "INHERIT"
+}
+export interface SpinnerProps extends AriaAttributes {
+    /**
+     * The control rung the spinner sits in. The ring is that rung's icon size (12 / 12 / 14 / 14 /
+     * 16px), so a host maps its own size with an identity map. With `children`, the size sets the
+     * line box and the label step; the content keeps its own size (give it the rung's icon px).
+     * @default SpinnerSize.MEDIUM
+     */
+    size?: SpinnerSize;
+    /**
+     * Color role of the ring and label. `INHERIT` follows the host's `currentColor` (inside Button).
+     * Turning `children` take it when they inherit (`Icon variant={IconVariant.INHERIT}`).
+     * @default SpinnerVariant.SECONDARY
+     */
+    variant?: SpinnerVariant;
+    /** Visible text after the ring ("Loading results…"); also the live region's text. */
+    label?: string;
+    /**
+     * What screen readers hear when there is no visible `label`. Ignored when `label` is set.
+     * @default "Loading"
+     */
+    ariaLabel?: string;
+    /**
+     * Content to turn instead of the ring, usually an `Icon` (a refresh glyph while a sync runs).
+     * Phrasing content only (it renders inside a `<span>`). Stands still under reduced motion.
+     */
+    children?: ReactNode;
+    /** DOM id on the root `<span>`. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the root `<span>`. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root `<span>`. */
+    className?: string;
+    /** Inline style on the root `<span>`; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** A turning ring (or turning `children`) with a polite live region; optionally a visible label beside it. */
+declare const Spinner: import("react").ForwardRefExoticComponent<SpinnerProps & import("react").RefAttributes<HTMLSpanElement>>;
+export default Spinner;

package/dist/feedback/Spinner.js

@@ -0,0 +1,141 @@
+import VisuallyHidden from "../a11y/VisuallyHidden.js";
+import Text, { TextSize, TextVariant } from "../text/Text.js";
+import Icon, { IconVariant } from "../icons/Icon.js";
+/* empty css                  */
+import { styled } from "@linaria/react";
+import { forwardRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "@linaria/core";
+import { CircleNotchIcon } from "@phosphor-icons/react";
+//#region src/feedback/Spinner.tsx
+/**
+* The indeterminate loading indicator: a turning ring for a short, unmeasured wait. A preset over
+* `Icon` (`CircleNotchIcon` + `isSpinning`), so the turn and its reduced-motion handling are the
+* Icon's. Spinner adds a polite `role="status"` live region with an accessible name, a size that
+* matches the control rung it sits in, and an optional visible `label` beside the ring.
+*
+* Hosts that swap their icon for a Spinner (`Button isLoading`) map their size with an identity
+* map (`BUTTON_SIZE_TO_SPINNER_SIZE_MAP`), render `variant={SpinnerVariant.INHERIT}`, pass
+* `aria-hidden`, and set `aria-busy="true"` on themselves, so their accessible name stays their
+* label. A loading region sets `aria-busy="true"` on itself and places a Spinner inside it.
+*
+* With `children`, Spinner turns that content instead of drawing the ring: a refresh glyph while a
+* sync runs, a sync badge, a custom mark (`<Spinner><Icon component={ArrowsClockwiseIcon} /></Spinner>`).
+* The turn is the ring's (one turn per `6 × duration.base`, linear) and stops under reduced
+* motion; the live region, name, size and variant work the same. Render the Spinner only while
+* the work runs and the plain content otherwise.
+*
+* Not progress (`ProgressBar`, `ProgressCircle`) and not the shape of loading content
+* (`Skeleton`).
+*/
+/** Canonical rungs; the member names the control rung the spinner sits in. */
+var SpinnerSize = /* @__PURE__ */ function(SpinnerSize) {
+	/** 20px rung: 12px ring, `caption` label. */
+	SpinnerSize["X_SMALL"] = "X_SMALL";
+	/** 24px rung: 12px ring, `body_sm` label. */
+	SpinnerSize["SMALL"] = "SMALL";
+	/** 32px rung: 14px ring, `body_md` label. The default. */
+	SpinnerSize["MEDIUM"] = "MEDIUM";
+	/** 36px rung: 14px ring, `body_lg` label. */
+	SpinnerSize["LARGE"] = "LARGE";
+	/** 40px rung: 16px ring, `body_lg` label. */
+	SpinnerSize["X_LARGE"] = "X_LARGE";
+	return SpinnerSize;
+}({});
+/** Color role of the ring and label (Constitution V-A color set, neutral subset). */
+var SpinnerVariant = /* @__PURE__ */ function(SpinnerVariant) {
+	/** `text.primary`. */
+	SpinnerVariant["PRIMARY"] = "PRIMARY";
+	/** `text.secondary`. The default: loading is quiet, auxiliary chrome. */
+	SpinnerVariant["SECONDARY"] = "SECONDARY";
+	/** `text.tertiary`. */
+	SpinnerVariant["TERTIARY"] = "TERTIARY";
+	/** The host's color (`currentColor`); used inside Button, Chip and Toast. */
+	SpinnerVariant["INHERIT"] = "INHERIT";
+	return SpinnerVariant;
+}({});
+/**
+* Phrasing content only (`span`, `svg`), so a Spinner is valid inside a `<button>`. The root is
+* exactly its rung's text line height and top-aligned, so an inline Spinner beside its paired
+* text step never grows the line box (the Kbd measurement).
+*/
+var Root = /*#__PURE__*/ styled("span")({
+	name: "Root",
+	class: "gx-Spinner-r1ivml5",
+	propsAsIs: false
+});
+/** Sets `color` on the root; the ring and label both inherit it, so they always match. */
+var SPINNER_VARIANT_TO_CSS_MAP = {
+	["PRIMARY"]: "gx-Spinner-PRIMARY-p13j7c2o",
+	["SECONDARY"]: "gx-Spinner-SECONDARY-s8zy9wb",
+	["TERTIARY"]: "gx-Spinner-TERTIARY-t5gu4wz",
+	["INHERIT"]: "gx-Spinner-INHERIT-i1rr97gm"
+};
+/** Root height = the line height of the rung's text step; gap = the rung's gap (as Button). */
+var SPINNER_SIZE_TO_CSS_MAP = {
+	["X_SMALL"]: "gx-Spinner-X_SMALL-xq5lz1a",
+	["SMALL"]: "gx-Spinner-SMALL-s1yd7rf9",
+	["MEDIUM"]: "gx-Spinner-MEDIUM-mvjisul",
+	["LARGE"]: "gx-Spinner-LARGE-lo34ltu",
+	["X_LARGE"]: "gx-Spinner-X_LARGE-x1ml6nkc"
+};
+/** Turns `children` about their center: inline, centered, never squeezed. */
+var Turn = /*#__PURE__*/ styled("span")({
+	name: "Turn",
+	class: "gx-Spinner-Turn-txbcxfl",
+	propsAsIs: false
+});
+/**
+* One turn every six `duration.base` steps (900ms), linear, forever: the `Icon isSpinning` period,
+* so a turning child and the ring move alike. The keyframes are global, so the name is `gx-`
+* prefixed. `REDUCED_MOTION` stops it.
+*/
+var TURNING_CSS = "gx-Spinner-TURNING_CSS-t19924lc";
+/** The ring is the rung's icon px, one step below III-A.4 (Mitch, 2026-10-04). Button draws its own ring at its icon px (13 / 13 / 15 / 15 / 17). */
+var SPINNER_SIZE_TO_ICON_PX_MAP = {
+	["X_SMALL"]: 12,
+	["SMALL"]: 12,
+	["MEDIUM"]: 14,
+	["LARGE"]: 14,
+	["X_LARGE"]: 16
+};
+/** The label is the rung's text step (Constitution III-A.4). */
+var SPINNER_SIZE_TO_TEXT_SIZE_MAP = {
+	["X_SMALL"]: TextSize.CAPTION,
+	["SMALL"]: TextSize.BODY_SM,
+	["MEDIUM"]: TextSize.BODY_MD,
+	["LARGE"]: TextSize.BODY_LG,
+	["X_LARGE"]: TextSize.BODY_LG
+};
+/** Whether `children` render anything; `undefined`, `null`, `false` and `""` draw the ring. */
+function hasContent(children) {
+	return children !== void 0 && children !== null && children !== false && children !== "";
+}
+/** A turning ring (or turning `children`) with a polite live region; optionally a visible label beside it. */
+var Spinner = forwardRef(function Spinner({ size = "MEDIUM", variant = "SECONDARY", label, ariaLabel = "Loading", children, id, className, style, ...rest }, ref) {
+	return /* @__PURE__ */ jsxs(Root, {
+		role: "status",
+		...rest,
+		ref,
+		id,
+		className: cx(SPINNER_VARIANT_TO_CSS_MAP[variant], SPINNER_SIZE_TO_CSS_MAP[size], className),
+		style,
+		children: [hasContent(children) ? /* @__PURE__ */ jsx(Turn, {
+			className: TURNING_CSS,
+			children
+		}) : /* @__PURE__ */ jsx(Icon, {
+			component: CircleNotchIcon,
+			isSpinning: true,
+			size: SPINNER_SIZE_TO_ICON_PX_MAP[size],
+			variant: IconVariant.INHERIT
+		}), label === void 0 ? /* @__PURE__ */ jsx(VisuallyHidden, { children: ariaLabel }) : /* @__PURE__ */ jsx(Text, {
+			as: "span",
+			size: SPINNER_SIZE_TO_TEXT_SIZE_MAP[size],
+			variant: TextVariant.INHERIT,
+			children: label
+		})]
+	});
+});
+Spinner.displayName = "Spinner";
+//#endregion
+export { SpinnerSize, SpinnerVariant, Spinner as default };

package/dist/fonts.css

@@ -0,0 +1,70 @@
+/*
+ * @galaxy-io/dls/fonts.css — the DLS font faces. Import once at the app root, beside
+ * styles.css and tokens.css. Families match `t.font.<family>.family`:
+ *   sans  → "ABC Diatype"    400, 500
+ *   mono  → "Berkeley Mono"  400, 500 (no Medium cut exists; 500 is Bold, as in 1.x)
+ *   serif → "Cardo"          400, 400 italic, 700 (editorial only)
+ * Not part of styles.css, so apps that self-host the files can skip it.
+ */
+
+@font-face {
+  font-family: "ABC Diatype";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("https://cdn.getgalaxy.io/fonts/Diatype/ABCDiatype-Regular.otf") format("opentype");
+}
+
+@font-face {
+  font-family: "ABC Diatype";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("https://cdn.getgalaxy.io/fonts/Diatype/ABCDiatype-Medium.otf") format("opentype");
+}
+
+@font-face {
+  font-family: "Berkeley Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("https://cdn.getgalaxy.io/fonts/BerkeleyMono/BerkeleyMono-Regular.otf")
+    format("opentype");
+}
+
+@font-face {
+  font-family: "Berkeley Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("https://cdn.getgalaxy.io/fonts/BerkeleyMono/BerkeleyMono-Bold.otf") format("opentype");
+}
+
+/*
+ * TODO: move Cardo to cdn.getgalaxy.io (`fonts/Cardo/Cardo-{Regular,Italic,Bold}.ttf`).
+ * Temporary: Google Fonts' static Cardo v21 files (OFL), whole-font TTFs so no unicode-range.
+ */
+
+@font-face {
+  font-family: "Cardo";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("https://fonts.gstatic.com/s/cardo/v21/wlp_gwjKBV1pqiv_.ttf") format("truetype");
+}
+
+@font-face {
+  font-family: "Cardo";
+  font-style: italic;
+  font-weight: 400;
+  font-display: swap;
+  src: url("https://fonts.gstatic.com/s/cardo/v21/wlpxgwjKBV1pqhv93IQ.ttf") format("truetype");
+}
+
+@font-face {
+  font-family: "Cardo";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("https://fonts.gstatic.com/s/cardo/v21/wlpygwjKBV1pqhND-aQR.ttf") format("truetype");
+}

package/dist/hooks/internal/useIsClient.d.ts

@@ -0,0 +1,2 @@
+/** @internal Whether this render is a client render after hydration. */
+export declare const useIsClient: () => boolean;

package/dist/hooks/internal/useIsClient.js

@@ -0,0 +1,14 @@
+import { useSyncExternalStore } from "react";
+//#region src/hooks/internal/useIsClient.ts
+/**
+* @internal `false` on the server and during hydration, `true` after (and on a plain client
+* render). Components that render something only a browser can (a portal, a lazily imported
+* module) return the server markup until this flips, so the hydrated tree matches the server's.
+*/
+var subscribeToNothing = () => () => {};
+var getClientSnapshot = () => true;
+var getServerSnapshot = () => false;
+/** @internal Whether this render is a client render after hydration. */
+var useIsClient = () => useSyncExternalStore(subscribeToNothing, getClientSnapshot, getServerSnapshot);
+//#endregion
+export { useIsClient };

package/dist/hooks/useClipboard.d.ts

@@ -0,0 +1,19 @@
+/** What `useClipboard` returns. */
+export interface UseClipboardReturn {
+    /** Writes `text` to the clipboard. Resolves `true` on success, `false` when the API is missing or refuses. */
+    copy: (text: string) => Promise<boolean>;
+    /** `true` for `timeoutMs` after a successful copy. */
+    hasCopied: boolean;
+}
+/**
+ * Copies text with `navigator.clipboard.writeText` and reports `hasCopied` for `timeoutMs` after
+ * a success. Each copy restarts the timer. There is no `execCommand` fallback.
+ *
+ * @param timeoutMs - How long `hasCopied` stays `true` after a success, in milliseconds (default `1500`)
+ * @returns `copy(text)` and `hasCopied`
+ *
+ * @example
+ * const { copy, hasCopied } = useClipboard();
+ * <Button icon={hasCopied ? Check : Copy} onClick={() => copy(apiKey)} ariaLabel="Copy" />
+ */
+export declare function useClipboard(timeoutMs?: number): UseClipboardReturn;

package/dist/hooks/useClipboard.js

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+//#region src/hooks/useClipboard.ts
+/**
+* Copies text with `navigator.clipboard.writeText` and reports `hasCopied` for `timeoutMs` after
+* a success. Each copy restarts the timer. There is no `execCommand` fallback.
+*
+* @param timeoutMs - How long `hasCopied` stays `true` after a success, in milliseconds (default `1500`)
+* @returns `copy(text)` and `hasCopied`
+*
+* @example
+* const { copy, hasCopied } = useClipboard();
+* <Button icon={hasCopied ? Check : Copy} onClick={() => copy(apiKey)} ariaLabel="Copy" />
+*/
+function useClipboard(timeoutMs = 1500) {
+	const [hasCopied, setHasCopied] = useState(false);
+	const timeoutRef = useRef(void 0);
+	const isMountedRef = useRef(false);
+	useEffect(() => {
+		isMountedRef.current = true;
+		return () => {
+			isMountedRef.current = false;
+			clearTimeout(timeoutRef.current);
+		};
+	}, []);
+	const copy = useCallback(async (text) => {
+		if (typeof navigator === "undefined" || typeof navigator.clipboard?.writeText !== "function") return false;
+		try {
+			await navigator.clipboard.writeText(text);
+		} catch {
+			return false;
+		}
+		if (isMountedRef.current) {
+			clearTimeout(timeoutRef.current);
+			setHasCopied(true);
+			timeoutRef.current = setTimeout(() => setHasCopied(false), timeoutMs);
+		}
+		return true;
+	}, [timeoutMs]);
+	return useMemo(() => ({
+		copy,
+		hasCopied
+	}), [copy, hasCopied]);
+}
+//#endregion
+export { useClipboard };

package/dist/hooks/useControlledOpenState.d.ts

@@ -0,0 +1,21 @@
+/** Options for `useControlledOpenState`; the `isOpen` / `defaultIsOpen` / `onOpenChange` triple (Constitution V). */
+export interface UseControlledOpenStateOptions {
+    /** Controlled open state. When not `undefined` the hook is controlled. */
+    isOpen?: boolean | undefined;
+    /** Initial open state while uncontrolled. @default false */
+    defaultIsOpen?: boolean | undefined;
+    /** Called with the next open state on every `setOpen`, controlled or not. */
+    onOpenChange?: ((isOpen: boolean) => void) | undefined;
+}
+/** What `useControlledOpenState` returns. */
+export interface ControlledOpenState {
+    /** Whether the overlay or disclosure is open. */
+    isOpen: boolean;
+    /** Request a new open state; calls `onOpenChange` and updates internal state while uncontrolled. */
+    setOpen: (isOpen: boolean) => void;
+}
+/**
+ * `useControlledState` for overlays and disclosures, named for readability. Returns
+ * `{ isOpen, setOpen }`.
+ */
+export declare function useControlledOpenState({ isOpen, defaultIsOpen, onOpenChange, }: UseControlledOpenStateOptions): ControlledOpenState;

package/dist/hooks/useControlledOpenState.js

@@ -0,0 +1,19 @@
+import { useControlledState } from "./useControlledState.js";
+//#region src/hooks/useControlledOpenState.ts
+/**
+* `useControlledState` for overlays and disclosures, named for readability. Returns
+* `{ isOpen, setOpen }`.
+*/
+function useControlledOpenState({ isOpen, defaultIsOpen = false, onOpenChange }) {
+	const [value, setOpen] = useControlledState({
+		value: isOpen,
+		defaultValue: defaultIsOpen,
+		onChange: onOpenChange
+	});
+	return {
+		isOpen: value,
+		setOpen
+	};
+}
+//#endregion
+export { useControlledOpenState };

package/dist/hooks/useControlledState.d.ts

@@ -0,0 +1,19 @@
+/** Options for `useControlledState`; the `value` / `defaultValue` / `onChange` triple (Constitution V). */
+export interface UseControlledStateOptions<T> {
+    /** Controlled value. When not `undefined` the hook is controlled; use `null`, not `undefined`, for "no value". */
+    value?: T | undefined;
+    /** Initial value while uncontrolled. */
+    defaultValue: T;
+    /** Called with the next value on every `setValue`, controlled or not. */
+    onChange?: ((value: T) => void) | undefined;
+}
+/**
+ * State that is controlled when `value` is passed and uncontrolled otherwise, like a native
+ * input. Returns `[value, setValue]`. `setValue(next)` always calls `onChange(next)` and updates
+ * internal state only while uncontrolled. There is no updater-function form: `onChange` receives
+ * the value (Constitution V).
+ *
+ * @example
+ * const [value, setValue] = useControlledState({ value: props.value, defaultValue: props.defaultValue ?? "", onChange: props.onChange });
+ */
+export declare function useControlledState<T>({ value, defaultValue, onChange, }: UseControlledStateOptions<T>): [value: T, setValue: (next: T) => void];

package/dist/hooks/useControlledState.js

@@ -0,0 +1,22 @@
+import { useCallback, useState } from "react";
+//#region src/hooks/useControlledState.ts
+/**
+* State that is controlled when `value` is passed and uncontrolled otherwise, like a native
+* input. Returns `[value, setValue]`. `setValue(next)` always calls `onChange(next)` and updates
+* internal state only while uncontrolled. There is no updater-function form: `onChange` receives
+* the value (Constitution V).
+*
+* @example
+* const [value, setValue] = useControlledState({ value: props.value, defaultValue: props.defaultValue ?? "", onChange: props.onChange });
+*/
+function useControlledState({ value, defaultValue, onChange }) {
+	const [internalValue, setInternalValue] = useState(defaultValue);
+	const isControlled = value !== void 0;
+	const setValue = useCallback((next) => {
+		if (!isControlled) setInternalValue(() => next);
+		onChange?.(next);
+	}, [isControlled, onChange]);
+	return [isControlled ? value : internalValue, setValue];
+}
+//#endregion
+export { useControlledState };

package/dist/hooks/useDebouncedValue.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns `value` once it has stopped changing for `delayMs`. Changing `delayMs` restarts the
+ * timer. While `isEnabled` is false the current `value` is returned immediately. SSR-safe: the
+ * timer runs in an effect, so the server renders the initial `value`.
+ *
+ * @param value - The value to debounce
+ * @param delayMs - Quiet period in milliseconds before the value is taken
+ * @param isEnabled - Whether to debounce at all (default `true`)
+ * @returns The debounced value
+ *
+ * @example
+ * const debouncedQuery = useDebouncedValue(query, 250);
+ */
+export declare function useDebouncedValue<T>(value: T, delayMs: number, isEnabled?: boolean): T;

package/dist/hooks/useDebouncedValue.js

@@ -0,0 +1,33 @@
+import { useEffect, useState } from "react";
+//#region src/hooks/useDebouncedValue.ts
+/**
+* Returns `value` once it has stopped changing for `delayMs`. Changing `delayMs` restarts the
+* timer. While `isEnabled` is false the current `value` is returned immediately. SSR-safe: the
+* timer runs in an effect, so the server renders the initial `value`.
+*
+* @param value - The value to debounce
+* @param delayMs - Quiet period in milliseconds before the value is taken
+* @param isEnabled - Whether to debounce at all (default `true`)
+* @returns The debounced value
+*
+* @example
+* const debouncedQuery = useDebouncedValue(query, 250);
+*/
+function useDebouncedValue(value, delayMs, isEnabled = true) {
+	const [debouncedValue, setDebouncedValue] = useState(value);
+	useEffect(() => {
+		if (!isEnabled) {
+			setDebouncedValue(() => value);
+			return;
+		}
+		const timeout = setTimeout(() => setDebouncedValue(() => value), delayMs);
+		return () => clearTimeout(timeout);
+	}, [
+		value,
+		delayMs,
+		isEnabled
+	]);
+	return isEnabled ? debouncedValue : value;
+}
+//#endregion
+export { useDebouncedValue };

package/dist/hooks/useDisclosure.d.ts

@@ -0,0 +1,26 @@
+/** What `useDisclosure` returns. Every function keeps a stable identity. */
+export interface UseDisclosureReturn {
+    /** Whether the disclosure is open. */
+    isOpen: boolean;
+    /** Opens it. */
+    open: () => void;
+    /** Closes it. */
+    close: () => void;
+    /** Flips it. */
+    toggle: () => void;
+    /** Sets it; fits an overlay's `onOpenChange` directly. */
+    setIsOpen: (isOpen: boolean) => void;
+}
+/**
+ * Open/closed state for a modal, drawer, popover or disclosure, with stable `open`, `close`,
+ * `toggle` and `setIsOpen`.
+ *
+ * @param defaultIsOpen - Whether it starts open (default `false`)
+ * @returns `isOpen` and the stable `open`, `close`, `toggle`, `setIsOpen`
+ *
+ * @example
+ * const { isOpen, open, setIsOpen } = useDisclosure();
+ * <Button onClick={open}>Edit</Button>
+ * <Modal isOpen={isOpen} onOpenChange={setIsOpen}>…</Modal>
+ */
+export declare function useDisclosure(defaultIsOpen?: boolean): UseDisclosureReturn;

package/dist/hooks/useDisclosure.js

@@ -0,0 +1,36 @@
+import { useCallback, useMemo, useState } from "react";
+//#region src/hooks/useDisclosure.ts
+/**
+* Open/closed state for a modal, drawer, popover or disclosure, with stable `open`, `close`,
+* `toggle` and `setIsOpen`.
+*
+* @param defaultIsOpen - Whether it starts open (default `false`)
+* @returns `isOpen` and the stable `open`, `close`, `toggle`, `setIsOpen`
+*
+* @example
+* const { isOpen, open, setIsOpen } = useDisclosure();
+* <Button onClick={open}>Edit</Button>
+* <Modal isOpen={isOpen} onOpenChange={setIsOpen}>…</Modal>
+*/
+function useDisclosure(defaultIsOpen = false) {
+	const [isOpen, setIsOpenState] = useState(defaultIsOpen);
+	const open = useCallback(() => setIsOpenState(true), []);
+	const close = useCallback(() => setIsOpenState(false), []);
+	const toggle = useCallback(() => setIsOpenState((previous) => !previous), []);
+	const setIsOpen = useCallback((next) => setIsOpenState(next), []);
+	return useMemo(() => ({
+		isOpen,
+		open,
+		close,
+		toggle,
+		setIsOpen
+	}), [
+		isOpen,
+		open,
+		close,
+		toggle,
+		setIsOpen
+	]);
+}
+//#endregion
+export { useDisclosure };

package/dist/hooks/useDismiss.d.ts

@@ -1,33 +1,29 @@
-import { RefObject } from "react";
+import { type RefObject } from "react";
+/** Options for `useDismiss`. */
 export interface UseDismissOptions {
-    /**
-     * Refs to exclude from click outside detection (e.g., dropdowns, tooltips)
-     */
-    excludeRefs?: RefObject<HTMLElement>[];
-    /**
-     * Whether to enable ESC key support
-     * @default true
-     */
-    enableEscape?: boolean;
-    /**
-     * Whether to enable click outside detection
-     * @default true
-     */
-    enableClickOutside?: boolean;
-    /**
-     * Whether the hook is enabled
-     * @default true
-     */
-    enabled?: boolean;
-    /**
-     * The function to call when the dismiss is triggered
-     */
+    /** Called when Escape is pressed or a mousedown lands outside the element (and outside `excludeRefs`). */
     onDismiss?: () => void;
+    /** Whether the hook listens at all; pass the overlay's `isOpen`. @default true */
+    isEnabled?: boolean;
+    /** Whether Escape dismisses. Ignored while focus is in an `input`, `textarea`, `select` or `[contenteditable]`. @default true */
+    shouldCloseOnEscape?: boolean;
+    /** Whether a mousedown outside the element dismisses. @default true */
+    shouldCloseOnOutsideClick?: boolean;
+    /** Elements that count as inside (e.g. a portalled dropdown or tooltip); clicks in them never dismiss. */
+    excludeRefs?: RefObject<HTMLElement | null>[];
 }
 /**
- * Closes a floating element on Escape or a click outside it. Returns the ref to
- * attach to the element you want to keep open.
+ * Dismisses an app-built floating element on Escape or on a mousedown outside it. Returns the ref
+ * to attach to the element that should stay open. DLS overlays (Popover, Modal, Drawer, Menu,
+ * Tooltip, Toast) dismiss themselves through the overlay stack and never need this hook.
  *
- * Accepts either a bare handler or an options object as the first argument.
+ * Every mounted `useDismiss` hears every Escape (its own `document` listener, no shortcut
+ * registry), except one an open DLS overlay has already consumed (the overlay stack calls
+ * `preventDefault()`; mount order decides which listener runs first). SSR-safe: listeners attach
+ * in effects only.
+ *
+ * @example
+ * const ref = useDismiss<HTMLDivElement>({ onDismiss: () => onOpenChange(false), isEnabled: isOpen });
+ * return <div ref={ref}>…</div>;
  */
-export declare const useDismiss: <T extends HTMLElement = HTMLElement>(handlerOrOptions: (() => void) | UseDismissOptions, options?: UseDismissOptions) => RefObject<T>;
+export declare function useDismiss<T extends HTMLElement = HTMLElement>({ onDismiss, isEnabled, shouldCloseOnEscape, shouldCloseOnOutsideClick, excludeRefs, }: UseDismissOptions): RefObject<T | null>;