@krizaka/charts 0.1.0 → 0.2.0

package/registry/credit-usage.json

@@ -0,0 +1,473 @@
+{
+  "name": "credit-usage",
+  "package": "@krizaka/charts",
+  "type": "chart",
+  "title": "Credit usage",
+  "summary": "What is left of an allowance: the remaining amount in large, a meter that turns to warning then danger, the use per day and the day it runs out.",
+  "description": "What is left of an allowance: the remaining amount in large, a meter that turns to warning then danger, the use per day and the day it runs out.",
+  "status": "beta",
+  "category": "charts",
+  "platforms": "both",
+  "engine": "svg",
+  "tier": "ready-made",
+  "whenToUse": [
+    "Orazaka's billing: the credits left this month and when they run out at the current pace.",
+    "A storage plan (Orochia's console): gigabytes used of the plan, with a unit format.",
+    "Any quota that renews: API calls, minutes of video."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "Money raised towards a goal.",
+      "use": "goal-progress"
+    },
+    {
+      "when": "A value in a range with no notion of running out (a load, a score).",
+      "use": "gauge"
+    }
+  ],
+  "bestPractices": [
+    "Pass the use of the recent days: the projection and the sparkline need it.",
+    "Pass `now` from the server when the page is server-rendered: both sides write the same date.",
+    "Lead with what is left, not what is used: it is what people decide on."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "The meter is a `meter` named by the title, its value said in words (“3,120 used (62 %)”).",
+      "The warning and danger tones come with words: the projection says when it runs out."
+    ]
+  },
+  "related": [
+    "gauge",
+    "sparkline",
+    "goal-progress"
+  ],
+  "source": "packages/charts/src/meta/credit-usage.ts",
+  "install": {
+    "web": "npm install @krizaka/charts",
+    "native": "npx expo install react-native-svg\nnpm install @krizaka/charts"
+  },
+  "web": {
+    "entry": "@krizaka/charts/credits",
+    "import": "import { CreditUsage } from \"@krizaka/charts/credits\";",
+    "props": [
+      {
+        "component": "CreditUsage",
+        "description": "What is left of an allowance: the remaining amount, a meter in tones, the use per day and the run-out date.",
+        "props": [
+          {
+            "name": "limit",
+            "type": "number",
+            "default": null,
+            "description": "The allowance.",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the allowance is (“Credits this month”): the heading and the meter's name.",
+            "required": true
+          },
+          {
+            "name": "used",
+            "type": "number",
+            "default": null,
+            "description": "How much is used.",
+            "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).",
+            "required": false
+          },
+          {
+            "name": "daily",
+            "type": "readonly (number | null)[]",
+            "default": null,
+            "description": "The use of each recent day, oldest first: the sparkline and the projection.",
+            "required": false
+          },
+          {
+            "name": "days",
+            "type": "readonly unknown[]",
+            "default": null,
+            "description": "The days of `daily` (ISO dates), for the sparkline's summary.",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "A line under the title: the plan, the period.",
+            "required": false
+          },
+          {
+            "name": "format",
+            "type": "ValueFormat",
+            "default": "integer",
+            "description": "How the amounts are written. Default `\"integer\"`; a `{ style: \"unit\", unit: \"gigabyte\" }` for storage.",
+            "required": false
+          },
+          {
+            "name": "hideTitle",
+            "type": "boolean",
+            "default": null,
+            "description": "Visually hide the title (it stays the accessible name).",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<CreditLabels>",
+            "default": null,
+            "description": "The words, passed translated; English by default.",
+            "required": false
+          },
+          {
+            "name": "levels",
+            "type": "readonly [number, number]",
+            "default": "[0.8, 0.95]",
+            "description": "The share where the meter turns to warning, then danger. Default `[0.8, 0.95]`.",
+            "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 (`\"fr-FR\"`). Default `\"en-US\"`.",
+            "required": false
+          },
+          {
+            "name": "now",
+            "type": "Date",
+            "default": null,
+            "description": "Today, for the projection (pass it from the server to render the same date on both sides). Default: now.",
+            "required": false
+          },
+          {
+            "name": "renewsAt",
+            "type": "string | Date",
+            "default": null,
+            "description": "When the allowance renews (an ISO date or a `Date`).",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "CSSProperties",
+            "default": null,
+            "description": "Inline style on the figure (layout only).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "monthly-credits",
+        "title": "Monthly credits",
+        "description": "An Orazaka plan: credits left, the daily use, the run-out date.",
+        "path": "examples/credit-usage/monthly-credits.tsx",
+        "module": "@krizaka/charts/registry/examples/credit-usage/monthly-credits",
+        "code": "import { CreditUsage } from \"@krizaka/charts/credits\";\n\n// The credits used each day of the last two weeks (an Orazaka Pro plan of 5,000 credits).\nconst daily = [120, 180, 95, 210, 260, 140, 60, 75, 230, 310, 280, 190, 240, 300];\n\nexport default function MonthlyCredits() {\n  return (\n    <CreditUsage\n      title=\"Credits this month\"\n      description=\"Pro plan\"\n      used={3_120}\n      limit={5_000}\n      daily={daily}\n      renewsAt=\"2026-11-01\"\n      now={new Date(\"2026-10-11T09:00:00Z\")}\n      labels={{ remaining: \"credits left of {limit}\" }}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "storage-plan",
+        "title": "Storage plan",
+        "description": "Orochia's console: gigabytes of the plan, past the warning level.",
+        "path": "examples/credit-usage/storage-plan.tsx",
+        "module": "@krizaka/charts/registry/examples/credit-usage/storage-plan",
+        "code": "import { CreditUsage } from \"@krizaka/charts/credits\";\n\n// Orochia's console: the platform's video storage, in gigabytes, past the warning level.\nexport default function StoragePlan() {\n  return (\n    <CreditUsage\n      title=\"Platform storage\"\n      description=\"Bunny Stream · Growth plan\"\n      used={1_742}\n      limit={2_000}\n      format={{ style: \"unit\", unit: \"gigabyte\" }}\n      labels={{ remaining: \"free of {limit}\" }}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/charts/native",
+    "import": "import { CreditUsage } from \"@krizaka/charts/native\";",
+    "differences": [
+      "No `description`, `loading` or `className`: lay it out with `style`.",
+      "The daily use is a native sparkline, read as one element."
+    ],
+    "props": [
+      {
+        "component": "CreditUsage",
+        "description": "What is left of an allowance (React Native): the remaining amount, a meter in tones, the use per day, the run-out date.",
+        "props": [
+          {
+            "name": "limit",
+            "type": "number",
+            "default": null,
+            "description": "The allowance.",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What the allowance is: the heading and the meter's name.",
+            "required": true
+          },
+          {
+            "name": "used",
+            "type": "number",
+            "default": null,
+            "description": "How much is used.",
+            "required": true
+          },
+          {
+            "name": "brand",
+            "type": "BrandId",
+            "default": null,
+            "description": "The brand whose palette leads. Default Krizaka.",
+            "required": false
+          },
+          {
+            "name": "daily",
+            "type": "readonly (number | null)[]",
+            "default": null,
+            "description": "The use of each recent day, oldest first.",
+            "required": false
+          },
+          {
+            "name": "format",
+            "type": "ValueFormat",
+            "default": "integer",
+            "description": "How the amounts are written. Default `\"integer\"`.",
+            "required": false
+          },
+          {
+            "name": "hideTitle",
+            "type": "boolean",
+            "default": null,
+            "description": "Hide the heading (it stays the accessible name).",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<CreditLabels>",
+            "default": null,
+            "description": "The words, passed translated.",
+            "required": false
+          },
+          {
+            "name": "levels",
+            "type": "readonly [number, number]",
+            "default": "[0.8, 0.95]",
+            "description": "The shares where the meter turns to warning, then danger. Default `[0.8, 0.95]`.",
+            "required": false
+          },
+          {
+            "name": "locale",
+            "type": "Locale",
+            "default": null,
+            "description": "The locale of every figure and date. Default `\"en-US\"`.",
+            "required": false
+          },
+          {
+            "name": "now",
+            "type": "Date",
+            "default": null,
+            "description": "Today, for the projection. Default: now.",
+            "required": false
+          },
+          {
+            "name": "renewsAt",
+            "type": "string | Date",
+            "default": null,
+            "description": "When the allowance renews.",
+            "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 container (layout only).",
+            "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
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "monthly-credits",
+        "title": "Monthly credits",
+        "description": "The credits card of the mobile app.",
+        "path": "examples/credit-usage/native/monthly-credits.tsx",
+        "module": "@krizaka/charts/registry/examples/credit-usage/native/monthly-credits",
+        "code": "import { CreditUsage } from \"@krizaka/charts/native\";\n\nconst daily = [120, 180, 95, 210, 260, 140, 60, 75, 230, 310, 280, 190, 240, 300];\n\n// The credits card of the mobile app.\nexport default function NativeMonthlyCredits() {\n  return (\n    <CreditUsage\n      title=\"Credits this month\"\n      used={3_120}\n      limit={5_000}\n      daily={daily}\n      renewsAt=\"2026-11-01\"\n      now={new Date(\"2026-10-11T09:00:00Z\")}\n      labels={{ remaining: \"credits left of {limit}\" }}\n    />\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/credit-usage/native/monthly-credits.dark.png",
+          "light": "examples/credit-usage/native/monthly-credits.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/credit-usage/monthly-credits.tsx",
+    "content": "import { CreditUsage } from \"@krizaka/charts/credits\";\n\n// The credits used each day of the last two weeks (an Orazaka Pro plan of 5,000 credits).\nconst daily = [120, 180, 95, 210, 260, 140, 60, 75, 230, 310, 280, 190, 240, 300];\n\nexport default function MonthlyCredits() {\n  return (\n    <CreditUsage\n      title=\"Credits this month\"\n      description=\"Pro plan\"\n      used={3_120}\n      limit={5_000}\n      daily={daily}\n      renewsAt=\"2026-11-01\"\n      now={new Date(\"2026-10-11T09:00:00Z\")}\n      labels={{ remaining: \"credits left of {limit}\" }}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "CreditUsage",
+      "description": "What is left of an allowance: the remaining amount, a meter in tones, the use per day and the run-out date.",
+      "props": [
+        {
+          "name": "limit",
+          "type": "number",
+          "default": null,
+          "description": "The allowance.",
+          "required": true
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "default": null,
+          "description": "What the allowance is (“Credits this month”): the heading and the meter's name.",
+          "required": true
+        },
+        {
+          "name": "used",
+          "type": "number",
+          "default": null,
+          "description": "How much is used.",
+          "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).",
+          "required": false
+        },
+        {
+          "name": "daily",
+          "type": "readonly (number | null)[]",
+          "default": null,
+          "description": "The use of each recent day, oldest first: the sparkline and the projection.",
+          "required": false
+        },
+        {
+          "name": "days",
+          "type": "readonly unknown[]",
+          "default": null,
+          "description": "The days of `daily` (ISO dates), for the sparkline's summary.",
+          "required": false
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "A line under the title: the plan, the period.",
+          "required": false
+        },
+        {
+          "name": "format",
+          "type": "ValueFormat",
+          "default": "integer",
+          "description": "How the amounts are written. Default `\"integer\"`; a `{ style: \"unit\", unit: \"gigabyte\" }` for storage.",
+          "required": false
+        },
+        {
+          "name": "hideTitle",
+          "type": "boolean",
+          "default": null,
+          "description": "Visually hide the title (it stays the accessible name).",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "Partial<CreditLabels>",
+          "default": null,
+          "description": "The words, passed translated; English by default.",
+          "required": false
+        },
+        {
+          "name": "levels",
+          "type": "readonly [number, number]",
+          "default": "[0.8, 0.95]",
+          "description": "The share where the meter turns to warning, then danger. Default `[0.8, 0.95]`.",
+          "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 (`\"fr-FR\"`). Default `\"en-US\"`.",
+          "required": false
+        },
+        {
+          "name": "now",
+          "type": "Date",
+          "default": null,
+          "description": "Today, for the projection (pass it from the server to render the same date on both sides). Default: now.",
+          "required": false
+        },
+        {
+          "name": "renewsAt",
+          "type": "string | Date",
+          "default": null,
+          "description": "When the allowance renews (an ISO date or a `Date`).",
+          "required": false
+        },
+        {
+          "name": "style",
+          "type": "CSSProperties",
+          "default": null,
+          "description": "Inline style on the figure (layout only).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}