@trinityui/design-system 2.11.0 → 2.13.0

package/dist/components/AI/AIReviewItem.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview AIReviewItem: one answer in the golden-dataset review, with what produced it and
+ * the reviewer's decision (master plan G-19; requirements R24-R26).
+ * @module components/AI/AIReviewItem
+ *
+ * A thin composition (BEHAVIOR_CONTRACT section 2) of AIContainer (without its title), MetaChip
+ * and KeyValueList (D blocks), AIConfidenceBadge, AIVerificationBadge and AIQueryDisclosure (F
+ * molecules), AIPlanReview `readOnly` (G-18), AIResponseRenderer `readOnly` or AITextBlock,
+ * ConfirmDialog with C-14's `reasonField`, DiffViewer and Timeline (configured, not edited), and
+ * B's `useAsyncAction`, `useAnnounce`, `useFocusOnReplace` and `AsyncOutcomeAlert`. The keyboard
+ * and focus model is keyboard-models.md, "G flow (a): AIReviewItem decisions".
+ *
+ * - **Content.** The question is the heading (`headingLevel`, default 2; `headingRef` reaches it).
+ *   A status chip (icon and text), the details list (asked by, asked at in the provider's locale
+ *   and time zone, confidence, verification), the plan (`AIPlanReview readOnly`), the query
+ *   (`AIQueryDisclosure`, expanded), the answer (`AIResponseRenderer readOnly` with
+ *   `hitlBlockRenderers` and an `idPrefix` from `useId`, so the same answer in a list and a
+ *   detail view never repeats a DOM id; AITextBlock for a string answer), the users' feedback
+ *   (rating icon and text, problem chips, comment) and the history.
+ * - **Decisions** (a group named 'Decision'). Approve runs `onDecision` through `useAsyncAction`.
+ *   Edit opens a form with one field per `editableFields` entry (the answer as plain text through
+ *   `getResponsePlainText`; the service rebuilds its structure). 'Review changes' shows one
+ *   unified DiffViewer per changed field (no mode switch, no copy, no collapsing, no `maxHeight`:
+ *   none of DiffViewer's known defects renders), each inside a named, focusable region that
+ *   scrolls on its own. With no change it shows a validation message; the button stays enabled.
+ *   Submit sends an `AIReviewEdits` payload. Cancel returns focus to Edit. Reject opens
+ *   ConfirmDialog with a required reason (C-14): an empty reason marks the field invalid, shows
+ *   the message and focuses the field; a failed rejection keeps the dialog open with its inline
+ *   alert; `onDecision` receives the trimmed reason.
+ * - **canDecide.** Defaults to `Boolean(onDecision)` (G-OD7). When false, no control renders and
+ *   `decisionBlockedReason` shows instead.
+ * - **Pending.** Every decision control is `aria-disabled` (never `disabled`) and the running one
+ *   `aria-busy`; clicks do nothing and focus stays. `loading` shows the same state from outside.
+ * - **Resolved.** The summary replaces the controls, is announced politely and, with
+ *   `focusOnResolve` 'summary' (the default), takes focus; 'none' leaves focus to the host (the
+ *   review queue moves to the next item). A failure shows AsyncOutcomeAlert with Try again.
+ * - **History.** Timeline 'compact', non-interactive: each entry is text plus an icon whose shape
+ *   follows its kind, so colour is never the only cue.
+ * - **Design.** Resolver colours only (ADR-26), logical properties, a container-query wrapper
+ *   inside the root (the buttons stack below the `compact` container width; the ref stays on
+ *   the root), 24px targets, forced-colours outlines.
+ * - **Telemetry (G-26).** `AIReviewInteraction` for decide, edit_start and reject_start: the
+ *   item id, the decision, the flag count and the edited field names, never the text.
+ *
+ * @example
+ * ```tsx
+ * <AIReviewItem
+ *   item={item}
+ *   editableFields={['question', 'answer']}
+ *   onDecision={(decision) => api.decide(decision)}
+ * />
+ * ```
+ */
+import * as React from 'react';
+import { type SxProps, type Theme } from '@mui/material/styles';
+import { type HeadingLevel } from '../shared/headingLevel';
+import { type TrinitySlotProps } from '../shared/rootProps';
+import type { AIBlockRendererMap } from './blockRendererContext';
+import type { AIActionErrorContext, AIReviewDecision, AIReviewEditableField, AIReviewItemData } from './types/hitl';
+/**
+ * Props of {@link AIReviewItem}. The rest props reach the root `<div>`.
+ *
+ * @since 2.13.0
+ */
+export interface AIReviewItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'title' | 'onChange' | 'defaultValue'> {
+    /** The answer under review, with what produced it and what happened to it. */
+    item: AIReviewItemData;
+    /**
+     * Whether the reviewer may decide. Without it, the decisions show when `onDecision` is set
+     * (G-OD7). When false, no control renders and `decisionBlockedReason` shows instead.
+     * @default Boolean(onDecision)
+     */
+    canDecide?: boolean;
+    /** Why the reviewer cannot decide, shown when `canDecide` is false (`ai.reviewItem.blockedReason`). */
+    decisionBlockedReason?: string;
+    /**
+     * Called with the reviewer's decision. A returned promise shows the pending state, and its
+     * rejection the error. An edit's `answer` is plain text: the service rebuilds its structure.
+     */
+    onDecision?(decision: AIReviewDecision): void | Promise<void>;
+    /**
+     * The fields the Edit form offers, in this order. `'query'` shows only when the item has a
+     * query.
+     * @default ['answer']
+     */
+    editableFields?: AIReviewEditableField[];
+    /**
+     * Where focus goes after a decision: `'summary'` moves it to the resolved summary; `'none'`
+     * leaves it to the host (the review queue moves to the next item). The summary is announced
+     * either way.
+     * @default 'summary'
+     */
+    focusOnResolve?: 'summary' | 'none';
+    /**
+     * The decision is in progress outside the item (for example the queue is saving it): every
+     * decision control is `aria-disabled` and the item is `aria-busy`.
+     * @default false
+     */
+    loading?: boolean;
+    /** Level of the question's heading; the sections' headings are one level below. @default 2 */
+    headingLevel?: HeadingLevel;
+    /** Reaches the question's heading (`tabIndex -1`), so a host can move focus to the item. */
+    headingRef?: React.Ref<HTMLHeadingElement>;
+    /** Renderers for the answer's blocks; read-only either way. @default hitlBlockRenderers */
+    blockRenderers?: AIBlockRendererMap;
+    /** Called with the error of a failed decision, with `{ source: 'decision', itemId }`. */
+    onActionError?(error: unknown, context: AIActionErrorContext): void;
+    /** Replaces the approve button's text (`ai.reviewItem.approve`). */
+    approveLabel?: string;
+    /** Replaces the edit button's text (`ai.reviewItem.edit`). */
+    editLabel?: string;
+    /** Replaces the reject button's text (`ai.reviewItem.reject`). */
+    rejectLabel?: string;
+    /** @default 'medium' */
+    size?: 'small' | 'medium';
+    className?: string;
+    sx?: SxProps<Theme>;
+    slotProps?: {
+        /** The heading row: the question and the status chip. */
+        header?: TrinitySlotProps<HTMLDivElement>;
+        /** The details list (`<dl>`). */
+        details?: TrinitySlotProps<HTMLElement>;
+        /** The decisions group, or the edit form while editing. */
+        decisions?: TrinitySlotProps<HTMLDivElement>;
+        /** The history section. */
+        history?: TrinitySlotProps<HTMLElement>;
+    };
+}
+/**
+ * One answer in the golden-dataset review: the question, the plan, the query, the answer and the
+ * users' feedback, with Approve, Edit (with a diff of the changes) and Reject (with a required
+ * reason), and the item's history. See the module notes.
+ *
+ * @example
+ * ```tsx
+ * <AIReviewItem item={item} onDecision={(decision) => api.decide(decision)} />
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare const AIReviewItem: React.ForwardRefExoticComponent<AIReviewItemProps & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=AIReviewItem.d.ts.map

package/dist/components/AI/AIReviewItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIReviewItem.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIReviewItem.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,OAAO,EAAiB,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAc/E,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI7E,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAU1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGjE,OAAO,KAAK,EACV,oBAAoB,EAEpB,gBAAgB,EAChB,qBAAqB,EAGrB,gBAAgB,EAGjB,MAAM,cAAc,CAAC;AAGtB;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;IACpI,8EAA8E;IAC9E,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uGAAuG;IACvG,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACzC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC3C,2FAA2F;IAC3F,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,yFAAyF;IACzF,aAAa,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpE,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACpB,SAAS,CAAC,EAAE;QACV,yDAAyD;QACzD,MAAM,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;QAC1C,iCAAiC;QACjC,OAAO,CAAC,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;QACxC,2DAA2D;QAC3D,SAAS,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;QAC7C,2BAA2B;QAC3B,OAAO,CAAC,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;KACzC,CAAC;CACH;AAuFD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,0FA8mBvB,CAAC"}

package/dist/components/AI/AISourceChip.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview AISourceChip: where one number, sentence or cell came from (master plan F-12).
+ * @module components/AI/AISourceChip
+ *
+ * A source chip names one source of an AI response at the place it supports: inline in text, in
+ * a table cell or on a chart point. Activating it opens the source's details.
+ *
+ * - **The chip** is D's MetaChip in interactive mode, so its root is a native
+ *   `<button type="button">`: valid phrasing content inside `<p>` and headings, unlike MUI Chip's
+ *   clickable `div`. The root carries the ref and the rest props. Its colours are the AI roles
+ *   `ai.badgeBackground` and `ai.primary` with an `ai.border` edge at the default border width;
+ *   under forced colours MetaChip draws a CanvasText border and a Highlight focus outline.
+ * - **Variants.** `'label'` (the default) shows `ai.sourceChip.label({ metric, period, title })`
+ *   and is named `ai.sourceChip.labelName(...)`, which starts with the visible label (WCAG
+ *   2.5.3); it meets the 24 by 24 target size. `'number'` shows only the source's number, named
+ *   `ai.sourceChip.numberName({ index, title })` ('Source 1: Q4 report'). The number is `index`,
+ *   else the response's number for the source (its 1-based place in `sources`, the number
+ *   `useBlockSources().getSourceNumber` and AISourcesPanel show); a source with no number falls
+ *   back to the label variant and warns once in development. A number chip inline in text uses
+ *   the meta type size and sits on the text baseline, smaller than 24 by 24: WCAG 2.5.8's inline
+ *   exception (a target in a sentence, whose size the line height constrains).
+ * - **Details** open in DetailsPopover (F-09): a modal dialog named by its visible heading, the
+ *   source's title. It lists the metric, filters (`formatFilter`), period, dataset, as-of date
+ *   (`useFormatAsOf`) and excerpt, or 'No additional details'; `renderDetails` replaces the list
+ *   (`null` renders nothing, `undefined` the default list).
+ * - **'Open source'** is a link only when the URL passes the link policy (`isSafeHref`, ADR-09):
+ *   a new tab with `rel="noopener noreferrer"` and a visually hidden '(opens in new tab)'. Any
+ *   other URL is shown as text and warns once in development.
+ * - **Favicon** only with `showFavicon`: the source URL's origin `/favicon.ico`, for http(s)
+ *   URLs that pass the image policy (`isSafeSrc`), on the label variant, decorative. Off by
+ *   default: loading it contacts the source's host.
+ * - **'Show query'** appears only when something can show the query: `onShowQuery`, or a query
+ *   view (AIQueryDisclosure, F-14) registered under the source's `queryId` in the response. It
+ *   closes the dialog with reason `'action'`; once the dialog has closed and focus has returned,
+ *   `onShowQuery(source)` runs, else the registered query view opens and takes focus (ADR-31).
+ * - **Open state** is controllable: `open`, `defaultOpen`, `onOpenChange(open, reason, event?)`
+ *   with the reasons `'trigger'`, `'escape'`, `'clickAway'` and `'action'`. Opening reports an
+ *   `AISourceOpenInteraction` (ids and enums only) through `AIConfigProvider`'s `onInteraction`.
+ * - Titles, labels and values are model or data text: bidi-isolated. There is no hover preview.
+ *
+ * @example
+ * ```tsx
+ * <AITextBlock content="Net revenue was $4.2M" />
+ * <AISourceChip variant="number" source={response.sources[0]} />
+ * ```
+ *
+ * @since 2.13.0
+ */
+import * as React from 'react';
+import { type SxProps, type Theme } from '@mui/material/styles';
+import type { TrinitySlotProps } from '../shared/rootProps';
+import type { AIResponseSource } from './types/response';
+/**
+ * Why an AISourceChip's details opened or closed: `'trigger'` (the chip), `'escape'`,
+ * `'clickAway'`, or `'action'` ('Show query' closed them).
+ *
+ * @since 2.13.0
+ */
+export type AISourceChipOpenChangeReason = 'trigger' | 'escape' | 'clickAway' | 'action';
+/**
+ * AISourceChip's own props.
+ *
+ * @since 2.13.0
+ */
+export interface AISourceChipOwnProps {
+    /** The source. Its title, metric, period, filters, dataset, as-of date and excerpt are display text. */
+    source: AIResponseSource;
+    /**
+     * `'label'`: the metric (else the title) and the period, as text. `'number'`: the source's
+     * number only, for text, table cells and chart points.
+     * @default 'label'
+     */
+    variant?: 'number' | 'label';
+    /**
+     * The number the `'number'` variant shows, 1-based. Default: the source's number in the
+     * response (its place in `sources`).
+     */
+    index?: number;
+    /** @default 'small' */
+    size?: 'small' | 'medium';
+    /** Whether the details are open (controlled). */
+    open?: boolean;
+    /**
+     * Whether the details start open (uncontrolled).
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Called on every requested change of the open state, with the reason and the event when there is one. */
+    onOpenChange?: (open: boolean, reason: AISourceChipOpenChangeReason, event?: React.SyntheticEvent | Event) => void;
+    /** Called when the 'Open source' link is activated. The link still opens. */
+    onOpenSource?: (source: AIResponseSource, event: React.MouseEvent<HTMLAnchorElement>) => void;
+    /**
+     * Shows the query behind the source. Called after the details have closed and focus has
+     * returned, so a focus move made here stays. Its presence shows the 'Show query' action.
+     */
+    onShowQuery?: (source: AIResponseSource) => void;
+    /**
+     * Shows the source host's favicon on the label variant: the source URL's origin
+     * `/favicon.ico`, for http(s) URLs only. Loading it contacts that host.
+     * @default false
+     */
+    showFavicon?: boolean;
+    /** Replaces the details list: `null` renders nothing, `undefined` the default list. */
+    renderDetails?: (source: AIResponseSource) => React.ReactNode | null | undefined;
+    /** Added to the root button's class names. */
+    className?: string;
+    /** Styles for the root button, after the chip's own. */
+    sx?: SxProps<Theme>;
+    slotProps?: {
+        /** The details dialog (DetailsPopover's paper). */
+        popover?: TrinitySlotProps<HTMLDivElement>;
+        /** The default details list (`<dl>`). */
+        details?: TrinitySlotProps<HTMLElement>;
+        /** The 'Open source' link. */
+        link?: TrinitySlotProps<HTMLAnchorElement>;
+        /** The 'Show query' button. */
+        showQueryButton?: TrinitySlotProps<HTMLButtonElement>;
+    };
+}
+/**
+ * Props of {@link AISourceChip}: its own props and the root button's HTML attributes.
+ *
+ * @since 2.13.0
+ */
+export interface AISourceChipProps extends AISourceChipOwnProps, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'type' | keyof AISourceChipOwnProps> {
+}
+/**
+ * A source chip: the source's number or label as a button that opens its details. See the module
+ * notes.
+ *
+ * @since 2.13.0
+ */
+export declare const AISourceChip: React.ForwardRefExoticComponent<AISourceChipProps & React.RefAttributes<HTMLButtonElement>>;
+export default AISourceChip;
+//# sourceMappingURL=AISourceChip.d.ts.map

package/dist/components/AI/AISourceChip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AISourceChip.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AISourceChip.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAW1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAO5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAQzD;;;;;GAKG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEzF;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,wGAAwG;IACxG,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2GAA2G;IAC3G,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,4BAA4B,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,KAAK,KAAK,IAAI,CAAC;IACnH,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IAC9F;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACjD;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uFAAuF;IACvF,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC;IACjF,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACpB,SAAS,CAAC,EAAE;QACV,mDAAmD;QACnD,OAAO,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;QAC3C,yCAAyC;QACzC,OAAO,CAAC,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;QACxC,8BAA8B;QAC9B,IAAI,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;QAC3C,+BAA+B;QAC/B,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;KACvD,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,iBACf,SAAQ,oBAAoB,EAC1B,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,oBAAoB,CAAC;CAAG;AA6CzG;;;;;GAKG;AACH,eAAO,MAAM,YAAY,6FA4MvB,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/dist/components/AI/AISources.d.ts

@@ -15,39 +15,99 @@
  */
 import React from 'react';
 import { SxProps, Theme } from '@mui/material';
+import { type IconName } from '../Icon';
+import { type HeadingLevel } from '../shared/headingLevel';
+import { type TrinityRootProps } from '../shared/rootProps';
 /**
- * Props for AISource component.
+ * AISource's own props.
  */
-export interface AISourceProps {
-    /** Source number */
-    number: number;
+export interface AISourceOwnProps {
+    /**
+     * Source number, shown in a round badge before the title. Without it the
+     * card renders no number badge (an unnumbered reference). Optional
+     * @since 2.13.0 (it was required).
+     */
+    number?: number;
     /** Source title */
     title: string;
-    /** Source URL */
+    /**
+     * Source URL. Only http(s), mailto, tel and relative URLs become a link (new
+     * tab, `rel="noopener noreferrer"`); any other scheme is shown as plain text,
+     * with a development warning.
+     */
     url?: string;
     /** Source description/snippet */
     description?: string;
-    /** Source type (webpage, document, etc.) */
+    /**
+     * Source type (webpage, document, etc.). Shown as an icon whose accessible
+     * name is the type: "Web page", "Document", "Article", "Video" or "Other source".
+     */
     type?: 'webpage' | 'document' | 'article' | 'video' | 'other';
-    /** Favicon URL */
+    /**
+     * Favicon URL: http(s), `blob:`, relative or a raster `data:image/*` source,
+     * loaded lazily without a referrer. Other sources are not loaded (development
+     * warning).
+     */
     favicon?: string;
-    /** Click handler */
+    /**
+     * Click handler. When set, the title becomes the card's primary action: a
+     * button named by the title that covers the card, with the URL link kept as
+     * its own tab stop beside it. Without it the card is plain content, with no
+     * pointer cursor and no hover effect.
+     */
     onClick?: () => void;
-    /** Custom sx props */
+    /**
+     * Short label shown as a chip after the title, such as "Primary" or "Updated".
+     *
+     * @since 2.13.0
+     */
+    badge?: string;
+    /**
+     * One line of secondary detail under the title, such as "p. 12-15" or
+     * "Updated 2 days ago".
+     *
+     * @since 2.13.0
+     */
+    meta?: string;
+    /**
+     * Replaces the type's glyph. The icon keeps the type's text as its name, so
+     * the type stays available to assistive technology.
+     *
+     * @since 2.13.0
+     */
+    icon?: IconName;
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the card's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
+/**
+ * Props for AISource: its own props, plus the HTML attributes of its root `div` (`id`,
+ * `data-*`, `aria-*`), which reach the root (ADR-04, WI-40).
+ */
+export interface AISourceProps extends AISourceOwnProps, TrinityRootProps<HTMLDivElement, AISourceOwnProps> {
+}
 /**
  * AI Source - Individual source citation card.
  */
 export declare const AISource: React.ForwardRefExoticComponent<AISourceProps & React.RefAttributes<HTMLDivElement>>;
 /**
- * Props for AISourcesSection component.
+ * AISourcesSection's own props.
  */
-export interface AISourcesSectionProps {
+export interface AISourcesSectionOwnProps {
     /** List of sources */
     sources: Omit<AISourceProps, 'number'>[];
-    /** Section title */
+    /** Section title. Default: the `ai.sourcesSection.title` string ('Sources'). */
     title?: string;
+    /**
+     * Heading level of the title: 2 to 6 for h2 to h6. Set it to fit the page outline.
+     * @default 6 (the h6 the title rendered before the prop existed)
+     * @since 2.13.0
+     */
+    headingLevel?: HeadingLevel;
     /** Whether section is collapsible */
     collapsible?: boolean;
     /** Default expanded state */
@@ -56,11 +116,29 @@ export interface AISourcesSectionProps {
     maxVisible?: number;
     /** Source click handler */
     onSourceClick?: (index: number, source: Omit<AISourceProps, 'number'>) => void;
-    /** Custom sx props */
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the section's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
+/**
+ * Props for AISourcesSection: its own props, plus the HTML attributes of its root `div`
+ * (`data-*`, `aria-*`, and `id`), which reach the root (ADR-04, WI-40). Collapsible, the root is
+ * a Disclosure, whose `id` is its header button's (the panel's is `${id}-panel`).
+ */
+export interface AISourcesSectionProps extends AISourcesSectionOwnProps, TrinityRootProps<HTMLDivElement, AISourcesSectionOwnProps> {
+}
 /**
  * AI Sources Section - Collapsible section displaying source citations.
+ *
+ * Collapsible (the default), the header renders through the internal Disclosure (D-29, D-08):
+ * the heading (`headingLevel`) holds one `<button type="button">` with `aria-expanded` and
+ * `aria-controls`, named by the title and the count; Enter and Space toggle it. The count is a
+ * MetaChip (D-04) on the resolver's AI roles (`ai.primary` on `ai.surfaceEmphasis`). With
+ * `collapsible={false}` the heading and the count are static and the list always shows.
  */
 export declare const AISourcesSection: React.ForwardRefExoticComponent<AISourcesSectionProps & React.RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=AISources.d.ts.map

package/dist/components/AI/AISources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AISources.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AISources.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AACxC,OAAO,EAUL,OAAO,EACP,KAAK,EACN,MAAM,eAAe,CAAC;AAUvB;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9D,kBAAkB;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,sFA4HnB,CAAC;AAMH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAC;IACzC,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6BAA6B;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC/E,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,8FA+E5B,CAAC"}
+{"version":3,"file":"AISources.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AISources.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AACxC,OAAO,EASL,OAAO,EACP,KAAK,EAEN,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ9C,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI7E,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAQ1E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9D;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,gBAAgB,EAAE,gBAAgB,CAAC,cAAc,EAAE,gBAAgB,CAAC;CAAG;AAe9G;;GAEG;AACH,eAAO,MAAM,QAAQ,sFAoLnB,CAAC;AAMH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,sBAAsB;IACtB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAC;IACzC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6BAA6B;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC/E;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,wBAAwB,EAAE,gBAAgB,CAAC,cAAc,EAAE,wBAAwB,CAAC;CAAG;AAEtI;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,8FA2F5B,CAAC"}

package/dist/components/AI/AISourcesPanel.d.ts

@@ -18,6 +18,7 @@
  */
 import React from 'react';
 import { SxProps, Theme } from '@mui/material';
+import { type TrinityRootProps } from '../shared/rootProps';
 export interface AISourceItem {
     /** Unique identifier */
     id: string;
@@ -25,6 +26,19 @@ export interface AISourceItem {
     label: string;
     /** Optional detail key-value pairs */
     details?: Record<string, string>;
+    /**
+     * Link to the source, shown with the item's details when its chip is selected (new tab,
+     * `rel="noopener noreferrer"`). Only http(s), mailto, tel and relative URLs become a link; any
+     * other scheme is shown as plain text, with a development warning.
+     * @since 2.13.0
+     */
+    url?: string;
+    /**
+     * The source's number, shown on the chip in place of its letter, so the panel matches the
+     * numbers of inline source chips (F-05's toSourceCategories sets it).
+     * @since 2.13.0
+     */
+    number?: number;
 }
 export interface AISourceCategory {
     /** Unique identifier */
@@ -37,12 +51,12 @@ export interface AISourceCategory {
     items?: AISourceItem[];
 }
 /**
- * Props for AISourcesPanel component.
+ * AISourcesPanel's own props.
  */
-export interface AISourcesPanelProps {
+export interface AISourcesPanelOwnProps {
     /** List of source categories */
     sources: AISourceCategory[];
-    /** Panel title */
+    /** Panel title. Default: the `ai.sourcesPanel.title` string ('Sources'); the header adds the count (`ai.sourcesPanel.titleWithCount`). */
     title?: string;
     /** Whether panel is initially expanded */
     defaultExpanded?: boolean;
@@ -50,13 +64,24 @@ export interface AISourcesPanelProps {
     expanded?: boolean;
     /** Callback when expanded state changes */
     onExpandedChange?: (expanded: boolean) => void;
-    /** Custom sx props */
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the panel's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
 /**
- * Props for AISourceCategoryItem component.
+ * Props for AISourcesPanel: its own props, plus the HTML attributes of its root `div` (`id`,
+ * `data-*`, `aria-*`), which reach the root (ADR-04, WI-40).
  */
-export interface AISourceCategoryItemProps {
+export interface AISourcesPanelProps extends AISourcesPanelOwnProps, TrinityRootProps<HTMLDivElement, AISourcesPanelOwnProps> {
+}
+/**
+ * AISourceCategoryItem's own props.
+ */
+export interface AISourceCategoryItemOwnProps {
     /** Source category data */
     category: AISourceCategory;
     /** Index number to display */
@@ -69,9 +94,20 @@ export interface AISourceCategoryItemProps {
     selectedItem: AISourceItem | null;
     /** Callback when item is selected */
     onSelectItem: (item: AISourceItem | null) => void;
-    /** Custom sx props */
+    /**
+     * Added to the root's own class names.
+     * @since 2.13.0
+     */
+    className?: string;
+    /** Custom sx props, applied after the row's own styles (object, array or function). */
     sx?: SxProps<Theme>;
 }
+/**
+ * Props for AISourceCategoryItem: its own props, plus the HTML attributes of its root `div`
+ * (`id`, `data-*`, `aria-*`), which reach the root (ADR-04, WI-40).
+ */
+export interface AISourceCategoryItemProps extends AISourceCategoryItemOwnProps, TrinityRootProps<HTMLDivElement, AISourceCategoryItemOwnProps> {
+}
 /**
  * AI Sources Panel - Collapsible panel displaying source citations
  */

package/dist/components/AI/AISourcesPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AISourcesPanel.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AISourcesPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AACxC,OAAO,EAQL,OAAO,EACP,KAAK,EACN,MAAM,eAAe,CAAC;AAQvB,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,2BAA2B;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,8BAA8B;IAC9B,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,qCAAqC;IACrC,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD,sBAAsB;IACtB,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAMD;;GAEG;AACH,eAAO,MAAM,cAAc,4FAgF1B,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,oBAAoB,kGA2JhC,CAAC;AAEF,eAAe,cAAc,CAAC"}
+{"version":3,"file":"AISourcesPanel.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AISourcesPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AAGxC,OAAO,EAKL,OAAO,EACP,KAAK,EACN,MAAM,eAAe,CAAC;AAavB,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM1E,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gCAAgC;IAChC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,0IAA0I;IAC1I,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB,EAAE,gBAAgB,CAAC,cAAc,EAAE,sBAAsB,CAAC;CAAG;AAEhI;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,2BAA2B;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,8BAA8B;IAC9B,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,qCAAqC;IACrC,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAA0B,SAAQ,4BAA4B,EAAE,gBAAgB,CAAC,cAAc,EAAE,4BAA4B,CAAC;CAAG;AAgBlJ;;GAEG;AACH,eAAO,MAAM,cAAc,4FAkG1B,CAAC;AAwDF;;GAEG;AACH,eAAO,MAAM,oBAAoB,kGAuIhC,CAAC;AAEF,eAAe,cAAc,CAAC"}