@eocrm/design-system 0.6.24 → 0.7.0

package/dist/components/_internal/overlay/useOverlayStack.d.ts

@@ -0,0 +1,75 @@
+export type OverlayStackMode = 'replace' | 'overlay';
+declare function depthOf(id: string): number;
+/**
+ * Module-level singleton tracking open overlay ids in registration order.
+ * Each overlay (Modal, Drawer) calls `register` on open and `unregister` on close. Depth is
+ * the overlay's index in the open-stack (0 = bottom, length-1 = top).
+ * Subscribers are notified after every register/unregister so consumers
+ * can re-derive `isTop` / `depth` / `topMode`.
+ */
+export declare const overlayStack: {
+    /**
+     * Register this overlay. If already present, update its mode in place
+     * (handles a parent re-render where stackMode prop changed).
+     */
+    register(id: string, mode: OverlayStackMode): number;
+    unregister(id: string): void;
+    isTop(id: string): boolean;
+    topDepth(): number;
+    topMode(): OverlayStackMode | null;
+    depthOf: typeof depthOf;
+    /** Register an open floating surface (Escape-yield participant, #274). */
+    registerFloating(id: string): void;
+    unregisterFloating(id: string): void;
+    /** True while any floating surface is open — hosts yield Escape to it. */
+    hasOpenFloating(): boolean;
+    /** A closing surface marks its Escape so hosts yield even when the
+     *  surface's listener ran first (registration order is not stable). */
+    consumeEscape(e: Event): void;
+    wasEscapeConsumed(e: Event): boolean;
+    /**
+     * True iff `id` is the INNERMOST open floating surface — the last one
+     * registered (surfaces register on open, outer-first, so the most-recently-
+     * opened is innermost). On Escape every surface defers unless it's innermost,
+     * so one press closes exactly the deepest surface (#280). Order-independent of
+     * listener firing: it reads the registry, not the event. Returns false if `id`
+     * isn't registered (e.g. already closing).
+     *
+     * Only CONTAINER surfaces that can host a deeper one (Popover, Select,
+     * DropdownMenu) gate their Escape on this. Leaf surfaces (date-time grids, the
+     * Rail flyout, RTE menus) are always innermost when nested and intentionally
+     * omit the guard — add it if a leaf ever hosts a Select/Popover/menu, or one
+     * Escape will wrongly close both.
+     */
+    isTopFloating(id: string): boolean;
+    /** Subscribe to register/unregister notifications. Returns unsubscribe. */
+    _subscribe(fn: () => void): () => void;
+    /** Test-only escape hatch. */
+    _reset(): void;
+};
+export interface OverlayStackState {
+    /** Current depth in the stack, or null if not registered. */
+    depth: number | null;
+    /** True iff this overlay is the topmost open overlay. */
+    isTop: boolean;
+    /** Mode of the current top overlay (null if stack is empty). */
+    topMode: OverlayStackMode | null;
+}
+/**
+ * Register/unregister this overlay in the singleton stack while `active` is
+ * true. Returns the current depth, whether this overlay is on top, and the
+ * top overlay's stackMode. Subscribes to stack mutations so state stays
+ * accurate when sibling overlays open/close.
+ */
+export declare function useOverlayStack(id: string, active: boolean, mode: OverlayStackMode): OverlayStackState;
+/**
+ * Register this floating surface in the Escape-yield registry while `open`
+ * (#274). Hosts (Modal/Drawer/Lightbox) skip their Escape-close while any
+ * surface is registered, so the surface's own Escape handling — a document-
+ * capture listener for most surfaces, an element-scoped handler for the
+ * editor-owned menus (Liquid autocomplete, RTE mentions) — closes it instead;
+ * the next press reaches the host. Layout effect: the registration must be
+ * observable before the browser can deliver the next keydown.
+ */
+export declare function useFloatingSurface(open: boolean): string;
+export {};

package/dist/components/_internal/overlay/useOverlayStack.js

