ionbase-ui 0.59.0 → 0.69.0

package/dist/meta/SidebarSection.json

@@ -0,0 +1,131 @@
+{
+  "name": "SidebarSection",
+  "source": "src/components/Sidebar.tsx",
+  "propsType": "SidebarSectionProps",
+  "import": "import { SidebarSection } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A group of sidebar items under an optional title, which can fold away and carry its own actions.",
+  "useWhen": [
+    "inside a Sidebar, once per group — the untitled top group, then Favorites, Spaces"
+  ],
+  "useInstead": [
+    {
+      "when": "the grouping is one item and its children",
+      "use": "SidebarItem",
+      "why": "an item with nested items already expands; a section per parent doubles the structure"
+    }
+  ],
+  "slots": {
+    "children": {
+      "accepts": "SidebarItem",
+      "note": "items only — the section renders a list"
+    },
+    "actions": {
+      "accepts": "Button",
+      "note": "beside the title — a + to create in this group. Icon-only buttons need aria-label"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "a titled section's list is named by its title, so a screen reader announces \"Spaces, list, 4 items\"",
+      "a collapsible title is a button with aria-expanded and aria-controls; the folded list is hidden, not unmounted"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "isCollapsible with no title",
+      "why": "there is nothing to press; the prop is ignored"
+    },
+    {
+      "dont": "collapsing the section that holds the current page by default",
+      "why": "the user's location is hidden on arrival — leave it open, or open it when the page is inside"
+    }
+  ],
+  "stylesheet": "src/styles/sidebar.css",
+  "tokens": [
+    "--border-focus",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-disabled",
+    "--icon-primary",
+    "--icon-secondary",
+    "--icon-size-sm",
+    "--icon-tertiary",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-md",
+    "--radius-sm",
+    "--radius-xs",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-hover",
+    "--surface-selected",
+    "--surface-selected-hover",
+    "--text-default",
+    "--text-disabled",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "title": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The group's name — \"Spaces\", \"Favorites\". Omit for the top group."
+    },
+    "isCollapsible": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Lets the title fold the section away. Needs a `title`."
+    },
+    "defaultExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled: whether a collapsible section starts open."
+    },
+    "isExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled: whether a collapsible section is open."
+    },
+    "onExpandedChange": {
+      "type": "((isExpanded: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "actions": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Controls beside the title — a `+` Button to create a space. Icon-only\nbuttons need their own `aria-label`."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "`SidebarItem`s only — the section renders a list."
+    }
+  },
+  "propCounts": {
+    "own": 7,
+    "aria": 0,
+    "dom": 276,
+    "other": 0
+  }
+}

package/dist/meta/Stepper.json

