{
  "name": "Timeline",
  "source": "src/components/Timeline.tsx",
  "propsType": "TimelineProps",
  "description": "Timeline — what happened to a record, in order: an audit log, a record's\nhistory, a ticket's activity.\n\nAN ORDERED LIST, because the events happened in an order and a screen\nreader should say \"3 of 12\". It is named by its `aria-label`, and each\nevent reads as one sentence: what happened, who did it, when.\n\nNOT FOR AGENT STEPS. An agent run is AgentActivity: it has a live status\nper step and announces the one in progress. A Timeline is history — every\nevent in it is done, so it has no status and says nothing on its own.\n\nTHE TIME IS A REAL `<time>`. Its `dateTime` is the exact instant, so the\nlabel can be relative (\"2 hours ago\") without losing it. The default label\nis a medium date and a short time; pass `locale` and `timeZone` when it\nrenders on a server, or the server's and the browser's can disagree.\n\nTHE LINE AND DOTS ARE DECORATION. The markers, and an event's icon, are\nhidden from assistive tech; the kind of event is in its title.",
  "import": "import { Timeline } from 'ionbase-ui';",
  "status": "stable",
  "summary": "What happened to a record, in order — an audit log, a record's history, a ticket's activity. An ordered list of TimelineItems, each one sentence: what happened, who did it, and when, in a real `<time>`. History only: every event is done, so there is no status and nothing is announced.",
  "useWhen": [
    "a record's history — who changed what, and when",
    "an audit log a person reads to find out what happened, newest first"
  ],
  "useInstead": [
    {
      "when": "the steps of an agent run",
      "use": "AgentActivity",
      "why": "it has a status per step and announces the one in progress; a Timeline is history and says nothing on its own"
    },
    {
      "when": "things the user has to read or act on — mentions, approvals, alerts",
      "use": "NotificationsPanel",
      "why": "it tracks read and unread and marks them; a Timeline is a record, not an inbox"
    },
    {
      "when": "events the user sorts, filters or selects",
      "use": "Table",
      "why": "a log searched by column, exported or acted on in bulk is a table of events, not a story"
    },
    {
      "when": "the entries are turns in a conversation — what a person asked and what an assistant answered",
      "use": "ChatMessage",
      "why": "a transcript is turns people took, each named by who and when; a Timeline is changes to a record"
    }
  ],
  "composition": {
    "order": [
      "Timeline",
      "TimelineItem"
    ],
    "note": "Name the list with `aria-label` — or `aria-labelledby` pointing at the card or section heading above it. Order the items as they are read, usually newest first. Each item's `title` is what happened, as a sentence; `actor` is who; `timestamp` is when; children are the detail — what it changed from and to. For a long history, show the latest and put a \"Show older\" Button below the list.",
    "example": "<Timeline aria-label=\"History\"><TimelineItem title=\"Paused the agent\" actor=\"Ada Reyes\" timestamp={event.at} /></Timeline>"
  },
  "a11y": {
    "requires": [
      "`aria-label` or `aria-labelledby` — the list's name, the history of what",
      "a `title` that says what happened in words — the icon and the line are not read"
    ],
    "guarantees": [
      "it is an `<ol>`: a screen reader says how many events there are and which one it is on",
      "each event reads in one order — what happened, who, when — then its detail",
      "the time is a `<time>` with the exact instant in `dateTime`, whatever its label says",
      "the line, the markers and any icon are hidden from assistive tech",
      "it renders on a server: no hooks, no effects"
    ],
    "notes": [
      "pass `locale` and `timeZone` to each item when rendering on a server, or its default label can differ from the browser's"
    ]
  },
  "antiPatterns": [
    {
      "dont": "<div className=\"timeline\">{events.map((e) => <div>…</div>)}</div>",
      "do": "<Timeline aria-label=\"History\">{events.map((e) => <TimelineItem … />)}</Timeline>",
      "why": "a column of divs is not a list: a screen reader cannot say how many events there are or skip past them"
    },
    {
      "dont": "a green dot for \"Approved\" and a red one for \"Rejected\", with the title \"Status changed\"",
      "do": "the title \"Approved the refund\" or \"Rejected the refund\"",
      "why": "the dots are hidden from assistive tech and fail WCAG 1.4.1 for everyone else; what happened belongs in the words"
    },
    {
      "dont": "<span>2 hours ago</span>",
      "do": "<TimelineItem timestamp={at} timestampLabel=\"2 hours ago\" … />",
      "why": "the relative label keeps the exact instant in `dateTime`, which a bare span throws away"
    }
  ],
  "stylesheet": "src/styles/timeline.css",
  "tokens": [
    "--border-default",
    "--border-strong",
    "--border-subtle",
    "--border-width-default",
    "--border-width-thick",
    "--font-family-sans",
    "--font-weight-semibold",
    "--icon-secondary",
    "--icon-size-xs",
    "--ion-timeline-marker",
    "--radius-full",
    "--spacing-12",
    "--spacing-16",
    "--spacing-2",
    "--spacing-24",
    "--spacing-4",
    "--spacing-8",
    "--surface-default",
    "--text-default",
    "--text-secondary",
    "--type-body-sm",
    "--type-body-sm-line-height",
    "--type-caption",
    "--type-caption-line-height"
  ],
  "props": {
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "TimelineItems, in the order they are read — usually newest first."
    }
  },
  "propCounts": {
    "own": 1,
    "aria": 0,
    "dom": 280,
    "other": 0
  }
}