@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/tooltip.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Chart tooltips, the state half: what a tooltip shows (rows, templates,
+ * formats), which datum is showing, the handlers marks attach, and the
+ * shared nearest-x mode's points. The panel itself is drawn by the chart
+ * (`frame/tooltip-overlay.ts`).
+ *
+ * A chart provides one {@link TooltipState} through {@link tooltipContext};
+ * marks read it with `ctx.context(tooltipContext)`.
+ */
+import type { ContextKey, Readable, ScenePointerEvent } from "@sophistry/core";
+import type { BandKey, Bounds, Point } from "@sophistry/core/geometry";
+/** Gap between a tooltip panel and the point it describes, scene units. */
+export declare const TIP_GAP = 0.18;
+/**
+ * One line of a tooltip: a channel's name and its formatted value.
+ *
+ * @category Charts
+ */
+export interface TooltipRow {
+    /** The channel the value comes from (`"x"`, `"y"`, `"series"`, `"size"`, `"value"`, …); `"text"` for a sentence. */
+    channel: string;
+    /** The row's name: the field's name when the channel is a key of the datum, else the channel's. Empty for none. */
+    name: string;
+    /** The value, formatted. */
+    value: string;
+    /** The value before formatting, when there is one. */
+    raw?: number | BandKey;
+    /** A swatch drawn before the row: the datum's series colour. */
+    color?: string;
+}
+/**
+ * What a tooltip shows: one line of text (`\n` breaks it), or rows of names
+ * and values in two columns.
+ *
+ * @category Charts
+ */
+export type TooltipContent = string | readonly TooltipRow[];
+/**
+ * Per-channel formatters replacing the chart's own, keyed by channel
+ * (`{ y: (v) => `$${v}` }`). A band axis's value is its category key.
+ *
+ * @category Charts
+ */
+export type TooltipFormat = {
+    readonly [channel: string]: ((value: number | BandKey) => string) | undefined;
+};
+/**
+ * A mark's `tooltip` as an object: the default rows, reformatted or rewritten.
+ *
+ * @see https://sophistry.dev/guides/charts/#tooltips
+ * @category Charts
+ */
+export interface TooltipOptions<T> {
+    /** Formatters for some channels, replacing the axis's or legend's format. */
+    format?: TooltipFormat;
+    /** Your own content from the formatted default rows: return text, or rows (filtered, reordered, renamed or added to). */
+    content?: (rows: readonly TooltipRow[], datum: T, index: number) => TooltipContent;
+}
+/**
+ * A mark's `tooltip` prop: `true` for its default rows (one per channel,
+ * formatted as the chart's axes write them); a template such as
+ * `"{series}: {y}"`; `(d, i) => string`; a {@link TooltipOptions} object;
+ * or `false` for none. Omitted, the enclosing `<Chart tooltip>` decides.
+ *
+ * @see https://sophistry.dev/guides/charts/#tooltips
+ * @category Charts
+ */
+export type TooltipSpec<T> = boolean | string | ((datum: T, index: number) => string) | TooltipOptions<T>;
+/**
+ * Where a hover tooltip stands: by the pointer, following it, or above its datum.
+ *
+ * @category Charts
+ */
+export type TooltipAnchor = "pointer" | "datum";
+/**
+ * A chart's tooltip settings (`<Chart tooltip>`), as its {@link TooltipState} carries them.
+ *
+ * @category Extending
+ */
+export interface TooltipConfig {
+    /** Marks without a `tooltip` of their own show their default. */
+    all: boolean;
+    /** Formatters for some channels; a mark's own win. */
+    format?: TooltipFormat;
+    /** Where a hover tooltip stands. @default "pointer" */
+    anchor?: TooltipAnchor;
+    /**
+     * `"x"`: one shared tooltip for every series at the x nearest the pointer,
+     * with a crosshair; marks' own tooltips are off.
+     * @default "item"
+     */
+    mode?: "item" | "x";
+}
+/**
+ * What a tooltip shows and where, in scene units.
+ *
+ * @category Extending
+ */
+export interface ActiveTooltip {
+    owner: object;
+    /** The content as one string: the accessible name. */
+    text: string;
+    content: TooltipContent;
+    at: Point;
+    /** Opened by a hovering pointer, so it follows it. */
+    follow: boolean;
+}
+/**
+ * One point a mark offers a chart's shared nearest-x tooltip
+ * (`<Chart tooltip={{ mode: "x" }}>`).
+ *
+ * @category Extending
+ */
+export interface TooltipPoint {
+    /** Where it is drawn, in scene units. */
+    at: Point;
+    /** Its x, as the x axis writes it: the tooltip's heading. */
+    x: string;
+    /** The row it adds: its series' name and its formatted y. */
+    row: TooltipRow;
+}
+/**
+ * One chart's tooltip: which datum, if any, it is showing.
+ *
+ * @category Extending
+ */
+export interface TooltipState {
+    /** What is showing, if anything; the overlay binds to it. */
+    active: Readable<ActiveTooltip | null>;
+    /** Shows `content` about the point `at` on behalf of `owner`; with `follow`, by the pointer while it hovers. */
+    show(owner: object, content: TooltipContent, at: Point, follow?: boolean): void;
+    /** Hides the tooltip, if `owner` is the one showing it. */
+    hide(owner: object): void;
+    /** The chart's settings (`chart`'s `tooltip`): undefined for none, false to turn tooltips off. */
+    config(): TooltipConfig | false | undefined;
+    /**
+     * Sets the points `owner` offers the shared nearest-x tooltip (a mark
+     * calls it from each update); `null` withdraws them (on dispose).
+     */
+    offerPoints(owner: object, points: readonly TooltipPoint[] | null): void;
+    /** Every point offered, from every mark, in the order they were first offered. */
+    points(): readonly TooltipPoint[];
+    /** Bumps whenever the offered points change: the overlay binds to it. */
+    pointsVersion: Readable<number>;
+}
+/**
+ * Creates a {@link TooltipState}.
+ *
+ * @param config - The chart's tooltip settings, read when asked.
+ * @category Extending
+ */
+export declare function createTooltipState(config?: () => TooltipConfig | false | undefined): TooltipState;
+/**
+ * The enclosing chart's tooltip state, or null outside a chart. Read it with
+ * `ctx.context(tooltipContext)`.
+ *
+ * @category Extending
+ */
+export declare const tooltipContext: ContextKey<TooltipState | null>;
+/**
+ * One channel a mark's default tooltip reports, before formatting.
+ *
+ * @category Extending
+ */
+export interface TooltipField {
+    /** The channel's prop name: `"x"`, `"y"`, `"series"`, `"size"`, … */
+    channel: string;
+    /** The channel prop as given; a key of the datum names the row. */
+    of?: unknown;
+    /** The row's name, overriding the one `of` gives. */
+    name?: string;
+    /** The value; null or undefined drops the row. */
+    value: number | BandKey | null | undefined;
+    /**
+     * How the chart writes the value (`useChart().format(…)`). Defaults to `formatTick` for
+     * numbers.
+     */
+    format?: (value: number | BandKey) => string;
+    /** A swatch before the row. */
+    color?: string;
+}
+/**
+ * A tooltip's content as one string, its accessible name: text as is, rows
+ * as `name: value` joined by commas.
+ *
+ * @category Extending
+ */
+export declare function tooltipLabel(content: TooltipContent): string;
+/**
+ * Resolves a {@link TooltipSpec} to one datum's content, or undefined for
+ * none. `fallback` is the mark's default; with `state`, the chart's
+ * `<Chart tooltip>` settings apply.
+ */
+export declare function tooltipText<T>(spec: TooltipSpec<T> | undefined, fallback: (datum: T, index: number) => string | readonly TooltipField[], datum: T, index: number, state?: TooltipState): TooltipContent | undefined;
+/**
+ * Interaction props that make a shape show its tooltip on hover, tap or
+ * Enter; spread onto the shape. A mark whose `tooltip` is off registers no
+ * interaction. Outside a chart, only the accessible `label` is set.
+ *
+ * @param tooltip - The chart's tooltip state, if any.
+ * @param text - The content, or undefined for none; read reactively.
+ * @param at - Where the tooltip points, in scene units.
+ * @category Extending
+ */
+export declare function tooltipHandlers(tooltip: TooltipState | undefined, text: () => TooltipContent | undefined, at: () => Point): {
+    readonly label?: string;
+    readonly onEnter?: (event: ScenePointerEvent) => void;
+    readonly onLeave?: (event: ScenePointerEvent) => void;
+    readonly onTap?: (event: ScenePointerEvent) => void;
+};
+/** Width and height of a tooltip's panel, padding included. */
+interface TooltipSize {
+    width: number;
+    height: number;
+}
+/**
+ * A tooltip panel's bounds: `"above"` centred over `at`, `"right"` beside it,
+ * flipped when `frame`'s edge would cut it, then clamped inside `frame`.
+ *
+ * @internal
+ */
+export declare function placeTooltip(size: TooltipSize, at: Point, frame: Bounds | undefined, side?: "above" | "right", gap?: number): Bounds;
+/**
+ * The points at the scene x nearest `x` (all within a hair of it, so series
+ * on one grid share a tooltip). Undefined for none.
+ *
+ * @internal
+ */
+export declare function nearestX(points: readonly TooltipPoint[], x: number): {
+    x: number;
+    points: TooltipPoint[];
+} | undefined;
+/**
+ * {@link nearestX} over one set of points, for a pointer that asks on every
+ * move: the points are sorted by x once and each query bisects, rather than
+ * scanning and filtering them all. Answers exactly as the scan did: the
+ * nearest finite point wins, a tie going to the one offered first, and the
+ * group is every point within a hair of its x, in the order offered.
+ *
+ * @internal
+ */
+export declare function nearestXIndex(points: readonly TooltipPoint[]): (x: number) => {
+    x: number;
+    points: TooltipPoint[];
+} | undefined;
+/**
+ * One datum's channel value: a key, or `(d, i) => value`; undefined for an
+ * omitted or constant channel.
+ *
+ * @internal
+ */
+export declare function datumValue<T>(of: unknown, datum: T, index: number): number | BandKey | undefined;
+/** One datum a mark offers the shared nearest-x tooltip, before formatting. @internal */
+export interface SharedTooltipDatum {
+    /** Data units. */
+    x: number;
+    y: number;
+    /** Where it is drawn, in scene units. */
+    at: Point;
+    /** Its series, naming its row; omitted, the row is named by the `y` channel. */
+    series?: BandKey;
+    color?: string;
+}
+/**
+ * The points a mark offers the shared nearest-x tooltip: one row each, named
+ * by series (else the `y` channel). Empty unless the chart's tooltip mode is
+ * `"x"`, so `data` is only read while it is on. Pass the result to
+ * `tooltip.offerPoints(owner, points)`.
+ *
+ * @internal
+ */
+export declare function sharedTooltipPoints(tooltip: TooltipState | null | undefined, data: () => readonly SharedTooltipDatum[], channels: {
+    y: unknown;
+    format?: (channel: "x" | "y" | "series") => (value: number | BandKey) => string;
+}): readonly TooltipPoint[];
+export {};

