@niekes/charts-3d 0.3.0 → 0.5.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

@@ -38,7 +38,6 @@
     </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, CubeFace, 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";
@@ -27,7 +27,7 @@ export type View3D = {
   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";
+export type Renderer3D = "svg" | "canvas" | "webgl";
 /** 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 = {
@@ -53,6 +53,19 @@ export type Mark3D = {
   stroke?: string;
   /** Shown while the pointer is over the mark. */
   tooltip?: Tooltip3D;
+  /**
+   * The marks of the same element as this one: the faces of a bar, the
+   * segments of a flow. Pointing at a mark gives them an edge in the focus
+   * color - `--chart-3d-focus`, or their own fill lightened - until the
+   * pointer leaves the mark; the fill never changes on hover.
+   */
+  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 +74,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, which `keymap` can turn off or rename but not rebind; the shortcut panel shows each with its modifier on the reader's platform. */
+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 }
@@ -87,9 +125,9 @@ export type ChartContainer3DProps = {
    */
   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.
+   * How the marks of the chart are drawn: "canvas" suits many marks, "webgl" more.
+   * The chart draws as SVG until the browser shows it has the requested renderer,
+   * "webgl" falling back to "canvas", and where it has none, as SVG.
    * @defaultValue "svg"
    */
   renderer?: Renderer3D;
@@ -98,21 +136,57 @@ 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 glides
+ * back to `enter`, the mirror of its entering - without one it stands where
+ * it is - and leaves when the glide is done. 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 stay those of `spec`; labels of ticks outside the gliding
+ * ends fade out in `edgeLabels` instead of popping out of the range. The
+ * outermost ticks glide too, so the line of the axis grows to a new tick and
+ * shrinks from a dropped one instead of jumping when the glide is done.
+ */
+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.
  */
 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. */
+}): 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";
+  anchor?: "start" | "middle" | "end";
+  toward?: Point2D;
 };
 /**
  * The labels of the marks of a chart, ringed by the background so that they
@@ -126,7 +200,10 @@ declare function ChartLegend3D({ config }: {
 }): 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;
@@ -136,16 +213,34 @@ 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
  * shade follows the theme variables.
  */
 declare function shade(face: TransformedPoint<unknown>[], color: string): string;
+/**
+ * `color` at `opacity`, from 0 to 1: a CSS color-mix with transparent, so a
+ * mark fades on every renderer while its color stays in CSS. Rounded to a
+ * percent, so the renderers that resolve colors cache a bounded few. Fade
+ * after `shade`, which would mix a translucent color back towards opaque.
+ */
+declare function faded(color: string, opacity: number): 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. */
@@ -153,7 +248,7 @@ declare function cubeMarks(id: string, faces: CubeFace[], color: string, tooltip
 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". */
+  /** The field that names each entry, such as "month"; a bar follows its name through updates, so the names should be unique. */
   index: keyof T & string;
   /**
    * The fields that hold the series, one row of bars each.
@@ -188,6 +283,13 @@ export type ScatterChart3DProps<T extends Record<string, unknown> = Record<strin
   y: keyof T & string;
   /** The field of the position along z. */
   z: keyof T & string;
+  /**
+   * The field that names an entry, so a point follows its name through
+   * updates: a new one grows, a gone one shrinks away, one that moves glides.
+   * The names should be unique.
+   * @defaultValue the position of the entry
+   */
+  id?: 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
@@ -207,12 +309,14 @@ export type ScatterChart3DProps<T extends Record<string, unknown> = Record<strin
  * 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 declare function ScatterChart3D<T extends Record<string, unknown>>({ data, x, y, z, id, 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.
+   * 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?: {
@@ -236,32 +340,5 @@ 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 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 };
+export { Axes3D, ChartContainer3D, ChartLegend3D, Labels3D, Marks3D, axis, center, cubeMarks, faded, intoWorld, linear, pad, shade, useTween, useTweenAxes, worldBox };
 //# sourceMappingURL=index.d.ts.map