@trinityui/design-system 2.11.1 → 2.13.1

package/dist/components/shared/useContainerInlineSize.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview useContainerInlineSize: an element's inline size from a ResizeObserver
+ * (master-plan H-20, ADR-11 (5), ADR-27).
+ * @module components/shared/useContainerInlineSize
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * For a switch CSS container queries cannot express: a structural change, such as
+ * ListDetailTemplate's split view becoming a list with a full-width drawer
+ * (`collapseMode="container"`). Styling that only changes properties uses
+ * `containerUp` / `containerDown` (containerQueries.ts) instead.
+ *
+ * Semantics:
+ *
+ * - The size is `null` until the element is measured: on the server and in the first client
+ *   render, so hydration matches (ADR-27's stable initial value). Callers treat `null` as
+ *   "wide enough" (the split layout).
+ * - The element is passed through the returned callback ref, so an element that is replaced
+ *   (a new root node) is observed again.
+ * - The size is the border box's content inline size (`contentBoxSize[0].inlineSize`, else
+ *   `contentRect.width`), updated on every ResizeObserver report; state changes only when the
+ *   value changes.
+ * - Without ResizeObserver (an old engine, a server) the size stays `null`.
+ * - `enabled: false` observes nothing and reports `null`.
+ *
+ * @example
+ * ```tsx
+ * const [inlineSize, measureRef] = useContainerInlineSize<HTMLDivElement>({ enabled: collapseMode === 'container' });
+ * const handleRef = useForkRef(ref, measureRef);
+ * const collapsed = inlineSize !== null && inlineSize < threshold;
+ * ```
+ */
+/** Options of {@link useContainerInlineSize}. @internal */
+export interface UseContainerInlineSizeOptions {
+    /** Observe the element. Default `true`; `false` reports `null`. */
+    enabled?: boolean;
+}
+/**
+ * The inline size of the element given to the returned ref, or `null` before it is measured.
+ * @internal
+ */
+export declare function useContainerInlineSize<El extends HTMLElement = HTMLElement>(options?: UseContainerInlineSizeOptions): [inlineSize: number | null, ref: (node: El | null) => void];
+//# sourceMappingURL=useContainerInlineSize.d.ts.map

package/dist/components/shared/useContainerInlineSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useContainerInlineSize.d.ts","sourceRoot":"","sources":["../../../src/components/shared/useContainerInlineSize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,2DAA2D;AAC3D,MAAM,WAAW,6BAA6B;IAC5C,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AASD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,SAAS,WAAW,GAAG,WAAW,EACzE,OAAO,GAAE,6BAAkC,GAC1C,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC,CAqB7D"}

package/dist/components/shared/useCopyAction.d.ts

@@ -0,0 +1,35 @@
+import { type AsyncActionResult } from '../../hooks';
+/** Options of {@link useCopyAction}. @internal */
+export interface UseCopyActionOptions {
+    /** Announced through `useAnnounce`: `success` politely, `error` assertively. */
+    messages?: {
+        success?: string;
+        error?: string;
+    };
+    /** Called with the copied text after a successful copy. */
+    onCopied?: (text: string) => void;
+    /** Called with the error after a failed copy. Without it the error goes to `globalThis.reportError`. */
+    onCopyError?: (error: unknown) => void;
+    /**
+     * How long `status` stays `'copied'` or `'error'`, in ms.
+     * @default 2000
+     */
+    feedbackDuration?: number;
+}
+/** Where the latest copy is. @internal */
+export type CopyActionStatus = 'idle' | 'pending' | 'copied' | 'error';
+/** Return value of {@link useCopyAction}. @internal */
+export interface UseCopyActionResult {
+    /** Copies `text`. Resolves to the outcome; never rejects. Stable identity. */
+    copy: (text: string) => Promise<AsyncActionResult>;
+    status: CopyActionStatus;
+    /** Back to `'idle'`. Stable identity. */
+    reset: () => void;
+}
+/**
+ * Copies text through `useClipboard` and `useAsyncAction`, with failures surfaced. See the
+ * module notes.
+ * @internal
+ */
+export declare function useCopyAction(options?: UseCopyActionOptions): UseCopyActionResult;
+//# sourceMappingURL=useCopyAction.d.ts.map