@@ -0,0 +1,184 @@
+'use client';
+import { useId, useLayoutEffect, useState } from "react";
+// src/components/_internal/overlay/useOverlayStack.ts
+var stack = [];
+var listeners = /* @__PURE__ */ new Set();
+var floating = /* @__PURE__ */ new Set();
+var consumedEscapes = /* @__PURE__ */ new WeakSet();
+function notify() {
+	for (const fn of listeners) fn();
+}
+function indexOf(id) {
+	return stack.findIndex((e) => e.id === id);
+}
+function depthOf(id) {
+	return indexOf(id);
+}
+function topEntry() {
+	return stack.length === 0 ? null : stack[stack.length - 1];
+}
+/**
+* Module-level singleton tracking open overlay ids in registration order.
+* Each overlay (Modal, Drawer) calls `register` on open and `unregister` on close. Depth is
+* the overlay's index in the open-stack (0 = bottom, length-1 = top).
+* Subscribers are notified after every register/unregister so consumers
+* can re-derive `isTop` / `depth` / `topMode`.
+*/
+var overlayStack = {
+	/**
+	* Register this overlay. If already present, update its mode in place
+	* (handles a parent re-render where stackMode prop changed).
+	*/
+	register(id, mode) {
+		const idx = indexOf(id);
+		if (idx === -1) stack.push({
+			id,
+			mode
+		});
+		else stack[idx].mode = mode;
+		notify();
+		return depthOf(id);
+	},
+	unregister(id) {
+		const idx = indexOf(id);
+		if (idx >= 0) {
+			stack.splice(idx, 1);
+			notify();
+		}
+	},
+	isTop(id) {
+		return topEntry()?.id === id;
+	},
+	topDepth() {
+		return stack.length;
+	},
+	topMode() {
+		return topEntry()?.mode ?? null;
+	},
+	depthOf,
+	/** Register an open floating surface (Escape-yield participant, #274). */
+	registerFloating(id) {
+		floating.add(id);
+	},
+	unregisterFloating(id) {
+		floating.delete(id);
+	},
+	/** True while any floating surface is open — hosts yield Escape to it. */
+	hasOpenFloating() {
+		return floating.size > 0;
+	},
+	/** A closing surface marks its Escape so hosts yield even when the
+	*  surface's listener ran first (registration order is not stable). */
+	consumeEscape(e) {
+		consumedEscapes.add(e);
+	},
+	wasEscapeConsumed(e) {
+		return consumedEscapes.has(e);
+	},
+	/**
+	* True iff `id` is the INNERMOST open floating surface — the last one
+	* registered (surfaces register on open, outer-first, so the most-recently-
+	* opened is innermost). On Escape every surface defers unless it's innermost,
+	* so one press closes exactly the deepest surface (#280). Order-independent of
+	* listener firing: it reads the registry, not the event. Returns false if `id`
+	* isn't registered (e.g. already closing).
+	*
+	* Only CONTAINER surfaces that can host a deeper one (Popover, Select,
+	* DropdownMenu) gate their Escape on this. Leaf surfaces (date-time grids, the
+	* Rail flyout, RTE menus) are always innermost when nested and intentionally
+	* omit the guard — add it if a leaf ever hosts a Select/Popover/menu, or one
+	* Escape will wrongly close both.
+	*/
+	isTopFloating(id) {
+		let last;
+		for (const x of floating) last = x;
+		return last === id;
+	},
+	/** Subscribe to register/unregister notifications. Returns unsubscribe. */
+	_subscribe(fn) {
+		listeners.add(fn);
+		return () => {
+			listeners.delete(fn);
+		};
+	},
+	/** Test-only escape hatch. */
+	_reset() {
+		stack.length = 0;
+		listeners.clear();
+		floating.clear();
+	}
+};
+/**
+* Register/unregister this overlay in the singleton stack while `active` is
+* true. Returns the current depth, whether this overlay is on top, and the
+* top overlay's stackMode. Subscribes to stack mutations so state stays
+* accurate when sibling overlays open/close.
+*/
+function useOverlayStack(id, active, mode) {
+	const [state, setState] = useState(() => {
+		if (!active) return {
+			depth: null,
+			isTop: false,
+			topMode: null
+		};
+		return {
+			depth: overlayStack.topDepth(),
+			isTop: true,
+			topMode: mode
+		};
+	});
+	useLayoutEffect(() => {
+		if (!active) {
+			setState({
+				depth: null,
+				isTop: false,
+				topMode: null
+			});
+			return;
+		}
+		overlayStack.register(id, mode);
+		const sync = () => {
+			setState({
+				depth: overlayStack.depthOf(id),
+				isTop: overlayStack.isTop(id),
+				topMode: overlayStack.topMode()
+			});
+		};
+		sync();
+		const unsubscribe = overlayStack._subscribe(sync);
+		return () => {
+			unsubscribe();
+			overlayStack.unregister(id);
+		};
+	}, [id, active]);
+	useLayoutEffect(() => {
+		if (!active) return;
+		overlayStack.register(id, mode);
+	}, [
+		id,
+		active,
+		mode
+	]);
+	return state;
+}
+/**
+* Register this floating surface in the Escape-yield registry while `open`
+* (#274). Hosts (Modal/Drawer/Lightbox) skip their Escape-close while any
+* surface is registered, so the surface's own Escape handling — a document-
+* capture listener for most surfaces, an element-scoped handler for the
+* editor-owned menus (Liquid autocomplete, RTE mentions) — closes it instead;
+* the next press reaches the host. Layout effect: the registration must be
+* observable before the browser can deliver the next keydown.
+*/
+function useFloatingSurface(open) {
+	const id = useId();
+	useLayoutEffect(() => {
+		if (!open) return;
+		overlayStack.registerFloating(id);
+		return () => {
+			overlayStack.unregisterFloating(id);
+		};
+	}, [id, open]);
+	return id;
+}
+export { overlayStack, useFloatingSurface, useOverlayStack };

