ionbase-ui 0.22.0 → 0.25.0

package/dist/meta/AgentStop.json

@@ -0,0 +1,164 @@
+{
+  "name": "AgentStop",
+  "source": "src/components/AgentStop.tsx",
+  "propsType": "AgentStopProps",
+  "description": "AgentStop — the always-visible way to end a run.\n\nNOT OPTIONAL, AND NOT BEHIND A MENU. A user who cannot stop an agent is\nwatching it, not supervising it. Human oversight of an automated process is\na compliance surface in regulated contexts, not a UX preference, and the\ncontrol that provides it has to be present and reachable at the moment it is\nwanted — not two clicks into an overflow menu.\n\nWHY IT IS NOT JUST `<Button variant=\"destructive\">`\n\nThree things it owns that a Button does not:\n\n  It keeps its place while stopping. A control that vanishes the instant it\n  is pressed leaves the user unsure whether the press registered, and the\n  run is usually still going. It stays, relabels, and disables — the layout\n  does not move.\n\n  It announces. The label change is only announced to a screen reader if the\n  button happens to hold focus, which it usually does not when a run was\n  started elsewhere. A polite live region says \"Stopping\" once.\n\n  It is not destructive-red. Stopping is a normal, expected, reversible-in-\n  spirit action — you can run it again. Colouring it like `delete` teaches\n  hesitation about the one control that must never be hesitated over.\n\nWHAT IT DOES NOT DO. It does not stop anything. It reports intent; the\ncaller aborts the request, closes the stream and settles the state. A stop\nbutton that resolves optimistically while tokens keep arriving is worse than\nnone, because it lies about a guarantee the user is relying on.",
+  "import": "import { AgentStop } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The always-visible way to end a running agent. Not optional, and not behind a menu.",
+  "useWhen": [
+    "anything runs long enough that a person might want it to stop — a generation, a tool chain, a batch job",
+    "the run was started by the user and is still going"
+  ],
+  "useInstead": [
+    {
+      "when": "the action is instant and there is nothing to interrupt",
+      "use": "Button"
+    },
+    {
+      "when": "you are asking permission before something happens rather than ending something already happening",
+      "use": "ApprovalGate"
+    },
+    {
+      "when": "the thing to undo has already finished",
+      "use": "Toast",
+      "why": "an undo affordance belongs with the confirmation of what was done"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "inside a toolbar or beside an inline activity row"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a full-width run surface where stopping is the primary available action"
+      }
+    }
+  },
+  "a11y": {
+    "role": "button",
+    "guarantees": [
+      "the control keeps its place while stopping — it relabels and disables rather than disappearing, so the layout does not move under the pointer",
+      "the transition to stopping is announced once through a polite live region, because the label change alone is only heard if the button happens to hold focus",
+      "`stopOnEscape` ignores Escape raised inside a dialog, so closing a modal never cancels a background run"
+    ],
+    "requires": [
+      "keeping it rendered and visible for the whole run — a stop control that scrolls away or hides in an overflow menu is the failure this component exists to prevent"
+    ],
+    "notes": [
+      "It does not stop anything. It reports intent; aborting the request and settling the state is the caller's. A stop that resolves optimistically while output keeps arriving lies about the one guarantee the user is relying on."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "putting the stop control in an overflow menu",
+      "why": "a user who cannot reach it is watching the agent, not supervising it"
+    },
+    {
+      "dont": "disabling it while the run is going",
+      "why": "the only correct disabled state is `isStopping` — after the request, never before"
+    },
+    {
+      "dont": "unmounting it the moment it is pressed",
+      "do": "pass `isStopping`",
+      "why": "the run is usually still going, and a control that vanishes leaves the user unsure the press registered"
+    },
+    {
+      "dont": "styling it as destructive",
+      "why": "stopping is normal and repeatable; red teaches hesitation about the one control that must never be hesitated over"
+    },
+    {
+      "dont": "`stopOnEscape` on a page with modals over the run",
+      "why": "Escape already means dismiss to every overlay in this system"
+    }
+  ],
+  "stylesheet": "src/styles/agent-stop.css",
+  "tokens": [
+    "--border-default",
+    "--border-error",
+    "--border-focus",
+    "--border-strong",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--icon-size-xs",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-md",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-20",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-40",
+    "--spacing-48",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-error-subtle",
+    "--surface-error-subtle-hover",
+    "--surface-muted",
+    "--text-default",
+    "--text-error",
+    "--text-secondary",
+    "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "onStop": {
+      "type": "() => void",
+      "required": true,
+      "origin": "own",
+      "description": "Called when the user asks the run to stop."
+    },
+    "isStopping": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The request is in flight. The control stays visible and keeps its place;\nit does not disappear while the thing it cancels is still running."
+    },
+    "label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Visible label."
+    },
+    "stoppingLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Visible label once `isStopping` is set."
+    },
+    "size": {
+      "type": "AgentStopSize | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "stopOnEscape": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Bind Escape, at the document, to stop the run.\n\nOff by default and deliberately so: Escape already means \"dismiss the\nthing in front of me\" to every modal, popover and menu in this system, and\na document-level handler would cancel a background run when the user meant\nto close a dialog. Turn it on only where the run IS the foreground task."
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 286,
+    "other": 0
+  }
+}

