@krizaka/charts 0.0.0-stage → 0.2.0

package/registry/globe.json

@@ -0,0 +1,469 @@
+{
+  "name": "globe",
+  "package": "@krizaka/charts",
+  "type": "chart",
+  "title": "Globe",
+  "summary": "The world as a lit 3D sphere — places, great-circle arcs, tinted regions — turning slowly while on screen, dragged by hand, in SVG without WebGL.",
+  "description": "The world as a lit 3D sphere — places, great-circle arcs, tinted regions — turning slowly while on screen, dragged by hand, in SVG without WebGL.",
+  "status": "beta",
+  "category": "charts",
+  "platforms": "web",
+  "engine": "svg",
+  "tier": "advanced",
+  "whenToUse": [
+    "Deployment regions and their replication links, on a product or status page.",
+    "A global presence told at a glance, with a few places named."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "Values to compare by country (half the globe is hidden).",
+      "use": "geo-map"
+    },
+    {
+      "when": "More than a dozen places: the far side hides them.",
+      "use": "geo-map"
+    }
+  ],
+  "bestPractices": [
+    "Name the places as a reader knows them (“Paris · eu-west-3”); give their status a tone.",
+    "Keep `autoRotate` for a showcase; turn it off where the reader works.",
+    "Use `regions` for where the service is available, not for values."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Arrow keys",
+        "action": "Walk the places: the globe turns to each one, which is announced."
+      },
+      {
+        "keys": "Home / End",
+        "action": "Jump to the first or the last place."
+      },
+      {
+        "keys": "Esc",
+        "action": "Clears the active place; the turn resumes."
+      }
+    ],
+    "notes": [
+      "The turn runs only while the globe is on screen and the page visible, never under reduced motion, and stops on focus or drag.",
+      "The summary and the table list every place with its value and coordinates.",
+      "No WebGL: the sphere is SVG (an orthographic projection), sharp at any size and exportable."
+    ]
+  },
+  "related": [
+    "geo-map",
+    "sankey"
+  ],
+  "source": "packages/charts/src/meta/globe.ts",
+  "install": {
+    "web": "npm install @krizaka/charts",
+    "native": "npx expo install react-native-svg\nnpm install @krizaka/charts"
+  },
+  "web": {
+    "entry": "@krizaka/charts/globe",
+    "import": "import { Globe3D } from \"@krizaka/charts/globe\";",
+    "props": [
+      {
+        "component": "Globe3D",
+        "description": "The world as a lit sphere: deployment regions, the arcs between them, a slow turn.",
+        "props": [
+          {
+            "name": "points",
+            "type": "readonly GlobePoint[]",
+            "default": null,
+            "description": "The places: deployment regions, data centres, audiences.",
+            "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": "arcs",
+            "type": "readonly GlobeArc[]",
+            "default": null,
+            "description": "Great-circle arcs between places: replication, traffic.",
+            "required": false
+          },
+          {
+            "name": "autoRotate",
+            "type": "boolean",
+            "default": null,
+            "description": "Turn slowly while on screen (never under reduced motion). Default true.",
+            "required": false
+          },
+          {
+            "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": "center",
+            "type": "readonly [number, number]",
+            "default": null,
+            "description": "The longitude and latitude facing the reader at first. Default: the first point.",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "default": null,
+            "description": "A class on the figure (layout: margins, grid placement).",
+            "required": false
+          },
+          {
+            "name": "dataTable",
+            "type": "boolean",
+            "default": null,
+            "description": "The \"Show data\" button (the table is in the page for screen readers either way). Default true.",
+            "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": "exportable",
+            "type": "boolean | readonly ExportFormat[]",
+            "default": null,
+            "description": "Export buttons: `true` for PNG, SVG and CSV, or the formats you want.",
+            "required": false
+          },
+          {
+            "name": "format",
+            "type": "ValueFormat",
+            "default": null,
+            "description": "How the points' values 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": "pointLabel",
+            "type": "string",
+            "default": null,
+            "description": "The header of the places and of their values in the table.",
+            "required": false
+          },
+          {
+            "name": "regions",
+            "type": "readonly string[]",
+            "default": null,
+            "description": "Countries to tint in the accent (ISO alpha-2): where the service is available.",
+            "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": "valueLabel",
+            "type": "string",
+            "default": null,
+            "description": "The header of the points' values (“Availability”).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "deployment-regions",
+        "title": "Deployment regions",
+        "description": "Orazaka's regions, their health as tones, the replication arcs between them.",
+        "path": "examples/globe/deployment-regions.tsx",
+        "module": "@krizaka/charts/registry/examples/globe/deployment-regions",
+        "code": "import { Globe3D } from \"@krizaka/charts/globe\";\n\nconst regions = [\n  { label: \"Paris · eu-west-3\", lon: 2.35, lat: 48.86, value: 0.9998, tone: \"success\" as const },\n  { label: \"Frankfurt · eu-central-1\", lon: 8.68, lat: 50.11, value: 0.9995, tone: \"success\" as const },\n  { label: \"Montréal · ca-central-1\", lon: -73.57, lat: 45.5, value: 0.9991, tone: \"success\" as const },\n  { label: \"Virginia · us-east-1\", lon: -77.46, lat: 38.95, value: 0.9962, tone: \"warning\" as const },\n  { label: \"Singapore · ap-southeast-1\", lon: 103.82, lat: 1.35, value: 0.9997, tone: \"success\" as const },\n];\n\nexport default function DeploymentRegions() {\n  return (\n    <Globe3D\n      title=\"Orazaka regions\"\n      description=\"Availability over 30 days · replication from Paris\"\n      points={regions}\n      arcs={[\n        { from: regions[0]!.label, to: regions[1]!.label },\n        { from: regions[0]!.label, to: regions[2]!.label },\n        { from: regions[2]!.label, to: regions[3]!.label },\n        { from: regions[1]!.label, to: regions[4]!.label },\n      ]}\n      regions={[\"FR\", \"DE\", \"BE\", \"CH\", \"CA\", \"US\", \"SG\"]}\n      center={[-20, 40]}\n      format={{ style: \"number\", options: { style: \"percent\", maximumFractionDigits: 2 } }}\n      pointLabel=\"Region\"\n      valueLabel=\"Availability\"\n    />\n  );\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/globe/deployment-regions.tsx",
+    "content": "import { Globe3D } from \"@krizaka/charts/globe\";\n\nconst regions = [\n  { label: \"Paris · eu-west-3\", lon: 2.35, lat: 48.86, value: 0.9998, tone: \"success\" as const },\n  { label: \"Frankfurt · eu-central-1\", lon: 8.68, lat: 50.11, value: 0.9995, tone: \"success\" as const },\n  { label: \"Montréal · ca-central-1\", lon: -73.57, lat: 45.5, value: 0.9991, tone: \"success\" as const },\n  { label: \"Virginia · us-east-1\", lon: -77.46, lat: 38.95, value: 0.9962, tone: \"warning\" as const },\n  { label: \"Singapore · ap-southeast-1\", lon: 103.82, lat: 1.35, value: 0.9997, tone: \"success\" as const },\n];\n\nexport default function DeploymentRegions() {\n  return (\n    <Globe3D\n      title=\"Orazaka regions\"\n      description=\"Availability over 30 days · replication from Paris\"\n      points={regions}\n      arcs={[\n        { from: regions[0]!.label, to: regions[1]!.label },\n        { from: regions[0]!.label, to: regions[2]!.label },\n        { from: regions[2]!.label, to: regions[3]!.label },\n        { from: regions[1]!.label, to: regions[4]!.label },\n      ]}\n      regions={[\"FR\", \"DE\", \"BE\", \"CH\", \"CA\", \"US\", \"SG\"]}\n      center={[-20, 40]}\n      format={{ style: \"number\", options: { style: \"percent\", maximumFractionDigits: 2 } }}\n      pointLabel=\"Region\"\n      valueLabel=\"Availability\"\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "Globe3D",
+      "description": "The world as a lit sphere: deployment regions, the arcs between them, a slow turn.",
+      "props": [
+        {
+          "name": "points",
+          "type": "readonly GlobePoint[]",
+          "default": null,
+          "description": "The places: deployment regions, data centres, audiences.",
+          "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": "arcs",
+          "type": "readonly GlobeArc[]",
+          "default": null,
+          "description": "Great-circle arcs between places: replication, traffic.",
+          "required": false
+        },
+        {
+          "name": "autoRotate",
+          "type": "boolean",
+          "default": null,
+          "description": "Turn slowly while on screen (never under reduced motion). Default true.",
+          "required": false
+        },
+        {
+          "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": "center",
+          "type": "readonly [number, number]",
+          "default": null,
+          "description": "The longitude and latitude facing the reader at first. Default: the first point.",
+          "required": false
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "A class on the figure (layout: margins, grid placement).",
+          "required": false
+        },
+        {
+          "name": "dataTable",
+          "type": "boolean",
+          "default": null,
+          "description": "The \"Show data\" button (the table is in the page for screen readers either way). Default true.",
+          "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": "exportable",
+          "type": "boolean | readonly ExportFormat[]",
+          "default": null,
+          "description": "Export buttons: `true` for PNG, SVG and CSV, or the formats you want.",
+          "required": false
+        },
+        {
+          "name": "format",
+          "type": "ValueFormat",
+          "default": null,
+          "description": "How the points' values 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": "pointLabel",
+          "type": "string",
+          "default": null,
+          "description": "The header of the places and of their values in the table.",
+          "required": false
+        },
+        {
+          "name": "regions",
+          "type": "readonly string[]",
+          "default": null,
+          "description": "Countries to tint in the accent (ISO alpha-2): where the service is available.",
+          "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": "valueLabel",
+          "type": "string",
+          "default": null,
+          "description": "The header of the points' values (“Availability”).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}