@trinityui/design-system 2.11.1 → 2.13.0

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

@@ -2,79 +2,161 @@
  * @fileoverview AIChainOfThought component.
  * @module components/AI/AIChainOfThought
  *
- * Evolved Chain-of-Thought UI — shows AI reasoning steps in a digestible,
- * personable way. Inspired by Replit, Perplexity, and VS Code Coding Agent.
+ * Shows an AI agent's reasoning as a chain of phases: Understanding, Plan,
+ * Execution, Outputs and Insight.
+ *
+ * ## The look (owner mockups, 2026-10-08)
+ *
+ * One rounded outer card. At the top, the "Thought process" header: a Disclosure trigger with
+ * the AI mark (AIAvatar's gradient role), the title, a status line ("Reasoning in progress…",
+ * "Done · 4.2s", the waiting text or "A step failed"), one progress dot per phase (ai.progress
+ * done, ai.primary current, a mid gray pending, red failed, amber waiting) and the chevron. Under
+ * it a vertical timeline: each phase is a row with a soft circle marker (a thin green check on a
+ * success tint, a purple partial-ring spinner, a small gray dot, a red cross, an amber question
+ * mark) and a thin connector to the next row, then a bordered card with the bold title and the
+ * phase's `subtitle` as its one line. Thinking phases sit in the header's panel; output and
+ * insight phases continue the timeline outside it. Plan steps are gray numbered chips; tasks are
+ * rows with a plain gray check and a right-aligned time, the running one purple with a dotted
+ * spinner; a failed task (or one retrying after a failure) is a red box (see Errors). Output
+ * artifacts are file cards, the insight ends with "Insight confidence", its percent and a bar.
+ * Below the `compact` container width the card and phase paddings drop to 12px and the marker to
+ * 20px.
+ *
+ * ## Phase status
+ *
+ * Each `ChainPhase` has a status: `pending`, `active`, `completed`, `error` or
+ * `awaiting-input` (the phase waits for the user). `derivePhaseStatus()`
+ * (AIChainOfThought.utils.ts) decides it. An explicit `phase.status` always
+ * wins. Without one, a plan-review phase reads its plan's status and an
+ * execution phase its tasks; every other type is `completed`. The status comes
+ * from the data alone, so the parent moves a phase to any status by updating
+ * `phases`.
+ *
+ * | Phase without `status`                          | Derived status |
+ * |-------------------------------------------------|----------------|
+ * | plan-review, plan status `review` or none       | `awaiting-input` |
+ * | plan-review, plan status `replanning`           | `active`       |
+ * | plan-review, any other plan status              | `completed`    |
+ * | execution, a task is `error`                    | `error`        |
+ * | execution, a task is `awaiting-input`           | `awaiting-input` |
+ * | execution, every task is `completed`            | `completed`    |
+ * | execution, no tasks                             | `completed`    |
+ * | execution, a task is `running` or `retrying`    | `active`       |
+ * | execution, any other mix (for example `pending`) | `pending`     |
+ * | understanding, plan, output or insight          | `completed`    |
+ *
+ * Rows are checked in this order. `AIChainOfThought.test.tsx` reads this table
+ * and checks each row against `derivePhaseStatus()`.
+ *
+ * ## Plan review and waiting for the user (G-22)
+ *
+ * A `plan-review` phase hosts a plan the user confirms, edits or clarifies. It is
+ * always a thinking phase (never in the response, never a response, whatever
+ * `thinkingPhaseIds` says). Its body is the `plan-review` block renderer the
+ * chain is given (`blockRenderers`, or a host's provider), else AIPlanReview
+ * through `hitlBlockRenderers`, with a block whose id is the phase id; the
+ * renderer's events go to `onBlockEvent`. While any thinking
+ * phase is `awaiting-input`, the thought process and that phase stay open (a
+ * forced, controlled open that overrides a user's collapse), the auto-collapse
+ * waits, and the indicator under the phases reads "Plan's ready — needs your
+ * confirmation" (a plan) or "Needs your input" (the header's status line, or
+ * without the header the indicator under the phases, with an icon instead of
+ * the spinner). The plan-review body sits in its card under the title at every
+ * width. `showQuery` shows the query above the thought process.
+ *
+ * ## Screen readers (WI-44, ADR-19)
+ *
+ * The root is a `role="group"` named "Reasoning for {query}" (or "AI reasoning
+ * chain"), with `aria-busy` while a thinking phase is active. It is not a live
+ * container: by default (`announcements="transitions"`) the chain announces
+ * "Thinking" when the first thinking phase becomes active and "Response ready"
+ * when the final phases appear, once each, through `useAnnounce`. A chain that
+ * mounts already thinking or complete announces nothing for that state.
+ * `announcements="stream"` restores the polite live container; `"off"` is
+ * silent. Inside a thread (`InThreadContext`) the thread announces, so the
+ * chain stays silent and is never live.
+ *
+ * **Waiting for the user (G-22):** a phase that starts waiting after mount is
+ * announced once, politely, with the indicator's text ("Plan's ready — needs
+ * your confirmation" once per plan id and revision, else "Needs your input"),
+ * with `announcements="transitions"`, also inside a thread (through the
+ * thread's announcer, never a live region in the log). The hosted plan
+ * renderer's own ready announcement is suppressed (`BlockReadyAnnouncementSuppressed`),
+ * so a plan is read exactly once.
+ *
+ * **Errors (WI-11a):** a task whose status is `error` (or `retrying` with an
+ * `error`) is a red box: the error icon, its label and time in red, then its
+ * `error.code` and `error.message` in a white MUI Alert (severity error), a
+ * `role="group"` named by the code and message, never `role="alert"`, so no
+ * live region nests inside a chat log; then `error.resolution`, or for a
+ * retrying task its `retryDetail` in purple after three animated dots. A task that enters `error` after
+ * mount is announced once, assertively ("{label} failed: {message}"), unless
+ * `announcements` is `"off"` or `"stream"` (the live container reads it); a
+ * task already failed at mount is not. With `onTaskRetry`, the alert has a
+ * "Retry" button that calls `onTaskRetry(task, phase)` through useAsyncAction:
+ * pending, it is `aria-disabled` and `aria-busy` and keeps focus; a rejection
+ * shows AsyncOutcomeAlert with "Try again" and goes to `onActionError`
+ * (`{ source: 'task', phaseId, taskId }`), else to `reportError`. When the
+ * retry succeeds and the task leaves `error`, focus moves to the task's row.
+ * A `retrying` task without an error shows its `retryDetail` under its label.
+ *
+ * ## UI state (internal)
+ *
+ * The component owns this UI-only state; it is not a prop:
+ *
+ * - `collapsed` — whether the thinking phases sit collapsed behind the toggle
+ *   bar. Seeded by `defaultCollapsed`; set to `true` once, automatically (see
+ *   below).
+ * - `expanded` — per-phase expansion. A phase is seeded from its own
+ *   `defaultExpanded` (unset means open) the first time its id is seen,
+ *   including a phase that streams in after mount. Later toggles are kept.
  *
- * ## State Machine
- *
- * AIChainOfThought displays a sequence of `ChainPhase` objects. Each phase has
- * a derived `status` (see `derivePhaseStatus()`) based on its type-specific
- * completion signals:
- *
- * ```
- *                  ┌──────────────────────────────────────────┐
- *                  │             PHASE LIFECYCLE              │
- *                  └──────────────────────────────────────────┘
- *
- *     ┌─pending────► active ──► completed ──┐       ╳ error
- *     │                                      │       ▲
- *     │                                      ▼       │
- *     │                               (next phase    │
- *     │                                starts here)  │
- *     │                                              │
- *     └──────────── retry / reset ───────────────────┘
- * ```
- *
- * Phase-type-specific "active → completed" triggers:
- *
- * | Phase type     | Becomes `active` when           | Becomes `completed` when                          |
- * |----------------|---------------------------------|---------------------------------------------------|
- * | `understanding`| Has ≥1 thought bubble           | `phase.complete === true`                         |
- * | `plan`         | Has ≥1 step                     | `phase.complete === true`                         |
- * | `execution`    | Any task is not `pending`       | All tasks are `completed` or user set `complete`  |
- * | `output`       | Has artifacts or `complete`     | `phase.complete === true`                         |
- * | `insight`      | Has content or `complete`       | `phase.complete === true`                         |
- *
- * **Error state:** Any phase flips to `error` if its `error` field is set
- * (execution) or if `phase.status === 'error'` is explicitly set. Rendering
- * shows the ErrorBanner and a retry affordance.
- *
- * ## UI State (internal)
- *
- * The component owns the following UI-only state. Do NOT pass these as props —
- * they're affordances, not domain data:
+ * ## Parent-owned data
  *
- * - `collapsed: boolean` — whether the "thinking" phases are collapsed behind
- *   the toggle bar. Auto-flips to `true` when all thinking phases complete AND
- *   the final-response phase arrives (controlled by `hasAutoCollapsed` ref).
- * - `expanded: Record<phaseId, boolean>` — per-phase expansion state, seeded
- *   from each phase's `defaultExpanded` field.
+ * - `phases: ChainPhase[]` — the phases, each with a discriminated `type`. The
+ *   parent updates the array as the agent streams its reasoning.
+ * - `sources`, `relatedQuestions`, `suggestedActions` — shown once a final phase
+ *   (output or insight) appears, in the response AIMessage's `attachments` slot,
+ *   aligned with its content column (G-21).
  *
- * ## Parent-owned data
+ * ## The response footer (G-21)
  *
- * - `phases: ChainPhase[]` — array of phase objects, each with a discriminated
- *   `type` field. The parent is responsible for updating this over time as the
- *   AI streams its reasoning.
- * - `sources`, `relatedQuestions`, `suggestedActions` — presented after the
- *   final-response phase appears.
+ * The final phases render in one AIMessage. Its footer shows Copy always (without
+ * `onCopy` it writes the final phases' visible text to the clipboard) and every
+ * other action only when it is wired: the thumbs with `onFeedback`,
+ * `onFeedbackChange` or a controlled `feedback`; Share with `onShare`; Download
+ * with `onDownload`; Regenerate with `onRegenerate`. `actions`, `badges`,
+ * `feedbackControl`, `defaultFeedback` and `copyText` are passed through.
  *
- * ## Auto-collapse behavior
+ * ## Auto-collapse
  *
- * When all "thinking" phases (default: understanding / plan / execution) reach
- * `completed` AND one or more "final" phases (output / insight) appear, the
- * thinking group collapses automatically — only fires once, tracked via
- * `hasAutoCollapsed` ref so subsequent toggles stick.
+ * Thinking phases are understanding, plan and execution, or the ids in
+ * `thinkingPhaseIds`. When every thinking phase is `completed` and a final
+ * phase has started while the chain is mounted, the thinking group collapses.
+ * It happens once, tracked by the `hasAutoCollapsed` ref, so a later toggle by
+ * the user sticks. A chain that mounts already complete starts open (the owner's
+ * complete-state mockup); `defaultCollapsed` starts it closed. Final phases
+ * still `pending` are drawn in the timeline but are not a response yet (no
+ * AIMessage, no "Response ready").
  *
  * Features:
- * - Collapsible "Thought Process" toggle bar with phase dots & elapsed time
- * - Understanding phase with thought bubbles (supports bold/code), sources
- * - Plan phase with numbered steps and optional "Run" button
- * - Execution phase with sub-detail, error banners, retry flow, per-task timing
- * - Output phase with summary header, stats, artifact cards with format badges
- * - Insight phase with highlighted text, metrics grid, references section
- * - Loading spinner indicator while thinking
- * - Reuses AIMessage, AISourcesSection, and AIRelatedQuestions from the chat components
- * - Typing indicator, spinner, staggered entrance animations
+ * - The "Thought process" header: the AI mark, the status line with the
+ *   elapsed time, the progress dots and the chevron
+ * - Understanding phase with its thoughts as lines of text and sources;
+ *   thoughts and the insight body are read as safe-content HTML, markdown or
+ *   plain text (`contentFormat`)
+ * - Plan phase with numbered step chips and an optional "Run" button (a
+ *   contained Button)
+ * - Execution phase with per-task status, detail, timing, an error box with an
+ *   optional Retry button (`onTaskRetry`) and retry detail
+ * - Output phase with summary, stats and file cards (format and meta, an
+ *   optional bar glyph drawn from `chartData`)
+ * - Insight phase with highlighted text, the insight confidence, a labelled
+ *   list of metrics and references as an ordered list of AISource cards
+ * - Without the header, a "Generating response…" spinner while a thinking
+ *   phase is active
+ * - Reuses AIMessage, AISourcesPanel, AIRelatedQuestions and AISuggestedAction
+ *   from the chat components
  *
  * @example
  * ```tsx
@@ -89,12 +171,12 @@
 import React from 'react';
 import { Theme } from '@mui/material';
 import { type CSSObject } from '@mui/material/styles';
-import type { StepStatus, PhaseStatus, ChainSource, TaskError, ExecutionTask, ChainArtifact, OutputStat, InsightMetric, InsightReference, UnderstandingPhase, PlanPhase, ExecutionPhase, OutputPhase, InsightPhase, ChainPhase, AIChainOfThoughtProps } from './AIChainOfThought.types';
+import type { StepStatus, PhaseStatus, ChainSource, TaskError, ExecutionTask, ChainArtifact, OutputStat, InsightMetric, InsightReference, UnderstandingPhase, PlanPhase, PlanReviewPhase, ExecutionPhase, OutputPhase, InsightPhase, ChainPhase, AIChainOfThoughtProps } from './AIChainOfThought.types';
 /**
  * @internal
- * Primary tint behind `<mark>` per mode, calibrated so the highlight measures at
- * least 1.5:1 against the thought and insight surfaces and text.primary on it
- * at least 7:1 (asserted in AIChainOfThought.security.test.tsx).
+ * Primary tint behind `<mark>` on a light and on a dark surface, calibrated so the highlight
+ * measures at least 1.5:1 against the thought and insight surfaces and text.primary on it at
+ * least 7:1 (asserted in AIChainOfThought.security.test.tsx).
  */
 export declare const MARK_TINT: {
     readonly light: 0.24;
@@ -102,7 +184,8 @@ export declare const MARK_TINT: {
 };
 /**
  * @internal
- * Styles for the links and highlights the allowlist keeps. Links resolve the
+ * Styles for the links and highlights in chain content (the allowlist's, and
+ * AITextBlock's in markdown mode). Links are underlined and resolve the
  * theme's link role like MUI Link with its default props: the colour prop (MUI
  * Link's default, or a theme MuiLink defaultProps colour) gives the base colour,
  * and a root style override goes on top — an object, or a function called with
@@ -120,22 +203,21 @@ export declare const safeContentSx: {
         readonly backgroundColor: (theme: Theme) => string;
         readonly color: "text.primary";
         readonly borderRadius: "4px";
-        readonly px: 0.25;
+        readonly paddingInline: 0.25;
     };
     readonly '& mark a, & mark a:hover': {
         readonly color: "inherit";
     };
 };
-export type { StepStatus, PhaseStatus, ChainSource, TaskError, ExecutionTask, ChainArtifact, OutputStat, InsightMetric, InsightReference, UnderstandingPhase, PlanPhase, ExecutionPhase, OutputPhase, InsightPhase, ChainPhase, AIChainOfThoughtProps, };
+export type { StepStatus, PhaseStatus, ChainSource, TaskError, ExecutionTask, ChainArtifact, OutputStat, InsightMetric, InsightReference, UnderstandingPhase, PlanPhase, PlanReviewPhase, ExecutionPhase, OutputPhase, InsightPhase, ChainPhase, AIChainOfThoughtProps, };
 /**
  * AIChainOfThought — Evolved reasoning UI.
  *
- * Displays the AI agent's thinking process as a vertical chain of
- * collapsible phases: Understanding → Plan → Execution → Outputs → Insight.
+ * Displays the AI agent's thinking process as one card: the "Thought process" header and a
+ * vertical timeline of phases: Understanding → Plan → Execution → Output → Insight.
  *
- * Thinking phases (understanding, plan, execution) live inside a collapsible
- * "Thought Process" toggle bar. Output and Insight phases are always visible
- * as the final response.
+ * Thinking phases (understanding, plan, execution) sit in the header's collapsible panel. Output
+ * and Insight phases continue the timeline outside it, so they stay visible as the response.
  */
 export declare const AIChainOfThought: React.ForwardRefExoticComponent<AIChainOfThoughtProps & React.RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=AIChainOfThought.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"AIChainOfThought.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIChainOfThought.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AAEH,OAAO,KAAmD,MAAM,OAAO,CAAC;AACxE,OAAO,EAQL,KAAK,EAEN,MAAM,eAAe,CAAC;AACvB,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAY7D,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,aAAa,EACb,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,EACtB,MAAM,0BAA0B,CAAC;AASlC;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;CAAuC,CAAC;AAsB9D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;4BACT,KAAK,KAAG,SAAS;;0CAkBL,KAAK;;;;;;;;CAMxB,CAAC;AAGX,YAAY,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,aAAa,EACb,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,CAAC;AA6vCF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8FAwO5B,CAAC"}
+{"version":3,"file":"AIChainOfThought.d.ts","sourceRoot":"","sources":["../../../src/components/AI/AIChainOfThought.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyKG;AAEH,OAAO,KAA+D,MAAM,OAAO,CAAC;AACpF,OAAO,EAUL,KAAK,EACN,MAAM,eAAe,CAAC;AACvB,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAsCtF,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,aAAa,EACb,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,EACtB,MAAM,0BAA0B,CAAC;AASlC;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;CAAuC,CAAC;AA8B9D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;4BACT,KAAK,KAAG,SAAS;;0CA0BL,KAAK;;;;;;;;CAMxB,CAAC;AAiCX,YAAY,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,aAAa,EACb,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,CAAC;AA0kDF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,8FA0hB5B,CAAC"}