package/dist/util.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Small helpers the chart components share: value equality for memo
+ * boundaries, point mixing, bisection. Internal; not exported from the
+ * package entry.
+ */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * Whether two values are equal one level deep: the same value, or arrays
+ * (or plain objects) whose members are identical (`Object.is`).
+ */
+export declare function shallowEqual(a: unknown, b: unknown): boolean;
+/**
+ * Whether two values are equal by structure (arrays, plain objects,
+ * primitives; functions and class instances by identity). For reports and
+ * other small configuration values, never for large data.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** `a + (b − a)·t`. */
+export declare function mix(a: number, b: number, t: number): number;
+/** Two points mixed by `t`. */
+export declare function mixPoint(a: Point, b: Point, t: number): Point;
+/** The first index of sorted `values` whose value is `>= target`. */
+export declare function lowerBound(values: readonly number[], target: number): number;
+/**
+ * A last-value cache by equality: returns the previous value while
+ * `equals(previous, next)` holds, so identity-keyed caches downstream hit.
+ */
+export declare function stableValue<T>(equals?: (a: T, b: T) => boolean): (next: T) => T;
+/**
+ * A last-input cache over a dependency list: `make()` runs only when `deps`
+ * differ (shallowly) from the last call's, else the last result is returned.
+ */
+export declare function keyedMemo<T>(): (deps: readonly unknown[], make: () => T) => T;

