@trinityui/design-system 2.13.1 → 2.13.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @trinityui/design-system
 
+## 2.13.2
+
+### Patch Changes
+
+- **Additive**: New AIClarificationFlow asks a short series of clarifying questions in one card, one at a time. ([`c82db92`](https://github.com/Trinity-UI-Components/trinity-design-system/commit/c82db92da37d0b6c331c93beb65aaf766813787f))
+
+  It shows a header label, "1 of 4" progress, Back and Next (Done on the last step), an optional Skip, collapse and close. Each step is an AIClarificationPrompt, and Done hands every answer to `onComplete` as `{ [stepId]: { optionIds, otherText } }`, then shows a summary. Its strings are `ai.clarificationFlow.*`. It ships in a patch (Trinity 2.13 line) by a recorded owner exception in docs/process/api-patch-additions.json; the API check gains that exception file.
+
+  Storybook also gains two guides: Patterns/Evidence-Based Answer (one answer with clarification, reasoning, citations, confidence, verification, the query, sources, related questions and feedback, and which component to use when) and AI/Choosing AI Components (the AI components by job, with a quick-answers table).
+
+  AIChainOfThought: the thought process now shows as one slim line in every state: a spinner and "Reasoning in progress…" while it runs, "A step failed", "Plan's ready — needs your confirmation", or "✓ Thought process · Done · 4.2s". Opening the line shows the steps and the results. A phase that needs the person (a plan to confirm, a question, a failed task with Retry, a plan's Run) stays in view under the line. Pass `defaultCollapsed={false}` to start the card open.
+
+  AIMessage gains a `reasoning` slot and ChatThread's message slots a `reasoning` slot, so the thought process shows before the answer; InsightEnginePanel's and AICopilotPattern's `getReasoning` now fill it instead of the attachments.
+
+  Round shapes that rendered square are round again: the circle radius token is `'50%'`, and ten places appended `px` to it (`50%px`, which CSS drops). Fixed in StepList's step numbers (AIPlanReview's numbered steps), StatusIndicator's icon, dot and badge shapes (the green "Ready" ticks), its Legend, Timeline's dots, Modal's step dot, and the chart tooltip and legend markers. A test now fails if a unit is added to the circle token again.
+
+  StepList (AIPlanReview's steps, AIChainOfThought's tasks, AssessmentDrawer) centres the number, the first line of the step and its status (icon and text) on one line; the status sat about 4px high because an icon has no text baseline.
+
+  ThreadHistorySidebar's "History" title is now an h2 by default, not an h6, so it no longer skips heading levels. A new `headingLevel` prop sets it; InsightEnginePanel passes its own title's level, because the history sits beside the conversation, not inside it.
+
+  AppLayout's content area is keyboard-scrollable: while it overflows it takes `tabIndex={0}`, so a keyboard user can scroll content that holds no control (axe scrollable-region-focusable, WCAG 2.1.1). In the top-nav layout it is the `main` landmark; in the sidebar layout it is a group named by the new string `ai.appLayout.contentRegion` ('Page content'). It shows the theme's focus outline. Content that does not overflow is unchanged.
+
+  Visual review: the owner's local Storybook review on the release/2.13.2 branch (2026-10-16): AIClarificationFlow, AIChangeSummary, AIReplyBar, the slim AIChainOfThought line (thinking, error, plan, done; in the docked panel), the Evidence-based answer pattern, the Choosing AI components guide, the round StatusIndicator, Timeline and step-number shapes and StepList's alignment (light, dark)
+
 ## 2.13.1
 
 ### Patch Changes

package/MIGRATION.md

@@ -343,7 +343,7 @@ This file is written in release PRs. A feature PR describes its correction in it
 | 2.13.0 | `AIMessage` footer actions | **Before:** `role="toolbar"` named "AI response actions", without the toolbar arrow-key model. **After:** `role="group"` with the same name; every action keeps its own tab stop. **Verified by:** `AIMessage.test.tsx` (G-04c) | b, c, e | G-04b: `copyBehavior="callback"`; G-04c: none (a toolbar without its arrow-key model fails the behavior contract); G-04d: none (WCAG 1.4.11 contrast); G-04e: none (the toggle state is the WCAG 4.1.2 fix); AIActionsGroup row wrap: none (WCAG 1.4.10 Reflow); AIMessage footer wrap: none (WCAG 1.4.10 Reflow) | Query `getByRole('group', { name: 'AI response actions' })` in tests. |
 | 2.13.0 | `AIMessage` idle action icons | **Before:** `text.disabled`, below 3:1 against the surface (WCAG 1.4.11). **After:** `text.secondary`, 3:1 or more in light and dark; focus outline; 24 by 24 px targets. **Verified by:** `AIMessage.test.tsx` (G-04d) | b, c, e | G-04b: `copyBehavior="callback"`; G-04c: none (a toolbar without its arrow-key model fails the behavior contract); G-04d: none (WCAG 1.4.11 contrast); G-04e: none (the toggle state is the WCAG 4.1.2 fix); AIActionsGroup row wrap: none (WCAG 1.4.10 Reflow); AIMessage footer wrap: none (WCAG 1.4.10 Reflow) | Nothing in code. Visual baselines of AIMessage and its hosts change. |
 | 2.13.0 | `AIMessage` feedback thumbs | **Before:** No pressed state; pressing the same thumb twice called `onFeedback` twice. **After:** `AIFeedbackControl` toggles with `aria-pressed`; the second press clears the rating and calls only `onFeedbackChange(null)`. **Verified by:** `AIMessage.test.tsx` (G-04e) | b, c, e | G-04b: `copyBehavior="callback"`; G-04c: none (a toolbar without its arrow-key model fails the behavior contract); G-04d: none (WCAG 1.4.11 contrast); G-04e: none (the toggle state is the WCAG 4.1.2 fix); AIActionsGroup row wrap: none (WCAG 1.4.10 Reflow); AIMessage footer wrap: none (WCAG 1.4.10 Reflow) | If you counted repeated `onFeedback` calls, use `onFeedbackChange`, which reports every change including the clear. |
-| 2.13.0 | `AIActionsGroup` `direction="row"` | **Before:** A row did not wrap and overflowed a narrow host (a 320 to 360px docked AI panel). **After:** Actions wrap onto the next line with the same `spacing` (a flex gap); each action sizes to its label, grows to share its line and shrinks with `minWidth: 0`, `maxWidth: 100%`. **Verified by:** `AIActions.test.tsx` (320px and 360px hosts), ai-aiactions--actions-group-row-narrow | b, c, e | G-04b: `copyBehavior="callback"`; G-04c: none (a toolbar without its arrow-key model fails the behavior contract); G-04d: none (WCAG 1.4.11 contrast); G-04e: none (the toggle state is the WCAG 4.1.2 fix); AIActionsGroup row wrap: none (WCAG 1.4.10 Reflow); AIMessage footer wrap: none (WCAG 1.4.10 Reflow) | Nothing. A consumer `sx` on an action still wins. |
+| 2.13.0 | `AIActionsGroup` `direction="row"` | **Before:** A row did not wrap and overflowed a narrow host (a 320 to 360px docked AI panel). **After:** Actions wrap onto the next line with the same `spacing` (a flex gap); each action sizes to its label, grows to share its line and shrinks with `minWidth: 0`, `maxWidth: 100%`. **Verified by:** `AIActions.test.tsx` (320px and 360px hosts), ai-aiactionsgroup--actions-group-row-narrow | b, c, e | G-04b: `copyBehavior="callback"`; G-04c: none (a toolbar without its arrow-key model fails the behavior contract); G-04d: none (WCAG 1.4.11 contrast); G-04e: none (the toggle state is the WCAG 4.1.2 fix); AIActionsGroup row wrap: none (WCAG 1.4.10 Reflow); AIMessage footer wrap: none (WCAG 1.4.10 Reflow) | Nothing. A consumer `sx` on an action still wins. |
 | 2.13.0 | `AIMessage` footer (timestamp and actions) | **Before:** In a narrow host the footer stayed on one line: the timestamp broke over two lines and the thumbs stacked into a column. **After:** The footer wraps: the actions move under the timestamp, aligned to the end, and wrap as a group; the actions are spaced by a 4px flex gap. **Verified by:** ai-chatthread--docked-panel-widths play (320px host: thumbs side by side, timestamp on one line) | b, c, e | G-04b: `copyBehavior="callback"`; G-04c: none (a toolbar without its arrow-key model fails the behavior contract); G-04d: none (WCAG 1.4.11 contrast); G-04e: none (the toggle state is the WCAG 4.1.2 fix); AIActionsGroup row wrap: none (WCAG 1.4.10 Reflow); AIMessage footer wrap: none (WCAG 1.4.10 Reflow) | Nothing. A consumer `slotProps.footer` `sx` still wins. |
 | 2.13.0 | `ChatHistoryList` options button | **Before:** Hidden until hover (invisible on focus and touch), named 'Chat options' on every row, no menu-trigger state; the Delete icon was missing. **After:** Visible on focus, while its menu is open and on touch; named 'Options for {title}' (`ai.chatHistoryList.optionsFor`); `aria-haspopup="menu"` and `aria-expanded`; Delete, Pin and Unpin icons. **Verified by:** `ChatHistoryList.test.tsx` (WI-23b) | b | WI-23b: none | Tests that query `getByRole('button', { name: 'Chat options' })` use the per-row name, for example `'Options for Q4 revenue'`. |
 | 2.13.0 | `ResizablePanel` under `theme.direction: 'rtl'` | **Before:** Arrow keys and drag followed the physical layout (Left Arrow always widened a right-side panel). **After:** The arrow and the drag toward the content widen the panel. **Verified by:** `ResizablePanel.test.tsx` [WH-31] | b | H-31: none; H-32: none (use the panel header's Exit fullscreen and Close while fullscreen) | Nothing; an app that inverted the keys itself removes that. |

package/README.md

@@ -2,7 +2,7 @@
 
 <!-- catalog-counts:start intro -->
 
-Enterprise component platform built on **MUI 9** and **React 19** for [Trinity LifeSciences](https://trinitylifesciences.com). Provides 143 accessible React components (43 of them AI and human-in-the-loop components, 17 chart components and 13 page templates), 32 hooks, a 3-tier design token system, and a CSS-only package for non-React consumers, with the tokens, the React theme and the CSS package kept in parity.
+Enterprise component platform built on **MUI 9** and **React 19** for [Trinity LifeSciences](https://trinitylifesciences.com). Provides 146 accessible React components (46 of them AI and human-in-the-loop components, 17 chart components and 13 page templates), 32 hooks, a 3-tier design token system, and a CSS-only package for non-React consumers, with the tokens, the React theme and the CSS package kept in parity.
 
 <!-- catalog-counts:end intro -->
 
@@ -49,15 +49,15 @@ Enterprise component platform built on **MUI 9** and **React 19** for [Trinity L
 
 | Capability | Details |
 |---|---|
-| **143 Components** | Navigation, layout, AI, data display, inputs, feedback, charts |
-| **43 AI Components** | InsightEngine, ChatThread, AIMessage, AIChainOfThought, the human-in-the-loop blocks, voice input, explainability, sources, personas |
+| **146 Components** | Navigation, layout, AI, data display, inputs, feedback, charts |
+| **46 AI Components** | InsightEngine, ChatThread, AIMessage, AIChainOfThought, the human-in-the-loop blocks, voice input, explainability, sources, personas |
 | **17 Chart Components** | Line, bar, area, pie, donut, scatter, bubble, radial, gauge, composed, sparkline, plus the chart wrapper, tooltips and legends |
 | **13 Page Templates** | Dashboard, list-detail, settings, auth, catalog, wizard, report, the AI review queue and more, plus one pattern (`AICopilotPattern`) |
 | **3-Tier Design Tokens** | Base → Semantic → Component tokens; the React theme and the CSS variables are generated from the same source and kept in parity |
 | **Dark Mode** | Automatic light/dark themes with WCAG 2.2 AA color contrast |
 | **3 Theme Presets** | CRM (compact), Portal (accessible), Analytics (data-viz) |
 | **32 Hooks** | Debounce, clipboard, breakpoints, disclosure, roving tabindex, live announcements, and more |
-| **TypeScript-First** | 850 root exports with full type definitions |
+| **TypeScript-First** | 861 root exports with full type definitions |
 | **CSS-Only Package** | Angular, Vue, and static HTML support through 1186 `--trinity-*` CSS variables |
 | **80+ Brand Assets** | Gradient icons, background images, logos |
 | **Bundle Governance** | A size-limit ratchet on every public entry; each raise is measured and recorded |
@@ -97,7 +97,7 @@ Enterprise component platform built on **MUI 9** and **React 19** for [Trinity L
 
 | Package / Import | Exports | Use Case |
 |---|---:|---|
-| `@trinityui/design-system` | 850 | Full API: components, templates, patterns, hooks, tokens, themes and utilities |
+| `@trinityui/design-system` | 861 | Full API: components, templates, patterns, hooks, tokens, themes and utilities |
 | `@trinityui/design-system/essentials` | 45 | Quick start: the themes and the core components |
 | `@trinityui/design-system/theme` | 52 | Theme utilities only (tree-shakeable) |
 | `@trinityui/design-system/tokens` | 131 | Design tokens only (tree-shakeable) |
@@ -214,7 +214,7 @@ The AI components read their built-in strings from one catalog, which `AIConfigP
 
 ### 6. Without React
 
-Load the CSS package and use the `--trinity-*` variables; `data-theme="dark"` switches the mode. See [CSS-Only Usage](#css-only-usage) and the CSS AI agent guide in Storybook (Getting Started/AI Agent Guide (CSS)).
+Load the CSS package and use the `--trinity-*` variables; `data-theme="dark"` switches the mode. See [CSS-Only Usage](#css-only-usage) and the AI agent guide in Storybook (Getting Started/AI Agent Guide, "CSS only" track).
 
 For the full getting-started guide, see [docs/QUICK_START.md](./docs/QUICK_START.md) and the Getting Started page in Storybook.
 
@@ -287,9 +287,9 @@ The largest component category — a full suite for building AI-powered experien
 | Component | Description | Storybook |
 |---|---|---|
 | `InsightEngineInput` | The AI composer: send, stop while generating, mentions, models and sources, voice input, and an unavailable state with its reason | AI/InsightEngineInput |
-| `AIVoiceOverlay` | Voice input overlay with transcription | AI/Chat Components |
+| `AIVoiceOverlay` | Voice input overlay with transcription | AI/AIVoiceMode |
 | `AIVoiceMode` | Full-screen voice conversation mode: an orb that follows the conversation, a live transcript, mute and end | AI/AIVoiceMode |
-| `AIListeningIndicator` | Animated listening state indicator | AI/Chat Components |
+| `AIListeningIndicator` | Animated listening state indicator | AI/AIVoiceMode |
 | `PredictiveTextInput` | AI-powered autocomplete text input (OpenAI-compatible) | Form Inputs/PredictiveTextInput |
 
 #### AI Human in the Loop
@@ -299,6 +299,9 @@ The largest component category — a full suite for building AI-powered experien
 | `AIPlanReview` | The plan the AI proposes before it runs a query, for the user to review, correct and confirm (inline or in a dialog; `readOnly` for the record) | AI/AIPlanReview |
 | `AIReviewItem` | One answer in a golden-dataset review: the question, what produced the answer, and the reviewer's approve, edit or reject decision with its history | AI/AIReviewItem |
 | `AIClarificationPrompt` | A clarifying question the AI asks before it answers: options, a free-text answer and a typed result the backend can act on | AI/AIClarificationPrompt |
+| `AIClarificationFlow` | Two to five related clarifying questions in one card, answered one at a time, with progress, Back and Next | AI/AIClarificationFlow |
+| `AIChangeSummary` | What the AI changed in a document, on its version card: changed rows first, unchanged muted, Open | AI/AIChangeSummary |
+| `AIReplyBar` | The next step at the end of an AI answer: one primary reply and a few suggestions, locked after use | AI/AIReplyBar |
 | `AIQueryDisclosure` | The query behind an answer, shown on demand, with Copy | AI/AIQueryDisclosure |
 | `AIFeedbackControl` | Thumbs up and down on an answer, and the "Tell us what went wrong" flow | AI/AIFeedbackControl |
 | `AIFeedbackForm` | What went wrong with an answer: problem types, a comment and an optional rerun | AI/AIFeedbackForm |
@@ -313,7 +316,7 @@ The largest component category — a full suite for building AI-powered experien
 | `AITextBlock` | Text of an AI response: plain text, or lightweight markdown (bold, italic, code, links, headings, lists, quotes, fenced code) with opt-in `[^id]` source citations and `headingOffset` | AI/AITextBlock |
 | `AIChainOfThought` | The reasoning behind an answer: thinking, a plan awaiting confirmation, execution with failed tasks and Retry, and the output | AI/AIChainOfThought |
 | `AIExplainability` | Confidence scores and explainability panel | AI/AIExplainability |
-| `AISource` | One source citation | none yet |
+| `AISource` | One source citation | AI/AISourcesSection |
 | `AISourcesSection` | A simple list of source citations | AI/AISourcesSection |
 | `AISourcesPanel` | Source citations grouped by category | AI/AISourcesPanel |
 | `AISourceChip` | One source at the number, sentence, table cell or chart point it supports: a number or label chip that opens the source's details | AI/AISourceChip |
@@ -334,8 +337,8 @@ The largest component category — a full suite for building AI-powered experien
 | Component | Description | Storybook |
 |---|---|---|
 | `AISuggestedAction` | A suggested action as a pill button | AI/AISuggestedAction |
-| `AICircularAction` | A suggested action as a circular icon button | AI/AIActions |
-| `AIActionsGroup` | A group of suggested actions | AI/AIActions |
+| `AICircularAction` | A suggested action as a circular icon button | AI/AICircularAction |
+| `AIActionsGroup` | A group of suggested actions | AI/AIActionsGroup |
 | `AIContainer` | Themed container for AI content | AI/AIContainer |
 | `AIExpandableSection` | Collapsible section for AI detail panels | AI/AIExpandableSection |
 | `AIPersonaCard` | AI persona/agent identity card | AI/AIContainer |
@@ -364,9 +367,9 @@ These still work in 2.x and warn once in development; do not start new work with
 | Deprecated | Use instead | Storybook |
 |---|---|---|
 | `AIChatMessage` | `AIMessage` (and `UserMessage` for the user's turn) | AI/AIMessage |
-| `AIChatInput` | `InsightEngineInput`, or `ChatThread` for a whole conversation | AI/AIChat |
-| `AITypingIndicator` | `AIMessage`'s streaming state with `AIShimmer` | AI/AIChat |
-| `AIQuickReply` | `AISuggestedAction` or `AIActionsGroup` | AI/AIChat |
+| `AIChatInput` | `InsightEngineInput`, or `ChatThread` for a whole conversation | Deprecated/AIChat |
+| `AITypingIndicator` | `AIMessage`'s streaming state with `AIShimmer` | Deprecated/AIChat |
+| `AIQuickReply` | `AISuggestedAction` or `AIActionsGroup` | Deprecated/AIChat |
 | `QueryInput` | `InsightEngineInput` | AI/InsightEngineInput |
 | `AIFabLayout` | `AppLayout` with `navStyle="topnav"` and `aiTrigger="fab"` | Templates/AppLayout |
 
@@ -381,7 +384,7 @@ All AI components import from `@trinityui/design-system`. AI-specific design tok
 | Component | Import | Description |
 |---|---|---|
 | `DataTable` | `@trinityui/design-system/data-table` | AG Grid Enterprise powered — sorting, filtering, grouping, pivot, server-side row models |
-| `SimpleTable` | `@trinityui/design-system` | Lightweight table for simple data (no AG Grid dependency) |
+| `SimpleTable` | `@trinityui/design-system/essentials` | Lightweight table for simple data (no AG Grid dependency) |
 | `DataCard` | `@trinityui/design-system` | KPI/metric card with trend indicator and sparkline |
 | `DiffViewer` | `@trinityui/design-system` | Side-by-side or unified diff viewer |
 | `Timeline` | `@trinityui/design-system` | Vertical timeline with status indicators |

package/dist/IllustratedMessage.js

@@ -32,7 +32,7 @@ const Ut = ({
                 justifyContent: "center",
                 width: h.icon + 4,
                 height: h.icon + 4,
-                borderRadius: `${nt.borders.radius.circle}px`,
+                borderRadius: nt.borders.radius.circle,
                 // Perfect circle
                 backgroundColor: c.fill,
                 color: c.onFill