package/dist/components/_internal/overlay/useScrollLock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Body scroll lock. Ref-counted across all callers so nested modals share
+ * the same lock — the first acquire suppresses scrolling, the last release
+ * restores it.
+ *
+ * Pins `body` to `position: fixed` with `top: -<scrollY>px` and
+ * `left: -<scrollX>px` so the user's visual scroll position is preserved
+ * while the body is locked. On unlock, the saved offsets are read back from
+ * body's inline styles and `scrollTo` returns the page to where the user
+ * left it. `overflow: hidden` on html is intentionally NOT used here
+ * because it clamps `scrollTop` to 0 and jumps the page to the top.
+ */
+export declare function useScrollLock(active: boolean): void;

package/dist/components/_internal/overlay/useScrollLock.js

@@ -0,0 +1,83 @@
+'use client';
+import { useLayoutEffect } from "react";
+// src/components/_internal/overlay/useScrollLock.ts
+var count = 0;
+var originalPosition = null;
+var originalTop = null;
+var originalLeft = null;
+var originalWidth = null;
+var originalPaddingRight = null;
+var rAFHandle = null;
+function lock() {
+	if (rAFHandle !== null) {
+		cancelAnimationFrame(rAFHandle);
+		rAFHandle = null;
+	}
+	if (count === 0) {
+		const scrollY = window.scrollY;
+		const scrollX = window.scrollX;
+		originalPosition = document.body.style.position;
+		originalTop = document.body.style.top;
+		originalLeft = document.body.style.left;
+		originalWidth = document.body.style.width;
+		originalPaddingRight = document.body.style.paddingRight;
+		const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+		if (scrollbarWidth > 0) document.body.style.paddingRight = `${scrollbarWidth}px`;
+		document.body.style.position = "fixed";
+		document.body.style.top = `-${scrollY}px`;
+		document.body.style.left = `-${scrollX}px`;
+		document.body.style.width = "100%";
+	}
+	count += 1;
+}
+function unlock() {
+	count = Math.max(0, count - 1);
+	if (count === 0) {
+		const savedY = -parseFloat(document.body.style.top || "0");
+		const savedX = -parseFloat(document.body.style.left || "0");
+		document.body.style.position = originalPosition ?? "";
+		document.body.style.top = originalTop ?? "";
+		document.body.style.left = originalLeft ?? "";
+		document.body.style.width = originalWidth ?? "";
+		document.body.style.paddingRight = originalPaddingRight ?? "";
+		originalPosition = null;
+		originalTop = null;
+		originalLeft = null;
+		originalWidth = null;
+		originalPaddingRight = null;
+		document.body.offsetHeight;
+		window.scrollTo({
+			left: savedX,
+			top: savedY,
+			behavior: "instant"
+		});
+		rAFHandle = requestAnimationFrame(() => {
+			rAFHandle = null;
+			window.scrollTo({
+				left: savedX,
+				top: savedY,
+				behavior: "instant"
+			});
+		});
+	}
+}
+/**
+* Body scroll lock. Ref-counted across all callers so nested modals share
+* the same lock — the first acquire suppresses scrolling, the last release
+* restores it.
+*
+* Pins `body` to `position: fixed` with `top: -<scrollY>px` and
+* `left: -<scrollX>px` so the user's visual scroll position is preserved
+* while the body is locked. On unlock, the saved offsets are read back from
+* body's inline styles and `scrollTo` returns the page to where the user
+* left it. `overflow: hidden` on html is intentionally NOT used here
+* because it clamps `scrollTop` to 0 and jumps the page to the top.
+*/
+function useScrollLock(active) {
+	useLayoutEffect(() => {
+		if (!active) return;
+		lock();
+		return unlock;
+	}, [active]);
+}
+export { useScrollLock };

