ionbase-ui 0.73.0 → 0.76.0

package/dist/meta/components.json

@@ -1,10 +1,23 @@
 {
   "package": "ionbase-ui",
-  "version": "0.73.0",
+  "version": "0.76.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",
@@ -6851,7 +7115,8 @@
         "guarantees": [
           "hover state comes from React Aria's pointer-aware `useHover`, so a tap does not stay hovered until the next tap elsewhere",
           "the focus ring shows for keyboard navigation only",
-          "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React"
+          "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React",
+          "`isCurrent` sets `aria-current=\"page\"`, and the current item is marked by an underline as well as colour, which survives forced-colours mode"
         ],
         "requires": [
           "an accessible name — `children`, or `aria-label` on an icon-only item"
@@ -6869,6 +7134,10 @@
           "dont": "marking the current page with colour only",
           "do": "`aria-current=\"page\"`",
           "why": "a screen-reader user is otherwise never told where they are"
+        },
+        {
+          "dont": "marking the current page with a className or colour of your own instead of `isCurrent`",
+          "why": "a screen reader hears nothing without `aria-current`, and a colour-only marker fails anyone who cannot see the difference"
         }
       ],
       "deprecated": [
@@ -6880,11 +7149,13 @@
       "stylesheet": "src/styles/nav-item.css",
       "tokens": [
         "--border-focus",
+        "--border-primary",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-regular",
+        "--font-weight-medium",
         "--icon-disabled",
         "--icon-interactive-hover",
+        "--icon-primary",
         "--icon-size-sm",
         "--icon-tertiary",
         "--ion-duration-base",
@@ -6892,6 +7163,7 @@
         "--radius-sm",
         "--spacing-4",
         "--spacing-8",
+        "--text-default",
         "--text-disabled",
         "--text-interactive-hover",
         "--text-secondary",
@@ -6911,6 +7183,12 @@
           "origin": "own",
           "description": "Figma's `Show Chevron`. Set on a nav item that opens a menu, not a plain link."
         },
+        "isCurrent": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The page the user is on. Marks the item `aria-current=\"page\"` and draws\nthe same indicator Tabs' underline does — so a section switcher built from\nNavItems says where you are, in words for a screen reader and in more than\ncolour for everyone else."
+        },
         "isDisabled": {
           "type": "boolean | undefined",
           "required": false,
@@ -6941,7 +7219,7 @@
         }
       },
       "propCounts": {
-        "own": 7,
+        "own": 8,
         "aria": 0,
         "dom": 276,
         "other": 0