@pharos-ds/charts 0.0.0-stage → 1.0.10

package/dist/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * @file types.ts
+ * @output Core types for the v2 chart architecture
+ * @position Foundation — consumed by layout, renderers, and interactions
+ */
+import type { ReactNode } from 'react';
+import type { ScaleLinear, ScaleBand } from 'd3-scale';
+export type ChartScale = ScaleLinear<number, number> | ScaleBand<string>;
+/**
+ * A color for a mark: either a constant CSS color/token, or an accessor that
+ * returns a color per datum (for per-element coloring, e.g. positive/negative).
+ */
+export type ColorAccessor = string | ((datum: Record<string, unknown>, index: number) => string);
+/**
+ * Fallback series color used when a mark has neither an explicit color nor a
+ * palette color assigned by the chart root. Uses an EMITTED core token
+ * (`--color-accent`) — the data-viz `--color-data-*` tokens are JS-only values
+ * (resolved via useChartColors), not CSS custom properties, so `var(--color-data-*)`
+ * would render nothing. The chart root normally assigns a resolved palette color,
+ * so this is only a last-resort fallback.
+ */
+export declare const DEFAULT_SERIES_COLOR = "var(--color-accent)";
+/**
+ * Controls how the y-axis domain is derived when no explicit `yDomain` is given:
+ * - `'auto'` (default) — bar/area marks pin an honest zero baseline; continuous-
+ *   only charts (line/dot/…) get a little headroom so points don't touch edges.
+ * - `'zero'` — symmetric around zero (good for +/- data like profit/loss).
+ * - `'data'` — tight fit to the data extent (no zero forcing, no headroom).
+ */
+export type YBaseline = 'auto' | 'zero' | 'data';
+export interface ChartMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Resolved pixel position for a single data point in a series */
+export interface ResolvedPoint {
+    /** Pixel x in plot area coordinates */
+    px: number;
+    /** Pixel y in plot area coordinates (top of mark) */
+    py: number;
+    /** Pixel y baseline (bottom of mark) — differs from py when stacked */
+    py0: number;
+    /** Index into the data array */
+    dataIndex: number;
+}
+/** Context passed to resolve() and render() on each series */
+export interface SeriesContext {
+    data: Record<string, unknown>[];
+    xKey: string;
+    xScale: ChartScale;
+    yScale: ScaleLinear<number, number>;
+    /**
+     * Categorical y band scale for row-based marks (e.g. heatmap). Present only
+     * when a series declares `layout.yBandKey`; in that case the y-axis is
+     * categorical and the linear `yScale` is unused/degenerate.
+     */
+    yBandScale?: ScaleBand<string>;
+    /** Width of the plot area */
+    width: number;
+    /** Height of the plot area */
+    height: number;
+}
+/**
+ * The standardized shape every mark helper returns.
+ * Each mark type is self-contained: it knows how to resolve positions
+ * and how to render itself. The chart root just iterates and calls.
+ *
+ * A SeriesDef instance is single-use: the layout/render pass annotates it in
+ * place (`_uid`, `_isTopOfStack`, `_resolvedColor`), so a given def must belong
+ * to exactly one <Chart>. Build a fresh series array per chart rather than
+ * sharing the same mark objects across charts.
+ */
+export interface SeriesDef {
+    /** Mark type identifier */
+    readonly type: string;
+    /**
+     * Semantic key for this series — typically the dataKey. Used as a
+     * human-readable label fallback and for stack/group coordination. It is NOT
+     * guaranteed unique (two series can share a dataKey), so it must never be
+     * used as a Map key or React key — use `_uid` for identity instead.
+     */
+    readonly key: string;
+    /** Data keys this series reads from — used to compute y domain */
+    readonly dataKeys: string[];
+    /**
+     * Collision-free per-instance identity, assigned by the layout pass from the
+     * series' position in the `series` array. This is the key used for the
+     * resolved map, React keys, and tooltip/hover lookups. Never set it yourself.
+     */
+    _uid?: string;
+    /** Whether this series is the topmost in its stack (set during layout) */
+    _isTopOfStack?: boolean;
+    /** Static color for legend display. Undefined if color is dynamic (accessor function). */
+    readonly color?: string;
+    /**
+     * Palette color assigned by the chart root for series that don't supply a
+     * static color (auto-colored or accessor-colored). Used as the render fallback
+     * and the legend/tooltip representative color. Never set it yourself.
+     */
+    _resolvedColor?: string;
+    /** Human-readable label for legend. Falls back to key if not provided. */
+    readonly label?: string;
+    /** Layout hints the chart root uses for cross-series coordination */
+    readonly layout: {
+        /** Stack group — series with same stack accumulate */
+        stack?: string;
+        /** Bar group — series with same group subdivide bandwidth */
+        group?: string;
+        /** Whether this series contributes to y-domain zero inclusion */
+        includeZero?: boolean;
+        /**
+         * When set, the chart's y-axis is a band scale built from this data key's
+         * unique values (categorical rows, e.g. a heatmap's days) rather than a
+         * linear value scale. The layout pass exposes it to marks and the axis as
+         * `yBandScale`, so a left `<ChartAxis>` renders the categories aligned to
+         * each row. A heatmap should also declare `dataKeys: []` so it doesn't feed
+         * the (now unused) linear y-domain.
+         */
+        yBandKey?: string;
+    };
+    /**
+     * Resolve pixel positions for each data point.
+     * Called by the chart root during the layout pass.
+     * Receives pre-computed stack offsets if stacked.
+     */
+    resolve(ctx: SeriesContext, stackOffsets?: {
+        y0: number;
+        y1: number;
+    }[], groupInfo?: {
+        index: number;
+        count: number;
+    }): ResolvedPoint[];
+    /**
+     * Render the mark given resolved positions.
+     * Called by the chart root during the render pass.
+     * Returns SVG elements (or manages its own canvas for WebGL).
+     */
+    render(resolved: ResolvedPoint[], ctx: SeriesContext): ReactNode;
+}
+/** Resolved positions for all series */
+export type ResolvedPositions = Map<string, ResolvedPoint[]>;
+/** Pointer event normalized to plot-area coordinates */
+export interface ChartPointerEvent {
+    x: number;
+    y: number;
+    nearest: (ResolvedPoint & {
+        seriesKey: string;
+    }) | null;
+    active: boolean;
+}
+/**
+ * Which way the chart reads. `'vertical'` (default): categories along x, values
+ * grow up. `'horizontal'`: categories along y, values grow right (horizontal
+ * bars). Marks always resolve in the vertical "plot space"; the chart root
+ * transposes them on screen.
+ */
+export type ChartOrientation = 'vertical' | 'horizontal';
+/** Context provided by Chart to interaction children */
+export interface ChartContext {
+    /**
+     * Chart orientation. Chrome (axes, grid) receives display-space scales: for
+     * `'horizontal'`, `xScale` is the value scale and `yBandScale` the category
+     * scale. `resolved` points stay in plot space (see `ChartOrientation`).
+     */
+    orientation?: ChartOrientation;
+    width: number;
+    height: number;
+    margin: ChartMargin;
+    data: Record<string, unknown>[];
+    xKey: string;
+    xScale: ChartScale;
+    yScale: ScaleLinear<number, number>;
+    /**
+     * Categorical y band scale (e.g. heatmap rows), present when a series declares
+     * `layout.yBandKey`. Chrome that renders the y-axis (`ChartAxis`) should
+     * prefer this over the linear `yScale` when it exists.
+     */
+    yBandScale?: ScaleBand<string>;
+    resolved: Map<string, ResolvedPoint[]>;
+    onPointer: (handler: (e: ChartPointerEvent) => void) => () => void;
+    svgRef: React.RefObject<SVGSVGElement | null>;
+}
+/**
+ * Series mark types that are utility / annotation marks rather than primary
+ * data. They're skipped from chrome surfaces (legend, tooltip rows) since
+ * they don't represent values the user is comparing.
+ */
+export declare const UTILITY_MARK_TYPES: ReadonlySet<string>;
+/** True if the series type is a utility / annotation mark. */
+export declare function isUtilityMarkType(type: string): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @output Core types for the v2 chart architecture
+ * @position Foundation — consumed by layout, renderers, and interactions
+ */
+
+/**
+ * A color for a mark: either a constant CSS color/token, or an accessor that
+ * returns a color per datum (for per-element coloring, e.g. positive/negative).
+ */
+
+/**
+ * Fallback series color used when a mark has neither an explicit color nor a
+ * palette color assigned by the chart root. Uses an EMITTED core token
+ * (`--color-accent`) — the data-viz `--color-data-*` tokens are JS-only values
+ * (resolved via useChartColors), not CSS custom properties, so `var(--color-data-*)`
+ * would render nothing. The chart root normally assigns a resolved palette color,
+ * so this is only a last-resort fallback.
+ */
+export const DEFAULT_SERIES_COLOR = 'var(--color-accent)';
+
+/**
+ * Controls how the y-axis domain is derived when no explicit `yDomain` is given:
+ * - `'auto'` (default) — bar/area marks pin an honest zero baseline; continuous-
+ *   only charts (line/dot/…) get a little headroom so points don't touch edges.
+ * - `'zero'` — symmetric around zero (good for +/- data like profit/loss).
+ * - `'data'` — tight fit to the data extent (no zero forcing, no headroom).
+ */
+
+/** Resolved pixel position for a single data point in a series */
+
+/** Context passed to resolve() and render() on each series */
+
+/**
+ * The standardized shape every mark helper returns.
+ * Each mark type is self-contained: it knows how to resolve positions
+ * and how to render itself. The chart root just iterates and calls.
+ *
+ * A SeriesDef instance is single-use: the layout/render pass annotates it in
+ * place (`_uid`, `_isTopOfStack`, `_resolvedColor`), so a given def must belong
+ * to exactly one <Chart>. Build a fresh series array per chart rather than
+ * sharing the same mark objects across charts.
+ */
+
+/** Resolved positions for all series */
+
+/** Pointer event normalized to plot-area coordinates */
+
+/**
+ * Which way the chart reads. `'vertical'` (default): categories along x, values
+ * grow up. `'horizontal'`: categories along y, values grow right (horizontal
+ * bars). Marks always resolve in the vertical "plot space"; the chart root
+ * transposes them on screen.
+ */
+
+/** Context provided by Chart to interaction children */
+
+/**
+ * Series mark types that are utility / annotation marks rather than primary
+ * data. They're skipped from chrome surfaces (legend, tooltip rows) since
+ * they don't represent values the user is comparing.
+ */
+export const UTILITY_MARK_TYPES = new Set(['referenceLine', 'errorBar', 'band']);
+
+/** True if the series type is a utility / annotation mark. */
+export function isUtilityMarkType(type) {
+  return UTILITY_MARK_TYPES.has(type);
+}

