@niekes/charts-3d 0.4.0 → 0.6.0

package/README.md

@@ -38,7 +38,7 @@
     </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>
+        <td><a target="_blank" href="https://niekes.github.io/charts-3d/docs/components/area-chart-3d"><img src="assets/examples/area-chart-3d.png" alt="Area Chart 3D"></a></td>
     </tr>
 </table>
 

package/dist/index.d.ts

@@ -27,12 +27,11 @@ 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>;
+/** What a mark says while the pointer is on it, beside the pointer. */
 export type Tooltip3D = {
-  /** The anchor in the units of the view box. */
-  at: Point2D;
   title?: React.ReactNode;
   items: {
     label: React.ReactNode;
@@ -54,9 +53,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 +80,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 +124,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;
@@ -146,20 +146,31 @@ export type ChartContainer3DProps = {
    * @defaultValue "bottom-left"
    */
   gizmo?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | false;
+  /**
+   * The corner beside the pointer the tooltip sits at. Where the tooltip would
+   * leave the chart, it flips to the other side, on each axis alone.
+   * @defaultValue "top-right"
+   */
+  tooltip?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
 };
-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;
+declare function ChartContainer3D({ id, config, defaultView, width, height, animationDuration, legend, renderer: requested, shortcuts, keymap, gizmo, tooltip, 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.
+ * 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 +179,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 +192,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,14 +239,79 @@ declare function intoWorld<Datum extends Point3D, T extends ShapeInstance<Datum>
  * 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;
+/**
+ * `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 entries of `data` and their series, for a chart that lays the entries
+ * out along x and the series along z, as the bar and the area chart do. The
+ * name of every entry comes from its `index` field, the series are `keys` or
+ * the keys of the config, and the `target` of every cell is keyed by the name
+ * of its entry and its series, so it follows its entry when the data
+ * reorders; a value that is not a number stands as 0. Each glides by name:
+ * `values` from 0, `rows` - the place of every entry - to where it stands, and
+ * `presence` from 0 to 1 as an entry comes and back as it goes, the gone ones
+ * still among them. `labels` name the ticks: the entry at a tick of x, through
+ * `format.x` - a tick of a gone entry fades out unnamed - and the series at a
+ * tick of z.
+ */
+declare function useSeries<T extends Record<string, unknown>>({ data, index, keys, format }: {
+  data: T[];
+  index: keyof T & string;
+  keys?: string[];
+  format?: {
+    x?: (label: string) => React.ReactNode;
+    y?: (value: number) => React.ReactNode;
+  };
+}): {
+  series: string[];
+  target: {
+    [k: string]: number;
+  };
+  values: Record<string, number>;
+  rows: Record<string, number>;
+  presence: Record<string, number>;
+  labels: {
+    x: (i: number) => React.ReactNode;
+    y: ((value: number) => React.ReactNode) | undefined;
+    z: (j: number) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | Iterable<React.ReactNode> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | React.ReactPortal | null | undefined> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+  };
+};
 /** 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 AreaChart3DProps<T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** One entry per point along x, with a value per series. */
+  data: T[];
+  /** The field that names each entry, such as "year"; a point follows its name through updates, so the names should be unique. */
+  index: keyof T & string;
+  /**
+   * The fields that hold the series, one ribbon each.
+   * @defaultValue the keys of the chart config
+   */
+  keys?: string[];
+  /** 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>>;
+};
+/**
+ * Areas pushed back into ribbons: the entries of `data` along x, one ribbon
+ * per series along z, the area under its line reaching down to the floor of
+ * the box. The series are the keys of the chart config unless `keys` names
+ * them.
+ */
+export declare function AreaChart3D<T extends Record<string, unknown>>({ data, index, keys, format, titles }: AreaChart3DProps<T>): React.JSX.Element;
 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 +346,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 +372,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 +403,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, cubeMarks, faded, intoWorld, linear, pad, shade, useSeries, useTween, useTweenAxes, worldBox };
 //# sourceMappingURL=index.d.ts.map