@rokkit/chart 1.7.0 → 1.8.1

package/dist/lib/plot/spec.js

@@ -0,0 +1,131 @@
+/**
+ * How `PlotChart` reads its inputs: a `spec` object and component props, which overlap.
+ *
+ * The rule is "a spec value overrides its prop", with one declared exception — `orientation`,
+ * where the prop wins so a wrapper can force direction over a shared spec. Written as a table
+ * so the exception is visible rather than one `??` in twenty turned the other way. Pure: the
+ * component derives from these, and they are tested without rendering.
+ */
+
+/** Where a config field comes from. A null/undefined value falls through to the other source. */
+const SOURCES = {
+	spec: (key, spec) => spec?.[key],
+	prop: (key, _spec, props) => props[key],
+	specFirst: (key, spec, props) => spec?.[key] ?? props[key],
+	propFirst: (key, spec, props) => props[key] ?? spec?.[key]
+}
+
+/**
+ * The PlotState config fields read straight from spec and/or props, in config order.
+ * @type {Array<[string, keyof typeof SOURCES]>}
+ */
+export const PLOT_CONFIG_FIELDS = [
+	['data', 'specFirst'],
+	['width', 'specFirst'],
+	['height', 'specFirst'],
+	['mode', 'prop'],
+	['margin', 'prop'],
+	['helpers', 'prop'],
+	['xDomain', 'specFirst'],
+	['yDomain', 'specFirst'],
+	['colorDomain', 'spec'],
+	['colorScale', 'spec'],
+	['colorScheme', 'spec'],
+	['colorMidpoint', 'spec'],
+	['orientation', 'propFirst'],
+	['axisOrigin', 'specFirst'],
+	['axisOffset', 'specFirst'],
+	['sort', 'spec'],
+	['continuousCategory', 'spec'],
+	['onselect', 'prop'],
+	['selectable', 'prop']
+]
+
+/**
+ * The config `PlotSurface` builds its `PlotState` from.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, any>} props - the component's props
+ * @param {unknown} chartPreset - the resolved preset (context, else the default)
+ */
+export function resolvePlotConfig(spec, props, chartPreset) {
+	const config = Object.fromEntries(
+		PLOT_CONFIG_FIELDS.map(([key, source]) => [key, SOURCES[source](key, spec, props)])
+	)
+	// A spec names its channels; the prop-driven form has none here (children declare them).
+	config.channels = spec ? { x: spec.x, y: spec.y, color: spec.color ?? spec.fill } : {}
+	config.labels = spec?.labels ?? {}
+	config.chartPreset = chartPreset
+	return config
+}
+
+/** An axis label: the spec's label for the field on that axis, else blank. */
+const axisLabel = (spec, field) => spec?.labels?.[field ?? ''] ?? ''
+
+/**
+ * The chrome around the marks: grid, legend, title, summary, axis labels, and the fields the
+ * trend / highlight overlays draw on.
+ *
+ * `grid`: `false` hides it; `true` is 'auto'; `'x' | 'y' | 'both'` names the lines.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, any>} props
+ */
+export function resolveChrome(spec, props) {
+	const grid = spec?.grid ?? props.grid
+	return {
+		showGrid: grid !== false,
+		gridLines: typeof grid === 'boolean' ? 'auto' : grid,
+		showLegend: spec?.legend ?? props.legend,
+		title: spec?.title ?? props.title,
+		summary: spec?.summary ?? props.summary,
+		overlayX: spec?.x ?? props.x,
+		overlayY: spec?.y ?? props.y,
+		xLabel: axisLabel(spec, spec?.x),
+		yLabel: axisLabel(spec, spec?.y)
+	}
+}
+
+/**
+ * The accessible table's columns: the spec's channels (deduped — a table's keyed each needs
+ * unique names, and `x === color` is normal), else the first row's keys.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, unknown>[]} rows
+ * @returns {string[]}
+ */
+export function tableColumns(spec, rows) {
+	const channels = [spec?.x, spec?.y, spec?.color ?? spec?.fill].filter(Boolean)
+	if (channels.length > 0) return [...new Set(channels)]
+	return rows[0] ? Object.keys(rows[0]) : []
+}
+
+/** Spec-level options every geom inherits — only when the spec sets them. */
+function inheritedOptions(spec) {
+	const options = {}
+	if (spec?.stack !== undefined) options.stack = spec.stack
+	if (spec?.orientation !== undefined) options.orientation = spec.orientation
+	return options
+}
+
+/**
+ * The props for one `spec.geoms` entry: the spec's channels unless the geom names its own,
+ * the spec's stack / orientation under the geom's options, and the geom's `props` over all.
+ *
+ * @param {Record<string, any>} geomSpec
+ * @param {Record<string, any> | undefined} spec
+ */
+export function specGeomProps(geomSpec, spec) {
+	return {
+		x: geomSpec.x ?? spec?.x,
+		y: geomSpec.y ?? spec?.y,
+		color: geomSpec.color ?? spec?.color,
+		fill: geomSpec.fill ?? spec?.fill,
+		pattern: geomSpec.pattern,
+		symbol: geomSpec.symbol,
+		stat: geomSpec.stat,
+		label: geomSpec.label,
+		options: { ...inheritedOptions(spec), ...(geomSpec.options ?? {}) },
+		...(geomSpec.props ?? {})
+	}
+}

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[];
+};

package/dist/lib/region.js