package/dist/useChartColors.d.ts

@@ -0,0 +1,16 @@
+import type { ChartColorsAPI } from './getChartColors';
+/**
+ * Theme-aware chart colors. Resolves data-viz tokens from the current
+ * theme context — respects light/dark mode and custom themes.
+ *
+ * @example
+ * ```
+ * const colors = useChartColors();
+ * colors.categorical(5)
+ * colors.sequential.blue(3)
+ * colors.diverging.positiveNegative(5)
+ * colors.alpha('#0171E3', 0.5)
+ * ```
+ */
+export declare function useChartColors(): ChartColorsAPI;
+//# sourceMappingURL=useChartColors.d.ts.map

package/dist/useChartColors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChartColors.d.ts","sourceRoot":"","sources":["../src/useChartColors.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAU/C"}

package/dist/useChartColors.js

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useChartColors.ts
+ * @output Theme-aware chart color palette hook
+ * @position React hook wrapping getChartColors — resolves from live theme context
+ *
+ * Returns a stable reference across renders — the palette only rebuilds when the
+ * resolved theme tokens change (theme or color mode), so consumers can safely
+ * use the result in effect/memo dependency arrays.
+ */
+
+import { useMemo } from 'react';
+import { useTheme } from '@pharos-ds/core/theme';
+import { getChartColorsFromResolver } from "./getChartColors.js";
+/**
+ * Theme-aware chart colors. Resolves data-viz tokens from the current
+ * theme context — respects light/dark mode and custom themes.
+ *
+ * @example
+ * ```
+ * const colors = useChartColors();
+ * colors.categorical(5)
+ * colors.sequential.blue(3)
+ * colors.diverging.positiveNegative(5)
+ * colors.alpha('#0171E3', 0.5)
+ * ```
+ */
+export function useChartColors() {
+  // Depend on the memoized token map (stable per theme + mode), not useTheme's
+  // `token` function, which is a fresh closure on every render and would defeat
+  // memoization — returning a new palette object each render.
+  const {
+    tokens
+  } = useTheme();
+  return useMemo(() => getChartColorsFromResolver(name => tokens[name] ?? ''), [tokens]);
+}

