@trinityui/design-system 2.11.1 → 2.13.1

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

@@ -0,0 +1,67 @@
+import type { AIResponseSource } from './types/response';
+/**
+ * What {@link useBlockSources} returns for one block. Every lookup is a map read: nothing
+ * rescans the sources, so a large table can look up each cell while it renders. The returned
+ * arrays are shared; read them, never change them.
+ *
+ * @since 2.13.0
+ */
+export interface AIBlockSourcesApi {
+    /** The sources whose `blockIds` name this block, in the response's `sources` order. */
+    sources: AIResponseSource[];
+    /**
+     * The sources whose `cellRefs` name one cell of this table block.
+     *
+     * @param row The row's `rowKey` value when the table sets `TableBlock.rowKey`, otherwise its
+     *   0-based index in `rows` as sent (before sorting). Matched as text: `0` and `'0'` are the
+     *   same row.
+     * @param column The column's `key`.
+     */
+    getCellSources(row: string | number, column: string): AIResponseSource[];
+    /**
+     * The sources whose `pointRefs` name one point of this chart block.
+     *
+     * @param series The series' `dataKey`.
+     * @param index The point's 0-based index in the chart's `data`.
+     */
+    getPointSources(series: string, index: number): AIResponseSource[];
+    /**
+     * A source's number: its 1-based place in the response's `sources`, the number inline source
+     * chips and AISourcesPanel show. `undefined` for an id the response does not have.
+     */
+    getSourceNumber(sourceId: string): number | undefined;
+}
+/**
+ * The sources behind one block of the AI response it renders in: the block's own sources, the
+ * sources of each table cell and chart point, and each source's number. Use it in a custom
+ * table or chart renderer to put source chips on the cells and points the response cites.
+ *
+ * It reads the response that AIResponseRenderer provides around its blocks. Outside one it
+ * returns an empty API (no sources, `undefined` numbers) with a stable identity, never throws,
+ * and warns once in development.
+ *
+ * Numbers follow the response's `sources` order. The backend appends sources while a response
+ * streams and keeps earlier ones in place; reordering them renumbers the chips.
+ *
+ * @param blockId The `id` of the table or chart block.
+ *
+ * @example
+ * ```tsx
+ * function RevenueCell({ blockId, row, column, value }: { blockId: string; row: number; column: string; value: string }) {
+ *   const { getCellSources, getSourceNumber } = useBlockSources(blockId);
+ *   const cited = getCellSources(row, column);
+ *   return (
+ *     <td>
+ *       {value}
+ *       {cited.map((source) => (
+ *         <sup key={source.id}>[{getSourceNumber(source.id)}]</sup>
+ *       ))}
+ *     </td>
+ *   );
+ * }
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function useBlockSources(blockId: string): AIBlockSourcesApi;
+//# sourceMappingURL=useBlockSources.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useBlockSources.d.ts","sourceRoot":"","sources":["../../../src/components/AI/useBlockSources.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B;;;;;;;OAOG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;IACzE;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;IACnE;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACvD;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAuBlE"}

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

@@ -35,11 +35,24 @@ export interface UseBrowserVoiceModeOptions {
      * silent and resume listening.
      */
     respond?: (text: string) => string | void | Promise<string | void>;
