@niekes/charts-3d 0.2.0 → 0.4.0

package/NOTICE

@@ -31,3 +31,36 @@ 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.
+
+charts-3d includes code adapted from React Bits (https://reactbits.dev),
+the Scanner component in docs/components/scanner.tsx, which draws the
+animated background of the landing page of the docs. It stays in the docs,
+which are not part of the npm package: React Bits is licensed under the
+MIT + Commons Clause License Condition v1.0, which permits use as part of
+an application but forbids selling or redistributing the components
+themselves.
+
+Copyright (c) 2026 David Haz
+
+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, and distribute the Software as part of
+an application, website, or product, 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.
+
+Commons Clause Restriction
+
+You may use this Software, including for any commercial purpose, so long as
+you do not sell, sublicense, or redistribute the components themselves -
+whether alone, in a bundle, or as a ported version.
+
+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

@@ -35,7 +35,10 @@
     <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>
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 "use client"
 import * as React from "react";
-import { AxesSpec, AxisSpec, Camera3DInstance, Point2D, TransformedPoint } from "d3-3d";
+import { AxesSpec, AxisSpec, Camera3DInstance, CubeFace, Point2D, Point3D, ShapeInstance, TransformedPoint } from "d3-3d";
 declare const THEMES: {
   readonly light: "";
   readonly dark: ".dark";
@@ -53,6 +53,18 @@ export type Mark3D = {
   stroke?: string;
   /** Shown while the pointer is over the mark. */
   tooltip?: Tooltip3D;
+  /**
+   * What the mark belongs to, such as a flow, or connects, such as a node.
+   * Pointing at a mark fades every mark and label that shares none of its
+   * groups, until the pointer leaves the chart; one without groups never fades.
+   */
+  groups?: string[];
+};
+/** The groups in focus, a store, so a change reaches the marks and labels without rendering the chart again. */
+type Focus3D = {
+  get: () => string[] | undefined;
+  set: (groups?: string[]) => void;
+  subscribe: (listener: () => void) => () => void;
 };
 type ChartContext3D = {
   config: ChartConfig;
@@ -61,11 +73,36 @@ type ChartContext3D = {
   /** The marks of the chart, which the hover and the canvas read. */
   scene: React.RefObject<Mark3D[]>;
   repaint: () => void;
+  focus: Focus3D;
+  /** The time in ms a chart takes to glide into new data, 600 unless the container says. */
+  animationDuration?: number;
 };
 export declare function useChart3D(): ChartContext3D;
+/** The actions a key triggers: each steps the camera, `help` opens the shortcut panel. */
+export type KeyAction3D = "rotateLeft" | "rotateRight" | "rotateUp" | "rotateDown" | "panLeft" | "panRight" | "panUp" | "panDown" | "zoomIn" | "zoomOut" | "reset" | "help";
+/** The gestures of the pointer: a drag turns the camera, with Space held it pans, Ctrl or ⌘ with the wheel zooms, a double click resets. */
+export type Gesture3D = "dragRotate" | "dragPan" | "wheelZoom" | "doubleClickReset";
+/**
+ * The shortcuts of a chart over their defaults, per action: `false` turns an
+ * action off, keys replace its keys and a label renames it in the shortcut
+ * panel, where the actions of one label share a row. Keys are written the way
+ * `aria-keyshortcuts` writes them, such as `"Shift+ArrowLeft"` or
+ * `"Control+Plus"`, and the panel shows the first.
+ */
+export type Keymap3D = { [A in KeyAction3D]?: false | string[] | {
+  keys?: string[];
+  label?: string;
+}; } & { [G in Gesture3D]?: false | {
+  label?: string;
+}; };
 export type ChartContainer3DProps = {
   /** The series of the chart: a label and a color per key, as in the chart of shadcn/ui. */
   config: ChartConfig;
+  /**
+   * The time in ms a chart takes to glide into new data; 0 makes it jump.
+   * @defaultValue 600
+   */
+  animationDuration?: number;
   /**
    * Where the camera starts, and where a reset returns it.
    * @defaultValue { yaw: π/6, tilt: π/6 }
@@ -98,8 +135,33 @@ export type ChartContainer3DProps = {
    * @defaultValue true
    */
   shortcuts?: boolean;
+  /**
+   * Rebinds, renames or turns off the keys and the gestures of the chart, per
+   * action; `false` turns them all off and the chart stands still.
+   * @defaultValue {}
+   */
+  keymap?: Keymap3D | false;
+  /**
+   * The corner that shows the axes of the chart, turned with the camera; `false` hides them.
+   * @defaultValue "bottom-left"
+   */
+  gizmo?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | false;
 };
-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;
+declare function ChartContainer3D({ id, config, defaultView, width, height, animationDuration, legend, renderer: requested, shortcuts, keymap, gizmo, className, children, "aria-label": ariaLabel, ...props }: React.ComponentProps<"div"> & ChartContainer3DProps): React.JSX.Element;
+/**
+ * Eases a chart into new data: the numbers of `values` glide from the ones
+ * on screen to these over the animationDuration of the container. A key
+ * that is new starts at `enter`, or where it ends; a key that is gone goes
+ * at once. Without time, or with reduced motion, the numbers jump.
+ */
+declare function useTween(values: Record<string, number>, enter?: number): Record<string, number>;
+/**
+ * `spec` gliding into new data with the marks: the ends of every axis glide
+ * as `useTween` glides the numbers, where ends rounded from the numbers on
+ * screen would jump from one round number to the next, and the box with
+ * them. The ticks are those of `spec` that lie between the ends.
+ */
+declare function useTweenAxes(spec: AxesSpec): AxesSpec;
 /**
  * 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.
@@ -107,12 +169,37 @@ declare function ChartContainer3D({ id, config, defaultView, width, height, lege
 declare function Marks3D({ marks }: {
   marks: Mark3D[];
 }): React.JSX.Element[] | null;
+/**
+ * A label beside a mark, at `at` in the units of the view box. `toward`, a
+ * unit vector, lays the label on that side of `at`, touching it, and slides
+ * it round `at` as the vector turns; without it, `anchor` is the end of the
+ * text that sits at `at`.
+ */
+export type Label3D = {
+  key: string;
+  at: Point2D;
+  text: React.ReactNode;
+  anchor?: "start" | "middle" | "end";
+  toward?: Point2D;
+  /** The groups of the mark it names, so it fades with the mark out of focus. */
+  groups?: string[];
+};
+/**
+ * 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.
+ * gridlines, the line of every axis along its edge with the mark of each of
+ * its ticks, and the labels of every axis on each of its four edges. Only the
+ * edge the axis sits on shows them, so when the axis moves to another edge,
+ * its line, its marks and its labels fade from one to the other.
  */
 declare function Axes3D({ spec, world, format, titles }: {
   spec: AxesSpec;
@@ -122,10 +209,21 @@ declare function Axes3D({ spec, world, format, titles }: {
 }): 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 axis `spec` with its domain widened by half a `cell` on each side, so
+ * the box keeps room between the outermost data and its walls. The ticks stay
+ * where they were, on the data.
+ */
+declare function pad(spec: AxisSpec, cell: 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;
+/**
+ * Hands the projection its accessors into the world box, so every chart maps
+ * its shapes onto the screen the same way.
+ */
+declare function intoWorld<Datum extends Point3D, T extends ShapeInstance<Datum>>(projection: T, world: World): T;
 /**
  * `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
@@ -134,6 +232,8 @@ declare function worldBox(spec: AxesSpec, depth?: number): World;
 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[];
@@ -197,6 +297,8 @@ export type SurfaceChart3DProps = {
   data: number[][];
   /**
    * The data values the first and the last column (x) and row (z) stand for.
+   * The chart keeps half a cell between the grid and the walls of its box; a
+   * domain given here names the box exactly, without that room.
    * @defaultValue the indices of the columns and rows
    */
   domain?: {
@@ -220,5 +322,32 @@ export type SurfaceChart3DProps = {
  * of the chart config, by default its first two.
  */
 export declare function SurfaceChart3D({ data, domain, colors, format, titles }: SurfaceChart3DProps): React.JSX.Element;
-export { Axes3D, ChartContainer3D, ChartLegend3D, Marks3D, axis, center, linear, shade, worldBox };
+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, intoWorld, linear, pad, shade, useTween, useTweenAxes, worldBox };
 //# sourceMappingURL=index.d.ts.map