package/dist/meta/ApprovalGate.json

@@ -0,0 +1,255 @@
+{
+  "name": "ApprovalGate",
+  "source": "src/components/ApprovalGate.tsx",
+  "propsType": "ApprovalGateProps",
+  "description": "ApprovalGate — a proposed action, held until a person decides.\n\nThe human-in-the-loop control. An agent proposes; this is where a person\napproves, rejects, or amends before anything happens. In regulated contexts\ndemonstrable human oversight is a compliance surface rather than a nicety,\nwhich is why this is a first-class component and not a Modal with two\nbuttons in it.\n\nIT ENFORCES NOTHING, AND SAYING SO IS THE POINT\n\nThis renders a decision. It does not gate execution — the caller does, by not\nacting until `onApprove` fires. A component that *looked* like it enforced a\npolicy would be the worst possible thing to ship here: teams would rely on a\nguarantee that lives entirely in their own call site. `risk` changes emphasis\nand nothing else, for the same reason.\n\nNOT A MODAL, DELIBERATELY\n\nA modal steals focus and hides the page. But the page is the evidence: the\nuser needs the plan, the diff, the tool call and the context in front of them\nwhile deciding. This sits inline, keeps everything visible, and never\ntraps focus — an approval a user was rushed through is not oversight.\n\nNEITHER BUTTON IS FOCUSED ON MOUNT. Autofocusing approve turns a decision\ninto an Enter keypress on a page the user has not read. Focus is moved to the\nregion's heading instead, so a screen-reader user lands on what is being\nasked rather than on the answer.\n\nTHE RESOLVED STATES ARE NOT DECORATION. `approved`, `rejected` and `expired`\nreplace the actions with what happened, so the record of the decision stays\non the page. `expired` exists because an approval request that nobody answers\nis the common real outcome, and a gate that sits pending for ever is\nindistinguishable from one that is broken.",
+  "import": "import { ApprovalGate } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A proposed action held until a person approves, rejects or amends it. It renders the decision; it does not enforce it.",
+  "useWhen": [
+    "an agent proposes something with consequences — spending, sending, deleting, deploying, changing permissions",
+    "a regulated or audited process needs demonstrable human oversight at a specific point",
+    "the proposal is worth showing in full, in context, before it runs"
+  ],
+  "useInstead": [
+    {
+      "when": "the action is already happening and needs stopping",
+      "use": "AgentStop"
+    },
+    {
+      "when": "a person initiated the action themselves and only needs to confirm it",
+      "use": "Modal",
+      "why": "confirming your own request is a dialog; reviewing something proposed for you is a decision"
+    },
+    {
+      "when": "you are reporting what happened rather than asking",
+      "use": "Alert"
+    }
+  ],
+  "variants": {
+    "risk": {
+      "low": {
+        "use": "reversible and cheap — a draft, a local edit. Neutral surface"
+      },
+      "medium": {
+        "use": "the default. Real but recoverable consequences"
+      },
+      "high": {
+        "use": "spending, sending externally, deleting, granting access. Warning surface, deliberately not error"
+      }
+    },
+    "status": {
+      "pending": {
+        "use": "the default, and the only state with actions"
+      },
+      "approved": {
+        "use": "resolved — the actions are replaced by the record"
+      },
+      "rejected": {
+        "use": "resolved, declined"
+      },
+      "expired": {
+        "use": "nobody answered. The common real outcome, and the reason a gate cannot sit pending for ever"
+      }
+    }
+  },
+  "slots": {
+    "title": {
+      "accepts": "text",
+      "note": "required, and the region's accessible name. Name the action and its object — \"Delete 14 projects\", never \"Confirm action\""
+    },
+    "children": {
+      "accepts": "any",
+      "note": "the evidence: the plan, the diff, the tool call. This is what the person is deciding about"
+    },
+    "resolution": {
+      "accepts": "text",
+      "note": "shown in place of the actions once resolved; defaults to the status"
+    }
+  },
+  "a11y": {
+    "role": "region, named by its title",
+    "guarantees": [
+      "neither button is focused on mount — autofocusing approve turns a decision into an Enter keypress on an unread page",
+      "the title is programmatically focusable, so the caller can move focus to the question rather than to an answer",
+      "reject precedes approve in the DOM, so a keyboard reaches the safe answer first",
+      "resolution is announced once through a polite live region",
+      "focus is never trapped: an approval a user was rushed through is not oversight"
+    ],
+    "requires": [
+      "not acting until `onApprove` fires — this component gates nothing on its own",
+      "a `title` that names the action and its object"
+    ],
+    "notes": [
+      "`risk` changes emphasis and nothing else. It does not add confirmation, does not disable anything, and must never be read as a policy the component enforces."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "treating the gate as the enforcement point",
+      "why": "it renders a decision. If your code acts before `onApprove`, there is no gate — only a picture of one"
+    },
+    {
+      "dont": "putting it in a Modal",
+      "why": "the page is the evidence; hiding it to ask about it removes what the decision needs"
+    },
+    {
+      "dont": "autofocusing the approve button",
+      "why": "Enter on an unread page is not oversight, and it is exactly what an audit will look for"
+    },
+    {
+      "dont": "an approve-only gate with no reject",
+      "why": "a decision with one answer is a notification wearing a button"
+    },
+    {
+      "dont": "`onEdit` when the proposal cannot actually be amended",
+      "why": "an edit button that discards the edit is worse than no edit button"
+    },
+    {
+      "dont": "leaving gates pending indefinitely",
+      "do": "the `expired` status",
+      "why": "a gate nobody answered is indistinguishable from one that is broken"
+    }
+  ],
+  "stylesheet": "src/styles/approval-gate.css",
+  "tokens": [
+    "--border-default",
+    "--border-disabled",
+    "--border-focus",
+    "--border-information",
+    "--border-strong",
+    "--border-success",
+    "--border-warning-strong",
+    "--border-width-default",
+    "--border-width-thick",
+    "--border-width-thicker",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-semibold",
+    "--icon-information",
+    "--icon-secondary",
+    "--icon-size-md",
+    "--icon-success",
+    "--icon-tertiary",
+    "--icon-warning",
+    "--ion-approval-accent",
+    "--ion-approval-border",
+    "--ion-approval-icon",
+    "--ion-approval-surface",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-md",
+    "--radius-sm",
+    "--radius-xs",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-disabled",
+    "--surface-hover",
+    "--surface-information-subtle",
+    "--surface-muted",
+    "--surface-primary",
+    "--surface-primary-hover",
+    "--surface-warning-subtle",
+    "--text-default",
+    "--text-disabled",
+    "--text-information",
+    "--text-on-color",
+    "--text-secondary",
+    "--text-success",
+    "--text-warning",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "title": {
+      "type": "React.ReactNode",
+      "required": true,
+      "origin": "own",
+      "description": "What is being approved, stated as the action and its object — \"Delete 14\nprojects\", not \"Confirm action\". Required: it is the region's accessible\nname, and a decision the user cannot name is not a decision."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Why it stopped here, and what happens on approval."
+    },
+    "risk": {
+      "type": "ApprovalGateRisk | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "How much is at stake. Drives emphasis only — it does NOT change what the\ncomponent enforces, because the component enforces nothing.",
+      "values": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "status": {
+      "type": "ApprovalGateStatus | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Where the decision has got to. `pending` is the only state with buttons.",
+      "values": [
+        "pending",
+        "approved",
+        "rejected",
+        "expired"
+      ]
+    },
+    "onApprove": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "onReject": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "onEdit": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Offer \"edit\" as a third way out. Omit it when the proposal cannot be\namended — an approve/reject pair the user cannot influence is honest;\nan edit button that discards their edit is not."
+    },
+    "approveLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "rejectLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "editLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "isSubmitting": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "A decision is in flight. Both actions disable; neither disappears."
+    },
+    "resolution": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Shown in place of the actions once the decision is made."
+    }
+  },
+  "propCounts": {
+    "own": 12,
+    "aria": 0,
+    "dom": 275,
+    "other": 0
+  }
+}

package/dist/meta/Avatar.json

@@ -113,10 +113,10 @@
       "origin": "own",
       "description": "Matches the Figma `Size` variant: Mini 24, Small 32, Medium 40, Large 48.",
       "values": [
-        "mini",
         "sm",
         "md",
-        "lg"
+        "lg",
+        "mini"
       ]
     },
     "shape": {

package/dist/meta/AvatarGroup.json

@@ -103,10 +103,10 @@
       "required": false,
       "origin": "own",
       "values": [
-        "mini",
         "sm",
         "md",
-        "lg"
+        "lg",
+        "mini"
       ]
     },
     "max": {

package/dist/meta/Citation.json

@@ -0,0 +1,101 @@
+{
+  "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
+  }
+}

package/dist/meta/CitationList.json

@@ -0,0 +1,94 @@
+{
+  "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
+  }
+}