-    /** BCP-47 language tag for recognition + synthesis. Default `en-US`. */
+    /**
+     * BCP 47 language tag for recognition and synthesis. Resolution order: this
+     * option, then the `locale` of the nearest `AIConfigProvider` that sets one
+     * (an ancestor's when the nearest sets none), then `en-US`. Without a
+     * provider locale the default stays `en-US`; the page's `lang` attribute is
+     * not read.
+     */
     lang?: string;
 }
 export interface UseBrowserVoiceModeResult {
-    /** Whether the browser supports the required Web Speech APIs. */
+    /**
+     * Whether the browser supports the required Web Speech APIs.
+     *
+     * `false` on the server and during hydration, so server and client markup
+     * match. React re-renders with the real value right after hydration. A
+     * client-only render (`createRoot`) gets the real value on its first render.
+     * Render your voice control from it as usual.
+     */
     supported: boolean;
     /** Whether voice mode is currently active. */
     open: boolean;
@@ -55,6 +68,22 @@ export interface UseBrowserVoiceModeResult {
     stop: () => void;
     /** Toggle the microphone on/off without leaving voice mode. */
     toggleMute: () => void;
+    /**
+     * Why voice mode stopped by itself. Set when the recognizer reports an error
+     * that restarting cannot fix; voice mode then closes instead of retrying.
+     * `undefined` while nothing has failed. The next `start()` clears it.
+     *
+     * - `'not-allowed'`: microphone access was denied.
+     * - `'no-microphone'`: no microphone could capture audio.
+     * - `'service-unavailable'`: the browser's speech service refused the
+     *   request or cannot recognize the requested language.
+     *
+     * Other recognition errors (`no-speech`, `aborted`, `network`) keep
+     * restarting recognition while voice mode is open.
+     *
+     * @since 2.13.0
+     */
+    error?: 'not-allowed' | 'no-microphone' | 'service-unavailable';
 }
 export declare function useBrowserVoiceMode(options?: UseBrowserVoiceModeOptions): UseBrowserVoiceModeResult;
 export default useBrowserVoiceMode;

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

@@ -1 +1 @@
-{"version":3,"file":"useBrowserVoiceMode.d.ts","sourceRoot":"","sources":["../../../src/components/AI/useBrowserVoiceMode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,0BAA0B;IACzC,gEAAgE;IAChE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnE,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,aAAa,CAAC;IACtB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAkBD,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CAmK3B;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"useBrowserVoiceMode.d.ts","sourceRoot":"","sources":["../../../src/components/AI/useBrowserVoiceMode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,MAAM,WAAW,0BAA0B;IACzC,gEAAgE;IAChE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnE;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,aAAa,CAAC;IACtB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,aAAa,GAAG,eAAe,GAAG,qBAAqB,CAAC;CACjE;AA8ED,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CA2L3B;AAED,eAAe,mBAAmB,CAAC"}

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

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview useWelcomeComposerHandoff: the start screen's composer moving to the bottom of a
+ * chat after the first message (post-M8 lane welcome).
+ * @module components/AI/useWelcomeComposerHandoff
+ *
+ * InsightEnginePanel and InsightEngine show AIChatWelcome, with their composer centred in it,
+ * before the first message, and their thread with the composer at the bottom after it. The
+ * composer element moves between the two places, so this hook carries focus over and plays the
+ * move: the bottom composer slides from where the centred one was.
+ */
+import * as React from 'react';
+/** The field inside a composer that takes focus (InsightEngine's selector). */
+export declare const WELCOME_FIELD_SELECTOR = "textarea:not([aria-hidden=\"true\"]), input:not([type=\"hidden\"]):not([type=\"file\"])";
+/**
+ * The welcome-to-thread handoff of a host that shows AIChatWelcome before the first message and
+ * its thread with a bottom composer after it (InsightEnginePanel, InsightEngine). Call
+ * `capture()` right before the send that ends the welcome: when the welcome goes away, focus
+ * moves to the bottom composer's field if it was inside the welcome, and the bottom composer
+ * slides from where the welcome's composer was (the token `motion.duration.slow` with the
+ * default easing; no motion under reduced motion).
+ *
+ * Host plumbing: no package entry exports it.
+ */
+export declare function useWelcomeComposerHandoff(welcomeVisible: boolean): {
+    welcomeRef: React.RefObject<HTMLDivElement | null>;
+    bottomRef: React.RefObject<HTMLDivElement | null>;
+    capture: () => void;
+    clear: () => void;
+};
+//# sourceMappingURL=useWelcomeComposerHandoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useWelcomeComposerHandoff.d.ts","sourceRoot":"","sources":["../../../src/components/AI/useWelcomeComposerHandoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,4FAAsF,CAAC;AAE1H;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,OAAO;;;;;EAqChE"}

package/dist/components/AI/utils/alphaIndex.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Letter indices for lists (WI-21a): a, b, ..., z, aa, ab, ..., az, ba, ..., zz, aaa.
+ *
+ * Bijective base 26, the way spreadsheet columns count, so every index has letters and none
+ * repeats. It replaces `String.fromCharCode(97 + index)`, which gave '{', '|' and '}' after z.
+ *
+ * Pure: no React, no DOM, no module state.
+ *
+ * @module components/AI/utils/alphaIndex
+ * @internal — not part of the public API; see ADR-02
+ */
+/**
+ * The letters for a zero-based index: `toAlphaIndex(0)` is 'a', `toAlphaIndex(25)` 'z',
+ * `toAlphaIndex(26)` 'aa' and `toAlphaIndex(27)` 'ab'.
+ *
+ * @throws RangeError for a negative, fractional or non-finite index.
+ */
+export declare function toAlphaIndex(index: number): string;
+//# sourceMappingURL=alphaIndex.d.ts.map

package/dist/components/AI/utils/alphaIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alphaIndex.d.ts","sourceRoot":"","sources":["../../../../src/components/AI/utils/alphaIndex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASlD"}

package/dist/components/AI/utils/blockReady.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @internal — not part of the public API; see ADR-02
+ *
+ * useBlockReadyAnnouncement: the one "ready" announcement of an interactive response block
+ * (master plan G-12, ADR-05 (4), ADR-19).
+ *
+ * An interactive block (a clarification, a plan to review, a query) streams in with its
+ * controls `aria-disabled`, and announces nothing while it streams. When it first becomes
+ * interactive after streaming, it announces `message` once, politely, through `useAnnounce`:
+ * inside a ChatThread that is the thread's `LiveRegionProvider` (so no live region is nested in
+ * the log), elsewhere the nearest provider or the document-level region.
+ *
+ * - A block that mounts complete (a reloaded thread, an answer that arrived whole) never
+ *   announces: nothing changed for the reader.
+ * - It announces once per block id: a re-render, a new `message`, React StrictMode's double
+ *   effects, or the block turning read-only and back do not repeat it. A new `blockId` is a new
+ *   block (it announces only if it streams in).
+ * - `message` defaults to `ai.blocks.ready` ('Ready for your input'). Blocks with better text
+ *   pass their own (`ai.clarificationPrompt.ready`, `ai.planReview.*`).
+ * - `BlockReadyAnnouncementSuppressed`: a host that announces on the block's behalf (the chain
+ *   hosting a plan-review phase announces the pinned plan text once, M8 W2-CH) provides `true`,
+ *   and the hook stays silent, so the reader hears the plan once. A block whose ready moment
+ *   passes while suppressed counts as announced.
+ *
+ * Effects only, so the server render and hydration are unaffected.
+ *
+ * Registered in src/components/internal/index.ts under AI ORGANISMS INTERNALS (G-30); no
+ * package entry exports it.
+ *
+ * @module components/AI/utils/blockReady
+ */
+import * as React from 'react';
+/**
+ * `true` inside a host that announces its blocks' ready moment itself; `useBlockReadyAnnouncement`
+ * then stays silent. Default `false`.
+ */
+export declare const BlockReadyAnnouncementSuppressed: React.Context<boolean>;
+/** Options of {@link useBlockReadyAnnouncement}. */
+export interface UseBlockReadyAnnouncementOptions {
+    /** Whether the block is still streaming (`block.status === 'streaming'`). */
+    streaming: boolean;
+    /** Whether the block's controls are usable now (false when read-only, resolved or without a handler). */
+    interactive: boolean;
+    /** The announcement. Default `ai.blocks.ready`. An empty string announces nothing. */
+    message?: string;
+    /** The block's id. A new id is a new block. */
+    blockId?: string;
+}
+/**
+ * Announces `message` once when the block first becomes interactive after streaming. See the
+ * module header for the rules.
+ */
+export declare function useBlockReadyAnnouncement({ streaming, interactive, message, blockId }: UseBlockReadyAnnouncementOptions): void;
+//# sourceMappingURL=blockReady.d.ts.map

package/dist/components/AI/utils/blockReady.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockReady.d.ts","sourceRoot":"","sources":["../../../../src/components/AI/utils/blockReady.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;;GAGG;AACH,eAAO,MAAM,gCAAgC,wBAAsC,CAAC;AAGpF,oDAAoD;AACpD,MAAM,WAAW,gCAAgC;IAC/C,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,yGAAyG;IACzG,WAAW,EAAE,OAAO,CAAC;IACrB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAUD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,gCAAgC,GAAG,IAAI,CAyB9H"}

package/dist/components/AI/utils/blocks.d.ts

@@ -0,0 +1,28 @@
+import type { AIBlockEvent } from '../types/hitl';
+import type { AIResponse, ClarificationBlock } from '../types/response';
+/** The message fields the gate reads: any chat message type with these fits. */
+export interface BlockGateMessage {
+    role: string;
+    streaming?: boolean;
+    response?: AIResponse;
+}
+/** A handler with ChatThread's `onBlockEvent` signature. */
+export type MessageBlockEventHandler<M extends BlockGateMessage> = (message: M, event: AIBlockEvent) => void | Promise<void>;
+/** What {@link useRequiredClarificationGate} returns. */
+export interface RequiredClarificationGate<M extends BlockGateMessage> {
+    /** The composer's visible reason while a required question waits for an answer, else `null`. */
+    blockedReason: string | null;
+    /** Pass to ChatThread's `onBlockEvent`; `undefined` when no `onBlockEvent` is wired. */
+    handleBlockEvent: MessageBlockEventHandler<M> | undefined;
+}
+/**
+ * The latest assistant message's first required clarification that is complete and unanswered,
+ * or `null`. See the module header.
+ */
+export declare function getPendingRequiredClarification(messages: readonly BlockGateMessage[], locallyResolvedIds?: ReadonlySet<string> | readonly string[]): ClarificationBlock | null;
+/**
+ * The required-clarification gate over `messages`, wrapping `onBlockEvent`. See the module
+ * header.
+ */
+export declare function useRequiredClarificationGate<M extends BlockGateMessage>(messages: readonly M[], onBlockEvent: MessageBlockEventHandler<M> | undefined): RequiredClarificationGate<M>;
+//# sourceMappingURL=blocks.d.ts.map

package/dist/components/AI/utils/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../../../src/components/AI/utils/blocks.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAExE,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,gBAAgB,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7H,yDAAyD;AACzD,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,gBAAgB;IACnE,gGAAgG;IAChG,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wFAAwF;IACxF,gBAAgB,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;CAC3D;AAWD;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,kBAAkB,GAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAO,GAC/D,kBAAkB,GAAG,IAAI,CAe3B;AAWD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,gBAAgB,EACrE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,YAAY,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,SAAS,GACpD,yBAAyB,CAAC,CAAC,CAAC,CAiD9B"}

package/dist/components/AI/utils/confidence.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Confidence utilities (master plan F-04, ADR-03).
+ *
+ * Pure functions for confidence values on the 0-1 scale (ADR-16 (4), contract rule 1): check a
+ * value, round it, rate it low, medium or high, and format it as a locale percent.
+ *
+ * Why not `Math.round(value * 100)`: it disagrees with Intl at half units. `Math.round(0.565 *
+ * 100)` is 56, because 0.565 * 100 is 56.49999… in binary floating point, while
+ * `Intl.NumberFormat('en-US', { style: 'percent' })` formats 0.565 as '57%': it rounds the
+ * decimal digits half away from zero ("halfExpand"). A level computed one way next to text
+ * formatted the other way shows '57%' rated below a 57% threshold. So rounding goes through Intl
+ * too, and `describeConfidence` rounds once, then rates and formats that same number.
+ *
+ * Rules for this module: no React, no DOM, no console and no module state, so every function
+ * is safe on the server and gives the same answer everywhere. Its one module-level call is
+ * marked `@__PURE__`, so bundles that do not use it drop it (OD-A3: this module sits in the
+ * app-shell chunk that every entry loads). Components emit warnings, from
+ * effects (ADR-30 (2)). There are no scale heuristics: 0-100 data is converted explicitly with
+ * `normalizeConfidence(value, 'percent')`.
+ *
+ * ICU caveat: locale output comes from the runtime's ICU data, which can differ between Node and
+ * browsers for some locales. Rounding does not: it always uses 'en-US' digits internally.
+ *
+ * @module components/AI/utils/confidence
+ */
+import type { AIConfidenceLevel, AIConfidenceThresholds } from '../types/hitl';
+/**
+ * Default confidence thresholds: 0.6 and above is medium, 0.85 and above is high. The single
+ * source for these numbers; `AIConfigProvider` and every component read them from here.
+ *
+ * Documented placeholders owned by product (ADR-06 (9)): override them with the provider's
+ * `thresholds` prop.
+ *
+ * @since 2.13.0
+ */
+export declare const DEFAULT_AI_CONFIDENCE_THRESHOLDS: Readonly<AIConfidenceThresholds>;
+/** Why a value was rejected: NaN or not a number at all ('0.5'), or outside 0-1 (92). */
+type InvalidReason = 'not-a-number' | 'out-of-range';
+/**
+ * Checks that a value is a confidence: a number from 0 to 1, inclusive. Otherwise it gives the
+ * reason: `'not-a-number'` (NaN, or not a number at all, such as the string '0.5') or
+ * `'out-of-range'` (below 0 or above 1, such as 92 on a 0-100 scale).
+ *
+ * @example
+ * ```ts
+ * validateConfidence(0.92); // { ok: true, value: 0.92 }
+ * validateConfidence(92); // { ok: false, reason: 'out-of-range' }
+ * validateConfidence('0.5'); // { ok: false, reason: 'not-a-number' }
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function validateConfidence(value: unknown): {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    reason: InvalidReason;
+};
+/**
+ * Fills in and checks thresholds. Missing keys take the defaults. When the result is not
+ * `0 <= medium <= high <= 1` (or a value is not a finite number), it returns the defaults and
+ * `valid: false`, so a caller can warn.
+ *
+ * @example
+ * ```ts
+ * resolveConfidenceThresholds({ high: 0.9 }); // { thresholds: { medium: 0.6, high: 0.9 }, valid: true }
+ * resolveConfidenceThresholds({ medium: 0.9, high: 0.5 }); // the defaults, valid: false
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function resolveConfidenceThresholds(partial?: Partial<AIConfidenceThresholds>): {
+    thresholds: Readonly<AIConfidenceThresholds>;
+    valid: boolean;
+};
+/**
+ * Rounds a 0-1 value to `fractionDigits` decimals of its percent, the same way Intl percent
+ * formatting rounds ("halfExpand" on the shortest decimal form): 0.565 becomes 0.57 at the
+ * default 0 digits, where `Math.round(0.565 * 100) / 100` gives 0.56.
+ *
+ * @param value A finite number; NaN and infinities are returned unchanged.
+ * @param fractionDigits Decimals of the percent to keep: an integer from 0 to 18. Default 0.
+ * @throws RangeError when `fractionDigits` is out of range.
+ *
+ * @example
+ * ```ts
+ * roundConfidence(0.565); // 0.57 (57%)
+ * roundConfidence(0.12345, 1); // 0.123 (12.3%)
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function roundConfidence(value: number, fractionDigits?: number): number;
+/**
+ * Rates a 0-1 value against the thresholds: `'high'` from `high` up, `'medium'` from `medium`
+ * up, `'low'` below. Both bounds are inclusive. The value is used as given; to rate what a
+ * user reads, rate the rounded value (`describeConfidence` does).
+ *
+ * @param thresholds Partial thresholds; missing or invalid ones fall back to the defaults.
+ * @returns The level, or `null` when the value is not a valid confidence.
+ *
+ * @example
+ * ```ts
+ * getConfidenceLevel(0.85); // 'high'
+ * getConfidenceLevel(0.5999); // 'low'
+ * getConfidenceLevel(92); // null
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function getConfidenceLevel(value: number, thresholds?: Partial<AIConfidenceThresholds>): AIConfidenceLevel | null;
+/**
+ * Formats a 0-1 value as a percent in `locale`, through `Intl.NumberFormat` with
+ * `style: 'percent'`. Pass a locale explicitly; when the app has none, pass 'en-US'.
+ *
+ * It formats any number as given (1.2 is '120%'); check the value first, or use
+ * `describeConfidence`, which does both.
+ *
+ * @param options.maximumFractionDigits Decimals of the percent: an integer from 0 to 18. Default 0.
+ * @throws RangeError when `locale` is not a valid language tag or the digits are out of range.
+ *
+ * @example
+ * ```ts
+ * formatConfidence(0.92, 'en-US'); // '92%'
+ * formatConfidence(0.92, 'de-DE'); // '92 %' (with a no-break space)
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function formatConfidence(value: number, locale: string, options?: {
+    maximumFractionDigits?: number;
+}): string;
+/**
+ * The one call a component needs: checks the value, rounds it once, then rates and formats
+ * that same rounded number, so the level and the text always agree (0.5999 reads '60%' and
+ * rates medium at the default thresholds).
+ *
+ * @param value Anything; only a number from 0 to 1 is valid.
+ * @param options.locale The locale for the text. Pass 'en-US' when the app has none.
+ * @param options.thresholds Partial thresholds; missing or invalid ones fall back to the defaults.
+ * @param options.fractionDigits Decimals of the percent: an integer from 0 to 18. Default 0.
+ *
+ * @example
+ * ```ts
+ * describeConfidence(0.565, { locale: 'en-US' });
+ * // { status: 'ok', rounded: 0.57, level: 'low', text: '57%' }
+ * describeConfidence(92, { locale: 'en-US' });
+ * // { status: 'invalid', reason: 'out-of-range' }
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function describeConfidence(value: unknown, options: {
+    thresholds?: Partial<AIConfidenceThresholds>;
+    locale: string;
+    fractionDigits?: number;
+}): {
+    status: 'ok';
+    rounded: number;
+    level: AIConfidenceLevel;
+    text: string;
+} | {
+    status: 'invalid';
+    reason: InvalidReason;
+};
+/**
+ * Converts a confidence to the 0-1 scale, from the scale you name. `'percent'` divides by 100
+ * (92 becomes 0.92); `'unit'` returns the value unchanged. It never guesses the scale and does
+ * not check the range: validate the result.
+ *
+ * @example
+ * ```ts
+ * normalizeConfidence(92, 'percent'); // 0.92
+ * normalizeConfidence(0.92, 'unit'); // 0.92
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function normalizeConfidence(value: number, from: 'percent' | 'unit'): number;
+export {};
+//# sourceMappingURL=confidence.d.ts.map

package/dist/components/AI/utils/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../../../../src/components/AI/utils/confidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE/E;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,EAAE,QAAQ,CAAC,sBAAsB,CAG5E,CAAC;AAEH,yFAAyF;AACzF,KAAK,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AAerD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAIrH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG;IACtF,UAAU,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IAC7C,KAAK,EAAE,OAAO,CAAC;CAChB,CAQA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,SAAI,GAAG,MAAM,CAKzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAOxH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAGxH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACjG;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAQ1H;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAEnF"}

package/dist/components/AI/utils/filters.d.ts

@@ -0,0 +1,31 @@
+import type { AIPlanFilter, AIStrings } from '../types/hitl';
+/**
+ * The display text of one filter.
+ *
+ * - `filter.label`, when set, is the whole text: the backend already wrote it.
+ * - Without an `operator`, an array value reads as `'in'` and any other value as `'eq'`
+ *   (`AIPlanFilter.operator`).
+ * - `'between'` takes `[min, max]`; a value of another shape is listed as for `'eq'`.
+ * - An array value under a single-value operator is joined into one list.
+ * - An operator this version does not know reads as `'eq'` (open unions, ADR-16 (4) rule 4).
+ *
+ * @param filter The filter, as the backend sent it.
+ * @param options.strings The AI strings, as `useAIStrings()` returns them. Default: the built-in
+ *   English strings.
+ * @param options.locale The locale for numbers and lists. Default 'en-US' (DN-13). An invalid
+ *   locale throws a RangeError, as `Intl` does.
+ *
+ * @example
+ * ```ts
+ * formatFilter({ field: 'Region', value: 'EMEA' }); // 'Region: EMEA'
+ * formatFilter({ field: 'Revenue', operator: 'gt', value: 1000 }); // 'Revenue greater than 1,000'
+ * formatFilter({ field: 'Region', value: ['EMEA', 'APAC'] }, { locale: 'de-DE' }); // 'Region: EMEA, APAC'
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function formatFilter(filter: AIPlanFilter, options?: {
+    strings?: AIStrings;
+    locale?: string;
+}): string;
+//# sourceMappingURL=filters.d.ts.map

package/dist/components/AI/utils/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../../../src/components/AI/utils/filters.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AA0B7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAoBjH"}

package/dist/components/AI/utils/responseText.d.ts

@@ -0,0 +1,8 @@
+import type { AIResponse } from '../types/response';
+/**
+ * The response as plain text, for the Copy action. See the module notes.
+ *
+ * @internal
+ */
+export declare function getResponsePlainText(response: AIResponse): string;
+//# sourceMappingURL=responseText.d.ts.map

package/dist/components/AI/utils/responseText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responseText.d.ts","sourceRoot":"","sources":["../../../../src/components/AI/utils/responseText.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,UAAU,EAA8B,MAAM,mBAAmB,CAAC;AAsFhF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAajE"}

package/dist/components/AI/utils/sources.d.ts

@@ -0,0 +1,110 @@
+import type { AISourceCategory } from '../AISourcesPanel';
+import type { AIStrings } from '../types/hitl';
+import type { AIResponseSource } from '../types/response';
+/**
+ * An ISO 8601 date or date-time as display text, the same on the server and in the browser.
+ *
+ * - A date-only value ('2026-06-30') is formatted in UTC, so it shows the same calendar day in
+ *   every time zone: 'June 30, 2026'.
+ * - A date-time ('2026-06-30T23:59:59Z') is formatted in `timeZone`, with the zone's short name:
+ *   'June 30, 2026 at 11:59 PM UTC'. A date-time without an offset is read as UTC, because the
+ *   runtime would otherwise read it in its own zone, which differs between server and browser.
+ * - Anything else, including an impossible date ('2026-02-31') and an empty string, is returned
+ *   unchanged.
+ *
+ * @param iso The date or date-time, as the data carries it (ADR-16 (4) rule 2).
+ * @param options.locale The locale of the text. Default 'en-US' (DN-13).
+ * @param options.timeZone The IANA time zone of a date-time. Default 'UTC'. Date-only values
+ *   ignore it.
+ *
+ * An invalid locale or time zone throws a RangeError, as `Intl` does.
+ *
+ * @example
+ * ```ts
+ * formatAsOf('2026-06-30'); // 'June 30, 2026'
+ * formatAsOf('2026-06-30T16:00:00Z', { timeZone: 'America/Los_Angeles' }); // 'June 30, 2026 at 9:00 AM PDT'
+ * formatAsOf('last quarter'); // 'last quarter'
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function formatAsOf(iso: string, options?: {
+    locale?: string;
+    timeZone?: string;
+}): string;
+/**
+ * `formatAsOf` with the locale and time zone of the nearest `AIConfigProvider`
+ * (`useAILocale()`, `useAITimeZone()`). Without a provider time zone it formats date-times in
+ * UTC during server rendering and hydration and in the browser's zone afterwards, so the markup
+ * hydrates without a mismatch (OD-F22 A). The returned function is stable while the locale and
+ * time zone stay the same.
+ *
+ * @example
+ * ```tsx
+ * function AsOf({ iso }: { iso: string }) {
+ *   const format = useFormatAsOf();
+ *   return <time dateTime={iso}>{format(iso)}</time>;
+ * }
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function useFormatAsOf(): (iso: string) => string;
+/**
+ * Options of {@link toSourceCategories}.
+ *
+ * @since 2.13.0
+ */
+export interface SourceCategoriesOptions {
+    /** The AI strings, as `useAIStrings()` returns them. Default: the built-in English strings. */
+    strings?: AIStrings;
+    /** The locale for numbers, lists and dates. Default 'en-US' (DN-13). */
+    locale?: string;
+    /** The IANA time zone of as-of date-times. Default 'UTC'. */
+    timeZone?: string;
+    /**
+     * `'type'` (default): one category per source type, in order of first appearance; a source
+     * without a type, or with one this version does not know, goes to 'other'. `'none'`: one
+     * category holding every source.
+     */
+    groupBy?: 'type' | 'none';
+}
+/**
+ * Turns a response's sources into AISourcesPanel categories.
+ *
+ * Every item carries the source's `number` (its 1-based place in `sources`, the same number
+ * inline source chips show), its `url` and its details; its label is the source's title.
+ * Category names and detail terms come from `ai.sources.*`.
+ *
+ * Numbering assumes `sources` only grows while a response streams (append-only); reordering
+ * sources renumbers them.
+ *
+ * @param sources The response's `sources`. `undefined` or empty gives `[]`.
+ *
+ * @example
+ * ```tsx
+ * <AISourcesPanel sources={toSourceCategories(response.sources)} />
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function toSourceCategories(sources: readonly AIResponseSource[] | undefined, options?: SourceCategoriesOptions): AISourceCategory[];
+/**
+ * {@link toSourceCategories} with the strings, locale and time zone of the nearest
+ * `AIConfigProvider`. The result keeps its identity while `sources`, `groupBy` and the provider
+ * values stay the same, so it can feed a memoized panel.
+ *
+ * @example
+ * ```tsx
+ * function ResponseSources({ response }: { response: AIResponse }) {
+ *   const categories = useSourceCategories(response.sources);
+ *   return categories.length > 0 ? <AISourcesPanel sources={categories} /> : null;
+ * }
+ * ```
+ *
+ * @since 2.13.0
+ */
+export declare function useSourceCategories(sources?: readonly AIResponseSource[], options?: {
+    groupBy?: 'type' | 'none';
+}): AISourceCategory[];
+//# sourceMappingURL=sources.d.ts.map

package/dist/components/AI/utils/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../../../src/components/AI/utils/sources.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,mBAAmB,CAAC;AAGxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAgB1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CA8BpG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,IAAI,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAIvD;AA8BD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,EAAE,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,EAAE,CAsB9I;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,EACrC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAO,GAC1C,gBAAgB,EAAE,CAMpB"}

package/dist/components/AIDigestCard/AIDigestCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIDigestCard.d.ts","sourceRoot":"","sources":["../../../src/components/AIDigestCard/AIDigestCard.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAc/B,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,SAAS,CAAC;AAuEjB,eAAO,MAAM,YAAY,0FA6JxB,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"AIDigestCard.d.ts","sourceRoot":"","sources":["../../../src/components/AIDigestCard/AIDigestCard.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAgB/B,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,SAAS,CAAC;AA2EjB,eAAO,MAAM,YAAY,0FAmLxB,CAAC;AAEF,eAAe,YAAY,CAAC"}