@@ -0,0 +1,135 @@
+{
+  "name": "Stepper",
+  "source": "src/components/Stepper.tsx",
+  "propsType": "StepperProps",
+  "description": "Stepper — where the user is in a task that has an order.\n\nWHY NOT TABS\n\nThe `tablist` role announces peers that can be visited in any order, which is\nthe opposite of a wizard. This is an ordered list: the steps are a sequence,\nand `ol` says so. Nothing here is a tab, and arrow keys do nothing.\n\nPOSITION AND STATUS ARE TEXT, NOT ONLY DRAWING\n\nEvery step renders \"Step 2 of 5\" and its status as visually hidden text. The\nnumber in the circle is for the eye; a screen reader cannot be relied on to\nannounce list position, and a coloured ring carries nothing in forced-colours\nmode. The complete and error glyphs also differ in SHAPE — a check and an\nexclamation — so the states survive greyscale, which WCAG 1.4.1 requires.\n\nONLY VISITED STEPS ARE LINKS\n\n`href` / `onPress` are honoured on `complete` and `error` steps that are not\ncurrent. An `incomplete` step renders as text even when given one, because\njumping forward past unanswered steps is exactly what a wizard exists to\nprevent — and a link that is there but should not be followed is worse than\nno link. The current step is text for the same reason Breadcrumb's is: a link\nto where you already are is a dead control.\n\nIT DOES NOT ANNOUNCE STEP CHANGES\n\nThe Wizard pattern moves focus to the new step's heading, which announces it.\nA live region here as well would say the same thing twice, on every step.",
+  "import": "import { Stepper } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Where the user is in a task that has an order. An ordered list of steps, each stating its position and status in text.",
+  "useWhen": [
+    "a Wizard — later steps depend on earlier answers and the user needs to see what is left",
+    "a multi-page flow such as checkout or onboarding, where the steps are fixed and known in advance"
+  ],
+  "useInstead": [
+    {
+      "when": "the sections can be visited in any order",
+      "use": "Tabs",
+      "why": "tabs promise peers; a stepper promises a sequence, and using one for the other misleads in both directions"
+    },
+    {
+      "when": "the progress is a quantity with no named stages — an upload, an import",
+      "use": "ProgressBar",
+      "why": "a stepper with no meaningful step names is a progress bar drawn in circles"
+    },
+    {
+      "when": "the steps are an agent's actions rather than the user's",
+      "use": "AgentActivity",
+      "why": "the user is not moving through those steps; they are supervising them"
+    }
+  ],
+  "variants": {
+    "orientation": {
+      "horizontal": {
+        "use": "the default — a header above the step's form. Below 40rem it keeps only the current label visible"
+      },
+      "vertical": {
+        "use": "a side rail beside the form, or when step names or descriptions are long"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "StepperStep",
+      "note": "first step first, and exactly one with isCurrent"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` naming the task when a page carries more than one stepper — it defaults to \"Progress\""
+    ],
+    "guarantees": [
+      "every step renders \"Step N of M\" and its status as visually hidden text, derived from the children rather than passed in",
+      "the current step carries aria-current=\"step\"",
+      "connectors are CSS and never enter the accessibility tree"
+    ],
+    "notes": [
+      "it does not announce step changes. The Wizard pattern moves focus to the new step's heading, which announces it; a live region here would say it twice"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<Tabs> as a wizard's step indicator",
+      "do": "<Stepper>",
+      "why": "the tablist role announces peers that can be visited in any order, which is the opposite of a wizard"
+    },
+    {
+      "dont": "more than about seven steps",
+      "why": "a stepper that has to scroll or wrap no longer shows what is left, which is the only thing it is for — group the steps instead"
+    }
+  ],
+  "stylesheet": "src/styles/stepper.css",
+  "tokens": [
+    "--border-default",
+    "--border-error",
+    "--border-focus",
+    "--border-primary",
+    "--border-strong",
+    "--border-width-thick",
+    "--border-width-thicker",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-semibold",
+    "--icon-error",
+    "--icon-primary",
+    "--icon-size-lg",
+    "--icon-size-sm",
+    "--radius-full",
+    "--radius-xs",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-24",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-primary",
+    "--text-default",
+    "--text-error",
+    "--text-on-color",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the list. Defaults to \"Progress\"; give it the task's name when a page\ncarries more than one — \"Checkout progress\"."
+    },
+    "orientation": {
+      "type": "StepperOrientation | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "`horizontal` for a page-width header above the form, `vertical` for a side\nrail. Below 40rem a horizontal stepper hides every label but the current\none, so it does not need a second variant for mobile.",
+      "values": [
+        "horizontal",
+        "vertical"
+      ]
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "`StepperStep` elements, first step first."
+    }
+  },
+  "propCounts": {
+    "own": 3,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/StepperStep.json

@@ -0,0 +1,148 @@
+{
+  "name": "StepperStep",
+  "source": "src/components/Stepper.tsx",
+  "propsType": "StepperStepProps",
+  "import": "import { StepperStep } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One step in a Stepper: a numbered indicator, a name, and a status carried by shape and text as well as colour.",
+  "useWhen": [
+    "inside a Stepper, once per step"
+  ],
+  "useInstead": [
+    {
+      "when": "it is a step an agent is running",
+      "use": "AgentActivityStep"
+    }
+  ],
+  "variants": {
+    "status": {
+      "incomplete": {
+        "use": "the default — not yet answered. Never a link, even with href"
+      },
+      "complete": {
+        "use": "answers accepted by the server, not merely filled in"
+      },
+      "error": {
+        "use": "the step's answers were rejected. Put the reason on the step's fields, not here"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the step's name, short — \"Shipping\", not \"Enter your shipping details\""
+    },
+    "description": {
+      "accepts": "text",
+      "note": "what the step asks for, or a summary of the answer once complete"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the current step and incomplete steps render as text, never as links, whatever href or onPress say",
+      "complete and error use different glyphs — a check and an exclamation — so status survives greyscale and forced-colours mode"
+    ],
+    "notes": [
+      "status and isCurrent are separate on purpose: a user who goes Back to step 1 is on a step that is both current and complete"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "status=\"complete\" as soon as the fields are filled",
+      "do": "mark it complete when the server accepts the step",
+      "why": "a green check on answers that are later rejected sends the user back through a step they were told was finished"
+    },
+    {
+      "dont": "href on every step so users can jump ahead",
+      "why": "incomplete steps ignore it; skipping unanswered steps is what a wizard exists to prevent"
+    },
+    {
+      "dont": "using it outside Stepper",
+      "why": "it renders an <li> and reads its position from the Stepper, and throws without one"
+    }
+  ],
+  "stylesheet": "src/styles/stepper.css",
+  "tokens": [
+    "--border-default",
+    "--border-error",
+    "--border-focus",
+    "--border-primary",
+    "--border-strong",
+    "--border-width-thick",
+    "--border-width-thicker",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-semibold",
+    "--icon-error",
+    "--icon-primary",
+    "--icon-size-lg",
+    "--icon-size-sm",
+    "--radius-full",
+    "--radius-xs",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-24",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-primary",
+    "--text-default",
+    "--text-error",
+    "--text-on-color",
+    "--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",
+      "description": "The step's name, in the user's language."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "A short second line — what the step asks for, or a summary of the answer."
+    },
+    "status": {
+      "type": "StepperStepStatus | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Whether the step's answers have been accepted. Orthogonal to `isCurrent`:\na user who goes Back to step 1 is on a step that is both current and\ncomplete.",
+      "values": [
+        "error",
+        "incomplete",
+        "complete"
+      ]
+    },
+    "isCurrent": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The step the user is on. Marked `aria-current=\"step\"`."
+    },
+    "href": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Makes a visited step a link back to it. Ignored on the current step and on\n`incomplete` steps — see the component's comment for why."
+    },
+    "onPress": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "As `href`, for a wizard that changes step without a route."
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Tabs.json

@@ -20,6 +20,11 @@
       "use": "Divider",
       "why": "tabs hide everything but the active panel, including from Ctrl-F"
     },
+    {
+      "when": "the options set a value — a view mode, a range, a unit — and no panel belongs to each",
+      "use": "SegmentedControl",
+      "why": "it looks like the pill type and is a radiogroup: a tab with no panel announces a relationship that does not exist"
+    },
     {
       "when": "it is navigation between pages rather than panels within one",
       "use": "NavItem"

package/dist/meta/ToolCall.json

@@ -0,0 +1,192 @@
+{
+  "name": "ToolCall",
+  "source": "src/components/ToolCall.tsx",
+  "propsType": "ToolCallProps",
+  "description": "ToolCall — the evidence behind one step of an agent run.\n\nAgentActivityStep says what the agent did in the user's language. ToolCall\nis where the person checking that account goes next: which tool, with what\narguments, and what came back. The title is still plain language and still\nrequired, so the technical detail supplements the account rather than\nreplacing it.\n\nCOLLAPSED BY DEFAULT, EXCEPT THE FAILURE\n\nA run makes dozens of calls, and a thread of expanded JSON is unreadable.\nBut `errorMessage` renders outside the disclosure: evidence that takes a\nclick to reach is evidence nobody reads, and a failure is the one thing in\nthe call a reader must not miss.\n\nTHE DETAILS ARE UNMOUNTED WHEN CLOSED — unlike Accordion, deliberately.\nAccordion keeps collapsed panels for the form state inside them; a tool call\nholds no user state, and its payloads can be megabytes of JSON multiplied by\nevery call in the thread.\n\nA CALL WITH NOTHING TO SHOW IS NOT A BUTTON. With no input and no output the\nheader renders as text: a disclosure that discloses nothing announces as\nexpandable and does nothing.\n\nTHE PAYLOADS ARE FOCUSABLE. Each is a scroll container capped in height, and\na scroll container a keyboard user cannot focus is one they cannot scroll.\n\nIt does not announce status changes. AgentActivity owns the run's live\nregion; a second one here would talk over it.",
+  "import": "import { ToolCall } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The evidence behind one step of an agent run: which tool, with what input, and what came back — collapsed by default, with any failure shown without a click.",
+  "useWhen": [
+    "a person may need to check how an agent reached a result — which search it ran, which record it wrote",
+    "beneath or beside an AgentActivityStep, for the steps that called a tool",
+    "debugging or audit views where the arguments matter as much as the outcome"
+  ],
+  "useInstead": [
+    {
+      "when": "the reader needs to know what the agent did, not how",
+      "use": "AgentActivityStep",
+      "why": "the plain-language log is the account; ToolCall is the evidence for it, and a thread of tool calls alone is a log nobody but an engineer can read"
+    },
+    {
+      "when": "the call has not happened yet and needs permission",
+      "use": "ApprovalGate",
+      "why": "ToolCall reports a call; it does not ask whether to make one"
+    }
+  ],
+  "variants": {
+    "status": {
+      "pending": {
+        "use": "the default — queued, not started"
+      },
+      "active": {
+        "use": "running now"
+      },
+      "done": {
+        "use": "returned successfully"
+      },
+      "failed": {
+        "use": "errored. Pass `errorMessage`, which shows without expanding"
+      },
+      "skipped": {
+        "use": "not run — rejected at an ApprovalGate, or a cached result was used"
+      }
+    }
+  },
+  "slots": {
+    "errorMessage": {
+      "accepts": "text",
+      "note": "what went wrong, in words — not a stack trace"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the header is a disclosure button with aria-expanded; with no input and no output it is plain text instead, because a disclosure that discloses nothing is a dead control",
+      "status is rendered as visually hidden text inside the header, and the glyph differs in shape per status",
+      "each payload is a focusable, named scroll region, so a keyboard user can scroll a capped payload",
+      "errorMessage renders outside the disclosure, so a failure is never hidden behind a click"
+    ],
+    "notes": [
+      "it does not announce status changes — AgentActivity owns the run's live region, and a second one would talk over it",
+      "the details unmount when collapsed, unlike Accordion: a tool call holds no user state and payloads can be large"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "title=\"search_invoices\"",
+      "do": "title=\"Searched the invoice archive\" name=\"search_invoices\"",
+      "why": "the function name describes the implementation; the title is what tells a reader whether the step was the right one"
+    },
+    {
+      "dont": "passing input or output with credentials, tokens or personal data still in it",
+      "why": "it renders exactly what it is given, to anyone who can see the thread"
+    },
+    {
+      "dont": "defaultExpanded on every call in a run",
+      "why": "a thread of open JSON buries the answer; open the one the reader is likely to check, or none"
+    },
+    {
+      "dont": "status=\"failed\" with no errorMessage",
+      "why": "a failure the reader cannot diagnose is just a red mark"
+    }
+  ],
+  "stylesheet": "src/styles/tool-call.css",
+  "tokens": [
+    "--border-error-subtle",
+    "--border-focus",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-mono",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-error",
+    "--icon-primary",
+    "--icon-secondary",
+    "--icon-size-sm",
+    "--icon-success",
+    "--icon-tertiary",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-md",
+    "--radius-sm",
+    "--spacing-12",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-error-subtle",
+    "--surface-hover",
+    "--surface-muted",
+    "--text-default",
+    "--text-error",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "What the call did, in the user's language — \"Searched the invoice archive\".\nRequired: the tool's function name is not a description of the work."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The tool's technical name, shown in monospace beside the title."
+    },
+    "status": {
+      "type": "AgentActivityStatus | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The same vocabulary as AgentActivityStep, so the two never disagree.",
+      "values": [
+        "pending",
+        "active",
+        "done",
+        "failed",
+        "skipped"
+      ]
+    },
+    "input": {
+      "type": "unknown",
+      "required": false,
+      "origin": "own",
+      "description": "What the agent passed in. Objects and arrays render as formatted JSON,\nstrings as they are. Redact secrets before passing it — this renders\nexactly what it is given."
+    },
+    "output": {
+      "type": "unknown",
+      "required": false,
+      "origin": "own",
+      "description": "What came back. Rendered as `input` is."
+    },
+    "errorMessage": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Why a `failed` call failed. Shown under the header whether or not the\ndetails are expanded — a failure that takes a click to read is not read."
+    },
+    "durationMs": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "How long the call took, in milliseconds."
+    },
+    "defaultExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled: whether the details start open."
+    },
+    "isExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled: whether the details are open. Pass `onExpandedChange` with it."
+    },
+    "onExpandedChange": {
+      "type": "((isExpanded: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 10,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}