ionbase-ui 0.24.0 → 0.25.0

package/dist/meta/components.json

@@ -1,11 +1,231 @@
 {
   "package": "ionbase-ui",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useToast"
   ],
   "components": {
+    "AgentActivity": {
+      "name": "AgentActivity",
+      "source": "src/components/AgentActivity.tsx",
+      "propsType": "AgentActivityProps",
+      "description": "AgentActivity — what the agent is doing, in plain language.\n\nAn ordered list, because the steps happened in an order and a screen reader\nshould say \"3 of 7\". Not a log viewer: this is the account a person reads to\ndecide whether to let the run continue, so the text belongs in their\nlanguage — \"Searched the invoice archive\", not `searchIndex(q, {limit:50})`.\n\nSTATUS IS NEVER CARRIED BY THE ICON ALONE. Every step renders its status as\ntext as well as a glyph. The glyphs differ in shape rather than only in\ncolour, so the list survives greyscale, colour blindness and forced-colours\nmode — WCAG 1.4.1, which a row of coloured dots fails outright.\n\nONE POLITE ANNOUNCEMENT PER STEP, not one per render. The active step's text\nis announced when it changes, so a user who is not watching still knows where\nthe run has got to. Watching the DOM instead would re-announce on every\nunrelated update, which is the failure mode that makes people turn logs off.",
+      "import": "import { AgentActivity } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "An ordered, plain-language log of what the agent is doing. Status is text and shape, never colour alone.",
+      "useWhen": [
+        "a run takes long enough that the user needs to know where it has got to",
+        "a person will decide whether to let it continue — which means they need to read what it did"
+      ],
+      "useInstead": [
+        {
+          "when": "the output is prose rather than steps",
+          "use": "StreamingText"
+        },
+        {
+          "when": "you need a decision, not a report",
+          "use": "ApprovalGate"
+        },
+        {
+          "when": "it is one finished outcome",
+          "use": "Alert"
+        }
+      ],
+      "composition": {
+        "order": [
+          "AgentActivity",
+          "AgentActivityStep"
+        ],
+        "note": "An <ol>, so a screen reader can say \"3 of 7\" and the order is structural rather than typed into each row.",
+        "example": "<AgentActivity><AgentActivityStep status=\"done\">Searched the invoice archive</AgentActivityStep><AgentActivityStep status=\"active\">Reading 12 matches</AgentActivityStep></AgentActivity>"
+      },
+      "a11y": {
+        "role": "list",
+        "guarantees": [
+          "every step renders its status as visually hidden text as well as a glyph, and the glyphs differ in shape rather than only in colour — a row of coloured dots fails WCAG 1.4.1 outright",
+          "the active step is announced once, when it changes, in a polite live region",
+          "the active step's spinner stops under `prefers-reduced-motion`"
+        ],
+        "requires": [
+          "step text in the user's language — \"Searched the invoice archive\", not a function signature",
+          "`announceActive={false}` when several logs are on screen, or they narrate over each other"
+        ],
+        "notes": [
+          "The active step is read out of the children rather than taken as a prop. Two sources for one fact is how they come to disagree."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "raw tool calls or JSON as the step label",
+          "why": "this is the account a person reads to decide whether to let the run continue"
+        },
+        {
+          "dont": "more than one step with `status=\"active\"`",
+          "why": "the announcement names one thing, and two claims about what is happening now cannot both be true"
+        },
+        {
+          "dont": "several announcing logs on one screen",
+          "do": "`announceActive={false}` on all but one",
+          "why": "they interrupt each other and the user turns the whole thing off"
+        }
+      ],
+      "stylesheet": "src/styles/agent-activity.css",
+      "tokens": [
+        "--font-family-sans",
+        "--icon-error",
+        "--icon-primary",
+        "--icon-size-sm",
+        "--icon-success",
+        "--icon-tertiary",
+        "--spacing-2",
+        "--spacing-8",
+        "--text-default",
+        "--text-error",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        },
+        "announceActive": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Announce the step that just became active, once, in a polite live region.\n\nOn by default because the whole point of an activity log is knowing what\nthe agent is doing without watching it. Turn it off when several logs are\non screen at once, or they narrate over each other."
+        }
+      },
+      "propCounts": {
+        "own": 2,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "AgentActivityStep": {
+      "name": "AgentActivityStep",
+      "source": "src/components/AgentActivity.tsx",
+      "propsType": "AgentActivityStepProps",
+      "import": "import { AgentActivityStep } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One step in an activity log: what happened, in the user's language, with a status carried by shape and text.",
+      "useWhen": [
+        "a child of AgentActivity — it is not usable elsewhere"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a row in a dropdown",
+          "use": "MenuItem"
+        },
+        {
+          "when": "it is a data row",
+          "use": "TableRow"
+        }
+      ],
+      "variants": {
+        "status": {
+          "pending": {
+            "use": "the default — queued, not started"
+          },
+          "active": {
+            "use": "happening now. Only one step should carry it"
+          },
+          "done": {
+            "use": "finished successfully"
+          },
+          "failed": {
+            "use": "did not finish. Say why in `detail`"
+          },
+          "skipped": {
+            "use": "deliberately not run — a branch not taken, a cached result"
+          }
+        }
+      },
+      "slots": {
+        "children": {
+          "accepts": "text",
+          "note": "the step in plain language"
+        },
+        "detail": {
+          "accepts": "text",
+          "note": "the result, a count, a tool name — whatever makes the step checkable"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the status name is rendered as visually hidden text, so it is never carried by the glyph's colour alone",
+          "each status has a differently shaped glyph, which survives greyscale and forced-colours mode"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "`failed` with no `detail`",
+          "why": "a failure the reader cannot diagnose is just a red mark"
+        },
+        {
+          "dont": "using it outside AgentActivity",
+          "why": "it renders an <li>, which is only valid inside a list"
+        }
+      ],
+      "stylesheet": "src/styles/agent-activity.css",
+      "tokens": [
+        "--font-family-sans",
+        "--icon-error",
+        "--icon-primary",
+        "--icon-size-sm",
+        "--icon-success",
+        "--icon-tertiary",
+        "--spacing-2",
+        "--spacing-8",
+        "--text-default",
+        "--text-error",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "What the agent did, in the user's language. Not a function name."
+        },
+        "status": {
+          "type": "AgentActivityStatus | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "pending",
+            "active",
+            "done",
+            "failed",
+            "skipped"
+          ]
+        },
+        "detail": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The result, a tool name, a count — whatever makes the step checkable."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 0,
+        "dom": 278,
+        "other": 0
+      }
+    },
     "AgentStop": {
       "name": "AgentStop",
       "source": "src/components/AgentStop.tsx",
@@ -1836,6 +2056,404 @@
         "other": 0
       }
     },
