@krizaka/charts 0.0.0-stage → 0.1.0

package/registry/gauge.json

@@ -0,0 +1,599 @@
+{
+  "name": "gauge",
+  "package": "@krizaka/charts",
+  "type": "chart",
+  "title": "Gauge",
+  "summary": "One value against its range on a 240° arc: zones that change its tone, a target tick, the value written in the middle.",
+  "description": "One value against its range on a 240° arc: zones that change its tone, a target tick, the value written in the middle.",
+  "status": "beta",
+  "category": "charts",
+  "platforms": "both",
+  "engine": "svg",
+  "whenToUse": [
+    "A quota: credits used of a plan, with a warning zone before the limit.",
+    "Progress towards a goal with a target: a challenge's escrow against its objective.",
+    "A load or a score that has a known range."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "Several values side by side (a gauge per item takes room and compares badly).",
+      "use": "bar-chart"
+    },
+    {
+      "when": "A value without a meaningful range.",
+      "use": "sparkline"
+    }
+  ],
+  "bestPractices": [
+    "Say the range in `caption` (“of 50,000 credits”): the arc alone is not a number.",
+    "Give zones their meaning in `label` (“Over quota”): it is read in the summary.",
+    "Use one gauge per screen at most; a row of figures reads better as stats."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "The gauge is a `meter`: its name is the title, its value, range and text (value and caption) are exposed.",
+      "The zone's tone is never the only signal: its label is in the summary.",
+      "The arc fills once, when the gauge comes on screen, and never under reduced motion."
+    ]
+  },
+  "related": [
+    "pie-chart",
+    "sparkline",
+    "bar-chart"
+  ],
+  "source": "packages/charts/src/meta/gauge.ts",
+  "install": {
+    "web": "npm install @krizaka/charts",
+    "native": "npx expo install react-native-svg\nnpm install @krizaka/charts"
+  },
+  "web": {
+    "entry": "@krizaka/charts/gauge",
+    "import": "import { Gauge } from \"@krizaka/charts/gauge\";",
+    "props": [
+      {
+        "component": "Gauge",
+        "description": "One figure against its range — credits used of a plan, a challenge's progress, a load.",
+        "props": [
+          {
+            "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": "value",
+            "type": "number",
+            "default": null,
+            "description": "The value.",
+            "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": "caption",
+            "type": "string",
+            "default": null,
+            "description": "The words under the value (“of 50 000 credits”).",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "default": null,
+            "description": "A class on the figure (layout: margins, grid placement).",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A sentence under the title: the period, the unit, the source.",
+            "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 value and the range are written.",
+            "required": false
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "default": null,
+            "description": "The height of the plot in pixels. Default 280 (a sparkline: 32).",
+            "required": false
+          },
+          {
+            "name": "hideTitle",
+            "type": "boolean",
+            "default": null,
+            "description": "Visually hide the title (it stays the chart's accessible name): a card that already has its heading.",
+            "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": "max",
+            "type": "number",
+            "default": null,
+            "description": "The end of the range. Default 100.",
+            "required": false
+          },
+          {
+            "name": "min",
+            "type": "number",
+            "default": null,
+            "description": "The start of the range. Default 0.",
+            "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": "target",
+            "type": "Threshold",
+            "default": null,
+            "description": "A tick on the arc: the objective.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "Tone",
+            "default": null,
+            "description": "The tone of the value without zones. Default `\"accent\"`.",
+            "required": false
+          },
+          {
+            "name": "zones",
+            "type": "readonly GaugeZone[]",
+            "default": null,
+            "description": "Coloured zones along the arc: the value takes the tone of the zone it is in.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "credits-quota",
+        "title": "Quota",
+        "description": "Credits used of a plan: green, then warning past 80 %, danger past the plan.",
+        "path": "examples/gauge/credits-quota.tsx",
+        "module": "@krizaka/charts/registry/examples/gauge/credits-quota",
+        "code": "import { Gauge } from \"@krizaka/charts/gauge\";\n\nexport default function CreditsQuota() {\n  return (\n    <Gauge\n      title=\"Credits used this month\"\n      value={41_250}\n      max={50_000}\n      format=\"compact\"\n      caption=\"of 50K credits\"\n      zones={[\n        { to: 40_000, tone: \"success\", label: \"Within plan\" },\n        { to: 47_500, tone: \"warning\", label: \"Nearing the limit\" },\n        { to: 50_000, tone: \"danger\", label: \"At the limit\" },\n      ]}\n      style={{ maxWidth: 320 }}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "challenge-goal",
+        "title": "Goal",
+        "description": "A challenge's escrowed amount against its objective, a target tick on the arc.",
+        "path": "examples/gauge/challenge-goal.tsx",
+        "module": "@krizaka/charts/registry/examples/gauge/challenge-goal",
+        "code": "import { Gauge } from \"@krizaka/charts/gauge\";\n\n// A challenge's escrow, in cents, against its objective.\nexport default function ChallengeGoal() {\n  return (\n    <Gauge\n      title=\"“Shoot the sunrise from the Mont-Royal”\"\n      description=\"Challenge in escrow · 6 days left\"\n      value={186_000}\n      max={300_000}\n      format={{ style: \"money\", currency: \"CAD\" }}\n      caption=\"raised\"\n      target={{ value: 250_000, label: \"Objective\" }}\n      tone=\"accent\"\n      style={{ maxWidth: 320 }}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/charts/native",
+    "import": "import { Gauge } from \"@krizaka/charts/native\";",
+    "differences": [
+      "No zone bands around the arc: the value takes the zone's tone.",
+      "The summary is the accessible label (no meter role in React Native)."
+    ],
+    "props": [
+      {
+        "component": "Gauge",
+        "description": "One figure against its range (React Native).",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the chart shows: its heading and accessible name.",
+            "required": true
+          },
+          {
+            "name": "value",
+            "type": "number",
+            "default": null,
+            "description": "The value.",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "BrandId",
+            "default": null,
+            "description": "The brand whose palette leads. Default Krizaka.",
+            "required": false
+          },
+          {
+            "name": "caption",
+            "type": "string",
+            "default": null,
+            "description": "The words under the value.",
+            "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 value is written.",
+            "required": false
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "default": null,
+            "description": "The plot's height.",
+            "required": false
+          },
+          {
+            "name": "hideTitle",
+            "type": "boolean",
+            "default": null,
+            "description": "Hide the heading (it stays the accessible name).",
+            "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": "max",
+            "type": "number",
+            "default": null,
+            "description": "The end of the range. Default 100.",
+            "required": false
+          },
+          {
+            "name": "min",
+            "type": "number",
+            "default": null,
+            "description": "The start of the range. Default 0.",
+            "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": "target",
+            "type": "Threshold",
+            "default": null,
+            "description": "A tick on the arc: the objective.",
+            "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": "tone",
+            "type": "Tone",
+            "default": null,
+            "description": "The tone of the value without zones. Default `\"accent\"`.",
+            "required": false
+          },
+          {
+            "name": "zones",
+            "type": "readonly { readonly to: number; readonly tone: Tone; readonly label?: string; }[]",
+            "default": null,
+            "description": "Zones: the value takes the tone of the zone it is in.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "credits-quota",
+        "title": "Quota",
+        "description": "Credits used of a plan.",
+        "path": "examples/gauge/native/credits-quota.tsx",
+        "module": "@krizaka/charts/registry/examples/gauge/native/credits-quota",
+        "code": "import { Gauge } from \"@krizaka/charts/native\";\n\nexport default function CreditsQuota() {\n  return (\n    <Gauge\n      title=\"Credits used this month\"\n      value={41_250}\n      max={50_000}\n      format=\"compact\"\n      caption=\"of 50K credits\"\n      zones={[\n        { to: 40_000, tone: \"success\" },\n        { to: 47_500, tone: \"warning\" },\n        { to: 50_000, tone: \"danger\" },\n      ]}\n    />\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/gauge/native/credits-quota.dark.png",
+          "light": "examples/gauge/native/credits-quota.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/gauge/credits-quota.tsx",
+    "content": "import { Gauge } from \"@krizaka/charts/gauge\";\n\nexport default function CreditsQuota() {\n  return (\n    <Gauge\n      title=\"Credits used this month\"\n      value={41_250}\n      max={50_000}\n      format=\"compact\"\n      caption=\"of 50K credits\"\n      zones={[\n        { to: 40_000, tone: \"success\", label: \"Within plan\" },\n        { to: 47_500, tone: \"warning\", label: \"Nearing the limit\" },\n        { to: 50_000, tone: \"danger\", label: \"At the limit\" },\n      ]}\n      style={{ maxWidth: 320 }}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "Gauge",
+      "description": "One figure against its range — credits used of a plan, a challenge's progress, a load.",
+      "props": [
+        {
+          "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": "value",
+          "type": "number",
+          "default": null,
+          "description": "The value.",
+          "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": "caption",
+          "type": "string",
+          "default": null,
+          "description": "The words under the value (“of 50 000 credits”).",
+          "required": false
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "A class on the figure (layout: margins, grid placement).",
+          "required": false
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "A sentence under the title: the period, the unit, the source.",
+          "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 value and the range are written.",
+          "required": false
+        },
+        {
+          "name": "height",
+          "type": "number",
+          "default": null,
+          "description": "The height of the plot in pixels. Default 280 (a sparkline: 32).",
+          "required": false
+        },
+        {
+          "name": "hideTitle",
+          "type": "boolean",
+          "default": null,
+          "description": "Visually hide the title (it stays the chart's accessible name): a card that already has its heading.",
+          "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": "max",
+          "type": "number",
+          "default": null,
+          "description": "The end of the range. Default 100.",
+          "required": false
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "default": null,
+          "description": "The start of the range. Default 0.",
+          "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": "target",
+          "type": "Threshold",
+          "default": null,
+          "description": "A tick on the arc: the objective.",
+          "required": false
+        },
+        {
+          "name": "tone",
+          "type": "Tone",
+          "default": null,
+          "description": "The tone of the value without zones. Default `\"accent\"`.",
+          "required": false
+        },
+        {
+          "name": "zones",
+          "type": "readonly GaugeZone[]",
+          "default": null,
+          "description": "Coloured zones along the arc: the value takes the tone of the zone it is in.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}