@rokkit/chart 1.6.0 → 1.8.0

package/dist/lib/plot/domains.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Band categories ordered by their summed value — "sort bars by size". Null when not sorting.
+ *
+ * @param {Record<string, unknown>[][]} datasets - every geom's rows
+ * @param {string | undefined} xf
+ * @param {string | undefined} yf
+ * @param {'asc' | 'desc' | undefined} sort
+ */
+export function sortedBandDomain(datasets: Record<string, unknown>[][], xf: string | undefined, yf: string | undefined, sort: "asc" | "desc" | undefined): any[] | null;
+/**
+ * A box/violin spans its whiskers (`iqr_min` / `iqr_max`) and every outlier.
+ *
+ * @param {Record<string, any>[]} rows - box-stat rows
+ */
+export function boxDomain(rows: Record<string, any>[]): number[] | null;
+/**
+ * A stacked bar reaches its column total; a 100%-filled one reaches 1.
+ *
+ * Summed per (x, stack key), keeping the LAST value per key — the builder's own lookup does the
+ * same, so rows sharing a key under an identity stat do not double-count. The stack key is the
+ * builder's (`stackFieldOf`); with none, the builder draws plain bars, so there is no total to
+ * size to and the normal extent applies (null).
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {{ x?: string, y?: string, group?: string, fill?: string, color?: string, pattern?: string }} channels
+ * @param {'stack' | 'fill' | undefined} position
+ */
+export function stackDomain(rows: Record<string, unknown>[], channels: {
+    x?: string;
+    y?: string;
+    group?: string;
+    fill?: string;
+    color?: string;
+    pattern?: string;
+}, position: "stack" | "fill" | undefined): number[] | null;
+/**
+ * A waterfall spans its running total: each step from where the last ended, a total row from 0.
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {string} field
+ * @param {string} [totalField] - rows flagged here are totals, drawn from zero
+ */
+export function waterfallDomain(rows: Record<string, unknown>[], field: string, totalField?: string): number[] | null;
+/**
+ * The value-axis domain the mounted geoms' geometry demands, or null for the plain extent.
+ *
+ * @param {Array<{ id: string, type: string, options?: Record<string, any> }>} geoms
+ * @param {(id: string) => Record<string, unknown>[]} rowsOf - a geom's rows (post-stat)
+ * @param {{ x?: string, fill?: string, color?: string, pattern?: string }} channels - effective
+ * @param {string} field - the value channel
+ */
+export function resolveValueDomain(geoms: Array<{
+    id: string;
+    type: string;
+    options?: Record<string, any>;
+}>, rowsOf: (id: string) => Record<string, unknown>[], channels: {
+    x?: string;
+    fill?: string;
+    color?: string;
+    pattern?: string;
+}, field: string): number[] | null;

package/dist/lib/plot/domains.js

