ionbase-ui 0.22.0 → 0.24.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/PhoneInput.json

@@ -122,6 +122,42 @@
       "origin": "own",
       "description": "Spread onto the dial-code `<button>`. This is how a country picker gets\nattached — see the note on scope below."
     },
+    "type": {
+      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+      "tags": {
+        "default": "'text'"
+      },
+      "default": "tel"
+    },
+    "disabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+      }
+    },
+    "form": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The current value (controlled)."
+    },
     "defaultValue": {
       "type": "string | undefined",
       "required": false,
@@ -359,36 +395,12 @@
       ],
       "default": "md"
     },
-    "type": {
-      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
-      "tags": {
-        "default": "'text'"
-      },
-      "default": "tel"
-    },
     "autoComplete": {
       "type": "string | undefined",
       "required": false,
       "origin": "aria",
       "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
     },
-    "disabled": {
-      "type": "boolean | undefined",
-      "required": false,
-      "origin": "own",
-      "tags": {
-        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-      }
-    },
-    "form": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
-    },
     "maxLength": {
       "type": "number | undefined",
       "required": false,
@@ -401,12 +413,6 @@
       "origin": "aria",
       "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
     },
-    "name": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
-    },
     "pattern": {
       "type": "string | undefined",
       "required": false,
@@ -419,12 +425,6 @@
       "origin": "aria",
       "description": "Temporary text that occupies the text input when it is empty."
     },
-    "value": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The current value (controlled)."
-    },
     "isDisabled": {
       "type": "boolean | undefined",
       "required": false,