package/dist/voxels-9lJ2TZS4.js

@@ -0,0 +1,235 @@
+//#region src/math/shared/pairs.ts
+function e(e, t) {
+	return Math.min(e.length, t.length);
+}
+//#endregion
+//#region src/math/3d/bar3d.ts
+function t(e, t) {
+	return typeof e == "number" ? e : e[t] ?? NaN;
+}
+function n(e) {
+	return typeof e == "number" ? null : e.length;
+}
+function r(r, i, a, o, s, c) {
+	let l = e(r, i);
+	l = Math.min(l, a.length);
+	for (let e of [
+		o,
+		s,
+		c
+	]) {
+		let t = n(e);
+		t !== null && (l = Math.min(l, t));
+	}
+	let u = [];
+	for (let e = 0; e < l; e++) {
+		let n = r[e], l = i[e], d = a[e], f = t(o, e), p = t(s, e), m = t(c, e);
+		Number.isFinite(n) && Number.isFinite(l) && Number.isFinite(d) && Number.isFinite(f) && Number.isFinite(p) && Number.isFinite(m) && u.push({
+			index: e,
+			x0: Math.min(n, n + f),
+			x1: Math.max(n, n + f),
+			y0: Math.min(l, l + p),
+			y1: Math.max(l, l + p),
+			z0: Math.min(d, d + m),
+			z1: Math.max(d, d + m)
+		});
+	}
+	return u;
+}
+function i(t, n, r, i, a, o, s = {}) {
+	let c = s.scale ?? 1, l = e(t, n);
+	l = Math.min(l, r.length, i.length, a.length, o.length);
+	let u = [];
+	for (let e = 0; e < l; e++) {
+		let s = t[e], l = n[e], d = r[e];
+		if (!Number.isFinite(s) || !Number.isFinite(l) || !Number.isFinite(d)) continue;
+		let f = i[e] * c, p = a[e] * c, m = o[e] * c;
+		Number.isFinite(f) && Number.isFinite(p) && Number.isFinite(m) && u.push({
+			index: e,
+			origin: {
+				x: s,
+				y: l,
+				z: d
+			},
+			vector: {
+				x: f,
+				y: p,
+				z: m
+			}
+		});
+	}
+	return u;
+}
+//#endregion
+//#region src/math/3d/scatter3d.ts
+function a(t, n, r) {
+	let i = e(t, n);
+	i = Math.min(i, r.length);
+	let a = [];
+	for (let e = 0; e < i; e++) {
+		let i = t[e], o = n[e], s = r[e];
+		Number.isFinite(i) && Number.isFinite(o) && Number.isFinite(s) && a.push({
+			index: e,
+			x: i,
+			y: o,
+			z: s
+		});
+	}
+	return a;
+}
+function o(t, n, r, i = {}) {
+	let a = i.baseline ?? 0, o = e(t, n);
+	o = Math.min(o, r.length);
+	let s = [];
+	for (let e = 0; e < o; e++) {
+		let i = t[e], o = n[e], c = r[e];
+		Number.isFinite(i) && Number.isFinite(o) && Number.isFinite(c) && s.push({
+			index: e,
+			drop: [{
+				x: i,
+				y: a,
+				z: c
+			}, {
+				x: i,
+				y: o,
+				z: c
+			}],
+			marker: {
+				x: i,
+				y: o,
+				z: c
+			}
+		});
+	}
+	return s;
+}
+//#endregion
+//#region src/math/3d/surfaceGrid3d.ts
+function s(e, t, n) {
+	let r = n.length;
+	if (e.length !== r || t.length !== r) throw Error(`surfaceGrid: X/Y/Z must have the same row count (X=${e.length}, Y=${t.length}, Z=${r}).`);
+	let i = r > 0 ? n[0].length : 0;
+	for (let a = 0; a < r; a++) if (e[a].length !== i || t[a].length !== i || n[a].length !== i) throw Error(`surfaceGrid: row ${a} of X/Y/Z must all have length ${i} (the grid's column count).`);
+	return {
+		nrows: r,
+		ncols: i
+	};
+}
+function c(e, t, n, r, i) {
+	return {
+		x: e[r][i],
+		y: t[r][i],
+		z: n[r][i]
+	};
+}
+function l(e, t, n) {
+	let { nrows: r, ncols: i } = s(e, t, n), a = [];
+	for (let o = 0; o < r - 1; o++) for (let r = 0; r < i - 1; r++) {
+		let i = c(e, t, n, o, r), s = c(e, t, n, o, r + 1), l = c(e, t, n, o + 1, r + 1), u = c(e, t, n, o + 1, r);
+		a.push({ points: [
+			i,
+			u,
+			l,
+			s
+		] });
+	}
+	return a;
+}
+function u(e, t, n) {
+	let { nrows: r, ncols: i } = s(e, t, n), a = [];
+	for (let o = 0; o < r; o++) {
+		let r = Array(i);
+		for (let a = 0; a < i; a++) r[a] = c(e, t, n, o, a);
+		a.push(r);
+	}
+	for (let o = 0; o < i; o++) {
+		let i = Array(r);
+		for (let a = 0; a < r; a++) i[a] = c(e, t, n, a, o);
+		a.push(i);
+	}
+	return a;
+}
+//#endregion
+//#region src/math/3d/voxels.ts
+function d(e, t, n, r) {
+	return e[t]?.[n]?.[r] === !0;
+}
+function f(e) {
+	let t = [];
+	for (let n = 0; n < e.length; n++) {
+		let r = e[n];
+		if (r) for (let i = 0; i < r.length; i++) {
+			let a = r[i];
+			if (a) for (let r = 0; r < a.length; r++) {
+				if (a[r] !== !0) continue;
+				let o = n, s = n + 1, c = i, l = i + 1, u = r, f = r + 1, p = {
+					x: o,
+					y: c,
+					z: u
+				}, m = {
+					x: o,
+					y: c,
+					z: f
+				}, h = {
+					x: o,
+					y: l,
+					z: u
+				}, g = {
+					x: o,
+					y: l,
+					z: f
+				}, _ = {
+					x: s,
+					y: c,
+					z: u
+				}, v = {
+					x: s,
+					y: c,
+					z: f
+				}, y = {
+					x: s,
+					y: l,
+					z: u
+				}, b = {
+					x: s,
+					y: l,
+					z: f
+				};
+				d(e, n + 1, i, r) || t.push({ points: [
+					_,
+					y,
+					b,
+					v
+				] }), d(e, n - 1, i, r) || t.push({ points: [
+					p,
+					m,
+					g,
+					h
+				] }), d(e, n, i + 1, r) || t.push({ points: [
+					h,
+					g,
+					b,
+					y
+				] }), d(e, n, i - 1, r) || t.push({ points: [
+					p,
+					_,
+					v,
+					m
+				] }), d(e, n, i, r + 1) || t.push({ points: [
+					m,
+					v,
+					b,
+					g
+				] }), d(e, n, i, r - 1) || t.push({ points: [
+					p,
+					h,
+					y,
+					_
+				] });
+			}
+		}
+	}
+	return t;
+}
+//#endregion
+export { a, e as c, o as i, l as n, i as o, u as r, r as s, f as t };