ionbase-ui 0.70.0 → 0.75.0

package/dist/meta/components.json

@@ -1,10 +1,23 @@
 {
   "package": "ionbase-ui",
-  "version": "0.70.0",
+  "version": "0.75.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
+    "useAgentRun",
     "useToast"
   ],
+  "helpers": [
+    "agentRunFrom",
+    "agentRunHasEnded",
+    "agentRunLog",
+    "agentRunReducer",
+    "chartAxisProps",
+    "chartGridProps",
+    "chartSeriesClass",
+    "chartTooltipProps",
+    "initialAgentRunState",
+    "replayAgentRun"
+  ],
   "components": {
     "Accordion": {
       "name": "Accordion",
@@ -2652,6 +2665,257 @@
         "other": 0
       }
     },
+    "ChartLegend": {
+      "name": "ChartLegend",
+      "source": "src/components/Chart.tsx",
+      "propsType": "ChartLegendProps",
+      "description": "ChartLegend — which colour is which series.\n\nColour alone never identifies a series (SC 1.4.1), so any chart with more\nthan one series needs this, or direct labels on the lines. The swatch reads\nthe same `--chart-<n>` as the series itself, through `chartSeriesClass`, so\nthe two cannot drift apart.",
+      "import": "import { ChartLegend } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.74.0",
+      "summary": "Which colour is which series, for a chart drawn with visx. The swatch reads the same token as the series.",
+      "useWhen": [
+        "a chart has more than one series",
+        "a single-series chart sits beside others and its colour needs naming"
+      ],
+      "useInstead": [
+        {
+          "when": "the lines are few and there is room to label each at its end",
+          "use": "direct labels in the SVG, with the series class on the text"
+        },
+        {
+          "when": "the scale is a magnitude ramp (a heatmap), not categories",
+          "use": "a Less-to-More row of .ion-chart__heat--0…5 cells"
+        }
+      ],
+      "composition": {
+        "note": "Items are listed in the order the series are drawn, with the same series numbers the chart uses. Place it above or below the plot inside the same .ion-chart figure.",
+        "example": "<ChartLegend shape=\"line\" items={[{ label: 'Production', series: 1 }, { label: 'Staging', series: 2 }]} />"
+      },
+      "variants": {
+        "shape": {
+          "square": {
+            "use": "the default — bars, areas and heatmap-like marks"
+          },
+          "line": {
+            "use": "line charts, so the key looks like the mark it names"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "a list, so a screen reader announces how many series there are",
+          "swatches are aria-hidden; every series is named in text"
+        ],
+        "requires": [
+          "series numbers matching the chart — the legend cannot see the chart"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a multi-series chart with no legend and no direct labels",
+          "why": "colour becomes the only way to tell series apart, which fails SC 1.4.1 and fails anyone who cannot tell blue from purple"
+        },
+        {
+          "dont": "listing series in a different order from the chart",
+          "why": "the reader matches legend to chart by position as much as by colour"
+        }
+      ],
+      "stylesheet": "src/styles/chart.css",
+      "tokens": [
+        "--border-default",
+        "--border-strong",
+        "--border-stronger",
+        "--border-subtle",
+        "--border-width-default",
+        "--chart-1",
+        "--chart-2",
+        "--chart-3",
+        "--chart-4",
+        "--chart-5",
+        "--chart-6",
+        "--chart-7",
+        "--chart-8",
+        "--chart-sequential-1",
+        "--chart-sequential-2",
+        "--chart-sequential-3",
+        "--chart-sequential-4",
+        "--chart-sequential-5",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--ion-chart-series",
+        "--ion-shadow-shadow-lg",
+        "--radius-2xs",
+        "--radius-full",
+        "--radius-md",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-4",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-raised",
+        "--surface-sunken",
+        "--text-default",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "items": {
+          "type": "ChartLegendItem[]",
+          "required": true,
+          "origin": "own",
+          "description": "One per series, in the order the series are drawn."
+        },
+        "shape": {
+          "type": "ChartLegendShape | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "`square` for bars and areas, `line` for line charts.",
+          "values": [
+            "square",
+            "line"
+          ]
+        }
+      },
+      "propCounts": {
+        "own": 2,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "ChartTooltip": {
+      "name": "ChartTooltip",
+      "source": "src/components/Chart.tsx",
+      "propsType": "ChartTooltipProps",
+      "description": "ChartTooltip — the panel that shows the values under the pointer.\n\nPut it inside visx's Tooltip with `chartTooltipProps`, so visx places it and\nthis draws it: raised, rimmed and shadowed like Popover and Toast.\n\nIT IS NOT THE ACCESSIBLE WAY TO THE DATA. It appears on hover, so a keyboard\nor screen-reader user never sees it. Every chart still needs a text summary\nand the values in a table (visually hidden is fine) — the tooltip is a\nconvenience for pointer users, never the only route to a number.",
+      "import": "import { ChartTooltip } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.74.0",
+      "summary": "The panel showing the values under the pointer on a visx chart. visx positions it; this draws it.",
+      "useWhen": [
+        "a chart drawn with visx shows exact values on hover",
+        "several series share an x value and the reader compares them at a point"
+      ],
+      "useInstead": [
+        {
+          "when": "it explains a control rather than a data point",
+          "use": "Tooltip"
+        },
+        {
+          "when": "it holds interactive content",
+          "use": "Popover"
+        },
+        {
+          "when": "the reader needs every value, or needs them without a pointer",
+          "use": "Table"
+        }
+      ],
+      "composition": {
+        "note": "Render it inside visx's Tooltip, TooltipWithBounds or TooltipInPortal with {...chartTooltipProps}, which turns off visx's own box so this one is the only panel. Axes take {...chartAxisProps} and gridlines {...chartGridProps}; a series takes className={chartSeriesClass(n)} plus ion-chart__line, __area, __bar or __point.",
+        "example": "<TooltipWithBounds top={top} left={left} {...chartTooltipProps}><ChartTooltip title=\"12 Sep\" rows={[{ label: 'Success rate', value: '96.2%', series: 1 }]} /></TooltipWithBounds>"
+      },
+      "a11y": {
+        "guarantees": [
+          "rows are a <dl>, so each value is announced with its label",
+          "the series swatch is aria-hidden; the label carries the name"
+        ],
+        "requires": [
+          "a text summary and the values in a table (visually hidden is fine) — the tooltip appears on hover, so keyboard and screen-reader users never reach it",
+          "`value` already formatted — the tooltip cannot know the unit or precision"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "making the tooltip the only way to read a value",
+          "why": "it exists only under a mouse pointer; without a table the data is invisible to keyboard and screen-reader users"
+        },
+        {
+          "dont": "leaving visx's default tooltip styles on",
+          "why": "it draws a second white box with a hardcoded shadow around this one, and that box does not theme"
+        },
+        {
+          "dont": "a swatch colour that does not match the series",
+          "why": "pass the same `series` number the line or bar uses — the swatch reads the same token only if it is told the same index"
+        }
+      ],
+      "stylesheet": "src/styles/chart.css",
+      "tokens": [
+        "--border-default",
+        "--border-strong",
+        "--border-stronger",
+        "--border-subtle",
+        "--border-width-default",
+        "--chart-1",
+        "--chart-2",
+        "--chart-3",
+        "--chart-4",
+        "--chart-5",
+        "--chart-6",
+        "--chart-7",
+        "--chart-8",
+        "--chart-sequential-1",
+        "--chart-sequential-2",
+        "--chart-sequential-3",
+        "--chart-sequential-4",
+        "--chart-sequential-5",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--ion-chart-series",
+        "--ion-shadow-shadow-lg",
+        "--radius-2xs",
+        "--radius-full",
+        "--radius-md",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-4",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-raised",
+        "--surface-sunken",
+        "--text-default",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "title": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "What the pointer is over — usually the x value, e.g. a date."
+        },
+        "rows": {
+          "type": "ChartTooltipRow[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "One row per series at that point."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Free content after the rows, for anything that is not label/value."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 0,
+        "dom": 276,
+        "other": 0
+      }
+    },
     "Checkbox": {
       "name": "Checkbox",
       "source": "src/components/Checkbox.tsx",
@@ -9745,6 +10009,108 @@
         "other": 0
       }
     },
+    "SettingRow": {
+      "name": "SettingRow",
+      "source": "src/components/SettingRow.tsx",
+      "propsType": "SettingRowProps",
+      "description": "SettingRow — one setting: its name and what it does on the left, the control\non the right. The row the SettingsPanel pattern is built from.\n\nTHE WIRING IS THE POINT, NOT THE LAYOUT\n\nA label placed beside a Toggle looks labelled and is not: a screen reader\nannounces \"switch, off\" and nothing else, and the description is never read\nat all. The pattern names this as its first a11y requirement, and the demo\napp's stand-in handed the ids to a render function — which still left the\nwiring as a step to remember. Here an element child is cloned with\n`aria-labelledby` and `aria-describedby` already set, so the row cannot be\nused without them. A value the caller passes explicitly wins, so an\nexisting name is never overwritten.\n\nA CONTROL WITH ITS OWN TEXT KEEPS ITS OWN NAME\n\nA Button reading \"Delete workspace…\" must be announced by that text — WCAG\n2.5.3 wants the visible words inside the accessible name, and a row label of\n\"Danger zone\" would replace them. So a child with children of its own is\nleft named by them, and the row's label joins its description instead: the\nsetting is still announced, just as context rather than as the name.\n\nThe label is text rather than a `<label>` because the control may not be a\nform field, and a `<label>` pointing at a button is invalid.\n\nIt stacks below 30rem of its OWN width, not the viewport's, so the same row\nworks in a full page and in a narrow drawer.",
+      "import": "import { SettingRow } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.72.0",
+      "summary": "One setting: its name and description on the left, the control on the right — and the control named and described by them automatically.",
+      "useWhen": [
+        "a settings or preferences panel, one row per setting",
+        "a control whose meaning needs a sentence of explanation beside it"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a form field with its own visible label above it",
+          "use": "Input",
+          "why": "Input, Select and the pickers carry their own label and description; a SettingRow around them names the field twice"
+        },
+        {
+          "when": "a group of options answers one question",
+          "use": "RadioGroup",
+          "why": "the group has its own label; put the RadioGroup under a heading rather than in a row"
+        }
+      ],
+      "slots": {
+        "children": {
+          "accepts": [
+            "Toggle",
+            "Checkbox",
+            "Select",
+            "Button"
+          ],
+          "note": "an element is cloned with aria-labelledby and aria-describedby pointing at the row's text; a function receives the ids instead, for a control that needs them somewhere else"
+        }
+      },
+      "a11y": {
+        "namesChild": true,
+        "guarantees": [
+          "an element child with no text of its own — a Toggle, a Checkbox with no label — is named by the row's label and described by its description, so it is announced as \"Weekly digest, switch, off\" plus what it does, not \"switch, off\"",
+          "a child with its own text — a Button — keeps that text as its name (WCAG 2.5.3), and the row's label and description are attached as its description instead",
+          "an aria-labelledby or aria-describedby the caller passes explicitly is kept, never overwritten",
+          "it stacks by its own width, so it reads the same in a page and in a narrow drawer"
+        ],
+        "requires": [
+          "one control per row — the ids name one element"
+        ],
+        "notes": [
+          "The label is text, not a <label>, because the control may be a Button; a <label> pointing at a button is invalid."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a Toggle or Checkbox with its own visible label inside a SettingRow",
+          "why": "the control then names itself, the row's label becomes a description, and the setting's name is shown twice"
+        },
+        {
+          "dont": "a Checkbox row that saves immediately",
+          "why": "Toggle is immediate and Checkbox is saved with a submit — the SettingsPanel pattern's first rule"
+        }
+      ],
+      "stylesheet": "src/styles/setting-row.css",
+      "tokens": [
+        "--font-family-sans",
+        "--font-weight-semibold",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-8",
+        "--text-default",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "React.ReactNode",
+          "required": true,
+          "origin": "own",
+          "description": "The setting's name. It becomes the control's accessible name."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "What the setting does, announced with the control."
+        },
+        "children": {
+          "type": "React.ReactElement<{ 'aria-labelledby'?: string; 'aria-describedby'?: string; children?: React.ReactNode; }, string | React.JSXElementConstructor<any>> | ((ids: SettingRowIds) => React.ReactNode)",
+          "required": true,
+          "origin": "own",
+          "description": "The control. Pass it as an element — `<Toggle />`, `<Select />`,\n`<Button />` — and the row names and describes it for you. Pass a\nfunction when the ids have to go somewhere other than the element's own\nprops; it receives them."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
     "Sidebar": {
       "name": "Sidebar",
       "source": "src/components/Sidebar.tsx",
@@ -10453,6 +10819,234 @@
         "other": 0
       }
     },
+    "StatGroup": {
+      "name": "StatGroup",
+      "source": "src/components/StatTile.tsx",
+      "propsType": "StatGroupProps",
+      "description": "StatGroup — a row of StatTiles.\n\nA `<dl>`: each tile is a term (the label) and its description (the figure),\nwhich is what a screen reader announces as a pair. The grid wraps on its own,\nso four tiles are one row on a desktop and two on a phone with no breakpoint\nin the caller's code.",
+      "import": "import { StatGroup } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.71.0",
+      "summary": "A row of StatTiles, as a description list. Wraps on its own — no breakpoints in the caller's code.",
+      "useWhen": [
+        "two or more headline figures shown side by side"
+      ],
+      "useInstead": [
+        {
+          "when": "the figures are rows of records to compare field by field",
+          "use": "Table"
+        }
+      ],
+      "composition": {
+        "order": [
+          "StatGroup",
+          "StatTile"
+        ],
+        "note": "StatGroup renders the <dl>; each StatTile renders a <dt> and a <dd> inside it. A StatTile outside a StatGroup is invalid HTML.",
+        "example": "<StatGroup><StatTile label=\"Runs\" value=\"1.2k\" change={4.1} goodWhen=\"neutral\" /><StatTile label=\"Median run time\" value=\"38s\" change={-6.2} goodWhen=\"down\" /></StatGroup>"
+      },
+      "slots": {
+        "children": {
+          "accepts": [
+            "StatTile"
+          ],
+          "note": "StatTiles only — the group is a <dl>, so anything else inside it is invalid"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "a <dl>, so each label is announced as the term for its figure"
+        ],
+        "notes": [
+          "Give the group a heading or aria-label when the page has more than one, so a screen reader can tell them apart."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "adding media queries to change the column count",
+          "why": "the grid already wraps by tile width; a breakpoint fights it"
+        }
+      ],
+      "stylesheet": null,
+      "tokens": [],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "StatTile elements."
+        }
+      },
+      "propCounts": {
+        "own": 1,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "StatTile": {
+      "name": "StatTile",
+      "source": "src/components/StatTile.tsx",
+      "propsType": "StatTileProps",
+      "description": "StatTile — one headline figure, and how it moved.\n\nPromoted from the demo app, where it was built for the Overview KPI row and\nsurvived three phases unchanged.\n\nGOOD AND BAD ARE NOT UP AND DOWN\n\nA rising median run time is bad news and a rising success rate is good, so\nthe colour comes from `goodWhen` and the direction together — never from the\nsign alone. `neutral` never colours: a run count going up is not a verdict.\nThe verdict is also spoken, as visually hidden text after the change, so it\nnever rests on the badge's colour.\n\nThe change is rounded BEFORE it is judged, so −0.04 reads \"No change\" rather\nthan a red \"−0.0%\".\n\nIt must sit inside a StatGroup: the tile renders a `<dt>` and a `<dd>`, which\nare only valid inside a `<dl>`.",
+      "import": "import { StatTile } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.71.0",
+      "summary": "One headline figure and how it moved against a comparison period. Good and bad come from `goodWhen`, never from the sign alone.",
+      "useWhen": [
+        "a dashboard or overview leads with a handful of key numbers",
+        "a change against a previous period is part of what the number means"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a summary with text and media rather than a number",
+          "use": "FullCard"
+        },
+        {
+          "when": "the figure is progress toward a known total",
+          "use": "ProgressBar"
+        },
+        {
+          "when": "there are more than about six figures, or they need comparing across rows",
+          "use": "Table"
+        }
+      ],
+      "composition": {
+        "order": [
+          "StatGroup",
+          "StatTile"
+        ],
+        "note": "Always inside a StatGroup: the tile renders a <dt> and a <dd>, which are only valid inside a <dl>.",
+        "example": "<StatGroup><StatTile label=\"Success rate\" value=\"96.2%\" change={1.1} changeUnit=\"points\" /></StatGroup>"
+      },
+      "variants": {
+        "goodWhen": {
+          "up": {
+            "use": "the default — revenue, success rate, anything where more is better"
+          },
+          "down": {
+            "use": "costs, durations, error counts and queues, where a rise is bad news"
+          },
+          "neutral": {
+            "use": "a change that is neither — run volume, traffic — so it is never coloured"
+          }
+        },
+        "changeUnit": {
+          "percent": {
+            "use": "the default — a relative change"
+          },
+          "points": {
+            "use": "the metric is itself a percentage: 95% to 96% is +1.0 pts, not +1.1%"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the verdict is spoken as text (\"better\" or \"worse\") after the change, so it never rests on the badge's colour",
+          "the direction is in the text as a sign as well as in the arrow",
+          "`isLoading` marks the tile aria-busy while its placeholder shows"
+        ],
+        "requires": [
+          "`value` already formatted — the tile cannot know the locale, precision or unit",
+          "the right `goodWhen` for the metric; the default `up` colours a rising cost green"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "leaving `goodWhen` at `up` for a duration, cost or error count",
+          "why": "a slower, costlier or more error-prone week is shown green and announced as better"
+        },
+        {
+          "dont": "a percentage change for a metric that is already a percentage",
+          "why": "95% to 96% is +1 point; +1.1% misreports it — use changeUnit=\"points\""
+        },
+        {
+          "dont": "passing a change of 0 to mean \"no data\"",
+          "why": "0 renders \"No change\", a claim; omit `change` when there is nothing to compare"
+        }
+      ],
+      "stylesheet": "src/styles/stat-tile.css",
+      "tokens": [
+        "--border-subtle",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-semibold",
+        "--radius-lg",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--text-default",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height",
+        "--type-h4",
+        "--type-h4-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "string",
+          "required": true,
+          "origin": "own",
+          "description": "What is being measured. Short: \"Success rate\", not a sentence."
+        },
+        "value": {
+          "type": "React.ReactNode",
+          "required": true,
+          "origin": "own",
+          "description": "The figure, already formatted — \"1.2k\", \"96.2%\", \"38s\". Formatting is the\ncaller's: only it knows the locale, the precision and the unit."
+        },
+        "change": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Change against the comparison period. Omit when there is none."
+        },
+        "changeUnit": {
+          "type": "StatTileChangeUnit | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "`percent` for a relative change; `points` for a metric that is already a\npercentage — 95% to 96% is +1 pt, and calling it +1.1% misreports it.",
+          "values": [
+            "points",
+            "percent"
+          ]
+        },
+        "goodWhen": {
+          "type": "StatTileGoodWhen | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Which direction is good news. `down` for costs, durations and queues;\n`neutral` when a change is neither, so it is never coloured.",
+          "values": [
+            "neutral",
+            "up",
+            "down"
+          ]
+        },
+        "comparison": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "What `change` is measured against."
+        },
+        "isLoading": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Shows a placeholder for the value and change while data loads."
+        }
+      },
+      "propCounts": {
+        "own": 7,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
     "Stepper": {
       "name": "Stepper",
       "source": "src/components/Stepper.tsx",