@niekes/charts-3d 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2026, Stefan Nieke
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author nor the names of contributors may be used to
+  endorse or promote products derived from this software without specific prior
+  written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,33 @@
+charts-3d
+Copyright 2026, Stefan Nieke
+Licensed under the BSD 3-Clause License, see LICENSE.
+
+charts-3d includes code adapted from shadcn/ui (https://github.com/shadcn-ui/ui):
+
+- the ChartConfig type and the ChartStyle component in
+  registry/new-york/ui/chart-3d.tsx, which mirror the chart component of shadcn/ui
+- the theme tokens in docs/app.css, the neutral theme of shadcn/ui
+
+shadcn/ui is licensed under the MIT License:
+
+MIT License
+
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://github.com/sponsors/niekes"><img src="https://img.shields.io/badge/Sponsor_charts--3d-EA4AAA?logo=githubsponsors&logoColor=white&style=for-the-badge" alt="Sponsor charts-3d"></a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <strong>3D charts for <a href="https://ui.shadcn.com">shadcn/ui</a>, built on <a href="https://github.com/niekes/d3-3d">d3-3d</a>.</strong><br>
+  Free and open source, kept alive by one maintainer and the people who sponsor the work.
+</p>
+
+<p align="center">
+  <a href="https://github.com/niekes/charts-3d/actions/workflows/main.yml"><img src="https://github.com/niekes/charts-3d/actions/workflows/main.yml/badge.svg" alt="Build"></a>
+  <a href="https://github.com/niekes/charts-3d/actions/workflows/main.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fniekes%2Fcharts-3d%2Fmaster%2F.github%2Fbadges%2Fcoverage.json" alt="Coverage"></a>
+  <a href="https://fallow.tools/docs/explanations/health/"><img src="https://raw.githubusercontent.com/niekes/charts-3d/master/.github/badges/health.svg" alt="fallow health"></a>
+  <a href="https://ui.shadcn.com/docs/registry"><img src="https://img.shields.io/badge/shadcn-registry-000000?logo=shadcnui&logoColor=white" alt="shadcn registry"></a>
+  <a href="https://www.npmjs.com/package/@niekes/charts-3d"><img src="https://img.shields.io/npm/v/@niekes/charts-3d" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@niekes/charts-3d"><img src="https://img.shields.io/npm/dw/@niekes/charts-3d" alt="npm weekly downloads"></a>
+  <a href="https://www.npmjs.com/package/d3-3d"><img src="https://img.shields.io/npm/v/d3-3d?label=d3-3d" alt="d3-3d version"></a>
+  <a href="https://github.com/niekes/charts-3d/blob/master/LICENSE"><img src="https://img.shields.io/github/license/niekes/charts-3d" alt="License"></a>
+  <img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript">
+  <a href="https://github.com/niekes/charts-3d"><img src="https://img.shields.io/github/stars/niekes/charts-3d" alt="GitHub stars"></a>
+  <a href="https://github.com/sponsors/niekes"><img src="https://img.shields.io/github/sponsors/niekes?logo=GitHub+Sponsors&logoColor=%23EA4AAA&style=flat" alt="GitHub Sponsors"></a>
+</p>
+
+<p align="center">
+  <a href="https://niekes.github.io/charts-3d/docs">Docs</a> ·
+  <a href="https://niekes.github.io/charts-3d/docs/installation">Installation</a> ·
+  <a href="https://niekes.github.io/charts-3d/docs/components/bar-chart-3d">Components</a> ·
+  <a href="https://niekes.github.io/charts-3d/docs/theming">Theming</a> ·
+  <a href="https://niekes.github.io/charts-3d/docs/how-it-works">How it works</a>
+</p>
+
+---
+
+<table>
+    <tr style="background-color: #f6f8fa">
+        <td><a target="_blank" href="https://niekes.github.io/charts-3d/docs/components/bar-chart-3d"><img src="assets/examples/bar-chart-3d.png" alt="Bar Chart 3D"></a></td>
+        <td><a target="_blank" href="https://niekes.github.io/charts-3d/docs/components/scatter-chart-3d"><img src="assets/examples/scatter-chart-3d.png" alt="Scatter Chart 3D"></a></td>
+    </tr>
+    <tr style="background-color: #f6f8fa">
+        <td><a target="_blank" href="https://niekes.github.io/charts-3d/docs/components/surface-chart-3d"><img src="assets/examples/surface-chart-3d.png" alt="Surface Chart 3D"></a></td>
+        <td><a target="_blank" href="https://niekes.github.io/charts-3d/docs/components/sankey-chart-3d"><img src="assets/examples/sankey-chart-3d.png" alt="Sankey Chart 3D"></a></td>
+    </tr>
+</table>
+
+Copy-paste components or an npm package, plain SVG, themed by the `--chart-*` tokens you already have. They render on the server, take the same `ChartConfig` as the chart of shadcn/ui and turn on drag and on the arrow keys.
+
+## Sponsor charts-3d
+
+**charts-3d** is free, and it always will be. There is no company behind it — just one maintainer working in spare time — so the cost of keeping it alive is paid for by the people who depend on it.
+
+If charts-3d saves you time, [become a sponsor](https://github.com/sponsors/niekes).
+
+| Tier        | What you get                                                                                |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| **$5/mo**   | Your name in the [sponsors list](#sponsors) and my sincere thanks                           |
+| **$25/mo**  | The above, plus your logo in the README and on the docs site, and priority issue triage     |
+| **$100/mo** | The above, plus direct email access for feature requests and a mention in the release notes |
+
+Where the money goes:
+
+- **Issue triage and bug fixes.** Sponsorship buys a reply within a couple of days instead of whenever I get to it.
+- **Components that keep up.** Keeping the registry in step with shadcn/ui, React, Tailwind CSS and d3-3d.
+- **The documentation site.** Hosting, builds and the live examples.
+- **Time for new work.** More charts, transitions, and eventually a WebGL renderer for large data.
+
+Prefer a one-off? The [sponsor page](https://github.com/sponsors/niekes) also takes one-time contributions.
+
+**Need a company sponsorship or an invoice?** [Get in touch](mailto:s@niekes.com).
+
+## Sponsors
+
+Thank you to the people who make this possible. Sponsors at $25/mo and above get their logo in this README and on the docs site; everyone gets their name below.
+
+<!-- New sponsors go below this line, one per line. -->
+
+## Using charts-3d
+
+```bash
+npx shadcn@latest add niekes/charts-3d/bar-chart-3d   # the code, in your project
+npm install @niekes/charts-3d                          # the same components, from npm
+```
+
+Everything else lives in the [documentation](https://niekes.github.io/charts-3d/docs): [installation](https://niekes.github.io/charts-3d/docs/installation), the [components](https://niekes.github.io/charts-3d/docs/components/bar-chart-3d), [theming](https://niekes.github.io/charts-3d/docs/theming) and [how it works](https://niekes.github.io/charts-3d/docs/how-it-works).
+
+charts-3d is not affiliated with shadcn/ui.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=niekes/charts-3d&type=date&legend=bottom-right)](https://www.star-history.com/#niekes/charts-3d&type=date&legend=bottom-right)

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+"use client"
+import * as React from "react";
+import { AxesSpec, AxisSpec, Camera3DInstance, CubeFace, Point2D, TransformedPoint } from "d3-3d";
+declare const THEMES: {
+  readonly light: "";
+  readonly dark: ".dark";
+};
+export type ChartConfig = { [k in string]: {
+  label?: React.ReactNode;
+  icon?: React.ComponentType;
+} & ({
+  color?: string;
+  theme?: never;
+} | {
+  color?: never;
+  theme: Record<keyof typeof THEMES, string>;
+}); };
+/** How the camera looks at the chart box, angles in radians. */
+export type View3D = {
+  yaw: number;
+  /** The angle above the floor the camera looks down from. */
+  tilt: number;
+  zoom?: number;
+  /** How far the chart is moved, in the units of the view box. */
+  pan?: Point2D;
+  /** The distance of the eye in box units; Infinity, the default, is orthographic. */
+  perspective?: number;
+};
+/** How the marks of a chart are drawn. The box, its labels, the tooltip and the legend are always SVG and HTML. */
+export type Renderer3D = "svg" | "canvas";
+/** Maps data values to the world box, which spans -1 to 1 on every axis, y up. */
+export type World = Record<keyof AxesSpec, (value: number) => number>;
+export type Tooltip3D = {
+  /** The anchor in the units of the view box. */
+  at: Point2D;
+  title?: React.ReactNode;
+  items: {
+    label: React.ReactNode;
+    value: React.ReactNode;
+    color?: string;
+  }[];
+};
+/** One shape of a chart, projected, in paint order: a polygon, or a circle of radius `r` around its one point. */
+export type Mark3D = {
+  /** Stable across renders, so React moves the shape instead of redrawing it. */
+  key: string;
+  /** The corners of a polygon, or the center of a circle, in the units of the view box. */
+  points: Point2D[];
+  r?: number;
+  /** A CSS color, such as the result of `shade` or `var(--color-x)`. */
+  fill: string;
+  /** The ring around a circle, a CSS color. */
+  stroke?: string;
+  /** Shown while the pointer is over the mark. */
+  tooltip?: Tooltip3D;
+};
+type ChartContext3D = {
+  config: ChartConfig;
+  camera: Camera3DInstance;
+  renderer: Renderer3D;
+  /** The marks of the chart, which the hover and the canvas read. */
+  scene: React.RefObject<Mark3D[]>;
+  repaint: () => void;
+};
+export declare function useChart3D(): ChartContext3D;
+export type ChartContainer3DProps = {
+  /** The series of the chart: a label and a color per key, as in the chart of shadcn/ui. */
+  config: ChartConfig;
+  /**
+   * Where the camera starts, and where a reset returns it.
+   * @defaultValue { yaw: π/6, tilt: π/6 }
+   */
+  defaultView?: View3D;
+  /**
+   * The width of the view box the chart is drawn in.
+   * @defaultValue 640
+   */
+  width?: number;
+  /**
+   * The height of the view box the chart is drawn in.
+   * @defaultValue 400
+   */
+  height?: number;
+  /**
+   * Shows the label and the color of every config key below the chart.
+   * @defaultValue false
+   */
+  legend?: boolean;
+  /**
+   * How the marks of the chart are drawn: "canvas" suits many marks. The
+   * chart draws as SVG until the browser shows it has a canvas, and where it
+   * has none.
+   * @defaultValue "svg"
+   */
+  renderer?: Renderer3D;
+  /**
+   * Shows a button that lists the keyboard shortcuts of the chart; `?` lists them too.
+   * @defaultValue true
+   */
+  shortcuts?: boolean;
+};
+declare function ChartContainer3D({ id, config, defaultView, width, height, legend, renderer: requested, shortcuts, className, children, "aria-label": ariaLabel, ...props }: React.ComponentProps<"div"> & ChartContainer3DProps): React.JSX.Element;
+/**
+ * The marks of a chart, drawn by the renderer of the container: as SVG
+ * elements, or on the canvas over the chart box. The hover reads them too.
+ */
+declare function Marks3D({ marks }: {
+  marks: Mark3D[];
+}): React.JSX.Element[] | null;
+/** A label beside a mark: `at` in the units of the view box, `anchor` the end of the text that sits there. */
+export type Label3D = {
+  key: string;
+  at: Point2D;
+  text: React.ReactNode;
+  anchor: "start" | "middle" | "end";
+};
+/**
+ * The labels of the marks of a chart, ringed by the background so that they
+ * read on the marks. Like the labels of the box, they are SVG with every renderer.
+ */
+declare function Labels3D({ labels }: {
+  labels: Label3D[];
+}): React.JSX.Element;
+declare function ChartLegend3D({ config }: {
+  config: ChartConfig;
+}): React.JSX.Element;
+/**
+ * The walls of the chart box that face away from the camera, with their
+ * gridlines, and an axis with ticks on the outline of the box.
+ */
+declare function Axes3D({ spec, world, format, titles }: {
+  spec: AxesSpec;
+  world: World;
+  format?: Partial<Record<keyof AxesSpec, (value: number) => React.ReactNode>>;
+  titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+}): React.JSX.Element;
+/** A nice axis from `lo` to `hi` with about `count` ticks. */
+declare function axis(lo: number, hi: number, count?: number): AxisSpec;
+/** The linear map from `domain` to `range`. */
+declare function linear([d0, d1]: number[], [r0, r1]: number[]): (value: number) => number;
+/** The world box of `spec`: x from -1 to 1, y up from 1 to -1, z from -`depth` to `depth`. */
+declare function worldBox(spec: AxesSpec, depth?: number): World;
+/**
+ * `color` lit by the light from the upper left: the face that looks at it
+ * keeps the color, one that turns away gets darker. A CSS color-mix, so the
+ * shade follows the theme variables.
+ */
+declare function shade(face: TransformedPoint<unknown>[], color: string): string;
+/** The mean of the projected points, where a tooltip points at. */
+declare function center(points: TransformedPoint<unknown>[]): Point2D;
+/** The marks of a cube: its faces that look at the camera, shaded in `color`, each with `tooltip` on hover. */
+declare function cubeMarks(id: string, faces: CubeFace[], color: string, tooltip: Tooltip3D): Mark3D[];
+export type BarChart3DProps<T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** One entry per row of bars, with a value per series. */
+  data: T[];
+  /** The field that names each entry, such as "month". */
+  index: keyof T & string;
+  /**
+   * The fields that hold the series, one row of bars each.
+   * @defaultValue the keys of the chart config
+   */
+  keys?: string[];
+  /**
+   * The share of its cell a bar covers.
+   * @defaultValue 0.6
+   */
+  barSize?: number;
+  /** Formats the labels of the entries along x and the values along y. */
+  format?: {
+    x?: (label: string) => React.ReactNode;
+    y?: (value: number) => React.ReactNode;
+  };
+  /** The titles of the axes. */
+  titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+};
+/**
+ * Bars on a floor: one row per entry of `data` along x, one per series
+ * along z, the value as the height. The series are the keys of the chart
+ * config unless `keys` names them.
+ */
+export declare function BarChart3D<T extends Record<string, unknown>>({ data, index, keys, barSize, format, titles }: BarChart3DProps<T>): React.JSX.Element;
+export type ScatterChart3DProps<T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** One entry per point. */
+  data: T[];
+  /** The field of the position along x. */
+  x: keyof T & string;
+  /** The field of the position along y, the height. */
+  y: keyof T & string;
+  /** The field of the position along z. */
+  z: keyof T & string;
+  /**
+   * The field whose value is the config key of the color of a point.
+   * @defaultValue the first key of the chart config for every point
+   */
+  series?: keyof T & string;
+  /**
+   * The radius of a point in the units of the view box.
+   * @defaultValue 4
+   */
+  radius?: number;
+  /** Formats the tick labels of each axis. */
+  format?: Partial<Record<keyof AxesSpec, (value: number) => React.ReactNode>>;
+  /** The titles of the axes. */
+  titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+};
+/**
+ * Points in the chart box, at the fields `x`, `y` and `z` of each entry.
+ * `series` names the field whose value is the config key of the color.
+ */
+export declare function ScatterChart3D<T extends Record<string, unknown>>({ data, x, y, z, series, radius, format, titles }: ScatterChart3DProps<T>): React.JSX.Element;
+export type SurfaceChart3DProps = {
+  /** The heights on the grid, `data[row][column]`. */
+  data: number[][];
+  /**
+   * The data values the first and the last column (x) and row (z) stand for.
+   * @defaultValue the indices of the columns and rows
+   */
+  domain?: {
+    x?: [number, number];
+    z?: [number, number];
+  };
+  /**
+   * The config keys of the colors at the lowest and at the highest height.
+   * @defaultValue the first two keys of the chart config
+   */
+  colors?: [string, string];
+  /** Formats the tick labels of each axis. */
+  format?: Partial<Record<keyof AxesSpec, (value: number) => React.ReactNode>>;
+  /** The titles of the axes. */
+  titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+};
+/**
+ * A surface over a grid: `data[row][column]` is the height, the columns run
+ * along x and the rows along z. The fill ramps from the first color of
+ * `colors` at the lowest height to the second at the highest; both are keys
+ * of the chart config, by default its first two.
+ */
+export declare function SurfaceChart3D({ data, domain, colors, format, titles }: SurfaceChart3DProps): React.JSX.Element;
+export type SankeyChart3DProps = {
+  /** One entry per flow. `source` and `target` are keys of the chart config, which names and colors the nodes. */
+  data: {
+    source: string;
+    target: string;
+    value: number;
+  }[];
+  /**
+   * The width of a node, as a share of the distance between two columns.
+   * @defaultValue 0.2
+   */
+  nodeWidth?: number;
+  /**
+   * The gap between two nodes of a column, as a share of the height.
+   * @defaultValue 0.05
+   */
+  nodePadding?: number;
+  /** Formats the values in the tooltip. */
+  format?: (value: number) => React.ReactNode;
+};
+/**
+ * Flows from left to right: every node a box in its column, as high as the
+ * larger of what flows in and what flows out, and every flow a band from node
+ * to node, as thick as its value, that turns from the color of its source to
+ * the color of its target.
+ */
+export declare function SankeyChart3D({ data, nodeWidth, nodePadding, format }: SankeyChart3DProps): React.JSX.Element;
+export { Axes3D, ChartContainer3D, ChartLegend3D, Labels3D, Marks3D, axis, center, cubeMarks, linear, shade, worldBox };
+//# sourceMappingURL=index.d.ts.map