package/dist/utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file utils.ts
+ * @output Shared utilities for chart components
+ * @position Internal helpers; consumed by mark, axis, and interaction components
+ */
+import type { ScaleBand } from 'd3-scale';
+import type { ChartScale } from './types';
+/** Type guard for d3 band scales */
+export declare function isBandScale(scale: ChartScale): scale is ScaleBand<string>;
+/**
+ * Get the x pixel position for a datum using the chart's xKey and xScale.
+ * For band scales, returns the center of the band.
+ */
+export declare function xPixel(d: Record<string, unknown>, xKey: string, xScale: ChartScale): number;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,SAAS,CAAC;AAExC,oCAAoC;AACpC,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,IAAI,SAAS,CAAC,MAAM,CAAC,CAEzE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,GACjB,MAAM,CAaR"}

package/dist/utils.js

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file utils.ts
+ * @output Shared utilities for chart components
+ * @position Internal helpers; consumed by mark, axis, and interaction components
+ */
+
+/** Type guard for d3 band scales */
+export function isBandScale(scale) {
+  return typeof scale === 'function' && 'bandwidth' in scale;
+}
+
+/**
+ * Get the x pixel position for a datum using the chart's xKey and xScale.
+ * For band scales, returns the center of the band.
+ */
+export function xPixel(d, xKey, xScale) {
+  const raw = d[xKey];
+  if (isBandScale(xScale)) {
+    return (xScale(String(raw)) ?? 0) + xScale.bandwidth() / 2;
+  }
+  // Not a band scale → the guard narrows `xScale` to the linear scale, so no
+  // cast is needed. Coerce explicitly: finite numbers pass through, Date/
+  // numeric-string map as d3 would. Anything that coerces to a non-finite value
+  // — a non-numeric (→ NaN) or a raw ±Infinity — collapses to NaN, a single
+  // off-canvas sentinel that marks already skip, rather than a silently wrong
+  // position (d3 maps ±Infinity to an out-of-range pixel, not off-canvas).
+  const value = typeof raw === 'number' ? raw : Number(raw);
+  return Number.isFinite(value) ? xScale(value) : NaN;
+}