@@ -0,0 +1,127 @@
+/**
+ * Region geometry — data-coordinate shapes resolved to plot (u, v) coordinates.
+ *
+ * Kept out of the component so the maths is testable without a DOM, and so every geom that
+ * needs "a shape in data space" (Region today, anything shaded tomorrow) resolves it the same
+ * way: continuous values map straight through the scale, band categories cover the WHOLE
+ * band, and an omitted range spans the axis.
+ */
+
+/** @typedef {{ (v: unknown): number | undefined, bandwidth?: () => number, range: () => number[], domain: () => unknown[] }} AnyScale */
+
+/** @param {AnyScale} scale */
+const isBand = (scale) => typeof scale.bandwidth === 'function'
+
+/**
+ * The data value an open (null/undefined) range end stands for: the low or high end of the
+ * axis's domain — the first or last category on a band axis.
+ *
+ * @param {AnyScale} scale
+ * @param {unknown} v
+ * @param {'lo' | 'hi'} side
+ */
+function endValue(scale, v, side) {
+	if (v !== null && v !== undefined) return v
+	const domain = scale.domain()
+	if (isBand(scale)) return side === 'lo' ? domain[0] : domain[domain.length - 1]
+	const nums = domain.map(Number)
+	return side === 'lo' ? Math.min(...nums) : Math.max(...nums)
+}
+
+/**
+ * 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, range) {
+	if (!range || range.length < 2) {
+		const r = scale.range()
+		return [Math.min(...r), Math.max(...r)]
+	}
+	const band = isBand(scale) ? /** @type {() => number} */ (scale.bandwidth)() : 0
+	const ends = [endValue(scale, range[0], 'lo'), endValue(scale, range[1], 'hi')].map((v) =>
+		Number(scale(v))
+	)
+	return [Math.min(...ends), Math.max(...ends) + band]
+}
+
+/**
+ * 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, v) {
+	const base = Number(scale(v))
+	return isBand(scale) ? base + /** @type {() => number} */ (scale.bandwidth)() / 2 : base
+}
+
+/**
+ * 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, xScale, yScale) {
+	if (shape.points) {
+		if (shape.points.length < 3) return []
+		return shape.points.map(([x, y]) => [positionOf(xScale, x), positionOf(yScale, y)])
+	}
+	if (!shape.x && !shape.y) return []
+	const [x0, x1] = spanOf(xScale, shape.x)
+	const [y0, y1] = spanOf(yScale, shape.y)
+	// Wound so the first vertex is the (lo-x, lo-y) corner in DATA terms: on a vertical chart
+	// the y range is inverted, so y1 (the larger pixel) is the lower value.
+	return [
+		[x0, y1],
+		[x1, y1],
+		[x1, y0],
+		[x0, y0]
+	]
+}
+
+/**
+ * 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) {
+	let a = 0
+	let cx = 0
+	let cy = 0
+	for (let i = 0; i < pts.length; i++) {
+		const p = pts[i]
+		const q = pts[(i + 1) % pts.length]
+		const cross = p.x * q.y - q.x * p.y
+		a += cross
+		cx += (p.x + q.x) * cross
+		cy += (p.y + q.y) * cross
+	}
+	if (Math.abs(a) < 1e-9) {
+		const n = pts.length || 1
+		return { x: pts.reduce((s, p) => s + p.x, 0) / n, y: pts.reduce((s, p) => s + p.y, 0) / n }
+	}
+	return { x: cx / (3 * a), y: cy / (3 * a) }
+}
+
+/**
+ * SVG path data for a closed polygon.
+ *
+ * @param {Array<{ x: number, y: number }>} pts
+ */
+export function polygonPath(pts) {
+	const fmt = (/** @type {number} */ n) => Math.round(n * 1000) / 1000
+	return `M${pts.map((p) => `${fmt(p.x)},${fmt(p.y)}`).join(' L')} Z`
+}

package/dist/state/AestheticState.svelte.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What each category looks like: its palette entry, pattern and symbol — and, for a numeric
+ * colour field, the continuous (sequential or diverging) colour scale.
+ */
+export class AestheticState {
+    /**
+     * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+     * @param {import('./ChannelState.svelte.js').ChannelState} channels
+     */
+    constructor(config: import("./PlotConfig.svelte.js").PlotConfig, channels: import("./ChannelState.svelte.js").ChannelState);
+    /** 'categorical' | 'sequential' | 'diverging' — inferred from the colour field and the spec. */
+    colorScaleType: any;
+    /** The sequential or diverging colour scale, or null for a categorical colour field. */
+    continuousColorScale: {
+        scale: (v: number) => string;
+        domain: [number, number];
+        type: "sequential";
+    } | {
+        scale: (v: number) => string;
+        domain: [number, number, number];
+        type: "diverging";
+    } | null;
+    /**
+     * Map<category, { fill, stroke }> — one shared palette across the colour and fill channels.
+     *
+     * A literal CSS colour is a singleton keyed by null, which every mark falls back to. A
+     * `colorDomain` (FacetPlot passes one so panels agree) wins over the local categories. With
+     * no colour field at all, a single series takes the first palette entry rather than grey.
+     */
+    colors: Map<unknown, {
+        fill: string;
+        stroke: string;
+    }> | Map<null, {
+        fill: any;
+        stroke: any;
+    }>;
+    /** Map<category, pattern name> — only for a categorical pattern field. */
+    patterns: Map<unknown, string> | SvelteMap<any, any>;
+    /** Map<category, symbol shape>. */
+    symbols: Map<unknown, string> | SvelteMap<any, any>;
+    #private;
+}
+import { SvelteMap } from 'svelte/reactivity';