@niekes/charts-3d 0.4.0 → 0.5.0

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

@@ -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 = {
@@ -54,9 +54,10 @@ export type Mark3D = {
   /** 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.
+   * 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[];
 };
@@ -80,7 +81,7 @@ type ChartContext3D = {
 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. */
+/** 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
@@ -124,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;
@@ -151,15 +152,20 @@ declare function ChartContainer3D({ id, config, defaultView, width, height, anim
 /**
  * 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.
+ * 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 are those of `spec` that lie between the ends.
+ * 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;
 /**
@@ -168,7 +174,7 @@ declare function useTweenAxes(spec: AxesSpec): AxesSpec;
  */
 declare function Marks3D({ marks }: {
   marks: Mark3D[];
-}): React.JSX.Element[] | null;
+}): 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
@@ -181,8 +187,6 @@ export type Label3D = {
   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
@@ -230,6 +234,13 @@ declare function intoWorld<Datum extends Point3D, T extends ShapeInstance<Datum>
  * 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. */
@@ -237,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.
@@ -272,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
@@ -291,7 +309,7 @@ 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[][];
@@ -322,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, intoWorld, linear, pad, shade, useTween, useTweenAxes, worldBox };
+export { Axes3D, ChartContainer3D, ChartLegend3D, Labels3D, Marks3D, axis, center, cubeMarks, faded, intoWorld, linear, pad, shade, useTween, useTweenAxes, worldBox };
 //# sourceMappingURL=index.d.ts.map