@krizaka/charts 0.0.0-stage → 0.2.0

package/registry/sparkline.json

@@ -0,0 +1,563 @@
+{
+  "name": "sparkline",
+  "package": "@krizaka/charts",
+  "type": "chart",
+  "title": "Sparkline",
+  "summary": "A word-sized trend without axes — in a stat, a table cell or a sentence — drawn on the server when its width is known.",
+  "description": "A word-sized trend without axes — in a stat, a table cell or a sentence — drawn on the server when its width is known.",
+  "status": "beta",
+  "category": "charts",
+  "platforms": "both",
+  "engine": "svg",
+  "tier": "core",
+  "whenToUse": [
+    "Beside a key figure: the last 30 days of a stat.",
+    "In a table, one per row: each model's throughput, each video's views."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "When the reader needs the values, the axes or a comparison.",
+      "use": "line-chart"
+    },
+    {
+      "when": "A value against a range.",
+      "use": "gauge"
+    }
+  ],
+  "bestPractices": [
+    "Give it a `width` in a table: it renders on the server, with no placeholder.",
+    "Colour by the trend with `trendTone` (`\"inverse\"` when down is good: costs, latency).",
+    "Write the current value next to it: the line shows the shape, not the figure."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "Its title is visually hidden but names it; its summary (first, last, extremes, trend) is read.",
+      "It does not take the focus: it is a picture of the trend, the figures are in the summary and its table."
+    ]
+  },
+  "related": [
+    "line-chart",
+    "gauge",
+    "bar-chart"
+  ],
+  "source": "packages/charts/src/meta/sparkline.ts",
+  "install": {
+    "web": "npm install @krizaka/charts",
+    "native": "npx expo install react-native-svg\nnpm install @krizaka/charts"
+  },
+  "web": {
+    "entry": "@krizaka/charts/sparkline",
+    "import": "import { Sparkline } from \"@krizaka/charts/sparkline\";",
+    "props": [
+      {
+        "component": "Sparkline",
+        "description": "The shape of a trend in a few pixels: a stat's last 30 days, a job's throughput.",
+        "props": [
+          {
+            "name": "data",
+            "type": "readonly (number | null)[]",
+            "default": null,
+            "description": "The values, oldest first (`null` for a gap).",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "BrandId",
+            "default": null,
+            "description": "The brand whose palette the charts use. Without it, a chart follows a `.brand-<id>` ancestor, else Krizaka. Set it\nwhen the app loads a brand stylesheet on `:root` (`@krizaka/tokens/brands/orazaka.css`).",
+            "required": false
+          },
+          {
+            "name": "categories",
+            "type": "readonly unknown[]",
+            "default": null,
+            "description": "The labels of the values (dates, ISO or `Date`), for the summary and the table. Default: their positions.",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "default": null,
+            "description": "A class on the figure (layout: margins, grid placement).",
+            "required": false
+          },
+          {
+            "name": "color",
+            "type": "SeriesColor",
+            "default": null,
+            "description": "A palette slot, a tone or a CSS colour. Default: the trend's tone when `trendTone`, else slot 1.",
+            "required": false
+          },
+          {
+            "name": "empty",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to show when there is nothing to draw (default: the `empty` label). An `EmptyState` of\n@krizaka /ui fits.",
+            "required": false
+          },
+          {
+            "name": "error",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The data could not be loaded: `true` says the default words, a node says yours (a retry button…).",
+            "required": false
+          },
+          {
+            "name": "format",
+            "type": "ValueFormat",
+            "default": null,
+            "description": "How the values are written in the summary and table.",
+            "required": false
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "default": null,
+            "description": "The height of the plot in pixels. Default 280 (a sparkline: 32).",
+            "required": false
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "default": null,
+            "description": "The id of the figure.",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "ChartLabelsInput",
+            "default": null,
+            "description": "The words, translated: the buttons, the states, the written summary.",
+            "required": false
+          },
+          {
+            "name": "live",
+            "type": "boolean",
+            "default": null,
+            "description": "Streaming data (a job queue, an auction): no entrance on updates, no announcement of every new point.",
+            "required": false
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": null,
+            "description": "The data is on its way: a skeleton of the chart, announced once.",
+            "required": false
+          },
+          {
+            "name": "locale",
+            "type": "Locale",
+            "default": null,
+            "description": "The locale of every figure and date (`\"fr-FR\"`). Default `\"en-US\"`.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "CSSProperties",
+            "default": null,
+            "description": "Inline style on the figure (layout only: colours come from the tokens).",
+            "required": false
+          },
+          {
+            "name": "summary",
+            "type": "\"hidden\" | \"visible\"",
+            "default": null,
+            "description": "The written summary: read by screen readers only (`\"hidden\"`, default), or shown under the chart (`\"visible\"`).",
+            "required": false
+          },
+          {
+            "name": "summaryText",
+            "type": "string",
+            "default": null,
+            "description": "Your own summary instead of the generated one (still read first by screen readers).",
+            "required": false
+          },
+          {
+            "name": "threshold",
+            "type": "Threshold",
+            "default": null,
+            "description": "A dashed reference line (yesterday's average, a quota).",
+            "required": false
+          },
+          {
+            "name": "trendTone",
+            "type": "boolean | \"inverse\"",
+            "default": null,
+            "description": "Colour by the trend: success up, danger down (or the reverse with `\"inverse\"`: costs, latency).",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"line\" | \"area\" | \"bar\"",
+            "default": null,
+            "description": "`line` (default), `area` (line over a wash) or `bar` (discrete counts: jobs per hour).",
+            "required": false
+          },
+          {
+            "name": "width",
+            "type": "number",
+            "default": null,
+            "description": "A fixed width in pixels: drawn on the server too. Default: the container's width.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "stat-trend",
+        "title": "In a stat",
+        "description": "Thirty days of views beside the figure, coloured by the trend.",
+        "path": "examples/sparkline/stat-trend.tsx",
+        "module": "@krizaka/charts/registry/examples/sparkline/stat-trend",
+        "code": "import { Sparkline } from \"@krizaka/charts/sparkline\";\n\nconst views = [820, 760, 910, 880, 1_020, 990, 1_130, 1_210, 1_090, 1_340, 1_280, 1_420, 1_390, 1_510, 1_620, 1_580, 1_700, 1_640, 1_810, 1_760, 1_930, 2_040, 1_980, 2_150, 2_090, 2_260, 2_340, 2_280, 2_410, 2_520];\n\nexport default function StatTrend() {\n  return (\n    <div style={{ display: \"flex\", alignItems: \"flex-end\", gap: 16 }}>\n      <div>\n        <p style={{ margin: 0, fontSize: 13, color: \"var(--kz-text-secondary)\" }}>Views, last 30 days</p>\n        <p style={{ margin: 0, fontSize: 28, fontWeight: 600, color: \"var(--kz-text-primary)\" }}>2,520</p>\n      </div>\n      <Sparkline title=\"Views, last 30 days\" data={views} variant=\"area\" trendTone width={140} height={40} format=\"integer\" />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "table-rows",
+        "title": "In a table",
+        "description": "One fixed-width sparkline per row, drawn on the server: latency, coloured inverse.",
+        "path": "examples/sparkline/table-rows.tsx",
+        "module": "@krizaka/charts/registry/examples/sparkline/table-rows",
+        "code": "import { Sparkline } from \"@krizaka/charts/sparkline\";\n\n// p95 latency (ms) over the last 12 hours: down is good, hence `trendTone=\"inverse\"`.\nconst models = [\n  { name: \"Chat · Mistral Large\", p95: [820, 790, 805, 760, 742, 731, 720, 704, 699, 688, 690, 676] },\n  { name: \"Image · Flux\", p95: [2_400, 2_380, 2_520, 2_610, 2_590, 2_700, 2_760, 2_810, 2_790, 2_880, 2_910, 2_950] },\n  { name: \"Speech · Whisper\", p95: [310, 305, 312, 309, 300, 311, 306, 304, 308, 302, 307, 305] },\n];\n\nexport default function TableRows() {\n  return (\n    <table style={{ borderCollapse: \"collapse\", fontSize: 13, color: \"var(--kz-text-primary)\" }}>\n      <tbody>\n        {models.map((m) => (\n          <tr key={m.name} style={{ borderTop: \"1px solid var(--kz-border-subtle)\" }}>\n            <th scope=\"row\" style={{ padding: \"8px 16px 8px 0\", textAlign: \"left\", fontWeight: 500 }}>{m.name}</th>\n            <td style={{ padding: 8 }}>\n              <Sparkline title={`${m.name}, p95 latency`} data={m.p95} trendTone=\"inverse\" width={120} height={28} format={{ style: \"unit\", unit: \"millisecond\" }} />\n            </td>\n            <td style={{ padding: 8, textAlign: \"right\" }}>{m.p95[m.p95.length - 1]} ms</td>\n          </tr>\n        ))}\n      </tbody>\n    </table>\n  );\n}\n"
+      },
+      {
+        "name": "bars",
+        "title": "Bars",
+        "description": "Discrete counts: jobs per hour.",
+        "path": "examples/sparkline/bars.tsx",
+        "module": "@krizaka/charts/registry/examples/sparkline/bars",
+        "code": "import { Sparkline } from \"@krizaka/charts/sparkline\";\n\nconst jobsPerHour = [12, 8, 5, 3, 2, 4, 9, 21, 38, 52, 61, 58, 64, 70, 66, 59, 63, 55, 47, 41, 33, 26, 19, 14];\n\nexport default function Bars() {\n  return <Sparkline title=\"Jobs per hour, today\" data={jobsPerHour} variant=\"bar\" width={180} height={36} format=\"integer\" color={2} />;\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/charts/native",
+    "import": "import { Sparkline } from \"@krizaka/charts/native\";",
+    "differences": [
+      "No threshold line."
+    ],
+    "props": [
+      {
+        "component": "Sparkline",
+        "description": "A word-sized trend (React Native).",
+        "props": [
+          {
+            "name": "data",
+            "type": "readonly (number | null)[]",
+            "default": null,
+            "description": "The values, oldest first (`null` for a gap).",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the chart shows: its heading and accessible name.",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "BrandId",
+            "default": null,
+            "description": "The brand whose palette leads. Default Krizaka.",
+            "required": false
+          },
+          {
+            "name": "categories",
+            "type": "readonly unknown[]",
+            "default": null,
+            "description": "The labels of the values (dates), for the summary.",
+            "required": false
+          },
+          {
+            "name": "color",
+            "type": "SeriesColor",
+            "default": null,
+            "description": "A palette slot, a tone or a colour.",
+            "required": false
+          },
+          {
+            "name": "empty",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Shown instead of the plot when there is nothing to draw. Default: the `empty` label.",
+            "required": false
+          },
+          {
+            "name": "format",
+            "type": "ValueFormat",
+            "default": null,
+            "description": "How the values are written in the summary.",
+            "required": false
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "default": null,
+            "description": "The plot's height.",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "ChartLabelsInput",
+            "default": null,
+            "description": "The words: the readout, the summary.",
+            "required": false
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": null,
+            "description": "The data is on its way.",
+            "required": false
+          },
+          {
+            "name": "locale",
+            "type": "Locale",
+            "default": null,
+            "description": "The locale of every figure and date. Default `\"en-US\"`.",
+            "required": false
+          },
+          {
+            "name": "scheme",
+            "type": "Mode",
+            "default": null,
+            "description": "Dark or light. Default: the device's (pass `useTheme().scheme` of\n@krizaka /ui/native to follow the app).",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "ViewStyle",
+            "default": null,
+            "description": "The style of the chart's container (layout only: colours come from the theme).",
+            "required": false
+          },
+          {
+            "name": "theme",
+            "type": "Partial<ChartTheme>",
+            "default": null,
+            "description": "The app's colour roles (`useTheme().theme` of\n@krizaka /ui/native): a product's brand overrides apply.",
+            "required": false
+          },
+          {
+            "name": "trendTone",
+            "type": "boolean | \"inverse\"",
+            "default": null,
+            "description": "Colour by the trend (success up, danger down; `\"inverse\"` for costs).",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"line\" | \"area\" | \"bar\"",
+            "default": null,
+            "description": "`line` (default), `area` or `bar`.",
+            "required": false
+          },
+          {
+            "name": "width",
+            "type": "number",
+            "default": null,
+            "description": "A fixed width. Default: the container's.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "stat-trend",
+        "title": "In a stat",
+        "description": "Thirty days of views, coloured by the trend.",
+        "path": "examples/sparkline/native/stat-trend.tsx",
+        "module": "@krizaka/charts/registry/examples/sparkline/native/stat-trend",
+        "code": "import { Sparkline } from \"@krizaka/charts/native\";\n\nconst views = [820, 760, 910, 880, 1_020, 990, 1_130, 1_210, 1_090, 1_340, 1_280, 1_420, 1_390, 1_510, 1_620, 1_580, 1_700, 1_640, 1_810, 1_760, 1_930, 2_040, 1_980, 2_150, 2_090, 2_260, 2_340, 2_280, 2_410, 2_520];\n\nexport default function StatTrend() {\n  return <Sparkline title=\"Views, last 30 days\" data={views} variant=\"area\" trendTone width={160} height={40} format=\"integer\" />;\n}\n",
+        "screenshots": {
+          "dark": "examples/sparkline/native/stat-trend.dark.png",
+          "light": "examples/sparkline/native/stat-trend.light.png"
+        }
+      }
+    ]
+  },
+  "files": [],
+  "dependencies": [
+    "@krizaka/intl@workspace:^",
+    "d3-geo@^3.1.1",
+    "echarts@^6.1.0",
+    "topojson-client@^3.1.0"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/sparkline/stat-trend.tsx",
+    "content": "import { Sparkline } from \"@krizaka/charts/sparkline\";\n\nconst views = [820, 760, 910, 880, 1_020, 990, 1_130, 1_210, 1_090, 1_340, 1_280, 1_420, 1_390, 1_510, 1_620, 1_580, 1_700, 1_640, 1_810, 1_760, 1_930, 2_040, 1_980, 2_150, 2_090, 2_260, 2_340, 2_280, 2_410, 2_520];\n\nexport default function StatTrend() {\n  return (\n    <div style={{ display: \"flex\", alignItems: \"flex-end\", gap: 16 }}>\n      <div>\n        <p style={{ margin: 0, fontSize: 13, color: \"var(--kz-text-secondary)\" }}>Views, last 30 days</p>\n        <p style={{ margin: 0, fontSize: 28, fontWeight: 600, color: \"var(--kz-text-primary)\" }}>2,520</p>\n      </div>\n      <Sparkline title=\"Views, last 30 days\" data={views} variant=\"area\" trendTone width={140} height={40} format=\"integer\" />\n    </div>\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "Sparkline",
+      "description": "The shape of a trend in a few pixels: a stat's last 30 days, a job's throughput.",
+      "props": [
+        {
+          "name": "data",
+          "type": "readonly (number | null)[]",
+          "default": null,
+          "description": "The values, oldest first (`null` for a gap).",
+          "required": true
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "default": null,
+          "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
+          "required": true
+        },
+        {
+          "name": "brand",
+          "type": "BrandId",
+          "default": null,
+          "description": "The brand whose palette the charts use. Without it, a chart follows a `.brand-<id>` ancestor, else Krizaka. Set it\nwhen the app loads a brand stylesheet on `:root` (`@krizaka/tokens/brands/orazaka.css`).",
+          "required": false
+        },
+        {
+          "name": "categories",
+          "type": "readonly unknown[]",
+          "default": null,
+          "description": "The labels of the values (dates, ISO or `Date`), for the summary and the table. Default: their positions.",
+          "required": false
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "A class on the figure (layout: margins, grid placement).",
+          "required": false
+        },
+        {
+          "name": "color",
+          "type": "SeriesColor",
+          "default": null,
+          "description": "A palette slot, a tone or a CSS colour. Default: the trend's tone when `trendTone`, else slot 1.",
+          "required": false
+        },
+        {
+          "name": "empty",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What to show when there is nothing to draw (default: the `empty` label). An `EmptyState` of\n@krizaka /ui fits.",
+          "required": false
+        },
+        {
+          "name": "error",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The data could not be loaded: `true` says the default words, a node says yours (a retry button…).",
+          "required": false
+        },
+        {
+          "name": "format",
+          "type": "ValueFormat",
+          "default": null,
+          "description": "How the values are written in the summary and table.",
+          "required": false
+        },
+        {
+          "name": "height",
+          "type": "number",
+          "default": null,
+          "description": "The height of the plot in pixels. Default 280 (a sparkline: 32).",
+          "required": false
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "default": null,
+          "description": "The id of the figure.",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "ChartLabelsInput",
+          "default": null,
+          "description": "The words, translated: the buttons, the states, the written summary.",
+          "required": false
+        },
+        {
+          "name": "live",
+          "type": "boolean",
+          "default": null,
+          "description": "Streaming data (a job queue, an auction): no entrance on updates, no announcement of every new point.",
+          "required": false
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "default": null,
+          "description": "The data is on its way: a skeleton of the chart, announced once.",
+          "required": false
+        },
+        {
+          "name": "locale",
+          "type": "Locale",
+          "default": null,
+          "description": "The locale of every figure and date (`\"fr-FR\"`). Default `\"en-US\"`.",
+          "required": false
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "default": null,
+          "description": "Inline style on the figure (layout only: colours come from the tokens).",
+          "required": false
+        },
+        {
+          "name": "summary",
+          "type": "\"hidden\" | \"visible\"",
+          "default": null,
+          "description": "The written summary: read by screen readers only (`\"hidden\"`, default), or shown under the chart (`\"visible\"`).",
+          "required": false
+        },
+        {
+          "name": "summaryText",
+          "type": "string",
+          "default": null,
+          "description": "Your own summary instead of the generated one (still read first by screen readers).",
+          "required": false
+        },
+        {
+          "name": "threshold",
+          "type": "Threshold",
+          "default": null,
+          "description": "A dashed reference line (yesterday's average, a quota).",
+          "required": false
+        },
+        {
+          "name": "trendTone",
+          "type": "boolean | \"inverse\"",
+          "default": null,
+          "description": "Colour by the trend: success up, danger down (or the reverse with `\"inverse\"`: costs, latency).",
+          "required": false
+        },
+        {
+          "name": "variant",
+          "type": "\"line\" | \"area\" | \"bar\"",
+          "default": null,
+          "description": "`line` (default), `area` (line over a wash) or `bar` (discrete counts: jobs per hour).",
+          "required": false
+        },
+        {
+          "name": "width",
+          "type": "number",
+          "default": null,
+          "description": "A fixed width in pixels: drawn on the server too. Default: the container's width.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}