@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/sparkline.json

@@ -0,0 +1,417 @@
+{
+  "family": "sparkline",
+  "ui": "sparkline",
+  "binding": "react",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Tiny inline trend chart."
+  },
+  "axes": {
+    "type": [
+      "line",
+      "bar"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "curve": [
+      "linear",
+      "monotone"
+    ],
+    "tone": [
+      "neutral",
+      "accent",
+      "secondary",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "series": [
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8"
+    ]
+  },
+  "members": {
+    "sparkline": {
+      "nativeElement": "span",
+      "defaults": {
+        "type": "line",
+        "size": "md",
+        "curve": "linear",
+        "area": false,
+        "marker": true
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "measurement",
+        "content"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root",
+        "plot",
+        "area",
+        "line",
+        "bar",
+        "reference",
+        "ring",
+        "marker"
+      ]
+    }
+  },
+  "docs": {
+    "sparkline": {
+      "imports": {
+        "source": "import { Sparkline, SparklineDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "span",
+          "required": true,
+          "purpose": "An inline image, role=\"img\", named by the generated description. Takes the whole inline size of what holds it and the height of its size step; measures itself and lays the drawing out in pixels."
+        },
+        {
+          "part": "plot",
+          "element": "svg",
+          "required": true,
+          "purpose": "The drawing, hidden from assistive technology. Its viewBox is the measured box, and until it is measured, the nominal grid of the size step."
+        },
+        {
+          "part": "area",
+          "element": "path",
+          "required": false,
+          "purpose": "The wash under a line, faded to nothing at the bottom edge. Present with area."
+        },
+        {
+          "part": "line",
+          "element": "path",
+          "required": false,
+          "purpose": "The series as a two-pixel line, straight or monotone, broken wherever the data has a gap. Present for type=\"line\" with two or more real points."
+        },
+        {
+          "part": "bar",
+          "element": "path",
+          "required": false,
+          "purpose": "One period, rounded at its data end and square at the baseline. Every bar but the last is dimmed; the last carries data-current."
+        },
+        {
+          "part": "reference",
+          "element": "line",
+          "required": false,
+          "purpose": "A dashed hairline at the reference value, in the neutral of the page."
+        },
+        {
+          "part": "ring",
+          "element": "path",
+          "required": false,
+          "purpose": "The ground-coloured ring under the marker, drawn as a round-capped stroke so it stays round on a stretched grid."
+        },
+        {
+          "part": "marker",
+          "element": "path",
+          "required": false,
+          "purpose": "The disc on the last real point, in the series colour. Present with marker on a line."
+        }
+      ],
+      "api": [
+        {
+          "name": "data",
+          "type": "(number | null)[]",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "The series, oldest first. null is a gap: the line breaks, the bar is not drawn, the summary ignores it"
+        },
+        {
+          "name": "type",
+          "type": "'line' | 'bar'",
+          "defaultValue": "line",
+          "appliesTo": "Sparkline",
+          "description": "A line through the points, or one bar per period"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "Sparkline",
+          "description": "The height of the box: 20, 32 or 48 pixels"
+        },
+        {
+          "name": "curve",
+          "type": "'linear' | 'monotone'",
+          "defaultValue": "linear",
+          "appliesTo": "Sparkline",
+          "description": "Straight segments, or a monotone curve that never draws a value the series does not hold"
+        },
+        {
+          "name": "area",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Sparkline",
+          "description": "The wash under a line"
+        },
+        {
+          "name": "marker",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Sparkline",
+          "description": "A disc on the last real point"
+        },
+        {
+          "name": "reference",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "A dashed hairline at this value. Widens the extent to hold it"
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "The lowest value the extent must hold. The data widens the extent, never narrows it"
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "The highest value the extent must hold"
+        },
+        {
+          "name": "tone",
+          "type": "'neutral' | 'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "How the series is doing. Wins over series; unset, a container may decide"
+        },
+        {
+          "name": "series",
+          "type": "1 | 2 | 3 | 4 | 5 | 6 | 7 | 8",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "Which series this is, as a slot of the data scale. Unset, a container decides, then slot 1"
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "What the series is, said first in the description"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "The whole accessible name, in place of the generated one"
+        },
+        {
+          "name": "formatOptions",
+          "type": "Intl.NumberFormatOptions",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "How each number in the description is written"
+        },
+        {
+          "name": "valueFormatter",
+          "type": "(value: number) => string",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "A formatter of your own for the description, in place of Intl"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "BCP 47, for the description’s numbers; the language in force when absent"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<SparklineMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "Words laid over the language in force, key by key: up, down and flat with {last}, {change} and {first}, and noData"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "Substitutes the root element. The role, the name and every data attribute are handed to it"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement>",
+          "defaultValue": "—",
+          "appliesTo": "Sparkline",
+          "description": "Reaches the root. Composed with the one the family measures with, never replaced"
+        },
+        {
+          "name": "--slotted-sparkline-color",
+          "type": "custom property",
+          "defaultValue": "—",
+          "appliesTo": "a container",
+          "description": "What a sparkline with no tone and no series is drawn in. stat-card writes it on its trend from the delta’s tone"
+        },
+        {
+          "name": "SparklineDefaultsProvider",
+          "type": "SparklineDefaults",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets curve, area, marker and formatOptions once for everything below it; a prop still wins"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The root carries role=\"img\" and an aria-label generated from the data: the last value, the direction and the change since the first — “Fill rate: 96.1%, up 3.2% since 92.9%”. Those are the two numbers a sparkline exists to compare, and they reach a reader who cannot see the shape.",
+        "The svg is aria-hidden. A drawing with no interaction is an image, and its content is pixels; there is no APG pattern for a sparkline, and the WAI-ARIA Graphics module reserves graphics-document for a drawing whose parts are navigable, which this one has none of.",
+        "Nothing here is focusable and nothing answers a key. Tooltips and per-point highlight belong to chart; a sparkline with them would be a small line chart.",
+        "Colour never carries the reading alone: the direction is in the description, the current bar is the last one by position as well as by colour, and a tone is a second encoding on top of the shape.",
+        "Under forced colours the data scale and the tones map to CanvasText, the wash is withdrawn, earlier bars take GrayText and the current one CanvasText, so a series still reads as one.",
+        "The eight slots of the data scale were chosen by measurement: adjacent slots separate by at least ΔE 16.8 under simulated protanopia and deuteranopia in every scheme, and every slot clears 3:1 against every surface."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-width-medium",
+    "--slotted-border-width-thick",
+    "--slotted-border-width-thin",
+    "--slotted-data-1",
+    "--slotted-data-2",
+    "--slotted-data-3",
+    "--slotted-data-4",
+    "--slotted-data-5",
+    "--slotted-data-6",
+    "--slotted-data-7",
+    "--slotted-data-8",
+    "--slotted-duration-medium",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-space-11",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-7",
+    "--slotted-space-9",
+    "--slotted-sparkline-area-opacity",
+    "--slotted-sparkline-bar-share",
+    "--slotted-sparkline-block-size",
+    "--slotted-sparkline-block-size-lg",
+    "--slotted-sparkline-block-size-sm",
+    "--slotted-sparkline-color",
+    "--slotted-sparkline-line-width",
+    "--slotted-sparkline-line-width-sm",
+    "--slotted-sparkline-marker-size",
+    "--slotted-sparkline-marker-size-lg",
+    "--slotted-sparkline-marker-size-sm",
+    "--slotted-sparkline-reference-color",
+    "--slotted-sparkline-ring-color",
+    "--slotted-sparkline-ring-width",
+    "--slotted-sparkline-ring-width-sm",
+    "--slotted-surface-raised",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-text",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One series, driven by the controls: switch the form, the curve, the wash and the marker, and read the description the screen reader gets in the tab title of the root.",
+      "language": "tsx",
+      "source": "<Sparkline data={fillRate} label=\"Fill rate, last 12 weeks\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "types",
+      "title": "A line for a trend, bars for a count per period",
+      "note": "The same twelve weeks four ways: a straight line, the line washed, the line smoothed with a monotone curve that never overshoots a point, and one bar per week with the current week at full colour.",
+      "language": "tsx",
+      "source": "<Sparkline data={orders} />;\n<Sparkline area data={orders} />;\n<Sparkline area curve=\"monotone\" data={orders} />;\n<Sparkline data={orders} type=\"bar\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Three heights, and the width is the container’s",
+      "note": "sm is twenty pixels tall for a table row, md thirty-two for a card, lg forty-eight for a card that leads a page. The stroke and the marker step down with sm; the width is always what the cell or the column gave.",
+      "language": "tsx",
+      "source": "<Sparkline data={orders} size=\"sm\" />;\n<Sparkline data={orders} size=\"md\" />;\n<Sparkline data={orders} size=\"lg\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "tone",
+      "title": "How the series is doing",
+      "note": "A tone paints the line in the tone’s text colour: success for an error rate that fell, danger for a lead time that grew, neutral for the comparison series behind a current one. Without a tone the line is the first slot of the data scale, the theme’s own blue.",
+      "language": "tsx",
+      "source": "<Sparkline data={errorRate} label=\"Error rate\" tone=\"success\" />;\n<Sparkline data={leadTime} label=\"Lead time\" tone=\"danger\" />;\n<Sparkline data={lastQuarter} label=\"Last quarter\" tone=\"neutral\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "series",
+      "title": "Which series this is",
+      "note": "Eight slots of the data scale in a fixed order, so the sparklines of eight warehouses beside each other are eight colours a reader with deuteranopia still tells apart. A tone wins over a series where both are given.",
+      "language": "tsx",
+      "source": "<>\n  {warehouses.map((warehouse, index) => (\n    <Sparkline\n      data={warehouse.shipments}\n      key={warehouse.id}\n      label={warehouse.name}\n      series={(index + 1) as SparklineSeries}\n    />\n  ))}\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reference",
+      "title": "A line that is not data",
+      "note": "The reference is dashed and neutral so it reads as a target before its colour does, and it widens the extent when it lies outside the data: a target of 95% above a series that peaks at 91% is drawn above the line, not clipped.",
+      "language": "tsx",
+      "source": "<Sparkline area data={onTime} label=\"On-time delivery\" reference={0.95} />;\n\n// A share of a whole is drawn from nought.\n<Sparkline data={onTime} min={0} type=\"bar\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "gaps",
+      "title": "A gap is a gap, not a value",
+      "note": "A null breaks the line and leaves the bar’s slot empty rather than being drawn as nought or bridged; a single point is a marker with no line; an empty series draws nothing and says so; a constant series runs through the middle.",
+      "language": "tsx",
+      "source": "<Sparkline area data={[10, 12, null, null, 15, 14, 16, null, 18, 19]} />;\n<Sparkline data={[10, 12, null, null, 15, 14, 16, null, 18, 19]} type=\"bar\" />;\n<Sparkline data={[7]} />;\n<Sparkline data={[]} label=\"Returns\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "extremes",
+      "title": "Content the family did not choose",
+      "note": "Four hundred points in eighty pixels stay one path; bars with no room for a gap draw contiguous and never under a pixel; a series that crosses nought hangs its bars from a baseline inside the box; a right-to-left document reads the series from the right.",
+      "language": "tsx",
+      "source": "<Sparkline data={everyMinute} label=\"Requests per minute\" />;\n<Sparkline data={netStock} type=\"bar\" />;\n<div dir=\"rtl\">\n  <Sparkline data={orders} />\n</div>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "in-table",
+      "title": "A trend column",
+      "note": "The sparkline’s real home beside a stat card: a size=\"sm\" line in a table cell, taking the column’s width, with the value it annotates in the column before it and the description carrying the same numbers to a screen reader.",
+      "language": "tsx",
+      "source": "<TableCell>\n  <Sparkline data={line.fillRate} label={`${line.name} fill rate`} size=\"sm\" />\n</TableCell>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "The root is an image named “Fill rate: 96.1%, up 3.2% since 92.9%” — last value, direction, change since the first, each number in the locale and format you give; description replaces the sentence, and messages replace its words.",
+      "language": "tsx",
+      "source": "<Sparkline\n  data={fillRate}\n  formatOptions={{ style: 'percent', maximumFractionDigits: 1 }}\n  label=\"Fill rate\"\n/>;\n\n<SlottedProvider locale=\"pt-BR\" catalogs={{ 'pt-BR': PT_BR }}>\n  <App />\n</SlottedProvider>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/sparkline.md

@@ -0,0 +1,208 @@
+<!-- index: ./index.md -->
+# sparkline
+
+`data-ui="sparkline"` · Tiny inline trend chart.
+
+## Import
+
+```tsx
+import { Sparkline, SparklineDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline data={fillRate} label="Fill rate, last 12 weeks" />;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | span | yes |
+| `plot` | svg | yes |
+| `area` | path | no |
+| `line` | path | no |
+| `bar` | path | no |
+| `reference` | line | no |
+| `ring` | path | no |
+| `marker` | path | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `data` | `(number \| null)[]` | — | Sparkline | The series, oldest first. null is a gap: the line breaks, the bar is not drawn, the summary ignores it |
+| `type` | `'line' \| 'bar'` | line | Sparkline | A line through the points, or one bar per period |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Sparkline | The height of the box: 20, 32 or 48 pixels |
+| `curve` | `'linear' \| 'monotone'` | linear | Sparkline | Straight segments, or a monotone curve that never draws a value the series does not hold |
+| `area` | `boolean` | false | Sparkline | The wash under a line |
+| `marker` | `boolean` | true | Sparkline | A disc on the last real point |
+| `reference` | `number` | — | Sparkline | A dashed hairline at this value. Widens the extent to hold it |
+| `min` | `number` | — | Sparkline | The lowest value the extent must hold. The data widens the extent, never narrows it |
+| `max` | `number` | — | Sparkline | The highest value the extent must hold |
+| `tone` | `'neutral' \| 'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | — | Sparkline | How the series is doing. Wins over series; unset, a container may decide |
+| `series` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8` | — | Sparkline | Which series this is, as a slot of the data scale. Unset, a container decides, then slot 1 |
+| `label` | `string` | — | Sparkline | What the series is, said first in the description |
+| `description` | `string` | — | Sparkline | The whole accessible name, in place of the generated one |
+| `formatOptions` | `Intl.NumberFormatOptions` | — | Sparkline | How each number in the description is written |
+| `valueFormatter` | `(value: number) => string` | — | Sparkline | A formatter of your own for the description, in place of Intl |
+| `locale` | `string` | — | Sparkline | BCP 47, for the description’s numbers; the language in force when absent |
+| `messages` | `Partial<SparklineMessages>` | — | Sparkline | Words laid over the language in force, key by key: up, down and flat with {last}, {change} and {first}, and noData |
+| `render` | `(props) => ReactNode` | — | Sparkline | Substitutes the root element. The role, the name and every data attribute are handed to it |
+| `ref` | `Ref<HTMLSpanElement>` | — | Sparkline | Reaches the root. Composed with the one the family measures with, never replaced |
+| `--slotted-sparkline-color` | `custom property` | — | a container | What a sparkline with no tone and no series is drawn in. stat-card writes it on its trend from the delta’s tone |
+| `SparklineDefaultsProvider` | `SparklineDefaults` | — | Application | Sets curve, area, marker and formatOptions once for everything below it; a prop still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `type` | `line`, `bar` | `line` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `curve` | `linear`, `monotone` | `linear` |
+| `tone` | `neutral`, `accent`, `secondary`, `success`, `warning`, `danger` | — |
+| `series` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` | — |
+
+## Rules
+
+- The root carries role="img" and an aria-label generated from the data: the last value, the direction and the change since the first — “Fill rate: 96.1%, up 3.2% since 92.9%”. Those are the two numbers a sparkline exists to compare, and they reach a reader who cannot see the shape.
+- The svg is aria-hidden. A drawing with no interaction is an image, and its content is pixels; there is no APG pattern for a sparkline, and the WAI-ARIA Graphics module reserves graphics-document for a drawing whose parts are navigable, which this one has none of.
+- Nothing here is focusable and nothing answers a key. Tooltips and per-point highlight belong to chart; a sparkline with them would be a small line chart.
+- Colour never carries the reading alone: the direction is in the description, the current bar is the last one by position as well as by colour, and a tone is a second encoding on top of the shape.
+- Under forced colours the data scale and the tones map to CanvasText, the wash is withdrawn, earlier bars take GrayText and the current one CanvasText, so a series still reads as one.
+- The eight slots of the data scale were chosen by measurement: adjacent slots separate by at least ΔE 16.8 under simulated protanopia and deuteranopia in every scheme, and every slot clears 3:1 against every surface.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-data-1`, `--slotted-data-2`, `--slotted-data-3`, `--slotted-data-4`, `--slotted-data-5`, `--slotted-data-6`, `--slotted-data-7`, `--slotted-data-8`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-space-11`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-7`, `--slotted-space-9`, `--slotted-sparkline-area-opacity`, `--slotted-sparkline-bar-share`, `--slotted-sparkline-block-size`, `--slotted-sparkline-block-size-lg`, `--slotted-sparkline-block-size-sm`, `--slotted-sparkline-color`, `--slotted-sparkline-line-width`, `--slotted-sparkline-line-width-sm`, `--slotted-sparkline-marker-size`, `--slotted-sparkline-marker-size-lg`, `--slotted-sparkline-marker-size-sm`, `--slotted-sparkline-reference-color`, `--slotted-sparkline-ring-color`, `--slotted-sparkline-ring-width`, `--slotted-sparkline-ring-width-sm`, `--slotted-surface-raised`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+
+## Examples
+
+### A line for a trend, bars for a count per period
+
+The same twelve weeks four ways: a straight line, the line washed, the line smoothed with a monotone curve that never overshoots a point, and one bar per week with the current week at full colour.
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline data={orders} />;
+<Sparkline area data={orders} />;
+<Sparkline area curve="monotone" data={orders} />;
+<Sparkline data={orders} type="bar" />;
+```
+
+### Three heights, and the width is the container’s
+
+sm is twenty pixels tall for a table row, md thirty-two for a card, lg forty-eight for a card that leads a page. The stroke and the marker step down with sm; the width is always what the cell or the column gave.
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline data={orders} size="sm" />;
+<Sparkline data={orders} size="md" />;
+<Sparkline data={orders} size="lg" />;
+```
+
+### How the series is doing
+
+A tone paints the line in the tone’s text colour: success for an error rate that fell, danger for a lead time that grew, neutral for the comparison series behind a current one. Without a tone the line is the first slot of the data scale, the theme’s own blue.
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline data={errorRate} label="Error rate" tone="success" />;
+<Sparkline data={leadTime} label="Lead time" tone="danger" />;
+<Sparkline data={lastQuarter} label="Last quarter" tone="neutral" />;
+```
+
+### Which series this is
+
+Eight slots of the data scale in a fixed order, so the sparklines of eight warehouses beside each other are eight colours a reader with deuteranopia still tells apart. A tone wins over a series where both are given.
+
+Excerpt — not a complete module
+
+```tsx
+<>
+  {warehouses.map((warehouse, index) => (
+    <Sparkline
+      data={warehouse.shipments}
+      key={warehouse.id}
+      label={warehouse.name}
+      series={(index + 1) as SparklineSeries}
+    />
+  ))}
+</>;
+```
+
+### A line that is not data
+
+The reference is dashed and neutral so it reads as a target before its colour does, and it widens the extent when it lies outside the data: a target of 95% above a series that peaks at 91% is drawn above the line, not clipped.
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline area data={onTime} label="On-time delivery" reference={0.95} />;
+
+// A share of a whole is drawn from nought.
+<Sparkline data={onTime} min={0} type="bar" />;
+```
+
+### A gap is a gap, not a value
+
+A null breaks the line and leaves the bar’s slot empty rather than being drawn as nought or bridged; a single point is a marker with no line; an empty series draws nothing and says so; a constant series runs through the middle.
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline area data={[10, 12, null, null, 15, 14, 16, null, 18, 19]} />;
+<Sparkline data={[10, 12, null, null, 15, 14, 16, null, 18, 19]} type="bar" />;
+<Sparkline data={[7]} />;
+<Sparkline data={[]} label="Returns" />;
+```
+
+### Content the family did not choose
+
+Four hundred points in eighty pixels stay one path; bars with no room for a gap draw contiguous and never under a pixel; a series that crosses nought hangs its bars from a baseline inside the box; a right-to-left document reads the series from the right.
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline data={everyMinute} label="Requests per minute" />;
+<Sparkline data={netStock} type="bar" />;
+<div dir="rtl">
+  <Sparkline data={orders} />
+</div>;
+```
+
+### A trend column
+
+The sparkline’s real home beside a stat card: a size="sm" line in a table cell, taking the column’s width, with the value it annotates in the column before it and the description carrying the same numbers to a screen reader.
+
+Excerpt — not a complete module
+
+```tsx
+<TableCell>
+  <Sparkline data={line.fillRate} label={`${line.name} fill rate`} size="sm" />
+</TableCell>;
+```
+
+### What a reader hears
+
+The root is an image named “Fill rate: 96.1%, up 3.2% since 92.9%” — last value, direction, change since the first, each number in the locale and format you give; description replaces the sentence, and messages replace its words.
+
+Excerpt — not a complete module
+
+```tsx
+<Sparkline
+  data={fillRate}
+  formatOptions={{ style: 'percent', maximumFractionDigits: 1 }}
+  label="Fill rate"
+/>;
+
+<SlottedProvider locale="pt-BR" catalogs={{ 'pt-BR': PT_BR }}>
+  <App />
+</SlottedProvider>;
+```