package/dist/webgl.d.ts

@@ -0,0 +1,77 @@
+/** Compile a WebGL shader, returns null on failure */
+export declare function compileShader(gl: WebGLRenderingContext, type: number, src: string): WebGLShader | null;
+/** Link a vertex + fragment shader into a program */
+export declare function createProgram(gl: WebGLRenderingContext, vertSrc: string, fragSrc: string): WebGLProgram | null;
+/**
+ * Parse a hex color to [r, g, b] floats in 0-1.
+ *
+ * Accepts `#rgb`, `#rgba`, `#rrggbb`, and `#rrggbbaa`, with or without the
+ * leading `#` (any alpha byte is ignored). Non-hex input — CSS custom
+ * properties, `rgb()`, named colors, or malformed strings — returns a neutral
+ * fallback rather than producing NaN, so the GPU never receives a bad uniform.
+ */
+export declare function hexToGL(hex: string): [number, number, number];
+/** DPR with 2x supersampling for crisp circles. SSR-safe (falls back to 2). */
+export declare function getCanvasDPR(): number;
+/**
+ * Create or get a WebGL context with correct alpha settings.
+ * Uses premultiplied alpha for correct compositing over the page.
+ */
+export declare function getWebGLContext(canvas: HTMLCanvasElement): WebGLRenderingContext | null;
+/**
+ * Set up standard GL state for chart rendering:
+ * - Clear with transparent
+ * - Enable premultiplied alpha blending
+ */
+export declare function setupGLState(gl: WebGLRenderingContext): void;
+/**
+ * Size a canvas for sharp rendering, accounting for DPR.
+ * Returns the DPR used.
+ */
+export declare function sizeCanvas(canvas: HTMLCanvasElement, width: number, height: number): number;
+/**
+ * Mount a canvas as an absolute-positioned sibling to an SVG element.
+ * Automatically aligns with the SVG marker's position — no manual margin
+ * offset needed. This is a Tier 1 guarantee: the canvas lands exactly
+ * where the SVG content area is, regardless of chart margins or transforms.
+ *
+ * Call from a useEffect. Returns a cleanup function.
+ */
+export declare function mountCanvasOverSVG(svgMarker: SVGGraphicsElement, canvas: HTMLCanvasElement, width: number, height: number): (() => void) | undefined;
+/**
+ * Register WebGL context-loss/restore handlers on a canvas.
+ *
+ * Calling `preventDefault()` on the lost event is REQUIRED — without it the
+ * browser will never fire `webglcontextrestored`. `onLost` should drop any
+ * cached GL handles (they are all invalid after loss); `onRestored` should
+ * trigger a rebuild + redraw.
+ *
+ * Returns a cleanup that removes both listeners.
+ */
+export declare function registerContextLossHandlers(canvas: HTMLCanvasElement, onLost: () => void, onRestored: () => void): () => void;
+/**
+ * Eagerly release a WebGL context and its GPU resources on teardown.
+ *
+ * Browsers cap the number of live contexts (~16), so freeing on unmount rather
+ * than waiting for GC prevents "too many active WebGL contexts" failures when
+ * many charts mount/unmount over a session.
+ */
+export declare function loseContext(gl: WebGLRenderingContext): void;
+/**
+ * GLSL fragment for premultiplied-alpha circle with smoothstep AA.
+ * Use in fragment shaders that render point sprites.
+ *
+ * Expects:
+ * - varying float v_alpha (the final alpha before edge AA)
+ * - uniform vec3 u_color
+ *
+ * Returns: gl_FragColor with premultiplied alpha
+ */
+export declare const CIRCLE_FRAG_BODY = "\n    vec2 coord = gl_PointCoord - vec2(0.5);\n    float dist = length(coord);\n    if (dist > 0.5) discard;\n    float edge = 1.0 - smoothstep(0.48, 0.5, dist);\n    float a = v_alpha * edge;\n    gl_FragColor = vec4(u_color * a, a);\n";
+/**
+ * Smoothstep compensation factor for gl_PointSize.
+ * The visible circle radius is 0.48 of the point sprite (smoothstep starts there),
+ * so we scale up by 1/0.96 to match SVG circle radius exactly.
+ */
+export declare const POINT_SIZE_COMPENSATION: number;
+//# sourceMappingURL=webgl.d.ts.map

package/dist/webgl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl.d.ts","sourceRoot":"","sources":["../src/webgl.ts"],"names":[],"mappings":"AAmBA,sDAAsD;AACtD,wBAAgB,aAAa,CAC3B,EAAE,EAAE,qBAAqB,EACzB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,WAAW,GAAG,IAAI,CAYpB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAC3B,EAAE,EAAE,qBAAqB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,YAAY,GAAG,IAAI,CAiCrB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAE7D;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,GACxB,qBAAqB,GAAG,IAAI,CAM9B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,qBAAqB,GAAG,IAAI,CAK5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,MAAM,CASR;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,kBAAkB,EAC7B,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAwC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,MAAM,IAAI,EAClB,UAAU,EAAE,MAAM,IAAI,GACrB,MAAM,IAAI,CAWZ;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,qBAAqB,GAAG,IAAI,CAK3D;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,iPAO5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAa,CAAC"}