{
  "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."
    },
    "labels": {
      "type": "StatTileLabels | undefined",
      "required": false,
      "origin": "own",
      "description": "The change's words, for translation. English by default. StatTile renders\non the server, where there is no locale to read, so its default formats\nthe number the English way — pass `labels.change` to format it in the\nreader's."
    },
    "isLoading": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Shows a placeholder for the value and change while data loads."
    }
  },
  "propCounts": {
    "own": 8,
    "aria": 0,
    "dom": 277,
    "other": 0
  }
}