package/dist/components/_internal/refs.d.ts

@@ -0,0 +1,25 @@
+import type { Ref } from 'react';
+/**
+ * Merge multiple refs into one. Each provided ref (callback or object) is set
+ * to the same value. Used by components that clone a child element and want
+ * to attach an internal ref alongside the consumer's own ref.
+ */
+export declare function mergeRefs<T>(...refs: Array<Ref<T> | undefined | null>): Ref<T>;
+/**
+ * Chain event handlers. Each provided handler runs in order with the same
+ * event. Used when a cloned element already has an `onX` and the wrapping
+ * component needs to add its own without overwriting.
+ */
+export declare function chain<E>(...fns: Array<((event: E) => void) | undefined>): (event: E) => void;
+/**
+ * Convert React's `useId()` output into a value safe to interpolate into a
+ * CSS-style id or class. Replaces every char that isn't `[A-Za-z0-9_-]` with
+ * an underscore.
+ */
+export declare function sanitizeId(raw: string): string;
+/**
+ * Merge a consumer-supplied `aria-describedby` with an additional id, keeping
+ * the consumer's value first and de-duplicating. Returns the additional id
+ * alone when the consumer didn't provide one.
+ */
+export declare function mergeAriaDescribedby(consumer: string | undefined, extra: string): string;

package/dist/components/_internal/refs.js