package/dist/components/shared/useCopyAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCopyAction.d.ts","sourceRoot":"","sources":["../../../src/components/shared/useCopyAction.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAgC,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAYnF,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,wGAAwG;IACxG,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvE,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACnD,MAAM,EAAE,gBAAgB,CAAC;IACzB,yCAAyC;IACzC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAmDrF"}

package/dist/components/shared/useOverflow.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview useOverflow: whether an element's content overflows its box (master-plan D-43).
+ * @module components/shared/useOverflow
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * One measurement for every component that reacts to overflow: OverflowTooltip today,
+ * MetaChip truncation (D-04) and CodeBlock scrolling (D-07) next. Semantics:
+ *
+ * - The first render reports no overflow, on the server and on the client, so hydration
+ *   matches.
+ * - The element is measured after layout, on every commit. A content change (a new value,
+ *   streamed text) is measured without a dependency list.
+ * - It is measured again when a ResizeObserver reports the element and on window resize.
+ *   Without ResizeObserver, window resize still works.
+ * - State changes only when a result changes, so a re-render or a resize with the same
+ *   overflow causes no extra render.
+ * - The observer is disconnected and the resize listener removed on unmount.
+ *
+ * @example
+ * ```tsx
+ * const ref = React.useRef<HTMLSpanElement>(null);
+ * const { overflowX } = useOverflow(ref, { axis: 'x' });
+ * ```
+ */
+import * as React from 'react';
+/** Which overflow to measure. `'both'` (the default) measures both axes. */
+export type OverflowAxis = 'x' | 'y' | 'both';
+export interface UseOverflowOptions {
+    /** Which axis to measure. An axis left out always reports `false`. Default `'both'`. */
+    axis?: OverflowAxis;
+}
+export interface UseOverflowResult {
+    /** `scrollWidth` is larger than `clientWidth`. */
+    overflowX: boolean;
+    /** `scrollHeight` is larger than `clientHeight`. */
+    overflowY: boolean;
+}
+/**
+ * Reports whether the element in `ref` overflows horizontally and vertically.
+ * @internal
+ */
+export declare function useOverflow(ref: React.RefObject<HTMLElement | null>, options?: UseOverflowOptions): UseOverflowResult;
+//# sourceMappingURL=useOverflow.d.ts.map

package/dist/components/shared/useOverflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../../src/components/shared/useOverflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;IACnB,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;CACpB;AAYD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACxC,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAuCnB"}

package/dist/components/shared/useResizable.d.ts

@@ -6,16 +6,24 @@
  * `ResizablePanel`, and any future drag-to-resize surface:
  *
  *   1. `mousedown` on a handle captures the start position + start size
