@krizaka/charts 0.0.0-stage → 0.2.0

package/registry/candlestick.json

@@ -0,0 +1,553 @@
+{
+  "name": "candlestick",
+  "package": "@krizaka/charts",
+  "type": "chart",
+  "title": "Candlestick",
+  "summary": "Open, high, low and close per period, rising candles hollow and falling ones filled, the volume in its own panel, zoom and thresholds.",
+  "description": "Open, high, low and close per period, rising candles hollow and falling ones filled, the volume in its own panel, zoom and thresholds.",
+  "status": "beta",
+  "category": "charts",
+  "platforms": "web",
+  "engine": "echarts",
+  "tier": "advanced",
+  "whenToUse": [
+    "A price that moves within each period: an auction's bids per hour, a credit's market price per day."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "One value per period.",
+      "use": "line-chart"
+    }
+  ],
+  "bestPractices": [
+    "Give the reserve or the target as a threshold.",
+    "Past forty periods the chart zooms on the last forty; the wheel and a drag move through the rest."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Tab",
+        "action": "Moves the focus to the plot (one tab stop), then to the data and export buttons."
+      },
+      {
+        "keys": "Arrow keys",
+        "action": "Walk the items one by one: each is announced and highlighted, its tooltip shown."
+      },
+      {
+        "keys": "Home / End",
+        "action": "Jump to the first or the last item."
+      },
+      {
+        "keys": "Esc",
+        "action": "Hides the tooltip and clears the highlight."
+      }
+    ],
+    "notes": [
+      "The plot is a group named by the title and described by a summary written from the data, read before anything else.",
+      "The data table is always in the page for assistive technology; “Show data” reveals it for everyone.",
+      "The engine (ECharts core and this one chart type) loads when the chart nears the screen; a skeleton of the same height holds its place, so nothing shifts.",
+      "Under reduced motion the chart is drawn without animation.",
+      "Rising candles are hollow and falling ones filled: the shape says the direction, not only green and red."
+    ]
+  },
+  "related": [
+    "line-chart",
+    "bar-chart"
+  ],
+  "source": "packages/charts/src/meta/candlestick.ts",
+  "install": {
+    "web": "npm install @krizaka/charts",
+    "native": "npx expo install react-native-svg\nnpm install @krizaka/charts"
+  },
+  "web": {
+    "entry": "@krizaka/charts/candlestick",
+    "import": "import { Candlestick } from \"@krizaka/charts/candlestick\";",
+    "props": [
+      {
+        "component": "Candlestick",
+        "description": "",
+        "props": [
+          {
+            "name": "close",
+            "type": "string | ((datum: T, index: number) => number)",
+            "default": null,
+            "description": "The field of the price at the end of the period.",
+            "required": true
+          },
+          {
+            "name": "data",
+            "type": "readonly T[]",
+            "default": null,
+            "description": "One row per period, oldest first.",
+            "required": true
+          },
+          {
+            "name": "high",
+            "type": "string | ((datum: T, index: number) => number)",
+            "default": null,
+            "description": "The field of the highest price of the period.",
+            "required": true
+          },
+          {
+            "name": "low",
+            "type": "string | ((datum: T, index: number) => number)",
+            "default": null,
+            "description": "The field of the lowest price of the period.",
+            "required": true
+          },
+          {
+            "name": "open",
+            "type": "string | ((datum: T, index: number) => number)",
+            "default": null,
+            "description": "The field of the price at the start of the period.",
+            "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": "x",
+            "type": "string | ((datum: T, index: number) => unknown)",
+            "default": null,
+            "description": "The field of the period (a date, an hour).",
+            "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": "className",
+            "type": "string",
+            "default": null,
+            "description": "A class on the figure (layout: margins, grid placement).",
+            "required": false
+          },
+          {
+            "name": "columnLabels",
+            "type": "{ readonly open: string; readonly high: string; readonly low: string; readonly close: string; readonly volume: string; }",
+            "default": null,
+            "description": "The words of the table's columns and the tooltip's rows.",
+            "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 prices and the volume 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": "renderer",
+            "type": "Renderer",
+            "default": null,
+            "description": "`svg` (default): sharp, exportable as SVG. `canvas`: for tens of thousands of marks.",
+            "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": "thresholds",
+            "type": "readonly Threshold[]",
+            "default": null,
+            "description": "Horizontal lines: a reserve price, a target.",
+            "required": false
+          },
+          {
+            "name": "volume",
+            "type": "string | ((datum: T, index: number) => number)",
+            "default": null,
+            "description": "The field of the volume: drawn in its own panel under the candles.",
+            "required": false
+          },
+          {
+            "name": "volumeFormat",
+            "type": "ValueFormat",
+            "default": null,
+            "description": "How the volume is written. Default `\"compact\"`.",
+            "required": false
+          },
+          {
+            "name": "xFormat",
+            "type": "CategoryFormat",
+            "default": null,
+            "description": "How the periods are written.",
+            "required": false
+          },
+          {
+            "name": "zoom",
+            "type": "boolean",
+            "default": null,
+            "description": "Zoom with the wheel and drag to pan. Default true from 40 periods.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "auction-bids",
+        "title": "Auction bids",
+        "description": "An Orochia auction's bids per hour, with the volume and the reserve price.",
+        "path": "examples/candlestick/auction-bids.tsx",
+        "module": "@krizaka/charts/registry/examples/candlestick/auction-bids",
+        "code": "import { Candlestick } from \"@krizaka/charts/candlestick\";\n\n// Bids in cents per hour on an auctioned video; a deterministic walk.\nlet price = 12_000;\nconst hours = Array.from({ length: 24 }, (_, i) => {\n  const open = price;\n  const close = open + ((i * 37) % 23) * 60 - 480 + (i > 15 ? 900 : 0);\n  const high = Math.max(open, close) + ((i * 11) % 7) * 90;\n  const low = Math.min(open, close) - ((i * 5) % 6) * 70;\n  price = close;\n  return { at: `2026-10-11T${String(i).padStart(2, \"0\")}:00Z`, open, high, low, close, bids: 4 + ((i * 17) % 13) };\n});\n\nexport default function AuctionBids() {\n  return (\n    <Candlestick\n      title=\"“Northern lights over Tadoussac” — bids per hour\"\n      data={hours}\n      x=\"at\"\n      xFormat=\"time\"\n      open=\"open\"\n      high=\"high\"\n      low=\"low\"\n      close=\"close\"\n      volume=\"bids\"\n      volumeFormat=\"integer\"\n      format={{ style: \"money\", currency: \"CAD\" }}\n      thresholds={[{ value: 15_000, label: \"Reserve price\", tone: \"warning\" }]}\n      columnLabels={{ open: \"Open\", high: \"High\", low: \"Low\", close: \"Close\", volume: \"Bids\" }}\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/candlestick/auction-bids.tsx",
+    "content": "import { Candlestick } from \"@krizaka/charts/candlestick\";\n\n// Bids in cents per hour on an auctioned video; a deterministic walk.\nlet price = 12_000;\nconst hours = Array.from({ length: 24 }, (_, i) => {\n  const open = price;\n  const close = open + ((i * 37) % 23) * 60 - 480 + (i > 15 ? 900 : 0);\n  const high = Math.max(open, close) + ((i * 11) % 7) * 90;\n  const low = Math.min(open, close) - ((i * 5) % 6) * 70;\n  price = close;\n  return { at: `2026-10-11T${String(i).padStart(2, \"0\")}:00Z`, open, high, low, close, bids: 4 + ((i * 17) % 13) };\n});\n\nexport default function AuctionBids() {\n  return (\n    <Candlestick\n      title=\"“Northern lights over Tadoussac” — bids per hour\"\n      data={hours}\n      x=\"at\"\n      xFormat=\"time\"\n      open=\"open\"\n      high=\"high\"\n      low=\"low\"\n      close=\"close\"\n      volume=\"bids\"\n      volumeFormat=\"integer\"\n      format={{ style: \"money\", currency: \"CAD\" }}\n      thresholds={[{ value: 15_000, label: \"Reserve price\", tone: \"warning\" }]}\n      columnLabels={{ open: \"Open\", high: \"High\", low: \"Low\", close: \"Close\", volume: \"Bids\" }}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "Candlestick",
+      "description": "",
+      "props": [
+        {
+          "name": "close",
+          "type": "string | ((datum: T, index: number) => number)",
+          "default": null,
+          "description": "The field of the price at the end of the period.",
+          "required": true
+        },
+        {
+          "name": "data",
+          "type": "readonly T[]",
+          "default": null,
+          "description": "One row per period, oldest first.",
+          "required": true
+        },
+        {
+          "name": "high",
+          "type": "string | ((datum: T, index: number) => number)",
+          "default": null,
+          "description": "The field of the highest price of the period.",
+          "required": true
+        },
+        {
+          "name": "low",
+          "type": "string | ((datum: T, index: number) => number)",
+          "default": null,
+          "description": "The field of the lowest price of the period.",
+          "required": true
+        },
+        {
+          "name": "open",
+          "type": "string | ((datum: T, index: number) => number)",
+          "default": null,
+          "description": "The field of the price at the start of the period.",
+          "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": "x",
+          "type": "string | ((datum: T, index: number) => unknown)",
+          "default": null,
+          "description": "The field of the period (a date, an hour).",
+          "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": "className",
+          "type": "string",
+          "default": null,
+          "description": "A class on the figure (layout: margins, grid placement).",
+          "required": false
+        },
+        {
+          "name": "columnLabels",
+          "type": "{ readonly open: string; readonly high: string; readonly low: string; readonly close: string; readonly volume: string; }",
+          "default": null,
+          "description": "The words of the table's columns and the tooltip's rows.",
+          "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 prices and the volume 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": "renderer",
+          "type": "Renderer",
+          "default": null,
+          "description": "`svg` (default): sharp, exportable as SVG. `canvas`: for tens of thousands of marks.",
+          "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": "thresholds",
+          "type": "readonly Threshold[]",
+          "default": null,
+          "description": "Horizontal lines: a reserve price, a target.",
+          "required": false
+        },
+        {
+          "name": "volume",
+          "type": "string | ((datum: T, index: number) => number)",
+          "default": null,
+          "description": "The field of the volume: drawn in its own panel under the candles.",
+          "required": false
+        },
+        {
+          "name": "volumeFormat",
+          "type": "ValueFormat",
+          "default": null,
+          "description": "How the volume is written. Default `\"compact\"`.",
+          "required": false
+        },
+        {
+          "name": "xFormat",
+          "type": "CategoryFormat",
+          "default": null,
+          "description": "How the periods are written.",
+          "required": false
+        },
+        {
+          "name": "zoom",
+          "type": "boolean",
+          "default": null,
+          "description": "Zoom with the wheel and drag to pan. Default true from 40 periods.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}