@krizaka/charts 0.1.0 → 0.2.0

package/registry/earnings-chart.json

@@ -0,0 +1,703 @@
+{
+  "name": "earnings-chart",
+  "package": "@krizaka/charts",
+  "type": "chart",
+  "title": "Earnings chart",
+  "summary": "Earnings per period in money: the bars of the net amount, the total and the last period's change written above, the payout threshold as a line.",
+  "description": "Earnings per period in money: the bars of the net amount, the total and the last period's change written above, the payout threshold as a line.",
+  "status": "beta",
+  "category": "charts",
+  "platforms": "both",
+  "engine": "svg",
+  "tier": "ready-made",
+  "whenToUse": [
+    "A creator's earnings page: net earnings per month, with the minimum to withdraw (Orochia /earnings).",
+    "A treasury view: gross and net per month side by side (Orochia's console).",
+    "The earnings card of the mobile app: the total in large, the bars under it."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "A count that is not money (jobs, views).",
+      "use": "job-throughput"
+    },
+    {
+      "when": "A trend over many points (a year of days).",
+      "use": "line-chart"
+    },
+    {
+      "when": "One figure against a goal.",
+      "use": "goal-progress"
+    }
+  ],
+  "bestPractices": [
+    "Pass the amounts in minor units (cents) as the ledger stores them, and the currency: the chart writes them.",
+    "Keep the periods in time order; the change compares the last two periods.",
+    "Say what the threshold means in its label (“Payout threshold”), never only its amount."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Tab",
+        "action": "Moves the focus to the plot, then to the data and export buttons."
+      },
+      {
+        "keys": "Arrow keys",
+        "action": "Walk the periods one by one: each amount is announced."
+      }
+    ],
+    "notes": [
+      "The total and the change are written in words under the title; the arrow beside the change is decorative.",
+      "The plot is described by a summary written from the data and backed by a data table, as every chart of the package."
+    ]
+  },
+  "related": [
+    "bar-chart",
+    "goal-progress",
+    "sparkline"
+  ],
+  "source": "packages/charts/src/meta/earnings-chart.ts",
+  "install": {
+    "web": "npm install @krizaka/charts",
+    "native": "npx expo install react-native-svg\nnpm install @krizaka/charts"
+  },
+  "web": {
+    "entry": "@krizaka/charts/earnings",
+    "import": "import { EarningsChart } from \"@krizaka/charts/earnings\";",
+    "props": [
+      {
+        "component": "EarningsChart",
+        "description": "Earnings per period in money — the total, the change of the last period, the payout threshold.",
+        "props": [
+          {
+            "name": "currency",
+            "type": "string",
+            "default": null,
+            "description": "The ISO 4217 currency (`\"USD\"`, `\"EUR\"`).",
+            "required": true
+          },
+          {
+            "name": "data",
+            "type": "readonly T[]",
+            "default": null,
+            "description": "The rows, in the order of the x axis.",
+            "required": true
+          },
+          {
+            "name": "net",
+            "type": "string | ((datum: T, index: number) => number | null | undefined)",
+            "default": null,
+            "description": "The net amount of each period, in **minor units** (cents), as the ledger stores it.",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "BrandId",
+            "default": null,
+            "description": "The brand whose palette the charts use. Without it, a chart follows a `.brand-<id>` ancestor, else Krizaka. Set it\nwhen the app loads a brand stylesheet on `:root` (`@krizaka/tokens/brands/orazaka.css`).",
+            "required": false
+          },
+          {
+            "name": "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": "gross",
+            "type": "string | ((datum: T, index: number) => number | null)",
+            "default": null,
+            "description": "The gross amount (before fees), drawn beside the net when given.",
+            "required": false
+          },
+          {
+            "name": "height",
+            "type": "number",
+            "default": null,
+            "description": "The height of the plot in pixels. Default 280 (a sparkline: 32).",
+            "required": false
+          },
+          {
+            "name": "hideSummary",
+            "type": "boolean",
+            "default": null,
+            "description": "Hide the total and the change above the bars.",
+            "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": "Partial<EarningsLabels>",
+            "default": null,
+            "description": "The words, passed translated; English by default.",
+            "required": false
+          },
+          {
+            "name": "legend",
+            "type": "boolean",
+            "default": null,
+            "description": "Show the legend (from two series). Default true.",
+            "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": "markers",
+            "type": "readonly Marker[]",
+            "default": null,
+            "description": "Vertical markers at a category: a launch, an incident.",
+            "required": false
+          },
+          {
+            "name": "onSelect",
+            "type": "((datum: T, index: number) => void)",
+            "default": null,
+            "description": "Called with the row when a point or a bar is clicked (or Enter is pressed on it).",
+            "required": false
+          },
+          {
+            "name": "payoutThreshold",
+            "type": "Threshold",
+            "default": null,
+            "description": "The minimum to withdraw, drawn as a line: `{ value: 5000, label: \"Payout threshold\" }`.",
+            "required": false
+          },
+          {
+            "name": "period",
+            "type": "CategoryFormat",
+            "default": "month",
+            "description": "How the periods are written. Default `\"month\"` (`Apr 2026`).",
+            "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": "x",
+            "type": "string | ((datum: T, index: number) => unknown)",
+            "default": "\"month\" as Accessor<T, unknown>",
+            "description": "The field (or function) of the period: an ISO month (`\"2026-04\"`), a day. Default `\"month\"`.",
+            "required": false
+          },
+          {
+            "name": "xLabel",
+            "type": "string",
+            "default": null,
+            "description": "The header of the categories in the data table (`Month`).",
+            "required": false
+          },
+          {
+            "name": "zero",
+            "type": "boolean",
+            "default": null,
+            "description": "Start the value axis at zero. Default: true for bars and areas; for lines, unless the values sit far from zero.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "creator-month",
+        "title": "A creator's months",
+        "description": "Six months of net earnings, the payout threshold, the change of the last month.",
+        "path": "examples/earnings-chart/creator-month.tsx",
+        "module": "@krizaka/charts/registry/examples/earnings-chart/creator-month",
+        "code": "import { EarningsChart } from \"@krizaka/charts/earnings\";\n\n// Net earnings in cents, as the ledger stores them (Orochia /earnings).\nconst months = [\n  { month: \"2026-05\", net: 182_40 },\n  { month: \"2026-06\", net: 245_10 },\n  { month: \"2026-07\", net: 210_75 },\n  { month: \"2026-08\", net: 398_20 },\n  { month: \"2026-09\", net: 441_05 },\n  { month: \"2026-10\", net: 512_90 },\n];\n\nexport default function CreatorMonth() {\n  return (\n    <EarningsChart\n      title=\"Your earnings\"\n      data={months}\n      net=\"net\"\n      currency=\"USD\"\n      payoutThreshold={{ value: 50_00, label: \"Payout threshold\" }}\n      labels={{ total: \"earned over {count} months\", change: \"{change} vs September\" }}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "gross-and-net",
+        "title": "Gross and net",
+        "description": "The treasury: gross and net per month side by side.",
+        "path": "examples/earnings-chart/gross-and-net.tsx",
+        "module": "@krizaka/charts/registry/examples/earnings-chart/gross-and-net",
+        "code": "import { EarningsChart } from \"@krizaka/charts/earnings\";\n\n// The platform's treasury: gross volume and creators' net, in cents.\nconst months = [\n  { month: \"2026-07\", gross: 12_480_00, net: 10_608_00 },\n  { month: \"2026-08\", gross: 15_920_00, net: 13_532_00 },\n  { month: \"2026-09\", gross: 18_210_00, net: 15_478_50 },\n  { month: \"2026-10\", gross: 21_045_00, net: 17_888_25 },\n];\n\nexport default function GrossAndNet() {\n  return (\n    <EarningsChart\n      title=\"Creator earnings\"\n      description=\"Gross volume and what creators keep after fees\"\n      data={months}\n      gross=\"gross\"\n      net=\"net\"\n      currency=\"USD\"\n      labels={{ total: \"paid to creators over {count} months\", change: \"{change} vs last month\", gross: \"Gross volume\", net: \"Creators' net\" }}\n      exportable={[\"csv\"]}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/charts/native",
+    "import": "import { EarningsChart } from \"@krizaka/charts/native\";",
+    "differences": [
+      "The total and the change sit above the chart as a headline (the first thing a phone shows), not in the description.",
+      "No data table or export: swipe on the chart to hear each period."
+    ],
+    "props": [
+      {
+        "component": "EarningsChart",
+        "description": "Earnings per period in money (React Native): the total and the change first, the bars under them.",
+        "props": [
+          {
+            "name": "currency",
+            "type": "string",
+            "default": null,
+            "description": "The ISO 4217 currency.",
+            "required": true
+          },
+          {
+            "name": "data",
+            "type": "readonly T[]",
+            "default": null,
+            "description": "The rows, in the order of the x axis.",
+            "required": true
+          },
+          {
+            "name": "net",
+            "type": "string | ((datum: T, index: number) => number | null | undefined)",
+            "default": null,
+            "description": "The net amount of each period, in minor units.",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the chart shows: its heading and accessible name.",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "BrandId",
+            "default": null,
+            "description": "The brand whose palette leads. Default Krizaka.",
+            "required": false
+          },
+          {
+            "name": "empty",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Shown instead of the plot when there is nothing to draw. Default: the `empty` label.",
+            "required": false
+          },
+          {
+            "name": "gross",
+            "type": "string | ((datum: T, index: number) => number | null)",
+            "default": null,
+            "description": "The gross amount, drawn beside the net.",
+            "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": "Partial<EarningsLabels>",
+            "default": null,
+            "description": "The words, passed translated.",
+            "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": "payoutThreshold",
+            "type": "Threshold",
+            "default": null,
+            "description": "The payout threshold, drawn as a line.",
+            "required": false
+          },
+          {
+            "name": "period",
+            "type": "CategoryFormat",
+            "default": "month",
+            "description": "How the periods are written. Default `\"month\"`.",
+            "required": false
+          },
+          {
+            "name": "scheme",
+            "type": "Mode",
+            "default": null,
+            "description": "Dark or light. Default: the device's (pass `useTheme().scheme` of\n@krizaka /ui/native to follow the app).",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "ViewStyle",
+            "default": null,
+            "description": "The style of the chart's container (layout only: colours come from the theme).",
+            "required": false
+          },
+          {
+            "name": "theme",
+            "type": "Partial<ChartTheme>",
+            "default": null,
+            "description": "The app's colour roles (`useTheme().theme` of\n@krizaka /ui/native): a product's brand overrides apply.",
+            "required": false
+          },
+          {
+            "name": "x",
+            "type": "string | ((datum: T, index: number) => unknown)",
+            "default": "\"month\" as Accessor<T, unknown>",
+            "description": "The field (or function) of the period. Default `\"month\"`.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "creator-month",
+        "title": "A creator's months",
+        "description": "The mobile earnings card: the total first, the bars under it.",
+        "path": "examples/earnings-chart/native/creator-month.tsx",
+        "module": "@krizaka/charts/registry/examples/earnings-chart/native/creator-month",
+        "code": "import { EarningsChart } from \"@krizaka/charts/native\";\n\nconst months = [\n  { month: \"2026-05\", net: 182_40 },\n  { month: \"2026-06\", net: 245_10 },\n  { month: \"2026-07\", net: 210_75 },\n  { month: \"2026-08\", net: 398_20 },\n  { month: \"2026-09\", net: 441_05 },\n  { month: \"2026-10\", net: 512_90 },\n];\n\n// The earnings card of the app: the total first, the bars under it.\nexport default function NativeCreatorMonth() {\n  return (\n    <EarningsChart\n      title=\"Your earnings\"\n      data={months}\n      net=\"net\"\n      currency=\"USD\"\n      height={160}\n      labels={{ total: \"over {count} months\", change: \"{change} vs September\" }}\n    />\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/earnings-chart/native/creator-month.dark.png",
+          "light": "examples/earnings-chart/native/creator-month.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/earnings-chart/creator-month.tsx",
+    "content": "import { EarningsChart } from \"@krizaka/charts/earnings\";\n\n// Net earnings in cents, as the ledger stores them (Orochia /earnings).\nconst months = [\n  { month: \"2026-05\", net: 182_40 },\n  { month: \"2026-06\", net: 245_10 },\n  { month: \"2026-07\", net: 210_75 },\n  { month: \"2026-08\", net: 398_20 },\n  { month: \"2026-09\", net: 441_05 },\n  { month: \"2026-10\", net: 512_90 },\n];\n\nexport default function CreatorMonth() {\n  return (\n    <EarningsChart\n      title=\"Your earnings\"\n      data={months}\n      net=\"net\"\n      currency=\"USD\"\n      payoutThreshold={{ value: 50_00, label: \"Payout threshold\" }}\n      labels={{ total: \"earned over {count} months\", change: \"{change} vs September\" }}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "EarningsChart",
+      "description": "Earnings per period in money — the total, the change of the last period, the payout threshold.",
+      "props": [
+        {
+          "name": "currency",
+          "type": "string",
+          "default": null,
+          "description": "The ISO 4217 currency (`\"USD\"`, `\"EUR\"`).",
+          "required": true
+        },
+        {
+          "name": "data",
+          "type": "readonly T[]",
+          "default": null,
+          "description": "The rows, in the order of the x axis.",
+          "required": true
+        },
+        {
+          "name": "net",
+          "type": "string | ((datum: T, index: number) => number | null | undefined)",
+          "default": null,
+          "description": "The net amount of each period, in **minor units** (cents), as the ledger stores it.",
+          "required": true
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "default": null,
+          "description": "What the chart shows, in a few words: its accessible name, and its heading unless `hideTitle`.",
+          "required": true
+        },
+        {
+          "name": "brand",
+          "type": "BrandId",
+          "default": null,
+          "description": "The brand whose palette the charts use. Without it, a chart follows a `.brand-<id>` ancestor, else Krizaka. Set it\nwhen the app loads a brand stylesheet on `:root` (`@krizaka/tokens/brands/orazaka.css`).",
+          "required": false
+        },
+        {
+          "name": "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": "gross",
+          "type": "string | ((datum: T, index: number) => number | null)",
+          "default": null,
+          "description": "The gross amount (before fees), drawn beside the net when given.",
+          "required": false
+        },
+        {
+          "name": "height",
+          "type": "number",
+          "default": null,
+          "description": "The height of the plot in pixels. Default 280 (a sparkline: 32).",
+          "required": false
+        },
+        {
+          "name": "hideSummary",
+          "type": "boolean",
+          "default": null,
+          "description": "Hide the total and the change above the bars.",
+          "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": "Partial<EarningsLabels>",
+          "default": null,
+          "description": "The words, passed translated; English by default.",
+          "required": false
+        },
+        {
+          "name": "legend",
+          "type": "boolean",
+          "default": null,
+          "description": "Show the legend (from two series). Default true.",
+          "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": "markers",
+          "type": "readonly Marker[]",
+          "default": null,
+          "description": "Vertical markers at a category: a launch, an incident.",
+          "required": false
+        },
+        {
+          "name": "onSelect",
+          "type": "((datum: T, index: number) => void)",
+          "default": null,
+          "description": "Called with the row when a point or a bar is clicked (or Enter is pressed on it).",
+          "required": false
+        },
+        {
+          "name": "payoutThreshold",
+          "type": "Threshold",
+          "default": null,
+          "description": "The minimum to withdraw, drawn as a line: `{ value: 5000, label: \"Payout threshold\" }`.",
+          "required": false
+        },
+        {
+          "name": "period",
+          "type": "CategoryFormat",
+          "default": "month",
+          "description": "How the periods are written. Default `\"month\"` (`Apr 2026`).",
+          "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": "x",
+          "type": "string | ((datum: T, index: number) => unknown)",
+          "default": "\"month\" as Accessor<T, unknown>",
+          "description": "The field (or function) of the period: an ISO month (`\"2026-04\"`), a day. Default `\"month\"`.",
+          "required": false
+        },
+        {
+          "name": "xLabel",
+          "type": "string",
+          "default": null,
+          "description": "The header of the categories in the data table (`Month`).",
+          "required": false
+        },
+        {
+          "name": "zero",
+          "type": "boolean",
+          "default": null,
+          "description": "Start the value axis at zero. Default: true for bars and areas; for lines, unless the values sit far from zero.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}