@krizaka/charts 0.3.0 → 0.4.0

package/registry/kpi-stat.json

@@ -0,0 +1,296 @@
+{
+  "name": "kpi-stat",
+  "package": "@krizaka/charts",
+  "type": "chart",
+  "title": "KPI stat",
+  "summary": "A key figure with its change against the previous period and a sparkline of the period, on the kit's Stat.",
+  "description": "A key figure with its change against the previous period and a sparkline of the period, on the kit's Stat.",
+  "status": "beta",
+  "category": "charts",
+  "platforms": "web",
+  "engine": null,
+  "tier": "ready-made",
+  "whenToUse": [
+    "The head of a dashboard: jobs, success rate, time to a result, spend.",
+    "Anywhere a figure needs its direction and its shape at a glance."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "A chart the reader will explore.",
+      "use": "line-chart"
+    },
+    {
+      "when": "A value against a limit.",
+      "use": "gauge"
+    }
+  ],
+  "bestPractices": [
+    "Pass `previous` and the trend is computed and written in words; the arrow is only decoration.",
+    "Use `good=down` for latency, failures and spend: the arrow's colour says whether the change is good news.",
+    "Put several in a `StatGrid` of the kit: they wrap with the width."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "The change is written (`+24 % vs previous period`), never colour or arrow alone.",
+      "The sparkline has its own accessible summary; the figure is read as text."
+    ]
+  },
+  "related": [
+    "chart-card",
+    "sparkline",
+    "gauge"
+  ],
+  "source": "packages/charts/src/meta/kpi-stat.ts",
+  "install": {
+    "web": "npm install @krizaka/charts",
+    "native": "npx expo install react-native-svg\nnpm install @krizaka/charts"
+  },
+  "web": {
+    "entry": "@krizaka/charts/card",
+    "import": "import { KpiStat } from \"@krizaka/charts/card\";",
+    "props": [
+      {
+        "component": "KpiStat",
+        "description": "A key figure, its change against the previous period and the shape of the period.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "What the figure is (“Jobs”).",
+            "required": true
+          },
+          {
+            "name": "value",
+            "type": "number",
+            "default": null,
+            "description": "The figure for the period.",
+            "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 `data` (dates), for the sparkline's summary and table.",
+            "required": false
+          },
+          {
+            "name": "color",
+            "type": "SeriesColor",
+            "default": null,
+            "description": "The sparkline's colour. Default: the brand's.",
+            "required": false
+          },
+          {
+            "name": "data",
+            "type": "readonly (number | null)[]",
+            "default": null,
+            "description": "The shape of the period, oldest first (`null` for a gap). Without it, no sparkline.",
+            "required": false
+          },
+          {
+            "name": "format",
+            "type": "ValueFormat",
+            "default": null,
+            "description": "How it is written. Default `\"number\"`.",
+            "required": false
+          },
+          {
+            "name": "good",
+            "type": "\"up\" | \"down\"",
+            "default": "up",
+            "description": "Which direction is good news. Default `\"up\"`; `\"down\"` for latency, failures, spend.",
+            "required": false
+          },
+          {
+            "name": "hint",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A line under the value: the period, the comparison.",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "ChartLabelsInput",
+            "default": null,
+            "description": "The words, translated: the buttons, the states, the written summary.",
+            "required": false
+          },
+          {
+            "name": "locale",
+            "type": "Locale",
+            "default": null,
+            "description": "The locale of every figure and date (`\"fr-FR\"`). Default `\"en-US\"`.",
+            "required": false
+          },
+          {
+            "name": "previous",
+            "type": "number",
+            "default": null,
+            "description": "The same figure for the previous period: the trend is computed from it.",
+            "required": false
+          },
+          {
+            "name": "trendLabel",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Your own words for the change instead of “+12 % vs previous period”.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"area\" | \"line\" | \"bar\"",
+            "default": "area",
+            "description": "`bar` for discrete counts (jobs per day), `area` (default) or `line`.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "dashboard-row",
+        "title": "A dashboard row",
+        "description": "Four figures in a StatGrid, with sparklines and trends.",
+        "path": "examples/kpi-stat/dashboard-row.tsx",
+        "module": "@krizaka/charts/registry/examples/kpi-stat/dashboard-row",
+        "code": "import { KpiStat } from \"@krizaka/charts/card\";\nimport { StatGrid } from \"@krizaka/ui/stat\";\n\nconst jobs = [12, 18, 9, 22, 31, 27, 35, 41];\nconst minutes = [4.2, 4.6, 5.1, 4.4, 3.9, 3.7, 3.5, 3.2];\n\n// The head of a dashboard: each figure with its change against the previous period and the shape of the period.\nexport default function DashboardRow() {\n  return (\n    <StatGrid>\n      <KpiStat label=\"Jobs\" value={195} previous={157} data={jobs} variant=\"bar\" hint=\"last 8 days\" />\n      <KpiStat label=\"Success rate\" value={0.94} previous={0.91} format=\"percent\" hint=\"completed / all\" />\n      <KpiStat label=\"Median time\" value={3.2} previous={4.2} good=\"down\" data={minutes} format={{ style: \"unit\", unit: \"minute\" }} hint=\"to a result\" />\n      <KpiStat label=\"Credits spent\" value={1240} previous={1100} good=\"down\" format=\"integer\" hint=\"this period\" />\n    </StatGrid>\n  );\n}\n"
+      },
+      {
+        "name": "single",
+        "title": "One figure",
+        "description": "A rise in latency is bad: good=down.",
+        "path": "examples/kpi-stat/single.tsx",
+        "module": "@krizaka/charts/registry/examples/kpi-stat/single",
+        "code": "import { KpiStat } from \"@krizaka/charts/card\";\n\n// A rise in latency is bad news: good=\"down\" makes the arrow say so.\nexport default function Single() {\n  return <KpiStat label=\"Time to a result\" value={48} previous={31} good=\"down\" format={{ style: \"unit\", unit: \"second\" }} data={[31, 29, 35, 38, 41, 44, 48]} hint=\"median, last 7 days\" />;\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [],
+  "dependencies": [
+    "@krizaka/intl@workspace:^",
+    "d3-geo@^3.1.1",
+    "echarts@^6.1.0",
+    "topojson-client@^3.1.0"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/kpi-stat/dashboard-row.tsx",
+    "content": "import { KpiStat } from \"@krizaka/charts/card\";\nimport { StatGrid } from \"@krizaka/ui/stat\";\n\nconst jobs = [12, 18, 9, 22, 31, 27, 35, 41];\nconst minutes = [4.2, 4.6, 5.1, 4.4, 3.9, 3.7, 3.5, 3.2];\n\n// The head of a dashboard: each figure with its change against the previous period and the shape of the period.\nexport default function DashboardRow() {\n  return (\n    <StatGrid>\n      <KpiStat label=\"Jobs\" value={195} previous={157} data={jobs} variant=\"bar\" hint=\"last 8 days\" />\n      <KpiStat label=\"Success rate\" value={0.94} previous={0.91} format=\"percent\" hint=\"completed / all\" />\n      <KpiStat label=\"Median time\" value={3.2} previous={4.2} good=\"down\" data={minutes} format={{ style: \"unit\", unit: \"minute\" }} hint=\"to a result\" />\n      <KpiStat label=\"Credits spent\" value={1240} previous={1100} good=\"down\" format=\"integer\" hint=\"this period\" />\n    </StatGrid>\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "KpiStat",
+      "description": "A key figure, its change against the previous period and the shape of the period.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": null,
+          "description": "What the figure is (“Jobs”).",
+          "required": true
+        },
+        {
+          "name": "value",
+          "type": "number",
+          "default": null,
+          "description": "The figure for the period.",
+          "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 `data` (dates), for the sparkline's summary and table.",
+          "required": false
+        },
+        {
+          "name": "color",
+          "type": "SeriesColor",
+          "default": null,
+          "description": "The sparkline's colour. Default: the brand's.",
+          "required": false
+        },
+        {
+          "name": "data",
+          "type": "readonly (number | null)[]",
+          "default": null,
+          "description": "The shape of the period, oldest first (`null` for a gap). Without it, no sparkline.",
+          "required": false
+        },
+        {
+          "name": "format",
+          "type": "ValueFormat",
+          "default": null,
+          "description": "How it is written. Default `\"number\"`.",
+          "required": false
+        },
+        {
+          "name": "good",
+          "type": "\"up\" | \"down\"",
+          "default": "up",
+          "description": "Which direction is good news. Default `\"up\"`; `\"down\"` for latency, failures, spend.",
+          "required": false
+        },
+        {
+          "name": "hint",
+          "type": "ReactNode",
+          "default": null,
+          "description": "A line under the value: the period, the comparison.",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "ChartLabelsInput",
+          "default": null,
+          "description": "The words, translated: the buttons, the states, the written summary.",
+          "required": false
+        },
+        {
+          "name": "locale",
+          "type": "Locale",
+          "default": null,
+          "description": "The locale of every figure and date (`\"fr-FR\"`). Default `\"en-US\"`.",
+          "required": false
+        },
+        {
+          "name": "previous",
+          "type": "number",
+          "default": null,
+          "description": "The same figure for the previous period: the trend is computed from it.",
+          "required": false
+        },
+        {
+          "name": "trendLabel",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Your own words for the change instead of “+12 % vs previous period”.",
+          "required": false
+        },
+        {
+          "name": "variant",
+          "type": "\"area\" | \"line\" | \"bar\"",
+          "default": "area",
+          "description": "`bar` for discrete counts (jobs per day), `area` (default) or `line`.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/latency-chart.json

@@ -72,11 +72,18 @@
             "required": true
           },
           {
-            "name": "title",
-            "type": "string",
+            "name": "actionsMenu",
+            "type": "boolean",
             "default": null,
-            "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
-            "required": true
+            "description": "The ⋯ actions menu of the kit. `false`: the former “Show data” and export buttons, drawn in line. Default true.",
+            "required": false
+          },
+          {
+            "name": "autoRange",
+            "type": "boolean",
+            "default": null,
+            "description": "Zoom the time axis on the period that has data: the empty days before the first and after the last value are\nleft out (never fewer than `minPoints`), and a sparse period says so under the chart instead of drawing 13 empty\ndays around one bar. Default false.",
+            "required": false
           },
           {
             "name": "brand",
@@ -96,7 +103,7 @@
             "name": "dataTable",
             "type": "boolean",
             "default": null,
-            "description": "The \"Show data\" button (the table is in the page for screen readers either way). Default true.",
+            "description": "“View as table” in the actions menu (the table is in the page for screen readers either way). Default true.",
             "required": false
           },
           {
@@ -124,7 +131,14 @@
             "name": "exportable",
             "type": "boolean | readonly ExportFormat[]",
             "default": null,
-            "description": "Export buttons: `true` for PNG, SVG and CSV, or the formats you want.",
+            "description": "The downloads of the actions menu: all three by default, or the formats you want, or `false` for none.",
+            "required": false
+          },
+          {
+            "name": "filterable",
+            "type": "boolean",
+            "default": null,
+            "description": "The legend chips switch the series on and off. Default true.",
             "required": false
           },
           {
@@ -155,6 +169,13 @@
             "description": "The id of the figure.",
             "required": false
           },
+          {
+            "name": "insight",
+            "type": "ReactNode",
+            "default": null,
+            "description": "One line that says what the chart shows, between the title and the chart: “100 jobs · +100 % vs last week”.",
+            "required": false
+          },
           {
             "name": "labels",
             "type": "Partial<LatencyLabels>",
@@ -197,6 +218,13 @@
             "description": "Vertical markers at a category: a launch, an incident.",
             "required": false
           },
+          {
+            "name": "minPoints",
+            "type": "number",
+            "default": null,
+            "description": "With `autoRange`, the fewest categories to keep so a short burst still has a time scale. Default 7.",
+            "required": false
+          },
           {
             "name": "objective",
             "type": "{ readonly value: number; readonly label: string; }",
@@ -246,6 +274,13 @@
             "description": "Your own summary instead of the generated one (still read first by screen readers).",
             "required": false
           },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`. Inside a `ChartCard`, the card's title is the default.",
+            "required": false
+          },
           {
             "name": "vertical",
             "type": "boolean",
@@ -463,11 +498,18 @@
           "required": true
         },
         {
-          "name": "title",
-          "type": "string",
+          "name": "actionsMenu",
+          "type": "boolean",
           "default": null,
-          "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
-          "required": true
+          "description": "The ⋯ actions menu of the kit. `false`: the former “Show data” and export buttons, drawn in line. Default true.",
+          "required": false
+        },
+        {
+          "name": "autoRange",
+          "type": "boolean",
+          "default": null,
+          "description": "Zoom the time axis on the period that has data: the empty days before the first and after the last value are\nleft out (never fewer than `minPoints`), and a sparse period says so under the chart instead of drawing 13 empty\ndays around one bar. Default false.",
+          "required": false
         },
         {
           "name": "brand",
@@ -487,7 +529,7 @@
           "name": "dataTable",
           "type": "boolean",
           "default": null,
-          "description": "The \"Show data\" button (the table is in the page for screen readers either way). Default true.",
+          "description": "“View as table” in the actions menu (the table is in the page for screen readers either way). Default true.",
           "required": false
         },
         {
@@ -515,7 +557,14 @@
           "name": "exportable",
           "type": "boolean | readonly ExportFormat[]",
           "default": null,
-          "description": "Export buttons: `true` for PNG, SVG and CSV, or the formats you want.",
+          "description": "The downloads of the actions menu: all three by default, or the formats you want, or `false` for none.",
+          "required": false
+        },
+        {
+          "name": "filterable",
+          "type": "boolean",
+          "default": null,
+          "description": "The legend chips switch the series on and off. Default true.",
           "required": false
         },
         {
@@ -546,6 +595,13 @@
           "description": "The id of the figure.",
           "required": false
         },
+        {
+          "name": "insight",
+          "type": "ReactNode",
+          "default": null,
+          "description": "One line that says what the chart shows, between the title and the chart: “100 jobs · +100 % vs last week”.",
+          "required": false
+        },
         {
           "name": "labels",
           "type": "Partial<LatencyLabels>",
@@ -588,6 +644,13 @@
           "description": "Vertical markers at a category: a launch, an incident.",
           "required": false
         },
+        {
+          "name": "minPoints",
+          "type": "number",
+          "default": null,
+          "description": "With `autoRange`, the fewest categories to keep so a short burst still has a time scale. Default 7.",
+          "required": false
+        },
         {
           "name": "objective",
           "type": "{ readonly value: number; readonly label: string; }",
@@ -637,6 +700,13 @@
           "description": "Your own summary instead of the generated one (still read first by screen readers).",
           "required": false
         },
+        {
+          "name": "title",
+          "type": "string",
+          "default": null,
+          "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`. Inside a `ChartCard`, the card's title is the default.",
+          "required": false
+        },
         {
           "name": "vertical",
           "type": "boolean",

package/registry/line-chart.json

@@ -93,11 +93,18 @@
             "required": true
           },
           {
-            "name": "title",
-            "type": "string",
+            "name": "actionsMenu",
+            "type": "boolean",
             "default": null,
-            "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
-            "required": true
+            "description": "The ⋯ actions menu of the kit. `false`: the former “Show data” and export buttons, drawn in line. Default true.",
+            "required": false
+          },
+          {
+            "name": "autoRange",
+            "type": "boolean",
+            "default": null,
+            "description": "Zoom the time axis on the period that has data: the empty days before the first and after the last value are\nleft out (never fewer than `minPoints`), and a sparse period says so under the chart instead of drawing 13 empty\ndays around one bar. Default false.",
+            "required": false
           },
           {
             "name": "brand",
@@ -124,7 +131,7 @@
             "name": "dataTable",
             "type": "boolean",
             "default": null,
-            "description": "The \"Show data\" button (the table is in the page for screen readers either way). Default true.",
+            "description": "“View as table” in the actions menu (the table is in the page for screen readers either way). Default true.",
             "required": false
           },
           {
@@ -166,7 +173,14 @@
             "name": "exportable",
             "type": "boolean | readonly ExportFormat[]",
             "default": null,
-            "description": "Export buttons: `true` for PNG, SVG and CSV, or the formats you want.",
+            "description": "The downloads of the actions menu: all three by default, or the formats you want, or `false` for none.",
+            "required": false
+          },
+          {
+            "name": "filterable",
+            "type": "boolean",
+            "default": null,
+            "description": "The legend chips switch the series on and off. Default true.",
             "required": false
           },
           {
@@ -197,6 +211,13 @@
             "description": "The id of the figure.",
             "required": false
           },
+          {
+            "name": "insight",
+            "type": "ReactNode",
+            "default": null,
+            "description": "One line that says what the chart shows, between the title and the chart: “100 jobs · +100 % vs last week”.",
+            "required": false
+          },
           {
             "name": "labels",
             "type": "ChartLabelsInput",
@@ -239,6 +260,13 @@
             "description": "Vertical markers at a category: a launch, an incident.",
             "required": false
           },
+          {
+            "name": "minPoints",
+            "type": "number",
+            "default": null,
+            "description": "With `autoRange`, the fewest categories to keep so a short burst still has a time scale. Default 7.",
+            "required": false
+          },
           {
             "name": "onSelect",
             "type": "((datum: T, index: number) => void)",
@@ -281,6 +309,13 @@
             "description": "Horizontal lines at a value: a goal, a payout threshold.",
             "required": false
           },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`. Inside a `ChartCard`, the card's title is the default.",
+            "required": false
+          },
           {
             "name": "x",
             "type": "string | ((datum: T, index: number) => unknown)",
@@ -557,11 +592,18 @@
           "required": true
         },
         {
-          "name": "title",
-          "type": "string",
+          "name": "actionsMenu",
+          "type": "boolean",
           "default": null,
-          "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
-          "required": true
+          "description": "The ⋯ actions menu of the kit. `false`: the former “Show data” and export buttons, drawn in line. Default true.",
+          "required": false
+        },
+        {
+          "name": "autoRange",
+          "type": "boolean",
+          "default": null,
+          "description": "Zoom the time axis on the period that has data: the empty days before the first and after the last value are\nleft out (never fewer than `minPoints`), and a sparse period says so under the chart instead of drawing 13 empty\ndays around one bar. Default false.",
+          "required": false
         },
         {
           "name": "brand",
@@ -588,7 +630,7 @@
           "name": "dataTable",
           "type": "boolean",
           "default": null,
-          "description": "The \"Show data\" button (the table is in the page for screen readers either way). Default true.",
+          "description": "“View as table” in the actions menu (the table is in the page for screen readers either way). Default true.",
           "required": false
         },
         {
@@ -630,7 +672,14 @@
           "name": "exportable",
           "type": "boolean | readonly ExportFormat[]",
           "default": null,
-          "description": "Export buttons: `true` for PNG, SVG and CSV, or the formats you want.",
+          "description": "The downloads of the actions menu: all three by default, or the formats you want, or `false` for none.",
+          "required": false
+        },
+        {
+          "name": "filterable",
+          "type": "boolean",
+          "default": null,
+          "description": "The legend chips switch the series on and off. Default true.",
           "required": false
         },
         {
@@ -661,6 +710,13 @@
           "description": "The id of the figure.",
           "required": false
         },
+        {
+          "name": "insight",
+          "type": "ReactNode",
+          "default": null,
+          "description": "One line that says what the chart shows, between the title and the chart: “100 jobs · +100 % vs last week”.",
+          "required": false
+        },
         {
           "name": "labels",
           "type": "ChartLabelsInput",
@@ -703,6 +759,13 @@
           "description": "Vertical markers at a category: a launch, an incident.",
           "required": false
         },
+        {
+          "name": "minPoints",
+          "type": "number",
+          "default": null,
+          "description": "With `autoRange`, the fewest categories to keep so a short burst still has a time scale. Default 7.",
+          "required": false
+        },
         {
           "name": "onSelect",
           "type": "((datum: T, index: number) => void)",
@@ -745,6 +808,13 @@
           "description": "Horizontal lines at a value: a goal, a payout threshold.",
           "required": false
         },
+        {
+          "name": "title",
+          "type": "string",
+          "default": null,
+          "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`. Inside a `ChartCard`, the card's title is the default.",
+          "required": false
+        },
         {
           "name": "x",
           "type": "string | ((datum: T, index: number) => unknown)",