ionbase-ui 0.32.0 → 0.38.0

package/dist/meta/index.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.32.0",
+  "version": "0.38.0",
   "usage": "Pick a component here, then read dist/meta/<Name>.json for its full contract.",
   "hooks": [
     "useToast"
@@ -170,6 +170,15 @@
           "warning",
           "error",
           "information"
+        ],
+        "size": [
+          "sm",
+          "md",
+          "lg"
+        ],
+        "shape": [
+          "pill",
+          "rounded"
         ]
       },
       "detail": "dist/meta/Badge.json",
@@ -262,6 +271,25 @@
       "detail": "dist/meta/Divider.json",
       "hasIntent": true
     },
+    "EmptyState": {
+      "summary": "The state a region shows when it has nothing to show, and why — first run, no results, no access, or a failed fetch.",
+      "status": "stable",
+      "variants": {
+        "reason": [
+          "error",
+          "first-run",
+          "no-results",
+          "no-access"
+        ],
+        "size": [
+          "inline",
+          "page",
+          "panel"
+        ]
+      },
+      "detail": "dist/meta/EmptyState.json",
+      "hasIntent": true
+    },
     "FullCard": {
       "summary": "A full-bleed row: a text column beside a framed media panel, mirrored by `alignment`.",
       "status": "stable",

package/dist/meta/patterns/AgentRun.json

@@ -0,0 +1,136 @@
+{
+  "name": "AgentRun",
+  "summary": "A single agent task from start to finish: what it is doing, what it produced, and a way to stop it at any point.",
+  "useWhen": [
+    "an agent performs work that takes long enough for the user to wonder whether it is still running",
+    "the work happens in steps the user would want to see — a tool call, a search, a write",
+    "the output arrives incrementally rather than all at once"
+  ],
+  "composes": [
+    "AgentActivity",
+    "AgentActivityStep",
+    "AgentStop",
+    "StreamingText",
+    "Alert",
+    "Badge"
+  ],
+  "structure": [
+    "A header row carrying the task name and the AgentStop control. The stop is the first thing on screen and it stays there for the whole run.",
+    "An AgentActivity list of AgentActivityStep, one per step, in the order they happened. Exactly one step is `active` at a time.",
+    "The result below the log, in a StreamingText with `isStreaming` true until the run ends.",
+    "An Alert only when the run fails or is stopped — not for ordinary progress, which the step log already carries."
+  ],
+  "states": {
+    "loading": {
+      "must": "Show the step log from the first step, not after the first result. Set `isStreaming` on the StreamingText and give it `minLines` so the region does not grow under the reader. AgentStop stays enabled the entire time.",
+      "why": "a spinner with no steps and no stop is indistinguishable from a hang, and the user's only remaining move is to reload the page and lose the run"
+    },
+    "empty": {
+      "must": "Before the first step exists, render the header and the AgentStop and nothing else. Do not render an empty AgentActivity list.",
+      "why": "an empty `<ol>` announces as a list of zero items, which tells a screen-reader user the run produced nothing rather than that it has not started"
+    },
+    "error": {
+      "must": "Mark the step that failed `status=\"failed\"`, leave every earlier step visible, and put an Alert with `intent=\"error\"` below the log naming which step failed and what it was doing. Clear `isStreaming`.",
+      "why": "replacing the log with an error message destroys the only record of how far the run got, which is the thing a user needs to decide whether to retry or start over"
+    },
+    "partial": {
+      "must": "When the user stops a run mid-flight, keep every completed step, mark the interrupted one `status=\"skipped\"`, and say plainly what was and was not done. Leave whatever the run already wrote on screen.",
+      "why": "a stopped agent has usually already changed something, and a UI that clears itself on stop hides the side effects the user stopped it to prevent"
+    }
+  },
+  "propsUsed": {
+    "AgentActivity": [
+      "announceActive"
+    ],
+    "AgentActivityStep": [
+      "status",
+      "detail"
+    ],
+    "AgentStop": [
+      "onStop",
+      "isStopping",
+      "label",
+      "size",
+      "stopOnEscape"
+    ],
+    "StreamingText": [
+      "isStreaming",
+      "minLines",
+      "label",
+      "hideCursor"
+    ],
+    "Alert": [
+      "intent",
+      "title"
+    ],
+    "Badge": [
+      "intent",
+      "size"
+    ]
+  },
+  "variantsUsed": {
+    "AgentActivityStep": {
+      "status": [
+        "pending",
+        "active",
+        "done",
+        "failed",
+        "skipped"
+      ]
+    },
+    "AgentStop": {
+      "size": [
+        "sm",
+        "md"
+      ]
+    },
+    "Alert": {
+      "intent": [
+        "error",
+        "warning"
+      ]
+    },
+    "Badge": {
+      "intent": [
+        "neutral",
+        "success",
+        "error"
+      ]
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`announceActive` on AgentActivity when the run is unattended — it announces only the step that becomes active, once",
+      "an AgentStop that is reachable by keyboard without passing through the step log",
+      "a `label` on StreamingText when the output is not preceded by a visible heading"
+    ],
+    "notes": [
+      "StreamingText is deliberately NOT a live region. `aria-live=\"polite\"` on streaming output queues an announcement per token, so the answer is re-read and stuttered dozens of times. The step log is where progress is announced; the output is ordinary readable text.",
+      "Do not also wrap the step log in your own live region. AgentActivity owns one, and two announcing regions produce interleaved speech.",
+      "`stopOnEscape` is off by default on purpose. Turn it on only when the run owns the whole screen — inside a dialog, Escape must close the dialog."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a stop control that appears only after the run has been going for a few seconds",
+      "why": "the moment a user most wants to stop is the moment they realise the agent misunderstood, which is usually within the first second"
+    },
+    {
+      "dont": "removing the AgentStop while the stop is in progress",
+      "do": "AgentStop",
+      "why": "the control vanishing is read as the click having failed; `isStopping` keeps it in place and says what is happening"
+    },
+    {
+      "dont": "collapsing finished steps to a single \"Done\" line",
+      "why": "the log is the audit trail — it is what the user reads when the result is wrong, and it is worthless after the fact"
+    },
+    {
+      "dont": "raw tool names or JSON in the step text",
+      "why": "\"Calling search_documents({q: ...})\" describes the implementation; \"Searching your documents\" describes the work, and only one of them is useful to the person deciding whether to stop"
+    },
+    {
+      "dont": "more than one step marked `active`",
+      "why": "the status is what tells a screen-reader user where the run is, and two active steps make that unanswerable"
+    }
+  ]
+}

package/dist/meta/patterns/AssistantAnswer.json

@@ -0,0 +1,130 @@
+{
+  "name": "AssistantAnswer",
+  "summary": "A generated answer presented so the reader can check it: the text, what it was drawn from, and how far to trust it.",
+  "useWhen": [
+    "an answer is generated from sources the user could go and read",
+    "the answer will be acted on — a policy question, a number, a recommendation",
+    "the answer may be wrong in ways that are not visible from the text alone"
+  ],
+  "composes": [
+    "StreamingText",
+    "Citation",
+    "CitationList",
+    "CitationListItem",
+    "ConfidenceIndicator",
+    "Alert",
+    "Link"
+  ],
+  "structure": [
+    "The answer in a StreamingText, with inline Citation markers at the claims they support — not gathered at the end.",
+    "A CitationList below the answer, one CitationListItem per source, numbered to match the inline markers.",
+    "A ConfidenceIndicator beside the answer, with `basis` saying what the level is derived from.",
+    "An Alert only when the answer is degraded — sources unavailable, knowledge stale, question outside scope."
+  ],
+  "states": {
+    "loading": {
+      "must": "Stream the text with `isStreaming` and `minLines` set. Render no ConfidenceIndicator and no CitationList until the answer is complete.",
+      "why": "a confidence level attached to half an answer is a claim about text that does not exist yet, and citations that appear one by one move the reader's place on every token"
+    },
+    "empty": {
+      "must": "When there is no answer — no sources matched, the question was out of scope — say that in words and render neither an empty CitationList nor a ConfidenceIndicator.",
+      "why": "an answer with no sources and no confidence shown reads as a confident answer, which is the opposite of what an empty result means"
+    },
+    "error": {
+      "must": "Keep whatever text arrived, mark it plainly as incomplete with an Alert of `intent=\"warning\"`, and drop the ConfidenceIndicator entirely.",
+      "why": "a truncated answer that keeps its confidence badge is rated on evidence it never finished reading"
+    },
+    "partial": {
+      "must": "When some sources were unreachable, cite the ones that were, lower the `level`, and name the gap in `basis` — \"3 of 7 sources; 4 unavailable\".",
+      "why": "an answer built on half its evidence looks identical to one built on all of it, and `basis` is the only place that difference can be stated"
+    }
+  },
+  "propsUsed": {
+    "StreamingText": [
+      "isStreaming",
+      "minLines",
+      "label"
+    ],
+    "Citation": [
+      "index",
+      "source",
+      "href"
+    ],
+    "CitationList": [
+      "label"
+    ],
+    "CitationListItem": [
+      "index",
+      "source",
+      "href"
+    ],
+    "ConfidenceIndicator": [
+      "level",
+      "basis",
+      "label"
+    ],
+    "Alert": [
+      "intent",
+      "title"
+    ],
+    "Link": [
+      "variant",
+      "href"
+    ]
+  },
+  "variantsUsed": {
+    "ConfidenceIndicator": {
+      "level": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "Alert": {
+      "intent": [
+        "warning",
+        "information"
+      ]
+    },
+    "Link": {
+      "variant": [
+        "standalone"
+      ]
+    }
+  },
+  "a11y": {
+    "requires": [
+      "an `index` on every Citation that matches its CitationListItem — the number is how a screen-reader user connects the two",
+      "a `basis` on ConfidenceIndicator, which the component requires and which must describe evidence, not feeling",
+      "a `label` on StreamingText when no visible heading precedes the answer"
+    ],
+    "notes": [
+      "A Citation with no `href` renders as a note, not a dead link. Pass `href` only when the source is genuinely reachable by the reader.",
+      "Citation's accessible name is `Source <index>: <source>`, so the source string should name the document, not say \"link\" or \"here\".",
+      "StreamingText is not a live region. Announcing that the answer finished is the caller's decision — a thread with ten answers on screen does not want ten announcements."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a percentage — \"87% confident\"",
+      "do": "ConfidenceIndicator",
+      "why": "the number is not calibrated against anything, and a false precision is trusted more than the vague statement it replaced"
+    },
+    {
+      "dont": "citations gathered only at the end of the answer",
+      "why": "the reader cannot tell which claim each source supports, so the list documents that sources exist rather than what they establish"
+    },
+    {
+      "dont": "citing a source the reader cannot open",
+      "why": "an unreachable citation is decoration that raises trust without supplying any way to check it"
+    },
+    {
+      "dont": "a confidence level derived from the model's own token probabilities and presented as certainty about the world",
+      "why": "fluency and correctness are different quantities, and only one of them is being measured"
+    },
+    {
+      "dont": "hiding the sources behind a disclosure that defaults closed",
+      "why": "evidence that takes a click to reach is evidence nobody checks"
+    }
+  ]
+}

package/dist/meta/patterns/HumanApproval.json

@@ -0,0 +1,139 @@
+{
+  "name": "HumanApproval",
+  "summary": "An agent stops and asks before doing something consequential, and a person approves, rejects or edits it.",
+  "useWhen": [
+    "the action spends money, sends something to a third party, deletes data, or changes access",
+    "the action is irreversible by the person who would have to undo it",
+    "a regulation or an internal policy requires a human decision on the record — the EU AI Act's human-oversight duty is the common case"
+  ],
+  "composes": [
+    "ApprovalGate",
+    "AgentActivity",
+    "AgentActivityStep",
+    "AgentStop",
+    "Alert"
+  ],
+  "structure": [
+    "The gate appears in place, where the run reached it — inside the step log, not in a dialog that covers it.",
+    "The AgentActivityStep that is waiting stays `active`; the ApprovalGate is its `detail`.",
+    "An ApprovalGate whose `title` names the action and its object, with the specifics — amount, recipient, record count — as `children`.",
+    "`risk` set from the consequence, not from the agent's confidence.",
+    "After the decision, `status` becomes `approved`, `rejected` or `expired` and `resolution` records who decided and when."
+  ],
+  "states": {
+    "loading": {
+      "must": "While the decision is being submitted, set `isSubmitting` — the gate keeps its buttons in place and disables them. Do not remove the gate or advance the step log until the server confirms.",
+      "why": "an optimistically-advanced run tells the user the action was approved before anything approved it, which is the one thing this pattern exists to prevent"
+    },
+    "empty": {
+      "must": "Render no ApprovalGate when nothing is waiting. A queue view with no pending items says so in words and does not render an empty gate shell.",
+      "why": "a gate with no action in it still shows Approve and Reject buttons, and a user who presses one has approved nothing while believing they approved something"
+    },
+    "error": {
+      "must": "If the decision fails to submit, keep `status=\"pending\"`, clear `isSubmitting`, and show an Alert with `intent=\"error\"` inside the gate. The action must not proceed.",
+      "why": "a failed approval that looks like a successful one is an unapproved action running with a human's name on it"
+    },
+    "expired": {
+      "must": "Set `status=\"expired\"` when the window closes, state what happened by default in `resolution`, and remove the decision buttons.",
+      "why": "a gate that sits pending forever hides that the agent already gave up, and buttons that no longer do anything are worse than no buttons"
+    }
+  },
+  "propsUsed": {
+    "ApprovalGate": [
+      "title",
+      "risk",
+      "status",
+      "onApprove",
+      "onReject",
+      "onEdit",
+      "approveLabel",
+      "rejectLabel",
+      "isSubmitting",
+      "resolution"
+    ],
+    "AgentActivity": [
+      "announceActive"
+    ],
+    "AgentActivityStep": [
+      "status",
+      "detail"
+    ],
+    "AgentStop": [
+      "onStop",
+      "label",
+      "size"
+    ],
+    "Alert": [
+      "intent",
+      "title"
+    ]
+  },
+  "variantsUsed": {
+    "ApprovalGate": {
+      "risk": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "status": [
+        "pending",
+        "approved",
+        "rejected",
+        "expired"
+      ]
+    },
+    "AgentActivityStep": {
+      "status": [
+        "active",
+        "done",
+        "skipped"
+      ]
+    },
+    "Alert": {
+      "intent": [
+        "error",
+        "warning"
+      ]
+    },
+    "AgentStop": {
+      "size": [
+        "sm"
+      ]
+    }
+  },
+  "a11y": {
+    "requires": [
+      "a `title` that names the action and the object — it is the gate's accessible name",
+      "`risk` set from consequence, so the level is the same for the same action every time",
+      "reject reachable before approve by keyboard, which the component's DOM order already guarantees"
+    ],
+    "notes": [
+      "ApprovalGate autofocuses nothing, deliberately. A dialog that focuses Approve turns Enter on an unread screen into consent.",
+      "Do not put the gate in a Modal that traps focus and hides the run behind it. The evidence for the decision is the step log, and a person cannot judge an action they can no longer see.",
+      "`risk` is a label on the consequence, not a colour scheme. Using `high` for emphasis on a routine action is how a team learns to ignore it."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "\"The agent wants to continue. Approve?\"",
+      "why": "it names neither the action nor its object, so the only available answer is a reflex — and a reflex is not oversight"
+    },
+    {
+      "dont": "an approval that also acts as the progress indicator",
+      "do": "the AgentRun pattern",
+      "why": "conflating \"I am working\" with \"I need you\" teaches the user to dismiss both"
+    },
+    {
+      "dont": "approve-all across a queue of unrelated actions",
+      "why": "one click covering many consequences is indistinguishable from no gate at all, and it is the failure regulators look for"
+    },
+    {
+      "dont": "a countdown that approves on expiry",
+      "why": "silence is not consent; an expired gate must default to the safe outcome, which is not doing the thing"
+    },
+    {
+      "dont": "hiding the gate's earlier steps once a decision is made",
+      "why": "the record of what was approved, on what evidence, is the artefact an audit asks for"
+    }
+  ]
+}

package/dist/meta/patterns/index.json

@@ -1,8 +1,45 @@
 {
   "package": "ionbase-ui",
-  "version": "0.32.0",
+  "version": "0.38.0",
   "usage": "A pattern is a documented composition of components, not a component. Read one here, then read the contracts of what it composes.",
   "patterns": {
+    "AgentRun": {
+      "summary": "A single agent task from start to finish: what it is doing, what it produced, and a way to stop it at any point.",
+      "composes": [
+        "AgentActivity",
+        "AgentActivityStep",
+        "AgentStop",
+        "StreamingText",
+        "Alert",
+        "Badge"
+      ],
+      "states": [
+        "loading",
+        "empty",
+        "error",
+        "partial"
+      ],
+      "detail": "dist/meta/patterns/AgentRun.json"
+    },
+    "AssistantAnswer": {
+      "summary": "A generated answer presented so the reader can check it: the text, what it was drawn from, and how far to trust it.",
+      "composes": [
+        "StreamingText",
+        "Citation",
+        "CitationList",
+        "CitationListItem",
+        "ConfidenceIndicator",
+        "Alert",
+        "Link"
+      ],
+      "states": [
+        "loading",
+        "empty",
+        "error",
+        "partial"
+      ],
+      "detail": "dist/meta/patterns/AssistantAnswer.json"
+    },
     "DataTable": {
       "summary": "A table of records with a toolbar, selection, and the three states everyone forgets.",
       "composes": [
@@ -64,6 +101,23 @@
       ],
       "detail": "dist/meta/patterns/Form.json"
     },
+    "HumanApproval": {
+      "summary": "An agent stops and asks before doing something consequential, and a person approves, rejects or edits it.",
+      "composes": [
+        "ApprovalGate",
+        "AgentActivity",
+        "AgentActivityStep",
+        "AgentStop",
+        "Alert"
+      ],
+      "states": [
+        "loading",
+        "empty",
+        "error",
+        "expired"
+      ],
+      "detail": "dist/meta/patterns/HumanApproval.json"
+    },
     "PageShell": {
       "summary": "The frame every screen sits in: header, navigation, a named content region.",
       "composes": [

package/dist/styles/badge.css

@@ -1,25 +1,36 @@
 /*
  * Badge
  *
- * Geometry measured from Figma `Badge` (152:73). Single size, six intents.
+ * Geometry measured from Figma `Badge` (152:73). Six intents x three sizes x
+ * two shapes.
  *
  * v2: Badge owns no tokens. Every value here is an Interface token, a Semantics
  * token, or a spacing primitive — the same ones the Figma component binds, so
- * the two cannot drift. Badge is 20px tall, below control/sm's 32px, so it is
- * not a control and does not read the control scale.
+ * the two cannot drift. Even Large, at 32px, is not a control: it has no hit
+ * target and no state, so it does not read the control scale.
+ *
+ * HEIGHT IS PINNED, NOT DERIVED. Figma binds each size's height to
+ * spacing/20|24|32, and the 2px vertical padding it also carries is inert
+ * because the pinned height already exceeds it. Reproducing that padding
+ * instead of the height is exactly how Button's ramp once landed 2px off on
+ * every size, so this reads the height token and pads the inline axis only.
+ *
+ * SMALL IS THE DEFAULT, matching Figma's default variant and the single size
+ * this component shipped with before the ramp existed.
  */
 .ion-badge {
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  min-height: var(--spacing-20);
 
   /*
-   * Figma's 1px stroke is drawn INSIDE the box, so it does not add height. A CSS
-   * border does, so the vertical padding absorbs it — otherwise the badge
-   * renders 2px taller than the design. Same correction as the Tabs underline
-   * indicator. Badge is 22px: padding 2 + caption line-height 18 + padding 2.
+   * Figma's 1px stroke is drawn INSIDE the box; a CSS border sits outside the
+   * padding. Subtracting one border width keeps the label the same distance
+   * from the outer edge in both. Same correction as Checkbox and Radio, and
+   * only needed on the inline axis now that height is pinned.
    */
-  padding: calc(var(--spacing-2) - var(--border-width-default)) var(--spacing-8);
+  padding-inline: calc(var(--spacing-4) - var(--border-width-default));
   gap: var(--spacing-4);
   font-family: var(--font-family-sans);
 
@@ -55,12 +66,77 @@
  * error that is #dc2828 against the label's #ba1c1c. `@ionbase-ui/icons` renders
  * with `currentColor`, so each intent sets `color` on the svg directly.
  *
- * Icon size is deliberately not set here. Figma has it at 14px, which is not on
- * the spacing scale, so it is most likely a slip rather than a decision. Until
- * that is settled the icon inherits 1em, matching the 12px label.
+ * Icon size IS set now, and is on the ladder. The previous note here recorded
+ * Figma at a single off-scale 14px and declined to follow it, on the grounds
+ * that it looked like a slip. The retuned component reads icon-size/2xs, /sm
+ * and /md — 12, 16, 20 — one rung per size, so the slip is gone and there is
+ * something to follow.
  */
 .ion-badge svg {
   flex-shrink: 0;
+  width: var(--icon-size-2xs);
+  height: var(--icon-size-2xs);
+}
+
+/*
+ * The label carries its own inline padding, which is Figma's `Label Slot`
+ * frame. The dot and the icon are its siblings rather than its children, so
+ * they sit at the badge's own padding and only the text takes the extra inset.
+ * Collapsing the two into one padding would move the dot.
+ */
+.ion-badge__label {
+  padding-inline: var(--spacing-2);
+}
+
+/* Size modifiers — Small is the base. */
+
+.ion-badge--md {
+  min-height: var(--spacing-24);
+  font-size: var(--type-body-sm);
+  line-height: var(--type-body-sm-line-height);
+}
+
+.ion-badge--md .ion-badge__label {
+  padding-inline: var(--spacing-4);
+}
+
+.ion-badge--md svg {
+  width: var(--icon-size-sm);
+  height: var(--icon-size-sm);
+}
+
+.ion-badge--lg {
+  min-height: var(--spacing-32);
+  padding-inline: calc(var(--spacing-6) - var(--border-width-default));
+  gap: var(--spacing-6);
+  font-size: var(--type-body-sm);
+  line-height: var(--type-body-sm-line-height);
+}
+
+.ion-badge--lg .ion-badge__label {
+  padding-inline: var(--spacing-6);
+}
+
+.ion-badge--lg svg {
+  width: var(--icon-size-md);
+  height: var(--icon-size-md);
+}
+
+/*
+ * Shape. Pill is the base radius/full; Rounded steps with the size so the
+ * corner stays proportional — 4 / 6 / 8 against heights of 20 / 24 / 32.
+ */
+
+.ion-badge--rounded {
+  border-radius: var(--radius-xs);
+}
+
+.ion-badge--md.ion-badge--rounded {
+  border-radius: var(--radius-sm);
+}
+
+.ion-badge--lg.ion-badge--rounded {
+  border-radius: var(--radius-md);
 }
 
 /* Intent modifiers */