@@ -0,0 +1,130 @@
+/**
+ * Axis domains that a geom's own geometry decides, rather than the raw extent of its rows.
+ *
+ * A box spans its whiskers and outliers, not its rows' y; a stacked bar reaches its column
+ * TOTAL; a waterfall bar sits on a running total. Pure functions over the rows a geom draws,
+ * so they are testable without Svelte, and `resolveValueDomain` asks them in a fixed order —
+ * a new geom with a geometry-driven domain adds a row to that table instead of editing the
+ * scale code.
+ */
+import { stackFieldOf } from './stacking.js'
+import { runningSpans } from './running.js'
+
+const valid = (v) => v !== null && v !== undefined && !isNaN(v)
+
+/**
+ * Band categories ordered by their summed value — "sort bars by size". Null when not sorting.
+ *
+ * @param {Record<string, unknown>[][]} datasets - every geom's rows
+ * @param {string | undefined} xf
+ * @param {string | undefined} yf
+ * @param {'asc' | 'desc' | undefined} sort
+ */
+export function sortedBandDomain(datasets, xf, yf, sort) {
+	if (!sort || !xf || !yf) return null
+	// A Map, not an object: keys are raw values (numbers, Dates) an object would stringify.
+	const totals = new Map()
+	for (const rows of datasets) {
+		for (const d of rows) totals.set(d[xf], (totals.get(d[xf]) ?? 0) + (Number(d[yf]) || 0))
+	}
+	const dir = sort === 'asc' ? 1 : -1
+	return [...totals.keys()].sort((a, b) => dir * (totals.get(a) - totals.get(b)))
+}
+
+/**
+ * A box/violin spans its whiskers (`iqr_min` / `iqr_max`) and every outlier.
+ *
+ * @param {Record<string, any>[]} rows - box-stat rows
+ */
+export function boxDomain(rows) {
+	const outliers = rows.flatMap((d) => d.outliers ?? []).filter(valid)
+	const mins = [...rows.map((d) => d.iqr_min).filter(valid), ...outliers]
+	const maxs = [...rows.map((d) => d.iqr_max).filter(valid), ...outliers]
+	return mins.length > 0 && maxs.length > 0 ? [Math.min(...mins), Math.max(...maxs)] : null
+}
+
+/**
+ * A stacked bar reaches its column total; a 100%-filled one reaches 1.
+ *
+ * Summed per (x, stack key), keeping the LAST value per key — the builder's own lookup does the
+ * same, so rows sharing a key under an identity stat do not double-count. The stack key is the
+ * builder's (`stackFieldOf`); with none, the builder draws plain bars, so there is no total to
+ * size to and the normal extent applies (null).
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {{ x?: string, y?: string, group?: string, fill?: string, color?: string, pattern?: string }} channels
+ * @param {'stack' | 'fill' | undefined} position
+ */
+export function stackDomain(rows, channels, position) {
+	if (position === 'fill') return [0, 1]
+	const stackField = stackFieldOf(channels)
+	if (!channels.x || rows.length === 0 || !stackField) return null
+	const columns = new Map()
+	for (const d of rows) {
+		const column = columns.get(d[channels.x]) ?? new Map()
+		column.set(String(d[stackField]), Number(d[channels.y]) || 0)
+		columns.set(d[channels.x], column)
+	}
+	const totals = [...columns.values()].map((c) => [...c.values()].reduce((s, v) => s + v, 0))
+	return [0, Math.max(0, ...totals)]
+}
+
+/**
+ * A waterfall spans its running total: each step from where the last ended, a total row from 0.
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {string} field
+ * @param {string} [totalField] - rows flagged here are totals, drawn from zero
+ */
+export function waterfallDomain(rows, field, totalField) {
+	if (rows.length === 0) return null
+	const spans = runningSpans(rows, field, totalField)
+	return [Math.min(0, ...spans.map((s) => s.lo)), Math.max(0, ...spans.map((s) => s.hi))]
+}
+
+/** A geom's channels without the keys it left undefined (to inherit). */
+const definedOf = (channels = {}) =>
+	Object.fromEntries(Object.entries(channels).filter(([, v]) => v !== undefined))
+
+const isStacked = (g) =>
+	g.options?.stack || g.options?.position === 'stack' || g.options?.position === 'fill'
+
+/**
+ * Geom types whose geometry decides the VALUE axis, asked in order; the first to return a
+ * domain wins. Each resolver reads the first mounted geom it matches.
+ */
+const VALUE_DOMAINS = [
+	{ matches: (g) => g.type === 'box' || g.type === 'violin', domain: (rows) => boxDomain(rows) },
+	{
+		matches: isStacked,
+		// The geom's OWN channels win — `group` exists only there — over the effective ones.
+		domain: (rows, geom, channels, field) =>
+			stackDomain(
+				rows,
+				{ ...channels, ...definedOf(geom.channels), y: field },
+				geom.options?.position === 'fill' ? 'fill' : 'stack'
+			)
+	},
+	{
+		matches: (g) => g.type === 'waterfall',
+		domain: (rows, geom, _channels, field) => waterfallDomain(rows, field, geom.options?.totalField)
+	}
+]
+
+/**
+ * The value-axis domain the mounted geoms' geometry demands, or null for the plain extent.
+ *
+ * @param {Array<{ id: string, type: string, options?: Record<string, any> }>} geoms
+ * @param {(id: string) => Record<string, unknown>[]} rowsOf - a geom's rows (post-stat)
+ * @param {{ x?: string, fill?: string, color?: string, pattern?: string }} channels - effective
+ * @param {string} field - the value channel
+ */
+export function resolveValueDomain(geoms, rowsOf, channels, field) {
+	for (const resolver of VALUE_DOMAINS) {
+		const geom = geoms.find(resolver.matches)
+		if (!geom) continue
+		const domain = resolver.domain(rowsOf(geom.id), geom, channels, field)
+		if (domain) return domain
+	}
+	return null
+}

