ionbase-ui 0.70.0 → 0.73.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.70.0",
+  "version": "0.73.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useToast"
@@ -9745,6 +9745,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 +10555,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",