@niekes/charts-3d 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-"use client"
+/// <reference types="geojson" />
 import * as React from "react";
 import { AxesSpec, AxisSpec, Camera3DInstance, CubeFace, Point2D, Point3D, ShapeInstance, TransformedPoint } from "d3-3d";
 declare const THEMES: {
@@ -26,7 +26,11 @@ export type View3D = {
   /** 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. */
+/**
+ * How the marks of a chart are drawn. The box, its labels, the tooltip and the
+ * legend are always SVG and HTML. "webgl" draws as "canvas", as it drew no
+ * faster, and goes in 1.0.0.
+ */
 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>;
@@ -50,13 +54,17 @@ export type Mark3D = {
   fill: string;
   /** The ring around a circle, a CSS color. */
   stroke?: string;
-  /** Shown while the pointer is over the mark. */
-  tooltip?: Tooltip3D;
+  /**
+   * Shown while the pointer is over the mark. A function is called when the
+   * pointer lands on the mark, so a chart with thousands of marks pays for
+   * one tooltip per hover, not one per mark per frame; `null` shows none.
+   */
+  tooltip?: Tooltip3D | (() => Tooltip3D | null);
   /**
    * 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.
+   * segments of a flow. Pointing at a mark fills them with the focus color -
+   * `--chart-3d-focus`, or their own fill lightened - until the pointer
+   * leaves the mark; a stroke of their own stays.
    */
   groups?: string[];
 };
@@ -72,6 +80,11 @@ type ChartContext3D = {
   renderer: Renderer3D;
   /** The marks of the chart, which the hover and the canvas read. */
   scene: React.RefObject<Mark3D[]>;
+  /** Puts the marks of the `Marks3D` of `id`, drawn at `node` in the tree, into the scene, or takes them out. */
+  place: (id: string, set?: {
+    marks: Mark3D[];
+    node: Element;
+  }) => void;
   repaint: () => void;
   focus: Focus3D;
   /** The time in ms a chart takes to glide into new data, 600 unless the container says. */
@@ -81,7 +94,7 @@ 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";
+export type Gesture3D = "dragRotate" | "touchOrbit" | "dragPan" | "wheelZoom" | "pinchZoom" | "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
@@ -124,9 +137,10 @@ export type ChartContainer3DProps = {
    */
   legend?: boolean;
   /**
-   * 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.
+   * 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, as SVG. "webgl" draws as "canvas", as it drew no faster; it is
+   * deprecated and goes in 1.0.0.
    * @defaultValue "svg"
    */
   renderer?: Renderer3D;
@@ -160,7 +174,8 @@ declare function ChartContainer3D({ id, config, defaultView, width, height, anim
  * 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.
+ * motion, the numbers jump. At rest it hands back the record of its target,
+ * no copy, so no frame rebuilds it: read it, never write to it.
  */
 declare function useTween(values: Record<string, number>, enter?: number): Record<string, number>;
 /**
@@ -173,13 +188,19 @@ declare function useTween(values: Record<string, number>, enter?: number): Recor
  * shrinks from a dropped one instead of jumping when the glide is done.
  */
 declare function useTweenAxes(spec: AxesSpec): AxesSpec;
+/**
+ * The color of the config key `key`: the CSS variable the container declares
+ * for it. A chart without a config has no first key to fall back on, and
+ * draws in a variable nobody declares: colorless, as before.
+ */
+declare const colorOf: (key: string | undefined) => string;
 /**
  * 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;
+}): React.JSX.Element;
 /**
  * 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
@@ -228,6 +249,70 @@ declare function pad(spec: AxisSpec, cell: number): AxisSpec;
 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;
+/**
+ * The point at `lon` and `lat`, in degrees, on the sphere of `radius` around
+ * the center of the world box: the prime meridian faces the viewer at yaw 0,
+ * east lies to the right and the north pole is up - towards -y, as the box
+ * counts y. The globe chart builds its tiles from it, since a chart may not
+ * do trigonometry of its own.
+ */
+declare function globe(lon: number, lat: number, radius?: number): Point3D;
+/** The radius of the globe in the world box: `geoView` projects the land at it, and a geo chart places its marks on it. */
+declare const GLOBE_RADIUS = 1.15;
+/**
+ * The camera without its perspective, a copy, since d3-3d shares the view of
+ * a camera it is handed: d3-geo has no perspective, so a geo chart projects
+ * its marks without one too, and they stay on the land.
+ */
+declare function orthographic(camera: Camera3DInstance): Camera3DInstance;
+/** What `earth` sets on a projection of d3-geo: the three setters it needs, each returning the projection. */
+export type GeoProjectionLike<P> = {
+  rotate(angles: [number, number]): P;
+  scale(scale: number): P;
+  translate(point: [number, number]): P;
+};
+/**
+ * Stands in for a canvas under d3-geo's `geoPath`: `marks(draw, key, fill)`
+ * runs `draw` and returns every ring it drew, cut at the horizon as d3-geo
+ * cuts it, as a polygon mark keyed `key-i`. A point is not a region: the ring
+ * its `moveTo` began goes with its `arc`. A hole is not one either: a ring
+ * wound the other way than the largest ring is left out, so the region
+ * around a hole fills it once, not twice.
+ */
+declare function ringSink(): {
+  beginPath: () => void;
+  moveTo: (x: number, y: number) => void;
+  lineTo: (x: number, y: number) => void;
+  closePath: () => void;
+  arc: () => void;
+  marks: (draw: () => void, key: string, fill: string) => Mark3D[];
+};
+/**
+ * The earth under the marks of a geo chart: the ocean and the land as marks,
+ * flat in `--chart-3d-ocean` and `--chart-3d-land`, falling back to the
+ * colors of the walls - scenery, grouped by nothing, with no tooltip, that
+ * neither enters nor glides. The chart hands in d3-geo's `geoOrthographic()`
+ * and `geoPath`, so the core carries no d3-geo; `earth` sets the projection
+ * to the camera and draws through a sink that collects every ring, cut at
+ * the horizon, as a polygon. `path` and `sink` come along for a chart that
+ * draws regions of its own: `sink.marks(() => path(feature), key, fill)`.
+ */
+declare function earth<Feature, P extends GeoProjectionLike<P>, Path extends (object: Feature | {
+  type: "Sphere";
+}) => unknown>(land: {
+  features: Feature[];
+}, camera: Camera3DInstance, projection: P, geoPath: (projection: P, sink: ReturnType<typeof ringSink>) => Path): {
+  marks: Mark3D[];
+  path: Path;
+  sink: {
+    beginPath: () => void;
+    moveTo: (x: number, y: number) => void;
+    lineTo: (x: number, y: number) => void;
+    closePath: () => void;
+    arc: () => void;
+    marks: (draw: () => void, key: string, fill: string) => Mark3D[];
+  };
+};
 /**
  * Hands the projection its accessors into the world box, so every chart maps
  * its shapes onto the screen the same way.
@@ -246,18 +331,33 @@ declare function shade(face: TransformedPoint<unknown>[], color: string): string
  * after `shade`, which would mix a translucent color back towards opaque.
  */
 declare function faded(color: string, opacity: number): string;
+/**
+ * Whether `value` is a number a chart can place: whatever `Number` reads as a
+ * finite number - a number, a string of one, a date, a bigint - but not what
+ * it reads as 0 for want of a value: null, a blank string and a boolean would
+ * draw an entry without a place at the origin.
+ */
+declare function finite(value: unknown): boolean;
+/**
+ * `value` as an amount a mark is sized by, such as the area of a dot or the
+ * height of a tile: one below 0, or one that is not a finite number, stands
+ * as 0.
+ */
+declare function nonNegative(value: unknown): number;
 /**
  * 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:
+ * reorders; a value that is not a finite 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.
+ * tick of z. Every entry is keyed by its id - its name, made unique where a
+ * name repeats - and `nameOf` reads the name back; `entries` holds the entry
+ * behind every id still in the data.
  */
 declare function useSeries<T extends Record<string, unknown>>({ data, index, keys, format }: {
   data: T[];
@@ -272,6 +372,7 @@ declare function useSeries<T extends Record<string, unknown>>({ data, index, key
   target: {
     [k: string]: number;
   };
+  entries: Map<string, T>;
   values: Record<string, number>;
   rows: Record<string, number>;
   presence: Record<string, number>;
@@ -280,13 +381,79 @@ declare function useSeries<T extends Record<string, unknown>>({ data, index, key
     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>>;
   };
+  nameOf: typeof nameOf;
 };
+/** The name of the entry of `id`, as its data names it. */
+declare const nameOf: (id: string) => string;
 /** 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[];
+declare function cubeMarks(id: string, faces: CubeFace[], color: string, tooltip: Mark3D["tooltip"]): Mark3D[];
+/**
+ * The corners of a bar on the floor of `world`, at `x` and `z` in the values
+ * of the data, from 0 to `value`, `size` wide and deep in the world box.
+ * box() rises towards -y, so a negative bar starts at its value.
+ */
+declare function barCorners(world: World, x: number, z: number, value: number, size: {
+  width: number;
+  depth: number;
+}): Point3D[];
+/** The marks of one bar: the faces that look at the camera, shaded and faded to `opacity`, each with `tooltip` on hover. Its group is the bar alone, so hovering highlights one bar. */
+declare function barMarks({ id, faces, color, tooltip, opacity }: {
+  id: string;
+  faces: CubeFace[];
+  color: string;
+  tooltip: Mark3D["tooltip"];
+  opacity: number;
+}): {
+  /** 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;
+  /** The ring around a circle, a CSS color. */
+  stroke?: string;
+  /**
+   * Shown while the pointer is over the mark. A function is called when the
+   * pointer lands on the mark, so a chart with thousands of marks pays for
+   * one tooltip per hover, not one per mark per frame; `null` shows none.
+   */
+  tooltip?: Tooltip3D | (() => Tooltip3D | null);
+  fill: string;
+  groups: string[];
+}[];
+/**
+ * The color at `value` on a ramp from the config color `low` at `lo` to
+ * `high` at `hi` - a value beyond them takes the color of the nearer end: a
+ * CSS color-mix, so it follows the theme.
+ */
+declare function ramp(value: number, [lo, hi]: [number, number], [low, high]: [string, string]): string;
+/**
+ * Where the `count` columns or rows of a grid stand along one axis of
+ * arrangement: at their value of `at`, in any order, or evenly over `ends`,
+ * by default their indices; one without a finite value has no place. With
+ * the cell, the smallest gap between two places - 1 where there is none -
+ * and the axis over the places, its ticks within: its walls half a cell
+ * beyond them - the padding - or at them where not `padded`, never at a
+ * rounder tick, which would leave the box empty beyond the data.
+ */
+declare function gridAxis(count: number, { at, ends, padded }?: {
+  at?: number[];
+  ends?: [number, number];
+  padded?: boolean;
+}): {
+  places: Record<number, number>;
+  cell: number;
+  spec: AxisSpec;
+};
+/** `cubes`, each with its bottom face as `floor`, found once: bars on one floor paint back to front by it. */
+declare function floored<C extends {
+  faces: CubeFace[];
+}>(cubes: C[]): (C & {
+  floor: CubeFace;
+})[];
 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. */
+  /** The field that names each entry, such as "year"; a point follows its name through updates, and an entry of a name that repeats is, in the order of the data, a point of its own. */
   index: keyof T & string;
   /**
    * The fields that hold the series, one ribbon each.
@@ -300,6 +467,17 @@ export type AreaChart3DProps<T extends Record<string, unknown> = Record<string,
   };
   /** The titles of the axes. */
   titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+  /**
+   * What a face of a ribbon says on hover: `tooltip` is what it would say,
+   * its series and, on a segment of the top, the two entries it spans with
+   * their values as the ticks name them; `data` the series key and those
+   * entries, none on a side; `null` shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    key: string;
+    entries: T[];
+  }) => Tooltip3D | null;
 };
 /**
  * Areas pushed back into ribbons: the entries of `data` along x, one ribbon
@@ -307,11 +485,11 @@ export type AreaChart3DProps<T extends Record<string, unknown> = Record<string,
  * 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 declare function AreaChart3D<T extends Record<string, unknown>>({ data, index, keys, format, titles, tooltip }: 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"; a bar follows its name through updates, so the names should be unique. */
+  /** The field that names each entry, such as "month"; a bar follows its name through updates, and an entry of a name that repeats is, in the order of the data, a bar of its own. */
   index: keyof T & string;
   /**
    * The fields that hold the series, one row of bars each.
@@ -330,15 +508,242 @@ export type BarChart3DProps<T extends Record<string, unknown> = Record<string, u
   };
   /** The titles of the axes. */
   titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+  /**
+   * What a bar says on hover: `tooltip` is what it would say, its entry and
+   * value as the ticks name them, `data` the entry and the series key behind
+   * it; `null` shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    entry: T;
+    key: string;
+  }) => Tooltip3D | null;
 };
 /**
  * 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 declare function BarChart3D<T extends Record<string, unknown>>({ data, index, keys, barSize, format, titles, tooltip }: BarChart3DProps<T>): React.JSX.Element;
+export type BarFieldChart3DProps = {
+  /**
+   * The value of every bar, `data[row][column]`: the columns run along x, the
+   * rows along z, and a bar rises from 0 to its value. One that is not a
+   * finite number draws no bar.
+   */
+  data: number[][];
+  /**
+   * The data values the first and the last column (x) and row (z) stand for,
+   * the others evenly between. The chart keeps half a cell between the bars
+   * and the walls of its box.
+   * @defaultValue the indices of the columns and rows
+   */
+  domain?: {
+    x?: [number, number];
+    z?: [number, number];
+  };
+  /**
+   * The value every column stands at along x, `x[column]`, in any order and
+   * at any spacing, in place of `domain.x`. A column without a finite value
+   * draws no bars.
+   * @defaultValue evenly over `domain.x`
+   */
+  x?: number[];
+  /**
+   * The value every row stands at along z, `z[row]`, in any order and at any
+   * spacing, in place of `domain.z`. A row without a finite value draws no
+   * bars.
+   * @defaultValue evenly over `domain.z`
+   */
+  z?: number[];
+  /**
+   * What a bar says on hover: `tooltip` is what it would say, its x, z and
+   * value as the ticks name them, `data` the row and column of the bar, the
+   * x and z they stand for and its value; `null` shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    row: number;
+    column: number;
+    x: number;
+    z: number;
+    value: number;
+  }) => Tooltip3D | null;
+  /** 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>>;
+  /**
+   * The config keys of the colors at the lowest and at the highest value.
+   * @defaultValue the first two keys of the chart config
+   */
+  colors?: [string, string];
+};
+/**
+ * A field of bars over a grid: `data[row][column]` is the value of a bar, the
+ * columns run along x and the rows along z. Everything about a bar comes from
+ * the data - its place from the value of its column and row, its footprint
+ * from the smallest gap between two of them, its height from its value, its
+ * color from the ramp between the two `colors` at the lowest and the highest
+ * value.
+ */
+export declare function BarFieldChart3D({ data, domain, x, z, tooltip, format, titles, colors }: BarFieldChart3DProps): React.JSX.Element;
+export type ChoroplethChart3DProps<T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** One entry per region: the region an entry names takes its color, and the last entry on a region wins. */
+  data: T[];
+  /**
+   * The regions of the earth, a GeoJSON feature collection, cut at the
+   * horizon; the `id` of a feature is what an entry names. d3-geo reads a
+   * region wound clockwise, the opposite of RFC 7946: topojson-client's
+   * `feature` winds it so, and a region wound the other way fills the globe
+   * around it.
+   */
+  land: GeoJSON.FeatureCollection;
+  /**
+   * The field whose value, as a string, is the `id` of the region of the land
+   * the entry colors: for world-atlas the ISO 3166-1 numeric code, `"276"`
+   * for Germany.
+   */
+  id: keyof T & string;
+  /** The field of the value of an entry, shown in the tooltip of its region. */
+  value: keyof T & string;
+  /**
+   * The field whose value is the config key of the color of a region.
+   * @defaultValue the first key of the chart config for every region
+   */
+  series?: keyof T & string;
+  /**
+   * The field that names an entry: the title of the tooltip of its region.
+   * @defaultValue the label of the series
+   */
+  label?: keyof T & string;
+  /** Formats the value in the tooltip. */
+  format?: (value: number) => React.ReactNode;
+  /**
+   * What a region says on hover: `tooltip` is what it would say, its name or
+   * its series and its value, `data` the entry behind it; `null` shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    entry: T;
+  }) => Tooltip3D | null;
+};
+/**
+ * The regions of the land on a globe, each in the color of its class. The
+ * region an entry names is colored over the land, in the config color of
+ * its series; one without an entry stays land. Nothing grows: a region fades
+ * in with its entry, out without it, and one that changes series leaves as
+ * one and enters as the other.
+ */
+export declare function ChoroplethChart3D<T extends Record<string, unknown>>({ data, land, id, value, series, label, format, tooltip }: ChoroplethChart3DProps<T>): React.JSX.Element;
+export type GlobeChart3DProps<T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** One entry per tile: the tile that holds an entry rises to its value, and the last entry on a tile wins. */
+  data: T[];
+  /**
+   * The regions of the earth under the tiles, a GeoJSON feature collection,
+   * cut at the horizon. d3-geo reads a region wound clockwise, the opposite
+   * of RFC 7946: topojson-client's `feature` winds it so, and a region
+   * wound the other way fills the globe around it.
+   */
+  land: GeoJSON.FeatureCollection;
+  /** The field of the longitude of an entry, in degrees east. */
+  lon: keyof T & string;
+  /** The field of the latitude of an entry, in degrees north. */
+  lat: keyof T & string;
+  /** The field of the value of an entry, the height of its tile; a value below 0, or one that is not a finite number, stands as 0. */
+  value: keyof T & string;
+  /**
+   * The field whose value is the config key of the color of a tile.
+   * @defaultValue the first key of the chart config for every tile
+   */
+  series?: keyof T & string;
+  /**
+   * The field that names an entry: the name of the last entry on a tile is
+   * the title of its tooltip.
+   * @defaultValue the label of the series
+   */
+  label?: keyof T & string;
+  /**
+   * The width of a tile in degrees, a divisor of 180; one that is not
+   * above 0 and up to 180 draws the default.
+   * @defaultValue 5
+   */
+  step?: number;
+  /** Formats the value in the tooltip. */
+  format?: (value: number) => React.ReactNode;
+  /**
+   * What a tile says on hover: `tooltip` is what it would say, its name or
+   * its series, its value and its center, `data` the entries on the tile;
+   * `null` shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    entries: T[];
+  }) => Tooltip3D | null;
+};
+/**
+ * A globe of tiles between meridians and parallels, `step` degrees wide, on
+ * the land. The tile that holds an entry rises from the globe to the entry's
+ * value, in the color of its series; one without an entry is not drawn.
+ */
+export declare function GlobeChart3D<T extends Record<string, unknown>>({ data, land, lon, lat, value, series, label, step: requested, format, tooltip }: GlobeChart3DProps<T>): React.JSX.Element;
+export type PlacesChart3DProps<T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** One entry per place: a dot on the globe. */
+  data: T[];
+  /**
+   * The regions of the earth under the dots, a GeoJSON feature collection,
+   * cut at the horizon. d3-geo reads a region wound clockwise, the opposite
+   * of RFC 7946: topojson-client's `feature` winds it so, and a region
+   * wound the other way fills the globe around it.
+   */
+  land: GeoJSON.FeatureCollection;
+  /** The field of the longitude of an entry, in degrees east. */
+  lon: keyof T & string;
+  /** The field of the latitude of an entry, in degrees north. */
+  lat: keyof T & string;
+  /**
+   * The field of the value of an entry: the area of its dot, relative to the
+   * largest; a value below 0, or one that is not a finite number, stands as 0.
+   * @defaultValue every dot the same size
+   */
+  value?: keyof T & string;
+  /**
+   * The field whose value is the config key of the color of a dot.
+   * @defaultValue the first key of the chart config for every dot
+   */
+  series?: keyof T & string;
+  /**
+   * The field that names an entry: the title of its tooltip, and its identity
+   * through updates, so a new dot grows, a gone one shrinks away and one that
+   * moves glides. The names should be unique.
+   * @defaultValue the place of the entry
+   */
+  id?: keyof T & string;
+  /**
+   * The radius of the largest dot - of every dot, without `value` - in the
+   * units of the view box.
+   * @defaultValue 6
+   */
+  radius?: number;
+  /** Formats the value in the tooltip. */
+  format?: (value: number) => React.ReactNode;
+  /**
+   * What a dot says on hover: `tooltip` is what it would say, its name or
+   * its series, its value and its place, `data` the entry behind it; `null`
+   * shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    entry: T;
+  }) => Tooltip3D | null;
+};
+/**
+ * Dots on the land of a globe, one per place, its area its value. A dot on
+ * the far side is hidden by the globe.
+ */
+export declare function PlacesChart3D<T extends Record<string, unknown>>({ data, land, lon, lat, value, series, id, radius, format, tooltip }: PlacesChart3DProps<T>): React.JSX.Element;
 export type ScatterChart3DProps<T extends Record<string, unknown> = Record<string, unknown>> = {
-  /** One entry per point. */
+  /** One entry per point; one whose x, y or z is missing or not a number has none. */
   data: T[];
   /** The field of the position along x. */
   x: keyof T & string;
@@ -367,25 +772,50 @@ export type ScatterChart3DProps<T extends Record<string, unknown> = Record<strin
   format?: Partial<Record<keyof AxesSpec, (value: number) => React.ReactNode>>;
   /** The titles of the axes. */
   titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+  /**
+   * What a point says on hover: `tooltip` is what it would say, its series
+   * and its x, y and z as the ticks name them, `data` the entry behind it;
+   * `null` shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    entry: T;
+  }) => Tooltip3D | null;
 };
 /**
  * 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, id, series, radius, format, titles }: ScatterChart3DProps<T>): React.JSX.Element;
+export declare function ScatterChart3D<T extends Record<string, unknown>>({ data: all, x, y, z, id, series, radius, format, titles, tooltip }: ScatterChart3DProps<T>): React.JSX.Element;
 export type SurfaceChart3DProps = {
-  /** The heights on the grid, `data[row][column]`. */
+  /** The heights on the grid, `data[row][column]`; one that is not a finite number stands at the lowest of the others. */
   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.
+   * The data values the first and the last column (x) and row (z) stand for,
+   * the others evenly between. 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?: {
     x?: [number, number];
     z?: [number, number];
   };
+  /**
+   * The value every column stands at along x, `x[column]`, at any spacing,
+   * in place of `domain.x`; the box spans them exactly. The surface joins
+   * the columns in the order of the data: give them ascending, or it folds
+   * back over itself. A column without a finite value drops out, its
+   * neighbours joined.
+   * @defaultValue evenly over `domain.x`
+   */
+  x?: number[];
+  /**
+   * The value every row stands at along z, `z[row]`, as `x` does for the
+   * columns.
+   * @defaultValue evenly over `domain.z`
+   */
+  z?: number[];
   /**
    * The config keys of the colors at the lowest and at the highest height.
    * @defaultValue the first two keys of the chart config
@@ -395,6 +825,17 @@ export type SurfaceChart3DProps = {
   format?: Partial<Record<keyof AxesSpec, (value: number) => React.ReactNode>>;
   /** The titles of the axes. */
   titles?: Partial<Record<keyof AxesSpec, React.ReactNode>>;
+  /**
+   * What a cell says on hover: `tooltip` is what it would say, its height as
+   * the ticks of y name it, `data` the row and column the cell starts at and
+   * its height, the mean of its four corners; `null` shows none.
+   * @defaultValue (tooltip) => tooltip
+   */
+  tooltip?: (tooltip: Tooltip3D, data: {
+    row: number;
+    column: number;
+    value: number;
+  }) => Tooltip3D | null;
 };
 /**
  * A surface over a grid: `data[row][column]` is the height, the columns run
@@ -402,6 +843,6 @@ export type SurfaceChart3DProps = {
  * `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 { Axes3D, ChartContainer3D, ChartLegend3D, Labels3D, Marks3D, axis, cubeMarks, faded, intoWorld, linear, pad, shade, useSeries, useTween, useTweenAxes, worldBox };
+export declare function SurfaceChart3D({ data: raw, domain, x, z, colors, format, titles, tooltip }: SurfaceChart3DProps): React.JSX.Element;
+export { Axes3D, ChartContainer3D, ChartLegend3D, GLOBE_RADIUS, Labels3D, Marks3D, axis, barCorners, barMarks, colorOf, cubeMarks, earth, faded, finite, floored, globe, gridAxis, intoWorld, linear, nonNegative, orthographic, pad, ramp, shade, useSeries, useTween, useTweenAxes, worldBox };
 //# sourceMappingURL=index.d.ts.map