@trinityui/design-system 2.11.1 → 2.13.0

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview mergeSx: one ordered sx array from several parts (ADR-04 (4), master-plan E-15).
+ * @module components/shared/mergeSx
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * Object spread of `sx` drops function sx and turns array sx into keys '0', '1' (ADR-04).
+ * `mergeSx(base, sx)` replaces both that and the hand-written
+ * `[base, ...(Array.isArray(sx) ? sx : [sx])]`: objects and functions are kept as entries,
+ * arrays are flattened one level, and `false`, `true`, `null` and `undefined` are dropped.
+ * Later parts win, so pass the component's own styles first and the consumer's `sx` last.
+ *
+ * @example
+ * ```tsx
+ * <Box sx={mergeSx({ display: 'flex' }, dense && { gap: 0.5 }, sx)} />
+ * ```
+ */
+import type { SxProps, Theme } from '@mui/material/styles';
+/** One part of {@link mergeSx}: any sx value, or a falsy value to skip. @internal */
+export type SxPart = SxProps<Theme> | false | null | undefined;
+/**
+ * Merges sx parts into one ordered array that MUI resolves left to right.
+ * @internal
+ */
+export declare function mergeSx(...parts: SxPart[]): SxProps<Theme>;
+//# sourceMappingURL=mergeSx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mergeSx.d.ts","sourceRoot":"","sources":["../../../src/components/shared/mergeSx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,qFAAqF;AACrF,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;AAQ/D;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAU1D"}

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

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Motion helpers: token durations in milliseconds, reduced-motion styles and
+ * scoped keyframes (master-plan E-13, ADR-11 §4).
+ * @module components/shared/motion
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * The motion policy (docs/TOKEN_USAGE_RULES.md, "Motion"):
+ *
+ * - Durations and easings come from `semanticTokens.motion` (or `aiTokens.motion`), never
+ *   from literals (ADR-22-R7, the motion-literal rule).
+ * - An infinite loop stops under reduced motion, and the state it shows stays visible: wrap
+ *   the stop in {@link reducedMotion}.
+ * - An entrance falls back to an instant change of opacity under reduced motion.
+ * - A JavaScript timeout (a MUI `Fade` or `Collapse` `timeout`, a delayed state change that
+ *   waits for an animation) reads {@link useMotionTimeout}, which is 0 under reduced motion.
+ * - Keyframes come only from {@link keyframes}, which gives each animation a scoped,
+ *   collision-free name. A nested `'@keyframes name'` key in `sx` declares a global name: two
+ *   components that both say `pulse` overwrite each other (E-13's characterization test).
+ *
+ * Components guard their own motion with these helpers, because only the component knows
+ * which state a stopped loop must keep visible. The theme's CssBaseline backstop (E-44+)
+ * collapses whatever they miss; motion that must keep running opts out with
+ * {@link ESSENTIAL_MOTION_CLASS}.
+ *
+ * @example
+ * ```tsx
+ * const spin = keyframes({ from: { transform: 'rotate(0deg)' }, to: { transform: 'rotate(360deg)' } });
+ * <Box sx={{
+ *   animation: `${spin} ${semanticTokens.motion.loop.spin} linear infinite`,
+ *   ...reducedMotion({ animation: 'none' }),
+ * }} />
+ *
+ * const timeout = useMotionTimeout(semanticTokens.motion.duration.slower);
+ * <Collapse in={open} timeout={timeout} />
+ * ```
+ */
+import { keyframes } from '@mui/material/styles';
+import type { CSSObject } from '@mui/material/styles';
+import { REDUCED_MOTION_QUERY } from '../../accessibility';
+import type { TrinitySemanticMotion } from '../../tokens';
+export { keyframes };
+/**
+ * A motion token in milliseconds: `'200ms'` → 200, `'1.5s'` → 1500, and a number is taken as
+ * milliseconds already. Throws on anything that is not a CSS time, so a malformed token fails
+ * loudly instead of turning into `NaN` or 0. The theme reads its transitions with the same
+ * parser (`cssTimeToMs`).
+ */
+export declare function toMs(token: string | number): number;
+/**
+ * The token's duration in milliseconds for a JavaScript timeout, or 0 when the user prefers
+ * reduced motion. SSR-stable: the server render and the hydration render use the token's
+ * duration, then the component re-renders with the user's preference (ADR-27).
+ */
+export declare function useMotionTimeout(token: string | number): number;
+/**
+ * Styles that apply only under reduced motion, keyed by the shared
+ * `REDUCED_MOTION_QUERY`, for spreading into an `sx` object:
+ * `{ animation: …, ...reducedMotion({ animation: 'none' }) }`.
+ */
+export declare function reducedMotion(styles: CSSObject): Record<typeof REDUCED_MOTION_QUERY, CSSObject>;
+/**
+ * The class that exempts an element from the theme's reduced-motion backstop. Only for motion
+ * that carries information with no static equivalent; the element still respects reduced
+ * motion in its own styles where it can. The exemption covers the element and its `::before`
+ * and `::after`, not its descendants.
+ */
+export declare const ESSENTIAL_MOTION_CLASS = "trinity-essential-motion";
+/** The duration the backstop gives every transition and animation under reduced motion. */
+export declare const REDUCED_MOTION_DURATION = "0.01ms";
+/**
+ * The theme's `transitions` option, read from the semantic motion tokens. Value-neutral where
+ * MUI's default equals a token, so default motion does not change:
+ *
+ * | theme.transitions | MUI default | Token |
+ * |---|---|---|
+ * | `duration.shortest` | 150 | `motion.duration.fast` |
+ * | `duration.shorter` | 200 | `motion.duration.normal` |
+ * | `duration.standard` | 300 | `motion.duration.slow` |
+ * | `easing.easeInOut` | `cubic-bezier(0.4, 0, 0.2, 1)` | `motion.easing.default` |
+ * | `easing.easeOut` | `cubic-bezier(0.0, 0, 0.2, 1)` | `motion.easing.enter` (the same curve) |
+ * | `easing.easeIn` | `cubic-bezier(0.4, 0, 1, 1)` | `motion.easing.exit` |
+ *
+ * MUI's `duration.short` (250), `complex` (375), `enteringScreen` (225), `leavingScreen` (195)
+ * and `easing.sharp` have no equal token and keep MUI's values (C-26 keeps 225/195 for the
+ * drawers and dialogs); docs/remediation/E-44-theme-motion-backstop.md records them. Token
+ * overrides now reach `theme.transitions`.
+ */
+export declare function themeTransitions(motion: TrinitySemanticMotion): {
+    duration: {
+        shortest: number;
+        shorter: number;
+        standard: number;
+    };
+    easing: {
+        easeInOut: string;
+        easeOut: string;
+        easeIn: string;
+    };
+};
+/**
+ * The CssBaseline `styleOverrides` that collapse motion under `REDUCED_MOTION_QUERY`: every
+ * element except one with {@link ESSENTIAL_MOTION_CLASS} (and its `::before` and `::after`)
+ * gets 0.01ms animation and transition durations, one animation iteration and
+ * `scroll-behavior: auto`. An animation jumps to its end state and a transition to its target.
+ * A safety net only: components still guard their own motion, because only a component knows
+ * which state a stopped loop must keep visible.
+ */
+export declare function reducedMotionBackstop(): CSSObject;
+//# sourceMappingURL=motion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../../src/components/shared/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAoB,MAAM,qBAAqB,CAAC;AAE7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEnD;AAGD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAG/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAE/F;AAOD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAEjE,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB;;;;;;;;;;;EAa7D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,CAYjD"}

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

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Stable React keys for lists whose items carry no id (WI-52).
+ * @module components/shared/occurrenceKeys
+ *
+ * @internal — not part of the public API; see ADR-02
+ */
+/**
+ * Stable React keys for a list whose items carry no id.
+ *
+ * Each key is the item's natural identity (a label, a URL, the text) plus how
+ * many earlier items share it, so duplicates stay distinct. Removing or
+ * reordering items leaves every other item's key unchanged: React keeps each
+ * DOM node, and the focus inside it, with the same logical item. An index key
+ * hands the node to whichever item now sits at that index, so focus silently
+ * moves to a different item (WCAG 2.4.3).
+ *
+ * The key is a JSON pair, so no identity string can collide with another
+ * identity's counted form.
+ *
+ * @internal Not exported from any package entry.
+ */
+export declare function occurrenceKeys<T>(items: readonly T[], identity: (item: T) => string): string[];
+//# sourceMappingURL=occurrenceKeys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"occurrenceKeys.d.ts","sourceRoot":"","sources":["../../../src/components/shared/occurrenceKeys.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,EAAE,CAQ9F"}

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

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Primary-action overlay: one pattern for a clickable container that holds nested actions.
+ * @module components/shared/primaryAction
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * A card or row that is clickable as a whole, and also holds its own buttons
+ * or links, must not become one big button: that nests interactive content
+ * (axe `nested-interactive`), and the nested actions lose their names. Use
+ * three layers instead (BEHAVIOR_CONTRACT §2 "Pressable elements"):
+ *
+ * 1. The host gets `primaryActionContainerSx` (`position: relative`).
+ * 2. Its first child is the primary action: a `ButtonBase` with
+ *    `disableRipple` and `primaryActionOverlaySx`. It covers the host
+ *    (`inset: 0`) and takes its name from the title through
+ *    `aria-labelledby`.
+ * 3. The content follows in a box with `primaryActionContentSx`. It sits
+ *    above the overlay and lets clicks fall through to it, except on
+ *    interactive descendants (buttons, links, inputs, `[tabindex]`), which
+ *    keep their own clicks.
+ *
+ * Tab order follows the DOM: the primary action first, then the nested
+ * actions. Enter and Space work because the overlay is a real button.
+ *
+ * The focus ring: MUI Card sets `overflow: hidden`, and the theme draws the
+ * ButtonBase ring outside the element (`outlineOffset: 2`). A ring on an
+ * overlay with `inset: 0` would be clipped. The overlay draws the same ring
+ * inside the host instead: the offset is minus the focus border width
+ * (`semanticTokens.borders.width.focus`), so the theme's ring colour stays.
+ *
+ * Fallback, if a browser clips the inset ring: draw it on the host with
+ * `'&:has(> .<overlay class>:focus-visible)': { outline: …, outlineOffset: -2 }`
+ * and remove the overlay's outline. Every browser that runs the
+ * test:storybook check (Chromium) passes without it.
+ *
+ * Limits: text in the content layer cannot be selected with the mouse,
+ * because the overlay takes the press. A component that needs selectable
+ * text keeps an explicit action button instead.
+ *
+ * @example
+ * ```tsx
+ * const titleId = React.useId();
+ * <Card sx={primaryActionContainerSx}>
+ *   <ButtonBase disableRipple aria-labelledby={titleId} onClick={open} sx={primaryActionOverlaySx} />
+ *   <Box sx={primaryActionContentSx}>
+ *     <Typography id={titleId}>Q3 report</Typography>
+ *     <Tooltip title="More actions">
+ *       <IconButton aria-label="More actions" onClick={openMenu}><MoreIcon /></IconButton>
+ *     </Tooltip>
+ *   </Box>
+ * </Card>
+ * ```
+ */
+import type { SxProps, Theme } from '@mui/material/styles';
+/**
+ * One style object of an `sx` array. Narrower than `SxProps<Theme>` (and assignable to it), so
+ * a host can combine the helper with its own styles: `sx={[{ overflow: 'hidden' }, primaryActionContainerSx]}`.
+ */
+type SxStyleObject = Exclude<Extract<SxProps<Theme>, ReadonlyArray<unknown>>[number], boolean | ((theme: Theme) => unknown)>;
+/**
+ * A CSS selector for interactive elements. A host that also handles clicks
+ * itself (a table row) uses it to ignore clicks that started on a nested
+ * control: `(event.target as Element).closest(PRIMARY_ACTION_INTERACTIVE_SELECTOR)`.
+ *
+ * @internal
+ */
+export declare const PRIMARY_ACTION_INTERACTIVE_SELECTOR: string;
+/**
+ * The host: positions the overlay. Required on the element the overlay covers.
+ *
+ * @internal
+ */
+export declare const primaryActionContainerSx: SxStyleObject;
+/**
+ * The primary action: a `ButtonBase` with `disableRipple`, the host's first
+ * child. It covers the host and draws the theme's focus ring inside it.
+ *
+ * @internal
+ */
+export declare const primaryActionOverlaySx: SxStyleObject;
+/**
+ * The content layer: above the overlay. Clicks on plain content reach the
+ * overlay; interactive descendants keep their own.
+ *
+ * @internal
+ */
+export declare const primaryActionContentSx: SxStyleObject;
+export {};
+//# sourceMappingURL=primaryAction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"primaryAction.d.ts","sourceRoot":"","sources":["../../../src/components/shared/primaryAction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAG3D;;;GAGG;AACH,KAAK,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC;AAqB7H;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,QAAyB,CAAC;AAI1E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,aAEtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAQpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAOpC,CAAC"}

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

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Keyboard model for resizable surfaces (internal).
+ * @module components/shared/resizeKeyboard
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * One keyboard model for the two resizable surfaces: SplitPane's separator and
+ * ResizablePanel's window splitter (APG Window Splitter). It is extracted from
+ * SplitPane's handler, the only RTL-aware keyboard resize in the library:
+ *
+ * - Arrow keys move the separator by `step` (10px), or `largeStep` (50px) with Shift.
+ * - Home goes to `min`, End goes to `max`.
+ * - Under RTL the horizontal arrows swap, so the arrow that points to the
+ *   inline end always moves the separator toward the inline end.
+ *
+ * SplitPane adopts it in H-33 and ResizablePanel in H-31. Until then neither
+ * calls it. It is not exported from any package entry.
+ */
+/** Layout of the two areas the separator divides (SplitPane's `direction`). */
+export type ResizeOrientation = 'horizontal' | 'vertical';
+/**
+ * Which way the resized area grows. 'forward': it grows when the separator
+ * moves toward the inline end (horizontal) or down (vertical), as SplitPane's
+ * first pane does. 'reverse': it grows when the separator moves the other way,
+ * as a panel docked at the inline end does. Same meaning as useResizable's
+ * `direction` option.
+ */
+export type ResizeGrowDirection = 'forward' | 'reverse';
+export interface ResizeKeyOptions {
+    /** Whether Shift is held: the arrow keys then use `largeStep`. */
+    shiftKey?: boolean;
+    /** 'horizontal': the areas sit side by side and the size is a width. */
+    orientation: ResizeOrientation;
+    /** Which way the resized area grows. */
+    growDirection: ResizeGrowDirection;
+    /** Right-to-left layout (`theme.direction === 'rtl'`). Swaps the horizontal arrows. */
+    isRtl: boolean;
+    /** The current size, in px. */
+    current: number;
+    /** The smallest size, in px. Home goes here. */
+    min: number;
+    /** The largest size, in px. End goes here. */
+    max: number;
+    /** Arrow-key step, in px. @default 10 */
+    step?: number;
+    /** Arrow-key step with Shift, in px. @default 50 */
+    largeStep?: number;
+    /**
+     * Also move the separator with the arrows of the other axis: Down and Right
+     * move it forward, Up and Left move it back, with no RTL swap. SplitPane does
+     * this today; APG and ResizablePanel use only the arrows of the separator's
+     * own axis. @default false
+     */
+    crossAxisKeys?: boolean;
+}
+/** Arrow-key step, in px (SplitPane and ResizablePanel). */
+export declare const RESIZE_KEY_STEP = 10;
+/** Arrow-key step with Shift, in px (SplitPane and ResizablePanel). */
+export declare const RESIZE_KEY_LARGE_STEP = 50;
+/**
+ * The size a key press resizes to, or `null` when the key is not a resize key
+ * (the caller then leaves the event alone). Arrow results are clamped to
+ * `[min, max]`; when `min` is above `max` (a container too small for both
+ * bounds), `min` wins, as in SplitPane's clamp. Home returns `min` and End
+ * returns `max`.
+ */
+export declare function getResizeKeyTarget(key: string, options: ResizeKeyOptions): number | null;
+//# sourceMappingURL=resizeKeyboard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resizeKeyboard.d.ts","sourceRoot":"","sources":["../../../src/components/shared/resizeKeyboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wCAAwC;IACxC,aAAa,EAAE,mBAAmB,CAAC;IACnC,uFAAuF;IACvF,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAqBxC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAuBxF"}

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

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Root props contract helpers (ADR-04, master-plan E-15).
+ * @module components/shared/rootProps
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * ADR-04 gives every new or touched component the same root contract: the ref and
+ * `className` reach the root, rest props are spread on it, a closed list of owned
+ * attributes stays the component's, and `id`, `aria-describedby` and `aria-labelledby` are
+ * composed. `useRootProps` implements the rest-props part once:
+ *
+ * - The consumer's rest props are spread first.
+ * - The owned attributes ({@link OwnedAttribute}) are always the component's. A consumer
+ *   value for one of them is dropped, and a development warning names it, once per
+ *   component. Production builds print nothing.
+ * - `id` defaults to `useId()`, so it is stable between the server and the client.
+ * - `aria-describedby` and `aria-labelledby` join the component's ids and the consumer's,
+ *   in that order, without duplicates.
+ *
+ * Two types here are public, because public `slotProps` and docs reference them:
+ * {@link OwnedAttribute} and {@link TrinitySlotProps}. Everything else is internal.
+ *
+ * @example
+ * ```tsx
+ * const { className, sx, id, ...rest } = props;
+ * const rootProps = useRootProps({ rest, id, owned: { role: 'log', 'aria-live': 'polite' }, componentName: 'ChatThread' });
+ * return <Box ref={ref} className={className} sx={mergeSx(baseSx, sx)} {...rootProps} />;
+ * ```
+ */
+import * as React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+/**
+ * The attributes a Trinity component owns on its root and on its slots. A consumer value
+ * for one of them is ignored, with a development warning, so rest props cannot break the
+ * component's role or live-region model (ADR-04, ADR-19).
+ *
+ * @since 2.13.0
+ */
+export type OwnedAttribute = 'role' | 'aria-live' | 'aria-busy' | 'aria-relevant' | 'aria-atomic' | 'aria-modal';
+/**
+ * Props of a Trinity-owned slot, as accepted by a component's `slotProps.<slot>`:
+ * `className`, `sx`, `id`, and the HTML attributes of the slot's element, including
+ * `aria-*`, `data-*` and event handlers. The {@link OwnedAttribute} attributes are not
+ * accepted. Slot names and elements are documented per component (ADR-04 (6)).
+ *
+ * @since 2.13.0
+ */
+export type TrinitySlotProps<El extends HTMLElement = HTMLElement> = {
+    /** Added to the slot's own class names. */
+    className?: string;
+    /** Applied after the slot's own styles. */
+    sx?: SxProps<Theme>;
+    /** Replaces the slot's generated id. The component's references follow it. */
+    id?: string;
+} & Omit<React.HTMLAttributes<El>, OwnedAttribute | 'className' | 'id'> & {
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+};
+/**
+ * The rest props a component's root accepts: every HTML attribute of the root element,
+ * minus the component's own prop names and `color` (ADR-04 (3)).
+ * @internal
+ */
+export type TrinityRootProps<El extends HTMLElement, Own> = Omit<React.HTMLAttributes<El>, keyof Own | 'color'>;
+/** The owned attributes, as a runtime list. @internal */
+export declare const OWNED_ATTRIBUTES: readonly OwnedAttribute[];
+/** An id list: one id string, or several, with empty entries skipped. @internal */
+export type IdList = string | ReadonlyArray<string | false | null | undefined> | false | null | undefined;
+/**
+ * Joins id lists into one space-separated value: tokens in order, duplicates and empty
+ * entries removed. Returns `undefined` when nothing is left.
+ * @internal
+ */
+export declare function joinIds(...lists: IdList[]): string | undefined;
+/** Whether `key` is one of the owned attributes. @internal */
+export declare function isOwnedAttribute(key: string): key is OwnedAttribute;
+/**
+ * Warns once per component that a consumer passed owned attributes, which were ignored.
+ * Silent in production builds.
+ * @internal
+ */
+export declare function warnOwnedAttributes(componentName: string, attributes: readonly string[], slotName?: string): void;
+/**
+ * Test-only: forget which components already warned, so a test can observe the warning
+ * again.
+ * @internal
+ */
+export declare function __resetOwnedAttributeWarnings(): void;
+/** Options of {@link useRootProps}. @internal */
+export interface UseRootPropsOptions<El extends HTMLElement = HTMLElement> {
+    /** The consumer's rest props. Spread first. */
+    rest?: React.HTMLAttributes<El> | Record<string, unknown>;
+    /**
+     * The owned attributes this component sets on its root. Applied after `rest`; a consumer
+     * value never replaces them. Owned attributes left out here are not set at all.
+     */
+    owned?: Partial<Record<OwnedAttribute, string | boolean | undefined>>;
+    /** The consumer's `id`, if the component takes it out of `rest`. Else `rest.id`, else `useId()`. */
+    id?: string;
+    /** The component's own description ids, joined before the consumer's `aria-describedby`. */
+    describedBy?: IdList;
+    /** The component's own label ids, joined before the consumer's `aria-labelledby`. */
+    labelledBy?: IdList;
+    /** Names the component in the development warning. */
+    componentName: string;
+}
+/** What {@link useRootProps} returns: props to spread on the root element. @internal */
+export type RootPropsResult<El extends HTMLElement = HTMLElement> = React.HTMLAttributes<El> & {
+    id: string;
+    [attribute: string]: unknown;
+};
+/**
+ * Builds the root's props: the consumer's rest props, then the component's owned
+ * attributes, a stable `id` and the joined `aria-describedby` and `aria-labelledby`.
+ * @internal
+ */
+export declare function useRootProps<El extends HTMLElement = HTMLElement>(options: UseRootPropsOptions<El>): RootPropsResult<El>;
+//# sourceMappingURL=rootProps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rootProps.d.ts","sourceRoot":"","sources":["../../../src/components/shared/rootProps.ts"],"names":[],"mappings":"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"}

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

@@ -1,5 +1,5 @@
 /**
- * @internal — not part of the public API; used by components that render untrusted content.
+ * @internal — not part of the public API; see ADR-02. Used by components that render untrusted content.
  * @fileoverview Safe rendering of untrusted (model-, user- or data-supplied) content.
  * @module components/shared/safeContent
  *
@@ -43,7 +43,7 @@ export declare function isSafeHref(url: string | null | undefined): boolean;
  * schemes (file:, asset:, tauri:, capacitor:).
  */
 export declare function isSafeSrc(url: string | null | undefined): boolean;
-/** @internal Test-only: forget which unsafe-URL warnings were shown (mirrors `__resetDeprecationWarnings`). */
+/** @internal Test-only: forget which unsafe-URL warnings were shown (mirrors `__resetDevWarnings` in warnDeprecated.ts). */
 export declare function __resetUnsafeUrlWarnings(): void;
 /**
  * @internal
@@ -109,6 +109,12 @@ export interface RenderSafeHtmlOptions {
      * `{ highlight: 'mark' }` renders a semantic `<mark>`. All other classes are dropped.
      */
     allowClasses?: Record<string, 'span' | 'mark'>;
+    /**
+     * The id of the caller's new-tab hint ("Opens in a new tab", WI-56). Every kept
+     * `target="_blank"` anchor gets `aria-describedby` with this id, so its name
+     * stays its text. The caller renders the hint element once.
+     */
+    newTabHintId?: string;
 }
 /**
  * @internal
@@ -118,6 +124,7 @@ export interface RenderSafeHtmlOptions {
  * Default tags: b, strong, i, em, code, br, p, ul, ol, li, span, a, mark.
  * Anchors keep only a safe `href`, `title` and `target="_blank"`, and always
  * get `rel="noopener noreferrer"`; an anchor with an unsafe href becomes text.
+ * With `newTabHintId`, a `target="_blank"` anchor is described by that hint.
  *
  * @example
  * ```tsx

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

@@ -1 +1 @@
-{"version":3,"file":"safeContent.d.ts","sourceRoot":"","sources":["../../../src/components/shared/safeContent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA6F/B;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,MAAM,CAqBzE;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAMlE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAQjE;AAID,+GAA+G;AAC/G,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,GAAE,MAAM,GAAG,OAAgB,GAAG,IAAI,CAetH;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAMnE;AA+BD,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAkC3D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAoBnG;AAMD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAIrD,CAAC;AAKH,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAEnD,CAAC;AA2BH,KAAK,KAAK,GACN;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAQlC,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,CAmIpD;AAoBD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,GAAG,GAAG,QAAQ,GAAG,GAAG,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC;AAEzH,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAChD;AAyMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,qBAA0B,GAAG,KAAK,CAAC,SAAS,CAIpH"}
+{"version":3,"file":"safeContent.d.ts","sourceRoot":"","sources":["../../../src/components/shared/safeContent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA6F/B;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,MAAM,CAqBzE;AAqBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAMlE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAQjE;AAID,4HAA4H;AAC5H,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,GAAE,MAAM,GAAG,OAAgB,GAAG,IAAI,CAetH;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAMnE;AA+BD,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAkC3D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAoBnG;AAMD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAIrD,CAAC;AAKH,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAEnD,CAAC;AA2BH,KAAK,KAAK,GACN;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAQlC,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,CAmIpD;AAoBD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,GAAG,GAAG,QAAQ,GAAG,GAAG,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC;AAEzH,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAC/C;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA6MD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,qBAA0B,GAAG,KAAK,CAAC,SAAS,CAIpH"}

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

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Target-size hit area: one recipe that grows a compact control's pointer target to
+ * the 24px floor without changing how it looks.
+ * @module components/shared/targetSize
+ *
+ * @internal — not part of the public API; see ADR-02
+ *
+ * WCAG 2.2 SC 2.5.8 Target Size (Minimum, AA) asks for a pointer target of at least 24 by 24 CSS
+ * pixels. The program's floor is that 24px (DN-12, 2026-10-05; the record is
+ * docs/remediation/primitives/target-size.md). Standard MUI controls already meet it. A compact
+ * control whose visual box is smaller (a 20px pill, a dense icon button) gets a larger hit area
+ * here, so its look and its layout stay the same:
+ *
+ * - the host keeps its box and gets `position: relative`;
+ * - an `::after` pseudo-element is the hit area. It is centred on the host and is
+ *   `max(box, floor)` on each axis: `inset: min(0px, (100% - floor) / 2)`. A host that is already
+ *   24px or larger on an axis gets a hit area equal to its box on that axis, so the recipe is a
+ *   no-op there;
+ * - the pseudo-element paints nothing. A press on it is a press on the host (hit testing reports
+ *   the originating element), so the host's own handlers, cursor and hover styles apply.
+ *
+ * The inset is symmetric, so the recipe needs no physical `left`/`right` and works the same in
+ * right-to-left layouts.
+ *
+ * Use it on a control that is not an inline target in a sentence (the 2.5.8 inline exception) and
+ * whose visual size cannot grow. Do not hand-roll a local `::before`/`::after` hit area instead:
+ * the remediation stop rule forbids local hit-area hacks (WI-54).
+ *
+ * Limits:
+ * - The host must not be absolutely or fixed positioned (the recipe sets `position: relative`);
+ *   put the recipe on an inner element instead.
+ * - The host must not use its own `::after`.
+ * - An ancestor with `overflow: hidden` clips the hit area at its edge, like any other content.
+ * - Two compact controls closer than 24px centre to centre would share hit area; the later one in
+ *   the DOM wins. Keep such controls at least 24px apart (the 2.5.8 spacing rule).
+ *
+ * @example
+ * ```tsx
+ * <IconButton aria-label="Remove filter" sx={[{ width: 20, height: 20 }, targetSizeHitAreaSx]}>
+ *   <CloseIcon fontSize="inherit" />
+ * </IconButton>
+ * ```
+ */
+import type { SxProps, Theme } from '@mui/material/styles';
+/**
+ * One style object of an `sx` array. Narrower than `SxProps<Theme>` (and assignable to it), so a
+ * host can combine the recipe with its own styles: `sx={[{ width: 20 }, targetSizeHitAreaSx]}`.
+ */
+type SxStyleObject = Exclude<Extract<SxProps<Theme>, ReadonlyArray<unknown>>[number], boolean | ((theme: Theme) => unknown)>;
+/**
+ * The floor in CSS pixels: `scaleHierarchy.touchTargets.floor` (24, DN-12).
+ *
+ * @internal
+ */
+export declare const TARGET_SIZE_FLOOR_PX: number;
+/**
+ * The hit-area recipe. Add it to the host's `sx` array after the component's own styles and
+ * before the consumer's `sx`, so a consumer can still override it deliberately.
+ *
+ * @internal
+ */
+export declare const targetSizeHitAreaSx: SxStyleObject;
+export {};
+//# sourceMappingURL=targetSize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"targetSize.d.ts","sourceRoot":"","sources":["../../../src/components/shared/targetSize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAG3D;;;GAGG;AACH,KAAK,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC;AAE7H;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAA0C,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAOjC,CAAC"}

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"}