package/dist/lib/plot/preset.d.ts

@@ -4,7 +4,7 @@ export function resolvePreset(name: any, helpers?: {}): {
     symbols: any;
 };
 export namespace DEFAULT_PRESET {
-    export let colors: any[];
+    export let colors: string[];
     export { PATTERN_ORDER as patterns };
     export { SYMBOL_ORDER as symbols };
 }

package/dist/lib/plot/preset.js

@@ -1,4 +1,4 @@
-import masterPalette from '../palette.json'
+import { categoricalPalette as masterPalette } from '@rokkit/core'
 import { defaultPreset } from '../preset.js'
 import { PATTERN_ORDER } from '../brewing/patterns.js'
 import { SYMBOL_ORDER } from '../brewing/symbols.js'

package/dist/lib/plot/running.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A waterfall's geometry: where each bar starts and ends on the value axis.
+ *
+ * One function for the builder that draws the bars and the domain that sizes the axis to them —
+ * two copies disagreed: the builder drew a negative total as a 1px sliver at zero, and let a
+ * missing value turn every later bar into NaN, while the axis was sized as if neither happened.
+ *
+ * A step runs from the running total before it to the running total after; a total row (flagged
+ * by `totalField`) runs from 0 to the running total, in whichever direction that is. A missing
+ * or non-numeric value is a step of 0.
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {string} field
+ * @param {string} [totalField]
+ * @returns {Array<{ lo: number, hi: number, total: number, isTotal: boolean, delta: number }>}
+ */
+export function runningSpans(rows: Record<string, unknown>[], field: string, totalField?: string): Array<{
+    lo: number;
+    hi: number;
+    total: number;
+    isTotal: boolean;
+    delta: number;
+}>;

package/dist/lib/plot/running.js

@@ -0,0 +1,32 @@
+/**
+ * A waterfall's geometry: where each bar starts and ends on the value axis.
+ *
+ * One function for the builder that draws the bars and the domain that sizes the axis to them —
+ * two copies disagreed: the builder drew a negative total as a 1px sliver at zero, and let a
+ * missing value turn every later bar into NaN, while the axis was sized as if neither happened.
+ *
+ * A step runs from the running total before it to the running total after; a total row (flagged
+ * by `totalField`) runs from 0 to the running total, in whichever direction that is. A missing
+ * or non-numeric value is a step of 0.
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {string} field
+ * @param {string} [totalField]
+ * @returns {Array<{ lo: number, hi: number, total: number, isTotal: boolean, delta: number }>}
+ */
+export function runningSpans(rows, field, totalField) {
+	let running = 0
+	return rows.map((d) => {
+		const isTotal = Boolean(totalField && d[totalField])
+		const delta = isTotal ? 0 : Number(d[field]) || 0
+		const start = isTotal ? 0 : running
+		running += delta
+		return {
+			lo: Math.min(start, running),
+			hi: Math.max(start, running),
+			total: running,
+			isTotal,
+			delta
+		}
+	})
+}