+    "Citation": {
+      "name": "Citation",
+      "source": "src/components/Citation.tsx",
+      "propsType": "CitationProps",
+      "description": "Citation — the inline marker.\n\nTHE MARKER IS NOT THE NAME. Rendered naively, a superscript \"1\" announces as\n\"link, 1\", which tells a screen-reader user nothing about whether to follow\nit. The visible marker stays a number; the accessible name is\n\"Source 1: <source>\". The number is for the sighted reader's eye and the\nsentence is for everyone.\n\nNOT A TOOLTIP. A tooltip cannot be reached on touch and closes on the way to\nit; attribution has to survive both. It is a real link, or a real\nnon-interactive marker when there is nowhere to go.\n\nWITHOUT `href` IT IS NOT A LINK. A citation to a phone call or an internal\ndocument has no address, and rendering a dead anchor for it puts an\nunfollowable link in the page's link list. It becomes a plain marked-up\nreference instead.",
+      "import": "import { Citation } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The inline source marker. The visible number is for the eye; the accessible name is the sentence.",
+      "useWhen": [
+        "a claim in generated text is drawn from a specific source the reader can check",
+        "attribution has to survive being read aloud, on touch, and in a links list"
+      ],
+      "useInstead": [
+        {
+          "when": "the source needs a full row with a passage",
+          "use": "CitationListItem"
+        },
+        {
+          "when": "it is an ordinary link in prose",
+          "use": "Link"
+        },
+        {
+          "when": "you were about to put the source in a hover-only hint",
+          "use": "Popover",
+          "why": "a tooltip cannot be reached on touch and closes on the way to it"
+        }
+      ],
+      "a11y": {
+        "role": "link when `href` is set, note otherwise",
+        "guarantees": [
+          "the accessible name is \"Source <index>: <source>\", never the bare number — a superscript 1 announces as \"link, 1\", which tells a screen-reader user nothing about whether to follow it",
+          "without `href` it renders a marker rather than a dead anchor, so an unfollowable link never enters the page's link list"
+        ],
+        "requires": [
+          "`source` naming what is being cited",
+          "an `index` matching the footer row, if there is one"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a bare superscript number with no accessible name",
+          "why": "\"link, 1\" is not attribution"
+        },
+        {
+          "dont": "an empty `href` for a source with no address",
+          "do": "omit `href`",
+          "why": "a dead anchor is announced as a link and goes nowhere"
+        },
+        {
+          "dont": "putting the source only in a tooltip",
+          "why": "undiscoverable on touch, and gone before it can be read"
+        }
+      ],
+      "stylesheet": "src/styles/citation.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--radius-xs",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-primary-subtle",
+        "--surface-primary-subtle-hover",
+        "--text-link",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "index": {
+          "type": "string | number",
+          "required": true,
+          "origin": "own",
+          "description": "The marker shown inline — usually a number matching the footer list."
+        },
+        "source": {
+          "type": "string",
+          "required": true,
+          "origin": "own",
+          "description": "What is being cited. Required: it is the link's accessible name, and a\ncitation a reader cannot identify without following it is not attribution."
+        },
+        "href": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Where it goes. Omit for a source with no address — a document, a call."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 0,
+        "dom": 284,
+        "other": 0
+      }
+    },
+    "CitationList": {
+      "name": "CitationList",
+      "source": "src/components/Citation.tsx",
+      "propsType": "CitationListProps",
+      "description": "The footer list. An `<ol>` so the numbering is structural rather than typed\ninto each row, and so a screen reader can say how many sources there are\nbefore the reader commits to hearing them.",
+      "import": "import { CitationList } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The footer list of sources, as an ordered list so the count and order are structural.",
+      "useWhen": [
+        "several claims cite sources and the reader should be able to see them all at once"
+      ],
+      "useInstead": [
+        {
+          "when": "there is one source and it belongs in the sentence",
+          "use": "Link"
+        },
+        {
+          "when": "it is tabular data with more than a source per row",
+          "use": "Table"
+        }
+      ],
+      "composition": {
+        "order": [
+          "CitationList",
+          "CitationListItem"
+        ],
+        "example": "<CitationList><CitationListItem index={1} source=\"Q3 filing\" href=\"/q3\">Revenue rose 4%.</CitationListItem></CitationList>"
+      },
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "rendered as plain text, not a heading element — it should not enter the document outline as a section"
+        },
+        "children": {
+          "accepts": "CitationListItem"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "an <ol>, so a screen reader can say how many sources there are before the reader commits to hearing them",
+          "list markers are hidden in CSS while the semantics stay, because the visible number must match the inline Citation's exactly"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a <div> stack of sources",
+          "why": "the count and the ordering are the useful part, and only a list carries them"
+        },
+        {
+          "dont": "numbers that disagree with the inline markers",
+          "why": "the marker is a promise about where to look"
+        }
+      ],
+      "stylesheet": "src/styles/citation.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--radius-xs",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-primary-subtle",
+        "--surface-primary-subtle-hover",
+        "--text-link",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        },
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Heading above the list. Rendered as plain text, not a heading element."
+        }
+      },
+      "propCounts": {
+        "own": 2,
+        "aria": 0,
+        "dom": 280,
+        "other": 0
+      }
+    },
+    "CitationListItem": {
+      "name": "CitationListItem",
+      "source": "src/components/Citation.tsx",
+      "propsType": "CitationListItemProps",
+      "import": "import { CitationListItem } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One source row: its number, what it is, and the passage it supports.",
+      "useWhen": [
+        "a child of CitationList"
+      ],
+      "useInstead": [
+        {
+          "when": "it is the inline marker in the prose",
+          "use": "Citation"
+        }
+      ],
+      "slots": {
+        "children": {
+          "accepts": "text",
+          "note": "the quoted or summarised passage this source supports"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the visible number is `aria-hidden`; the row is named by its source text, which is what a reader needs to hear",
+          "without `href` the source renders as text rather than a dead link"
+        ],
+        "requires": [
+          "`source` naming what is being cited"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a bare URL as the `source`",
+          "why": "a screen reader spells it out character by character, and it names nothing"
+        }
+      ],
+      "stylesheet": "src/styles/citation.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--radius-xs",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-primary-subtle",
+        "--surface-primary-subtle-hover",
+        "--text-link",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "index": {
+          "type": "string | number",
+          "required": true,
+          "origin": "own"
+        },
+        "source": {
+          "type": "string",
+          "required": true,
+          "origin": "own"
+        },
+        "href": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The quoted or summarised passage this citation supports."
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 0,
+        "dom": 278,
+        "other": 0
+      }
+    },
+    "ConfidenceIndicator": {
+      "name": "ConfidenceIndicator",
+      "source": "src/components/ConfidenceIndicator.tsx",
+      "propsType": "ConfidenceIndicatorProps",
+      "description": "ConfidenceIndicator — how much to trust the thing next to it.\n\nTHERE IS NO PERCENTAGE PROP, AND THERE WILL NOT BE ONE\n\n\"87% confident\" reads as a measurement. Almost nowhere is it one: it is\nusually a softmax score, a heuristic, or a number a model produced about\nitself — none of which are calibrated probabilities, and all of which invite\na reader to treat two digits of precision as real. Three levels cannot\noverclaim in that way.\n\n`basis` IS REQUIRED FOR THE SAME REASON. A level with nothing behind it is\ndecoration that changes behaviour: people act on \"high confidence\" whether or\nnot anything justifies it. Making the justification a required prop is the\nonly enforcement available here, and it is a type error rather than a policy\n— which is the strongest kind this system can offer.\n\nIt renders as text plus a three-bar meter, never the meter alone. The bars\ndiffer in filled COUNT, not only in colour, so the reading survives greyscale\nand forced-colours mode.",
+      "import": "import { ConfidenceIndicator } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "How much to trust the thing next to it — three levels with a required basis, never a percentage.",
+      "useWhen": [
+        "a generated answer varies in reliability and the reader should weigh it",
+        "you can say what the confidence rests on"
+      ],
+      "useInstead": [
+        {
+          "when": "the answer is wrong or missing rather than uncertain",
+          "use": "Alert"
+        },
+        {
+          "when": "you want to show where the claim came from",
+          "use": "Citation",
+          "why": "a source is stronger than a confidence level, and often what the reader actually wanted"
+        },
+        {
+          "when": "it is a status rather than a reliability",
+          "use": "Badge"
+        }
+      ],
+      "variants": {
+        "level": {
+          "low": {
+            "use": "thin or conflicting evidence. One bar, warning colour"
+          },
+          "medium": {
+            "use": "reasonable support with real gaps. Two bars"
+          },
+          "high": {
+            "use": "corroborated, and you can say by what. Three bars"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the level is spelled out in text, so it never depends on the meter",
+          "the meter differs in filled COUNT rather than only in colour, and in forced-colours mode filled bars are solid while empty ones are outlined"
+        ],
+        "requires": [
+          "`basis` — a type error if omitted, and the reason this component exists rather than a coloured dot"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "asking for a percentage prop",
+          "why": "\"87% confident\" reads as a measurement and almost never is one — usually a softmax score or a model's claim about itself, neither of which is a calibrated probability. Three levels cannot overclaim that way"
+        },
+        {
+          "dont": "a vague basis like \"model output\"",
+          "why": "it satisfies the type and defeats the purpose — say \"3 of 4 sources agree\" or \"single unverified source\""
+        },
+        {
+          "dont": "high confidence on every response",
+          "why": "an indicator that never varies is decoration that still changes behaviour"
+        }
+      ],
+      "stylesheet": "src/styles/confidence-indicator.css",
+      "tokens": [
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-information",
+        "--icon-success",
+        "--icon-tertiary",
+        "--icon-warning",
+        "--radius-2xs",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-8",
+        "--text-default",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "level": {
+          "type": "ConfidenceLevel",
+          "required": true,
+          "origin": "own",
+          "values": [
+            "low",
+            "medium",
+            "high"
+          ]
+        },
+        "basis": {
+          "type": "string",
+          "required": true,
+          "origin": "own",
+          "description": "What the level is based on. REQUIRED, and the reason this component exists\nrather than a coloured dot: a confidence with no stated basis is a number\nthe reader has no way to weigh. \"3 of 4 sources agree\", \"no matching\nrecords found\", \"single unverified source\"."
+        },
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Override the level's word. Keep it a word, not a percentage."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
     "Divider": {
       "name": "Divider",
       "source": "src/components/Divider.tsx",
@@ -2552,13 +3170,13 @@
           "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
         },
         "enterKeyHint": {
-          "type": "\"enter\" | \"done\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+          "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
           "required": false,
           "origin": "aria",
           "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
           "values": [
-            "enter",
             "done",
+            "enter",
             "go",
             "next",
             "previous",
@@ -4149,13 +4767,13 @@
           "description": "Class names for the control box (`.ion-input`). Always lands here —\nnever on the form-field wrapper. Use `wrapperClassName` for that."
         },
         "enterKeyHint": {
-          "type": "\"enter\" | \"done\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+          "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
           "required": false,
           "origin": "aria",
           "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
           "values": [
-            "enter",
             "done",
+            "enter",
             "go",
             "next",
             "previous",
@@ -5394,6 +6012,105 @@
         "other": 0
       }
     },
+    "StreamingText": {
+      "name": "StreamingText",
+      "source": "src/components/StreamingText.tsx",
+      "propsType": "StreamingTextProps",
+      "description": "StreamingText — model output arriving a token at a time.\n\nIT IS NOT A LIVE REGION, AND THAT IS THE WHOLE DESIGN\n\nThe obvious implementation — `aria-live=\"polite\"` on the container — is the\none that makes a screen reader unusable. Every token mutation queues an\nannouncement, so the user hears the answer re-read, stuttered, dozens of\ntimes, and cannot get ahead of it. `aria-live=\"off\"` is not an oversight\nhere; it is the accessible choice.\n\nWhat it does instead: `aria-busy` while streaming, so assistive tech knows\nthe region is unsettled and can wait. The text is ordinary readable content\nthroughout — a screen-reader user navigates into it whenever they want,\nexactly like sighted users reading ahead of the cursor.\n\nANNOUNCING COMPLETION IS THE CALLER'S CALL, not this component's. Some\nsurfaces want \"response complete\"; a chat with ten turns on screen does not\nwant ten of them. Render your own `role=\"status\"` when you want it.\n\nTHE HEIGHT IS RESERVED, NOT ANIMATED. `minLines` holds space in `lh` units so\nthe content below stays still. A container that grows token by token drags\nthe whole page, which is worse for someone using magnification than the wait.\n\nThe cursor is CSS and `aria-hidden`. It stops blinking under\n`prefers-reduced-motion` — a blinking element is a WCAG 2.3.1 concern and a\ngenuine problem for some vestibular and attention conditions.",
+      "import": "import { StreamingText } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Model output arriving a token at a time, in a container that does not move. Deliberately not a live region.",
+      "useWhen": [
+        "rendering a response that streams in rather than arriving whole",
+        "the reader should be able to start reading before generation finishes"
+      ],
+      "useInstead": [
+        {
+          "when": "the text is already complete",
+          "use": "Alert",
+          "why": "nothing about this component helps once there is nothing left to arrive"
+        },
+        {
+          "when": "you are showing progress through steps rather than producing text",
+          "use": "AgentActivity"
+        }
+      ],
+      "a11y": {
+        "role": "region when `label` is set, none otherwise",
+        "guarantees": [
+          "`aria-live=\"off\"`, deliberately — a polite live region re-announces the whole answer on every token, which makes a streaming response unusable with a screen reader",
+          "`aria-busy` while streaming, so assistive tech knows the region is unsettled",
+          "the text stays ordinary readable content throughout, so a screen-reader user can read ahead exactly as a sighted user does",
+          "the cursor is `aria-hidden`, is a styled box rather than a text character, and stops blinking under `prefers-reduced-motion` (WCAG 2.3.1)"
+        ],
+        "requires": [
+          "announcing completion yourself, with your own `role=\"status\"`, if the surface wants it — a chat with ten turns on screen does not want ten announcements",
+          "`label` when the region needs a name of its own"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "wrapping it in `aria-live=\"polite\"`",
+          "why": "every token queues an announcement; the user hears the answer stuttered dozens of times and cannot get ahead of it"
+        },
+        {
+          "dont": "letting the container grow token by token with no reserved height",
+          "do": "`minLines`",
+          "why": "the content below climbs the screen while someone is reading it, which is worse under magnification than the wait"
+        },
+        {
+          "dont": "a text-character cursor like ▌",
+          "why": "some screen readers read it aloud even inside an aria-hidden span"
+        }
+      ],
+      "stylesheet": "src/styles/streaming-text.css",
+      "tokens": [
+        "--font-family-sans",
+        "--ion-streaming-min-lines",
+        "--text-default",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The text so far. Re-render with more of it; this component appends nothing."
+        },
+        "isStreaming": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "More is still arriving. Shows the cursor and marks the region busy."
+        },
+        "minLines": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Rows of height to hold while the text is short, so the page below does not\nclimb the screen as tokens arrive. Costs blank space at the start and buys\na layout that does not move under a reader."
+        },
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible name for the region."
+        },
+        "hideCursor": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Hide the trailing cursor. The text still marks itself busy."
+        }
+      },
+      "propCounts": {
+        "own": 5,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
     "TabItem": {
       "name": "TabItem",
       "source": "../../node_modules/.pnpm/react-stately@3.48.0_react@19.2.8/node_modules/react-stately/dist/types/src/collections/Item.d.ts",