@@ -0,0 +1,45 @@
+// src/components/_internal/refs.ts
+/**
+* Merge multiple refs into one. Each provided ref (callback or object) is set
+* to the same value. Used by components that clone a child element and want
+* to attach an internal ref alongside the consumer's own ref.
+*/
+function mergeRefs(...refs) {
+	return (value) => {
+		for (const ref of refs) {
+			if (!ref) continue;
+			if (typeof ref === "function") ref(value);
+			else ref.current = value;
+		}
+	};
+}
+/**
+* Chain event handlers. Each provided handler runs in order with the same
+* event. Used when a cloned element already has an `onX` and the wrapping
+* component needs to add its own without overwriting.
+*/
+function chain(...fns) {
+	return (event) => {
+		for (const fn of fns) fn?.(event);
+	};
+}
+/**
+* Convert React's `useId()` output into a value safe to interpolate into a
+* CSS-style id or class. Replaces every char that isn't `[A-Za-z0-9_-]` with
+* an underscore.
+*/
+function sanitizeId(raw) {
+	return raw.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/**
+* Merge a consumer-supplied `aria-describedby` with an additional id, keeping
+* the consumer's value first and de-duplicating. Returns the additional id
+* alone when the consumer didn't provide one.
+*/
+function mergeAriaDescribedby(consumer, extra) {
+	if (!consumer) return extra;
+	const tokens = consumer.split(/\s+/).filter(Boolean);
+	if (tokens.includes(extra)) return consumer;
+	return [...tokens, extra].join(" ");
+}
+export { chain, mergeAriaDescribedby, mergeRefs, sanitizeId };

package/dist/components/_internal/statusColor.d.ts

@@ -0,0 +1,14 @@
+import { type PaletteColor } from '../../palette/index.js';
+/**
+ * Workflow status category — maps to a default palette color. Shared by
+ * `PillMenu` and `EntityChip` so both resolve the same category → color
+ * mapping.
+ */
+export type StatusCategory = 'to_do' | 'in_progress' | 'open' | 'done' | 'won' | 'lost';
+/** Category → default palette color: to_do slate / in_progress blue / open violet / done green / won green / lost red. */
+export declare const STATUS_CATEGORY_COLOR: Record<StatusCategory, PaletteColor>;
+/** `color` wins; otherwise fall back to the category's default; otherwise slate. */
+export declare function resolveStatusColor(status: {
+    category?: StatusCategory;
+    color?: PaletteColor;
+}): PaletteColor;

package/dist/components/_internal/statusColor.js

@@ -0,0 +1,15 @@
+// src/components/_internal/statusColor.ts
+/** Category → default palette color: to_do slate / in_progress blue / open violet / done green / won green / lost red. */
+var STATUS_CATEGORY_COLOR = {
+	to_do: "slate",
+	in_progress: "blue",
+	open: "violet",
+	done: "green",
+	won: "green",
+	lost: "red"
+};
+/** `color` wins; otherwise fall back to the category's default; otherwise slate. */
+function resolveStatusColor(status) {
+	return status.color ?? (status.category && STATUS_CATEGORY_COLOR[status.category]) ?? "slate";
+}
+export { STATUS_CATEGORY_COLOR, resolveStatusColor };

package/dist/components/_internal/timeUtils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Re-export shim for the time-of-day utilities that live in
+ * `components/DatePicker/utils.ts`. `<TimeField>` lives at
+ * `components/TimeField/` and needs these helpers, but importing them
+ * via `'../DatePicker/utils'` would trick `scripts/generate-manifest.mjs`
+ * into recording a `TimeField → DatePicker` edge in the manifest's
+ * dependency graph — which is wrong (TimeField does not consume the
+ * DatePicker component, only its sibling utility module) and would
+ * introduce a cycle (DatePicker → TimeField → DatePicker).
+ *
+ * The manifest generator's parent-path regex captures only directory
+ * names that start with an uppercase letter, so this `_internal`
+ * detour is invisible to it. Update both modules if the utility
+ * surface changes.
+ */
+export { formatTime, parseTime, resolveHourCycle, roundTimeToStep, type HourCycle, type TimeValue, } from '../DatePicker/utils.js';

package/dist/components/_internal/useAsyncOptions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Args accepted by `useAsyncOptions`.
+ *
+ * `loadOptions` is the consumer-supplied fetcher; the hook is a no-op when
+ * it's `undefined`. `query` and `enabled` drive when fetches happen:
+ * `enabled` gates the very first request (the `loadOnOpen` semantic — wait
+ * until the popover opens), `query` is what gets debounced and passed to
+ * each call. `debounceMs` is the delay between the last `query` change and
+ * the actual `loadOptions` invocation.
+ */
+export interface UseAsyncOptionsArgs<R extends readonly unknown[]> {
+    /** Async fetcher. Receives the current query and an `AbortSignal`. */
+    loadOptions?: (query: string, signal: AbortSignal) => Promise<R>;
+    /** Current search query string. Empty string is a valid fetch trigger. */
+    query: string;
+    /**
+     * When `false`, no fetches happen (going `false` aborts the in-flight one).
+     * Select wires it to "has the popover ever opened"; OptionsPicker to "is
+     * the panel open now" (a fresh fetch per open).
+     */
+    enabled: boolean;
+    /** Debounce window before firing `loadOptions` after a query change. */
+    debounceMs: number;
+}
+/**
+ * Return value of `useAsyncOptions`.
+ *
+ * `options` is `[]` until the first successful fetch resolves. `loading` is
+ * `true` while a request is in flight (but flips back to `false` on abort
+ * too — the next request's `loading=true` takes over immediately). `error`
+ * is set on non-abort rejections and cleared at the start of each new
+ * fetch. `retry()` re-runs the current query (no debounce).
+ */
+export interface UseAsyncOptionsReturn<R extends readonly unknown[]> {
+    options: R;
+    loading: boolean;
+    error: Error | null;
+    /** The query `options` belongs to; `null` until the first request settles. */
+    loadedQuery: string | null;
+    retry: () => void;
+}
+/**
+ * Hook that wraps an async `loadOptions(query, signal)` into a state-row
+ * friendly shape (options/loading/error + retry). Handles three concerns
+ * the Select would otherwise reinvent:
+ *
+ * 1. Debouncing — collapses keystroke bursts into one request.
+ * 2. Cancellation — aborts the in-flight request when a new one starts, so
+ *    a slow response from query "ab" can't overwrite a fresh result for
+ *    "abc".
+ * 3. Lifecycle — aborts on unmount.
+ *
+ * The hook is gated by `enabled`: while it is false no fetches fire. Select
+ * passes "has opened at least once" (its `loadOnOpen` semantic); OptionsPicker
+ * passes "is open now", so every open refetches. Shared by both — not
+ * exported from the package root.
+ */
+export declare function useAsyncOptions<R extends readonly unknown[]>(args: UseAsyncOptionsArgs<R>): UseAsyncOptionsReturn<R>;

package/dist/components/_internal/useAsyncOptions.js

@@ -0,0 +1,86 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from "react";
+// src/components/_internal/useAsyncOptions.ts
+/**
+* Hook that wraps an async `loadOptions(query, signal)` into a state-row
+* friendly shape (options/loading/error + retry). Handles three concerns
+* the Select would otherwise reinvent:
+*
+* 1. Debouncing — collapses keystroke bursts into one request.
+* 2. Cancellation — aborts the in-flight request when a new one starts, so
+*    a slow response from query "ab" can't overwrite a fresh result for
+*    "abc".
+* 3. Lifecycle — aborts on unmount.
+*
+* The hook is gated by `enabled`: while it is false no fetches fire. Select
+* passes "has opened at least once" (its `loadOnOpen` semantic); OptionsPicker
+* passes "is open now", so every open refetches. Shared by both — not
+* exported from the package root.
+*/
+function useAsyncOptions(args) {
+	const { loadOptions, query, enabled, debounceMs } = args;
+	const [options, setOptions] = useState([]);
+	const [loading, setLoading] = useState(false);
+	const [loadedQuery, setLoadedQuery] = useState(null);
+	const [error, setError] = useState(null);
+	const [retryToken, setRetryToken] = useState(0);
+	const debounceTimerRef = useRef(null);
+	const abortRef = useRef(null);
+	const runFetch = useCallback((q) => {
+		if (!loadOptions) return;
+		if (abortRef.current) abortRef.current.abort();
+		const ac = new AbortController();
+		abortRef.current = ac;
+		setLoading(true);
+		setError(null);
+		loadOptions(q, ac.signal).then((next) => {
+			if (ac.signal.aborted) return;
+			setOptions(next);
+			setLoadedQuery(q);
+			setLoading(false);
+		}).catch((err) => {
+			if (ac.signal.aborted) return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+			setLoadedQuery(q);
+			setLoading(false);
+		});
+	}, [loadOptions]);
+	useEffect(() => {
+		if (!enabled || !loadOptions) return;
+		if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
+		debounceTimerRef.current = setTimeout(() => {
+			runFetch(query);
+		}, debounceMs);
+		return () => {
+			if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
+		};
+	}, [
+		query,
+		enabled,
+		debounceMs,
+		retryToken,
+		runFetch,
+		loadOptions
+	]);
+	useEffect(() => {
+		if (enabled) return;
+		abortRef.current?.abort();
+		abortRef.current = null;
+		setLoading(false);
+	}, [enabled]);
+	useEffect(() => {
+		return () => {
+			if (abortRef.current) abortRef.current.abort();
+		};
+	}, []);
+	return {
+		options,
+		loading,
+		error,
+		retry: useCallback(() => {
+			setRetryToken((n) => n + 1);
+		}, []),
+		loadedQuery
+	};
+}
+export { useAsyncOptions };

package/dist/components/_internal/useClippedTooltip.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode, type RefObject } from 'react';
+export interface ClippedTooltip<T extends HTMLElement> {
+    /** Attach to the element whose text may be clipped by an ellipsis. */
+    ref: RefObject<T | null>;
+    /** Pass to `<Tooltip open>`. */
+    open: boolean;
+    /** Pass to `<Tooltip onOpenChange>`; refuses to open unless the label overflows. */
+    onOpenChange: (next: boolean) => void;
+    /** Pass to `<Tooltip content>`. */
+    content: ReactNode;
+}
+/**
+ * State for a controlled `Tooltip` that shows a label's full text only when the
+ * label is actually clipped. A fully visible label gets no tooltip and no
+ * `aria-describedby`, so it is not announced twice.
+ *
+ * `content`: a STRING `label` is used directly, so it is always fresh off the
+ * prop, even if it changes while the tooltip is open. Any other `label` (styled
+ * node, icon, …) falls back to plain text captured from the element's
+ * `textContent` when the tooltip opens, so a styled label's colour and weight
+ * don't leak onto the dark tooltip background.
+ *
+ * The captured text falls back to `label` with `||`, not `??`: Tooltip treats
+ * `null`/`undefined`/`''` content as "disabled" (no listeners at all), so an
+ * EMPTY capture (a label that renders no text, e.g. an icon) is stored as
+ * `null` and must resolve back to the current `label`. Otherwise the tooltip
+ * would stay disabled even after `label` becomes a long, clipped string (#592).
+ *
+ * `enabled`: pass `false` while the caller renders no Tooltip (e.g. a loading
+ * state). An open tooltip that unmounts has nothing left to close it, so the
+ * state resets during render and cannot remount already open.
+ */
+export declare function useClippedTooltip<T extends HTMLElement>(label: ReactNode, enabled?: boolean): ClippedTooltip<T>;