package/dist/lib/plot/stacking.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The distinct non-x fields among [group, color, pattern] — the fields that put more than one
+ * bar in a single x band (dodge) or more than one segment in a column (stack). `group`, the
+ * explicit grouping channel, comes first. Literal colours are paint, not fields.
+ *
+ * @param {{ x?: string, group?: string, color?: string, pattern?: string }} channels
+ * @returns {string[]}
+ */
+export function subBandFields(channels: {
+    x?: string;
+    group?: string;
+    color?: string;
+    pattern?: string;
+}): string[];
+/**
+ * The field a stacked bar stacks by, from a bar's own channels — or null when there is none,
+ * in which case the builder draws plain bars. One rule for the builder that draws the stack
+ * and the domain that sizes the axis to it: two copies disagreed, and the axis ended below
+ * the tallest bar.
+ *
+ * `group` defaults to the interior (`fill ?? color`), exactly as the bar marks resolve it.
+ *
+ * @param {{ x?: string, group?: string, fill?: string, color?: string, pattern?: string }} channels
+ * @returns {string | null}
+ */
+export function stackFieldOf({ x, group, fill, color, pattern }: {
+    x?: string;
+    group?: string;
+    fill?: string;
+    color?: string;
+    pattern?: string;
+}): string | null;

package/dist/lib/plot/stacking.js

@@ -0,0 +1,34 @@
+import { isLiteralColor } from '../brewing/colors.js'
+
+/**
+ * The distinct non-x fields among [group, color, pattern] — the fields that put more than one
+ * bar in a single x band (dodge) or more than one segment in a column (stack). `group`, the
+ * explicit grouping channel, comes first. Literal colours are paint, not fields.
+ *
+ * @param {{ x?: string, group?: string, color?: string, pattern?: string }} channels
+ * @returns {string[]}
+ */
+export function subBandFields(channels) {
+	const { x: xf, group: gf, color: cf, pattern: pf } = channels
+	const out = []
+	for (const f of [gf, cf, pf]) {
+		if (f && f !== xf && !out.includes(f) && !isLiteralColor(f)) out.push(f)
+	}
+	return out
+}
+
+/**
+ * The field a stacked bar stacks by, from a bar's own channels — or null when there is none,
+ * in which case the builder draws plain bars. One rule for the builder that draws the stack
+ * and the domain that sizes the axis to it: two copies disagreed, and the axis ended below
+ * the tallest bar.
+ *
+ * `group` defaults to the interior (`fill ?? color`), exactly as the bar marks resolve it.
+ *
+ * @param {{ x?: string, group?: string, fill?: string, color?: string, pattern?: string }} channels
+ * @returns {string | null}
+ */
+export function stackFieldOf({ x, group, fill, color, pattern }) {
+	const interior = fill ?? color
+	return subBandFields({ x, group: group ?? interior, color: interior, pattern })[0] ?? null
+}

package/dist/lib/plot/types.d.ts

