{
  "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",
    "--ion-duration-cycle",
    "--ion-ease-linear",
    "--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
  }
}