+ *      (the current size through the caller's clamp)
  *   2. Global `mousemove` listener updates size (clamped by the caller)
  *   3. Global `mouseup` ends the drag
  *   4. Optional body cursor lock and text-selection suppression during drag
  *
+ * The size can be uncontrolled (seeded once from `initialSize`) or controlled
+ * (`size` + `onSizeChange`), through MUI `useControlled` (ADR-35). Every size
+ * write — drag, `setSize`, `setSizeClamped` — goes through one internal
+ * commit that stores the size when uncontrolled and reports it through
+ * `onSizeChange` in both modes.
+ *
  * **Not used by `DockLayout`** — that component uses the HTML5 Drag-and-Drop
  * API (`DragEvent`, `dataTransfer`) for whole-panel moves between zones, which
  * is a fundamentally different mechanism. Don't try to unify them.
  *
  * @example
  * ```tsx
+ * // Uncontrolled: the hook owns the size.
  * const { size, isResizing, onMouseDown, setSize } = useResizable({
  *   initialSize: 400,
  *   axis: 'x',
@@ -26,11 +34,85 @@
  *
  * return <div onMouseDown={onMouseDown}>...</div>;
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled: the caller owns the size; the hook reports changes.
+ * const [width, setWidth] = React.useState(400);
+ * const { size, onMouseDown } = useResizable({
+ *   initialSize: 400,
+ *   size: width,
+ *   onSizeChange: (next) => setWidth(next),
+ *   axis: 'x',
+ * });
+ * ```
  */
 import * as React from 'react';
+/**
+ * Why the size changed, as reported to `onSizeChange`.
+ *
+ * - `'drag'`: a mouse or touch drag on the handle (set by the hook).
+ * - `'keyboard'`: a key press on the handle. The hook binds no keys itself; the
+ *   caller passes this reason to `setSize` / `setSizeClamped`.
+ * - `'set'`: any other `setSize` / `setSizeClamped` call (the default).
+ */
+export type ResizeReason = 'drag' | 'keyboard' | 'set';
 export interface UseResizableOptions {
-    /** Initial pixel size — can be a function for lazy/derived values */
+    /**
+     * Initial pixel size when uncontrolled — can be a function for lazy/derived
+     * values. Read once, on mount: later changes (a new number or a new
+     * function) are ignored, so a caller may recompute it on every render
+     * (e.g. `controlledSize ?? 200`) without resetting the size or triggering
+     * MUI's "changing the default size state" warning. When `size` is
+     * controlled it is still resolved on mount, but not used.
+     */
     initialSize: number | (() => number);
+    /**
+     * Controlled pixel size. When defined on the first render, the hook never
+     * changes the size on its own: drags and `setSize` / `setSizeClamped`
+     * report the next (clamped) size through `onSizeChange`, and the returned
+     * `size` changes only when this option changes. A drag starts from
+     * `clamp(size)`, so a controlled size outside the caller's bounds has no
+     * dead zone. The mode is decided on the first render; switching between
+     * `undefined` and a number afterwards is unsupported and logs MUI's
+     * controlled/uncontrolled warning in development (it names `name` and
+     * `stateName`). Implemented with MUI `useControlled` (ADR-35).
+     */
+    size?: number;
+    /**
+     * Component name shown in MUI's controlled/uncontrolled warning. A
+     * component built on the hook passes its own name, so the warning points
+     * at the component the consumer rendered (for example `'ResizablePanel'`).
+     * @internal
+     * @default 'useResizable'
+     */
+    name?: string;
+    /**
+     * Name of the controlled prop shown in MUI's controlled/uncontrolled
+     * warning (for example `'width'`).
+     * @internal
+     * @default 'size'
+     */
+    stateName?: string;
+    /**
+     * Turns drag resizing off. While true, `onMouseDown` and `onTouchStart`
+     * start nothing, and a drag already in progress ends at once: its global
+     * listeners and the body cursor lock are released, no further move is
+     * reported, and `onResizeEnd` fires once with the size it reached.
+     * `setSize` and `setSizeClamped` still work.
+     * @internal
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Fires with the next size on every write, in both controlled and
+     * uncontrolled mode: once per drag move (the clamped size, like `onResize`,
+     * including repeats of the same value at a bound) with reason `'drag'`, and
+     * once per `setSize` / `setSizeClamped` call with the reason passed there
+     * (default `'set'`). Not called when a controlled `size` changes. The latest
+     * function is always used (no re-binding needed).
+     */
+    onSizeChange?: (size: number, reason: ResizeReason) => void;
     /** Which axis the drag handle moves along */
     axis: 'x' | 'y';
     /**
@@ -45,7 +127,13 @@ export interface UseResizableOptions {
     onResize?: (size: number) => void;
     /** Fires once when drag begins */
     onResizeStart?: () => void;
-    /** Fires once when drag ends (with the final size) */
+    /**
+     * Fires once when drag ends (with the final size). It runs in an effect
+     * after the commit in which `isResizing` turns false, so it reports the
+     * settled size (for a controlled `size`, the value the parent kept). A
+     * consumer that switches animations off while `isResizing` is true sees
+     * them come back one commit before this call.
+     */
     onResizeEnd?: (size: number) => void;
     /**
      * Lock body cursor + suppress text selection during drag. Default true.
@@ -59,7 +147,7 @@ export interface UseResizableOptions {
     dragCursor?: string;
 }
 export interface UseResizableReturn {
-    /** Current pixel size */
+    /** Current pixel size: the controlled `size` when given, else the hook's own state */
     size: number;
     /** True while a drag is in progress */
     isResizing: boolean;
@@ -67,10 +155,20 @@ export interface UseResizableReturn {
     onMouseDown: (e: React.MouseEvent) => void;
     /** Attach to the drag handle's onTouchStart (mobile touch support) */
     onTouchStart: (e: React.TouchEvent) => void;
-    /** Imperatively set the size (for keyboard nav, reset buttons, etc.) */
-    setSize: (size: number) => void;
-    /** Same as setSize but routes through clamp first */
-    setSizeClamped: (size: number) => void;
+    /**
+     * Imperatively set the size (for keyboard nav, reset buttons, etc.). Stores
+     * it when uncontrolled and reports it through `onSizeChange` with `reason`.
+     * Stable identity.
+     * @param size Next pixel size, used as given (not clamped).
+     * @param reason Reported to `onSizeChange` (default `'set'`).
+     */
+    setSize: (size: number, reason?: ResizeReason) => void;
+    /**
+     * Same as setSize but routes through clamp first. Stable identity.
+     * @param size Next pixel size, clamped with the latest `clamp`.
+     * @param reason Reported to `onSizeChange` (default `'set'`).
+     */
+    setSizeClamped: (size: number, reason?: ResizeReason) => void;
 }
 /**
  * useResizable — React hook that owns the pointer-drag lifecycle for a
@@ -79,4 +177,5 @@ export interface UseResizableReturn {
  * The hook does NOT render anything. It's a headless primitive.
  */
 export declare function useResizable(options: UseResizableOptions): UseResizableReturn;
+export { getResizeKeyTarget, RESIZE_KEY_STEP, RESIZE_KEY_LARGE_STEP, type ResizeKeyOptions, type ResizeOrientation, type ResizeGrowDirection, } from './resizeKeyboard';
 //# sourceMappingURL=useResizable.d.ts.map

package/dist/components/shared/useResizable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useResizable.d.ts","sourceRoot":"","sources":["../../../src/components/shared/useResizable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IACrC,6CAA6C;IAC7C,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAClC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,sDAAsD;IACtD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,sEAAsE;IACtE,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,wEAAwE;IACxE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,qDAAqD;IACrD,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAoJ7E"}
+{"version":3,"file":"useResizable.d.ts","sourceRoot":"","sources":["../../../src/components/shared/useResizable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IACrC;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5D,6CAA6C;IAC7C,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAClC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,sEAAsE;IACtE,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;IACvD;;;;OAIG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CAC/D;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAwL7E;AAMD,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC"}

package/dist/components/shared/warnDeprecated.d.ts

@@ -1,30 +1,104 @@
 /**
- * @fileoverview Dev-only runtime warning for deprecated components.
+ * @fileoverview Development-only warnings: deprecations (ADR-30) and keyed one-time warnings.
  * @module components/shared/warnDeprecated
  *
- * Emits a single `console.warn` the first time a deprecated component is
- * rendered in the current session. Silent in production builds. IDEs already
- * strike through `@deprecated` JSDoc at the call site — this adds a runtime
- * signal for consumers who paste code without reading the hover hint (Replit
- * Agent output, LLM-generated code, copy-paste from Stack Overflow, etc.).
+ * @internal — not part of the public API; see ADR-02
  *
- * Each component should call this once at module scope (NOT inside the
- * render function) so the warning fires once per page load, not once per
- * render.
+ * Placement rule (ADR-30):
+ *
+ * 1. Never warn at module scope. A module-scope call warns every app that
+ *    imports the chunk, whether or not it renders the component.
+ * 2. Never warn during render. Warn from an effect. `useDeprecationWarning`
+ *    does this for you.
+ * 3. An unconditional deprecation (the whole component is deprecated) warns
+ *    from a mount effect, keyed by the component name:
+ *    `useDeprecationWarning('OldCard', 'v3.0', '`Card`')`.
+ * 4. A conditional deprecation (a deprecated prop is passed, or a default is
+ *    relied on) warns from an effect keyed by `<Component>.<condition>`, and
+ *    only when the condition holds:
+ *    `useDeprecationWarning('Chart.legacyColors', 'v3.0', '`colors`', legacyColors !== undefined)`.
+ * 5. Trinity components that render a deprecated component on purpose wrap
+ *    it in `DeprecationSuppressionContext.Provider value={true}`. The consumer
+ *    cannot change that usage, so no warning fires for it.
+ * 6. Each key warns once per session. All warnings are development-only:
+ *    production builds drop the warning code.
+ *
+ * `src/components/shared/__tests__/warnDeprecated.test.ts` enforces rule 1
+ * and 2 with an AST check over `src/components`. It holds a ratchet of the
+ * render-phase calls that are left; the ratchet can only go down.
+ *
+ * `warnOnce(key, message)` is the single helper for other development
+ * warnings (a missing handler, an unsupported value). Call it from an effect
+ * too, and keep the call inside the literal check
+ * `if (process.env.NODE_ENV !== 'production')`, so bundlers drop your message
+ * text as well as the helper.
+ *
+ * Tests: `src/test-setup.ts` calls `__resetDevWarnings()` after every test,
+ * so each test sees its own first warning.
  *
  * @example
  * ```tsx
- * // Top of AIChat.tsx:
- * warnDeprecated('AIChatMessage', 'v3.0', 'AIMessage from @trinityui/design-system');
- * export const AIChatMessage = ...;
+ * export function OldCard(props: OldCardProps) {
+ *   useDeprecationWarning('OldCard', 'v3.0', '`Card`');
+ *   return <Card {...props} />;
+ * }
+ *
+ * // Inside a Trinity component that still renders OldCard internally:
+ * <DeprecationSuppressionContext.Provider value={true}>
+ *   <OldCard />
+ * </DeprecationSuppressionContext.Provider>
  * ```
  */
+import * as React from 'react';
+/**
+ * `true` inside a Trinity component that renders a deprecated component on
+ * purpose. `useDeprecationWarning` does not warn while it is `true`.
+ *
+ * @internal
+ */
+export declare const DeprecationSuppressionContext: React.Context<boolean>;
+/**
+ * Warns once per session that `componentName` is deprecated. Development only.
+ *
+ * Prefer `useDeprecationWarning` in components: it warns from an effect and
+ * respects `DeprecationSuppressionContext`. Call this function directly only
+ * from an effect, never at module scope or during render.
+ *
+ * @param componentName - The key and the name shown in the message, e.g.
+ *   `'OldCard'` or `'Chart.legacyColors'`.
+ * @param removalVersion - The version that removes it, e.g. `'v3.0'`.
+ * @param replacement - What to use instead, as Markdown-style text.
+ */
 export declare function warnDeprecated(componentName: string, removalVersion: string, replacement: string): void;
 /**
- * Test-only helper — clear the warned-set so repeated test runs can observe
- * the warning. NOT part of the public API.
+ * Warns from an effect that `name` is deprecated (ADR-30). Development only.
+ * Does nothing inside `DeprecationSuppressionContext` or while `when` is
+ * `false`. Each `name` warns once per session.
+ *
+ * @param name - The component name, or `<Component>.<condition>` for a
+ *   conditional deprecation.
+ * @param removalVersion - The version that removes it, e.g. `'v3.0'`.
+ * @param replacement - What to use instead.
+ * @param when - The deprecation condition. Defaults to `true` (unconditional).
+ *
+ * @internal
+ */
+export declare function useDeprecationWarning(name: string, removalVersion: string, replacement: string, when?: boolean): void;
+/**
+ * Logs `message` once per `key` per session. Development only. Call it from
+ * an effect, inside `if (process.env.NODE_ENV !== 'production')`.
+ *
+ * @param key - Identifies the warning, e.g. `'AIResponseRenderer.unknownBlock.chart'`.
+ * @param message - The text after the `[trinity]` prefix.
+ *
+ * @internal
+ */
+export declare function warnOnce(key: string, message: string): void;
+/**
+ * Test-only: forget every key that already warned, so the next call warns
+ * again. `src/test-setup.ts` calls it after each test.
  *
  * @internal
  */
-export declare function __resetDeprecationWarnings(): void;
+export declare function __resetDevWarnings(): void;
 //# sourceMappingURL=warnDeprecated.d.ts.map

package/dist/components/shared/warnDeprecated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"warnDeprecated.d.ts","sourceRoot":"","sources":["../../../src/components/shared/warnDeprecated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,IAAI,CAeN;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}
+{"version":3,"file":"warnDeprecated.d.ts","sourceRoot":"","sources":["../../../src/components/shared/warnDeprecated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,wBAAsC,CAAC;AAGjF;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,IAAI,CAcN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,OAAc,GACnB,IAAI,CAON;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQ3D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/components/shared/zIndexRoles.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Named overlay layer roles on `theme.zIndex` (ADR-03-R12, master-plan E-46+).
+ * @module components/shared/zIndexRoles
+ *
+ * Remediation §5.6 names every overlay layer and bans arbitrary 1000, 1300 and 9999 values. The
+ * roles are offsets on MUI's own zIndex scale, which every MUI overlay already uses (Trinity's
+ * CSS z-index scale tops out at 1070, below MUI's modal, so it cannot order a toast or a skip
+ * link above an open dialog). No new absolute value is introduced.
+ *
+ * | Role | Value | Used by |
+ * |---|---|---|
+ * | `aiPanel` | `drawer - 1` | AppLayout's AI panel, under the header and the sidebar |
+ * | `appChrome` | `drawer + 1` | the application header |
+ * | `aiFab` | `drawer + 1` | the AI floating action button |
+ * | `popover` | `modal` | anchored listboxes and popovers (SearchInput's suggestions) |
+ * | `toast` | `snackbar` | Toast's stacks |
+ * | `skipLink` | `tooltip + 1` | SkipLink, above every overlay but the diagnostic layer |
+ * | `diagnostic` | `tooltip + 2` | emergency and diagnostic layers |
+ *
+ * `fab` (GoToTop) and `tooltip` are MUI's own keys and stay as they are.
+ *
+ * Trinity themes carry the roles on `theme.zIndex` (optional keys in the published types).
+ * Components read them through {@link getZIndexRole}, which derives the role from the theme's
+ * scale when a theme does not carry it (a plain `createTheme()`, a consumer theme), so a role
+ * always resolves (ADR-26). A theme extended from a Trinity theme
+ * (`createTheme(trinityTheme, { zIndex: { tooltip } })`) keeps the carried roles: override the
+ * role keys with the scale. Not exported from a package entry.
+ */
+import type { Theme } from '@mui/material/styles';
+/** The MUI zIndex keys the roles derive from. */
+export interface ZIndexScale {
+    drawer: number;
+    modal: number;
+    snackbar: number;
+    tooltip: number;
+}
+/** The named overlay layer roles (ADR-03-R12). */
+export interface TrinityZIndexRoles {
+    appChrome: number;
+    aiPanel: number;
+    aiFab: number;
+    popover: number;
+    toast: number;
+    skipLink: number;
+    diagnostic: number;
+}
+export type TrinityZIndexRole = keyof TrinityZIndexRoles;
+/** Every role name, in stacking order (lowest first). */
+export declare const Z_INDEX_ROLE_NAMES: readonly TrinityZIndexRole[];
+/** The roles for a MUI zIndex scale: offsets only, no absolute value. */
+export declare function zIndexRoles(scale: ZIndexScale): TrinityZIndexRoles;
+/**
+ * The z-index of `role` for `theme`: the theme's own value when it carries the role (a Trinity
+ * theme, or a consumer override), else the value derived from the theme's MUI scale.
+ */
+export declare function getZIndexRole(theme: Pick<Theme, 'zIndex'>, role: TrinityZIndexRole): number;
+/**
+ * `theme` with every role on `theme.zIndex`, derived from its scale; a role the theme already
+ * carries is kept. The Trinity theme factories call it (E-46+ theme wire).
+ */
+export declare function withZIndexRoles<T extends Pick<Theme, 'zIndex'>>(theme: T): T;
+//# sourceMappingURL=zIndexRoles.d.ts.map

package/dist/components/shared/zIndexRoles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zIndexRoles.d.ts","sourceRoot":"","sources":["../../../src/components/shared/zIndexRoles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,kBAAkB,CAAC;AAEzD,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,EAAE,SAAS,iBAAiB,EAQzD,CAAC;AAEH,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,kBAAkB,CAUlE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAG3F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAG5E"}