@@ -1,6 +1,6 @@
 export type GeomSpec = {
     /**
-     * - Geom type: 'bar'|'line'|'area'|'point'|'box'|'violin'|'arc' or custom
+     * - Geom type: 'bar'|'line'|'area'|'point'|'box'|'violin'|'arc'|'hull'|'contour'|'rule'|'region' or custom
      */
     type: string;
     x?: string | undefined;
@@ -16,6 +16,13 @@ export type GeomSpec = {
     stat?: string | undefined;
     label?: string | boolean | undefined;
     options?: Record<string, unknown> | undefined;
+    /**
+     * - Geom-specific props spread onto the component
+     * (`Region`'s `points`/`label`, `Rule`'s `slope`, `Hull`'s `padding`). For the annotation
+     * geoms (`rule`, `region`) these are the ONLY props: they read no data, and a Region's `x`/`y`
+     * are ranges, so inheriting the spec's field names would be wrong.
+     */
+    props?: Record<string, unknown> | undefined;
 };
 export type PlotSpec = {
     data?: Record<string, unknown>[] | undefined;

package/dist/lib/plot/types.js

@@ -3,7 +3,7 @@
 
 /**
  * @typedef {Object} GeomSpec
- * @property {string} type - Geom type: 'bar'|'line'|'area'|'point'|'box'|'violin'|'arc' or custom
+ * @property {string} type - Geom type: 'bar'|'line'|'area'|'point'|'box'|'violin'|'arc'|'hull'|'contour'|'rule'|'region' or custom
  * @property {string} [x]
  * @property {string} [y]
  * @property {string} [color]
@@ -14,6 +14,10 @@
  * @property {string} [stat] - Built-in or helpers.stats key
  * @property {boolean | string} [label]
  * @property {Record<string, unknown>} [options]
+ * @property {Record<string, unknown>} [props] - Geom-specific props spread onto the component
+ *   (`Region`'s `points`/`label`, `Rule`'s `slope`, `Hull`'s `padding`). For the annotation
+ *   geoms (`rule`, `region`) these are the ONLY props: they read no data, and a Region's `x`/`y`
+ *   are ranges, so inheriting the spec's field names would be wrong.
  */
 
 /**

package/dist/lib/preset.d.ts

@@ -34,6 +34,8 @@ export namespace defaultPreset {
         let ribbon: number;
         let waterfall: number;
         let rule: number;
+        let hull: number;
+        let contour: number;
         let radar: number;
     }
     let patterns: string[];

package/dist/lib/preset.js

@@ -1,36 +1,71 @@
 // packages/chart/src/lib/preset.js
 
 export const defaultPreset = {
-  colors: ['blue', 'emerald', 'rose', 'amber', 'violet', 'sky', 'pink', 'teal',
-           'orange', 'indigo', 'lime', 'cyan', 'gold', 'lavender'],
-  shades: {
-    light: { fill: '300', stroke: '700' },
-    dark:  { fill: '500', stroke: '200' }
-  },
-  // Per-geom default mark opacity. `alpha` (a fixed 0–1 prop on each geom / Plot.Root)
-  // overrides these; solid marks default to 1 so `alpha` is the single opacity knob.
-  opacity: {
-    area:        0.6,
-    bar:         1,
-    line:        1,
-    point:       0.8,
-    arc:         1,
-    box:         0.5,
-    violin:      0.5,
-    jitter:      0.8,
-    heatmap:     1,
-    candlestick: 1,
-    hexbin:      1,
-    ribbon:      0.5,
-    waterfall:   1,
-    rule:        1,
-    radar:       0.25
-  },
-  patterns: ['diagonal', 'dots', 'triangles', 'hatch', 'lattice', 'swell',
-             'checkerboard', 'waves', 'petals', 'brick', 'diamonds', 'tile',
-             'scales', 'circles', 'pip', 'rings', 'chevrons', 'shards',
-             'wedge', 'argyle', 'shell'],
-  symbols: ['circle', 'square', 'triangle', 'diamond', 'cross', 'star']
+	colors: [
+		'blue',
+		'emerald',
+		'rose',
+		'amber',
+		'violet',
+		'sky',
+		'pink',
+		'teal',
+		'orange',
+		'indigo',
+		'lime',
+		'cyan',
+		'gold',
+		'lavender'
+	],
+	shades: {
+		light: { fill: '300', stroke: '700' },
+		dark: { fill: '500', stroke: '200' }
+	},
+	// Per-geom default mark opacity. `alpha` (a fixed 0–1 prop on each geom / Plot.Root)
+	// overrides these; solid marks default to 1 so `alpha` is the single opacity knob.
+	opacity: {
+		area: 0.6,
+		bar: 1,
+		line: 1,
+		point: 0.8,
+		arc: 1,
+		box: 0.5,
+		violin: 0.5,
+		jitter: 0.8,
+		heatmap: 1,
+		candlestick: 1,
+		hexbin: 1,
+		ribbon: 0.5,
+		waterfall: 1,
+		rule: 1,
+		hull: 0.15,
+		contour: 0.5,
+		radar: 0.25
+	},
+	patterns: [
+		'diagonal',
+		'dots',
+		'triangles',
+		'hatch',
+		'lattice',
+		'swell',
+		'checkerboard',
+		'waves',
+		'petals',
+		'brick',
+		'diamonds',
+		'tile',
+		'scales',
+		'circles',
+		'pip',
+		'rings',
+		'chevrons',
+		'shards',
+		'wedge',
+		'argyle',
+		'shell'
+	],
+	symbols: ['circle', 'square', 'triangle', 'diamond', 'cross', 'star']
 }
 
 /**
@@ -40,15 +75,15 @@ export const defaultPreset = {
  * @returns {typeof defaultPreset}
  */
 export function createChartPreset(overrides = {}) {
-  return {
-    ...defaultPreset,
-    ...overrides,
-    shades: overrides.shades
-      ? {
-          light: { ...defaultPreset.shades.light, ...overrides.shades.light },
-          dark:  { ...defaultPreset.shades.dark,  ...overrides.shades.dark  }
-        }
-      : defaultPreset.shades,
-    opacity: { ...defaultPreset.opacity, ...overrides.opacity }
-  }
+	return {
+		...defaultPreset,
+		...overrides,
+		shades: overrides.shades
+			? {
+					light: { ...defaultPreset.shades.light, ...overrides.shades.light },
+					dark: { ...defaultPreset.shades.dark, ...overrides.shades.dark }
+				}
+			: defaultPreset.shades,
+		opacity: { ...defaultPreset.opacity, ...overrides.opacity }
+	}
 }

package/dist/lib/region.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Screen span of a [lo, hi] range on one axis. A band category contributes its whole band,
+ * so `x={['a', 'b']}` shades both columns edge to edge. Omitted → the full range; a `null`
+ * end runs to that edge of the axis, so `[p75, null]` is "the top quartile and beyond".
+ *
+ * @param {AnyScale} scale
+ * @param {unknown[] | undefined} range
+ * @returns {[number, number]}
+ */
+export function spanOf(scale: AnyScale, range: unknown[] | undefined): [number, number];
+/**
+ * Position of a single data value — band categories resolve to the band centre, which is
+ * where a point in that category is drawn.
+ *
+ * @param {AnyScale} scale
+ * @param {unknown} v
+ */
+export function positionOf(scale: AnyScale, v: unknown): number;
+/**
+ * The region's vertices in (u, v) plot coordinates — before orientation `place`.
+ *
+ * `points` (a polygon, three or more vertices) wins over `x`/`y` ranges. Fewer than three
+ * points is not an area, so it resolves to nothing rather than a degenerate sliver.
+ *
+ * @param {{ x?: unknown[], y?: unknown[], points?: unknown[][] }} shape
+ * @param {AnyScale} xScale
+ * @param {AnyScale} yScale
+ * @returns {Array<[number, number]>}
+ */
+export function regionVertices(shape: {
+    x?: unknown[];
+    y?: unknown[];
+    points?: unknown[][];
+}, xScale: AnyScale, yScale: AnyScale): Array<[number, number]>;
+/**
+ * Area centroid of a simple polygon — where its label goes. Falls back to the vertex mean for
+ * a zero-area (collinear) polygon, which has no area centroid.
+ *
+ * @param {Array<{ x: number, y: number }>} pts
+ * @returns {{ x: number, y: number }}
+ */
+export function centroid(pts: Array<{
+    x: number;
+    y: number;
+}>): {
+    x: number;
+    y: number;
+};
+/**
+ * SVG path data for a closed polygon.
+ *
+ * @param {Array<{ x: number, y: number }>} pts
+ */
+export function polygonPath(pts: Array<{
+    x: number;
+    y: number;
+}>): string;
+export type AnyScale = {
+    (v: unknown): number | undefined;
+    bandwidth?: () => number;
+    range: () => number[];
+    domain: () => unknown[];
+};