@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/_internal/overlay/useOverlayStack.ts

@@ -0,0 +1,232 @@
+import { useId, useLayoutEffect, useState } from 'react';
+
+export type OverlayStackMode = 'replace' | 'overlay';
+
+interface Entry {
+  id: string;
+  mode: OverlayStackMode;
+}
+
+// Internal ordered list of open overlay entries, most-recently-registered last.
+const stack: Entry[] = [];
+const listeners = new Set<() => void>();
+const floating = new Set<string>();
+// Escape events already handled (surface closed on them). Order-independent
+// complement to the registry: a re-render can re-register a surface's
+// document-capture listener AHEAD of its host's (effects re-fire child-
+// first), so the surface may close + unregister within the same press —
+// the host must still yield to a consumed event. WeakSet: no leaks.
+const consumedEscapes = new WeakSet<Event>();
+
+// Open floating surfaces (Select listbox, Popover, DropdownMenu levels,
+// date/time popovers, Rail flyout). Hosts' Escape handlers yield while any
+// is open so a single press closes the innermost surface, not the host too
+// (#274). A Set of ids — hosts only need "is anything open". Surface-vs-
+// surface ordering is NOT guaranteed here (a Select inside a Popover still
+// closes with it on one press); only two hardcoded pairs defer today:
+// DropdownMenu sub->parent and TimeField clock->calendar. See #280. The
+// registry is also global, not host-scoped: any host yields to any open
+// surface, even one belonging to a lower overlay — rare but reachable (e.g.
+// a modal opened from a control inside a Popover: the popover dismisses only
+// on outside pointerdown, so it stays open and registered underneath, and
+// the modal's first Escape press yields to it).
+
+function notify() {
+  for (const fn of listeners) fn();
+}
+
+function indexOf(id: string): number {
+  return stack.findIndex((e) => e.id === id);
+}
+
+function depthOf(id: string): number {
+  return indexOf(id);
+}
+
+function topEntry(): Entry | null {
+  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`.
+ */
+export 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 {
+    const idx = indexOf(id);
+    if (idx === -1) {
+      stack.push({ id, mode });
+    } else {
+      stack[idx]!.mode = mode;
+    }
+    notify();
+    return depthOf(id);
+  },
+  unregister(id: string): void {
+    const idx = indexOf(id);
+    if (idx >= 0) {
+      stack.splice(idx, 1);
+      notify();
+    }
+  },
+  isTop(id: string): boolean {
+    return topEntry()?.id === id;
+  },
+  topDepth(): number {
+    return stack.length;
+  },
+  topMode(): OverlayStackMode | null {
+    return topEntry()?.mode ?? null;
+  },
+  depthOf,
+  /** Register an open floating surface (Escape-yield participant, #274). */
+  registerFloating(id: string): void {
+    floating.add(id);
+  },
+  unregisterFloating(id: string): void {
+    floating.delete(id);
+  },
+  /** True while any floating surface is open — hosts yield Escape to it. */
+  hasOpenFloating(): boolean {
+    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: Event): void {
+    consumedEscapes.add(e);
+  },
+  wasEscapeConsumed(e: Event): boolean {
+    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: string): boolean {
+    let last: string | undefined;
+    for (const x of floating) last = x; // Set preserves insertion (open) order
+    return last === id;
+  },
+  /** Subscribe to register/unregister notifications. Returns unsubscribe. */
+  _subscribe(fn: () => void): () => void {
+    listeners.add(fn);
+    return () => {
+      listeners.delete(fn);
+    };
+  },
+  /** Test-only escape hatch. */
+  _reset(): void {
+    stack.length = 0;
+    listeners.clear();
+    floating.clear();
+  },
+};
+
+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 function useOverlayStack(
+  id: string,
+  active: boolean,
+  mode: OverlayStackMode,
+): OverlayStackState {
+  // Lazy initializer pre-computes the post-registration state so the FIRST
+  // render of an opened overlay already has correct `topMode` / `isTop` /
+  // `depth`. Without this, paint and stack-position attributes would be
+  // wrong on the first paint (transparent overlay flash, etc.). The actual
+  // register() still happens in useLayoutEffect; this is read-only.
+  const [state, setState] = useState<OverlayStackState>(() => {
+    if (!active) return { depth: null, isTop: false, topMode: null };
+    return {
+      depth: overlayStack.topDepth(),
+      isTop: true,
+      topMode: mode,
+    };
+  });
+
+  // useLayoutEffect (not useEffect) so registration + state sync happen
+  // synchronously after commit, before the browser paints. Prevents a
+  // one-frame flash of the wrong overlay attributes.
+  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);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mode handled by separate effect below to avoid tear-down on mode change
+  }, [id, active]);
+
+  // Update mode in place without tearing down the entry. overlayStack.register
+  // handles existing entries by updating their mode and re-notifying.
+  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.
+ */
+export function useFloatingSurface(open: boolean): string {
+  const id = useId();
+  useLayoutEffect(() => {
+    if (!open) return;
+    overlayStack.registerFloating(id);
+    return () => {
+      overlayStack.unregisterFloating(id);
+    };
+  }, [id, open]);
+  // Returned so a surface can gate its Escape handler on `isTopFloating(id)` and
+  // defer to a deeper surface (#280). Stable across renders (useId).
+  return id;
+}

package/src/components/_internal/overlay/useScrollLock.ts

@@ -0,0 +1,112 @@
+import { useLayoutEffect } from 'react';
+
+// Module-level state shared across all useScrollLock callers.
+let count = 0;
+let originalPosition: string | null = null;
+let originalTop: string | null = null;
+let originalLeft: string | null = null;
+let originalWidth: string | null = null;
+let originalPaddingRight: string | null = null;
+let rAFHandle: number | null = null;
+
+function lock() {
+  // Cancel any pending unlock rAF — if a new modal opens before the
+  // previous unlock's rAF fired, we don't want the deferred scrollTo
+  // to fire after the new lock has set body.style.top.
+  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;
+
+    // Scrollbar-width compensation: body becomes position:fixed, the html
+    // scrollbar disappears, and content would otherwise reflow horizontally
+    // into the freed space. Padding on body absorbs that shift.
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+    if (scrollbarWidth > 0) {
+      document.body.style.paddingRight = `${scrollbarWidth}px`;
+    }
+
+    // Fix the body in place at the user's current visual scroll position.
+    // top: -<scrollY>px keeps the content visually where it was; the body
+    // is now out of flow so no scrolling is possible. This avoids the
+    // scroll-to-top jump that `overflow: hidden` causes on the html element
+    // (overflow:hidden clamps scrollTop to 0).
+    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) {
+    // Read saved scroll position from the body's top/left offset BEFORE
+    // restoring, so we can scroll back to exactly where we were.
+    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;
+
+    // Force a synchronous reflow so the document's scrollable height is
+    // recalculated from the now-restored body BEFORE we scrollTo. Without
+    // this, the browser can clamp scrollTo to maxScrollY = 0 (the height
+    // while body was still fixed) and the page jumps to the top.
+    void document.body.offsetHeight;
+
+    // `behavior: 'instant'` bypasses any smooth-scroll preference and forces
+    // a single-frame jump. Without it, an animated scroll could be
+    // interrupted by post-unlock reflow (focus restoration) and land at an
+    // intermediate position.
+    window.scrollTo({ left: savedX, top: savedY, behavior: 'instant' });
+
+    // Belt-and-braces: re-issue on the next frame in case the synchronous
+    // call was clamped because the layout pipeline hadn't yet committed.
+    // No-op when the first call already succeeded. The handle is tracked so
+    // lock() can cancel this if a new modal opens before the frame fires.
+    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.
+ */
+export function useScrollLock(active: boolean): void {
+  useLayoutEffect(() => {
+    if (!active) return;
+    lock();
+    return unlock;
+  }, [active]);
+}

package/src/components/_internal/refs.ts

@@ -0,0 +1,48 @@
+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 function mergeRefs<T>(...refs: Array<Ref<T> | undefined | null>): Ref<T> {
+  return (value: T | null) => {
+    for (const ref of refs) {
+      if (!ref) continue;
+      if (typeof ref === 'function') ref(value);
+      else (ref as React.MutableRefObject<T | null>).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.
+ */
+export function chain<E>(...fns: Array<((event: E) => void) | undefined>): (event: E) => void {
+  return (event: E) => {
+    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.
+ */
+export function sanitizeId(raw: string): string {
+  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.
+ */
+export function mergeAriaDescribedby(consumer: string | undefined, extra: string): string {
+  if (!consumer) return extra;
+  const tokens = consumer.split(/\s+/).filter(Boolean);
+  if (tokens.includes(extra)) return consumer;
+  return [...tokens, extra].join(' ');
+}

package/src/components/_internal/statusColor.ts

@@ -0,0 +1,26 @@
+import { type PaletteColor } from '../../palette';
+
+/**
+ * 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 const STATUS_CATEGORY_COLOR: Record<StatusCategory, PaletteColor> = {
+  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. */
+export function resolveStatusColor(status: {
+  category?: StatusCategory;
+  color?: PaletteColor;
+}): PaletteColor {
+  return status.color ?? (status.category && STATUS_CATEGORY_COLOR[status.category]) ?? 'slate';
+}

package/src/components/_internal/timeUtils.ts

@@ -0,0 +1,23 @@
+/**
+ * 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';

package/src/components/_internal/useAsyncOptions.ts

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * 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 function useAsyncOptions<R extends readonly unknown[]>(
+  args: UseAsyncOptionsArgs<R>,
+): UseAsyncOptionsReturn<R> {
+  const { loadOptions, query, enabled, debounceMs } = args;
+
+  const [options, setOptions] = useState<R>([] as unknown as R);
+  const [loading, setLoading] = useState<boolean>(false);
+  // The query `options` actually belongs to, or null before the first settle.
+  // Callers cannot infer this from `loading`: it is false for the whole
+  // debounce window, during which `options` is still the PREVIOUS query's.
+  const [loadedQuery, setLoadedQuery] = useState<string | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [retryToken, setRetryToken] = useState<number>(0);
+
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  // `runFetch` aborts any in-flight request before starting a new one, so a
+  // slow response can never overwrite a fresher one. `signal.aborted` is
+  // checked again on both resolution paths to handle the race where the
+  // abort fires AFTER the network call resolved but BEFORE React processes
+  // the `.then`.
+  const runFetch = useCallback(
+    (q: string) => {
+      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],
+  );
+
+  // Debounced trigger: any time `query`, `enabled`, or the retry token
+  // changes, queue a fetch `debounceMs` later. The cleanup clears the
+  // pending timer so rapid changes collapse to a single fetch.
+  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]);
+
+  // Disabled (OptionsPicker closing) aborts the in-flight request: its answer
+  // has no reader. Select's gate never returns to false.
+  useEffect(() => {
+    if (enabled) return;
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setLoading(false);
+  }, [enabled]);
+
+  // Abort on unmount so a still-in-flight request can't write into a
+  // dead component.
+  useEffect(() => {
+    return () => {
+      if (abortRef.current) abortRef.current.abort();
+    };
+  }, []);
+
+  const retry = useCallback(() => {
+    setRetryToken((n) => n + 1);
+  }, []);
+
+  return { options, loading, error, retry, loadedQuery };
+}

package/src/components/_internal/useClippedTooltip.ts

@@ -0,0 +1,50 @@
+import { useRef, useState, 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 function useClippedTooltip<T extends HTMLElement>(
+  label: ReactNode,
+  enabled = true,
+): ClippedTooltip<T> {
+  const ref = useRef<T>(null);
+  const [open, setOpen] = useState(false);
+  const [text, setText] = useState<string | null>(null);
+  if (!enabled && open) setOpen(false);
+  const onOpenChange = (next: boolean) => {
+    const el = ref.current;
+    if (next && el != null) setText(el.textContent || null);
+    setOpen(next && el != null && el.scrollWidth > el.clientWidth);
+  };
+  const content = typeof label === 'string' ? label : text || label;
+  return { ref, open, onOpenChange, content };
+}