ionbase-ui 0.70.0 → 0.75.0

package/dist/meta/StatGroup.json

@@ -0,0 +1,65 @@
+{
+  "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
+  }
+}

package/dist/meta/StatTile.json

@@ -0,0 +1,163 @@
+{
+  "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
+  }
+}