@rokkit/chart 1.7.0 → 1.8.0

package/README.md

@@ -100,6 +100,19 @@ const dimensions = brewer.getDimensions()
 | `Plot.Grid`   | Background grid lines derived from axis scales.           |
 | `Plot.Legend` | Color legend; clicking items filters the visible series.  |
 
+Every geom is on the namespace too — `Line`, `Area`, `Point`, `Arc`, `Box`, `Violin`, `Jitter`,
+`Heatmap`, `Hexbin`, `Candlestick`, `Waterfall`, `Ribbon`, `Radar`, `Highlight`, `Trend` — plus four
+that annotate the metric plane rather than draw rows:
+
+| Component      | Description                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------- |
+| `Plot.Rule`    | Reference lines at `x` / `y` values, or `slope` + `intercept`, clipped to the plot.           |
+| `Plot.Region`  | Shaded band (`[lo, hi]`, `null` = open end) or polygon (`points`) in data coordinates.        |
+| `Plot.Hull`    | Padded convex hull around each group of the `fill` / `color` field.                           |
+| `Plot.Contour` | Kernel-density contours per group — rings, or `filled` bands.                                 |
+
+Together they draw architecture charts such as Robert Martin's main sequence — see the Charts guide.
+
 ### `Plot.Root` props
 
 | Prop                | Type               | Default                               | Description                                                           |

package/dist/Plot.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import { getContext } from 'svelte'
-	import type { Snippet } from 'svelte'
+	import type { Component, Snippet } from 'svelte'
 	import { defaultPreset } from './lib/preset.js'
 	import type { PlotSpec, PlotHelpers } from './lib/plot/types.js'
 	import PlotSurface from './PlotSurface.svelte'
@@ -21,6 +21,10 @@
 	import Hexbin from './geoms/Hexbin.svelte'
 	import Ribbon from './geoms/Ribbon.svelte'
 	import Radar from './geoms/Radar.svelte'
+	import Rule from './geoms/Rule.svelte'
+	import Region from './geoms/Region.svelte'
+	import Hull from './geoms/Hull.svelte'
+	import Contour from './geoms/Contour.svelte'
 	import Highlight from './geoms/Highlight.svelte'
 	import Trend from './geoms/Trend.svelte'
 
@@ -66,6 +70,11 @@
 		axisOrigin?: [number | undefined, number | undefined]
 		/** Nudge an edge-pinned axis outward by N px (Q1 only). Also via `spec.axisOffset`. */
 		axisOffset?: number
+		/** Fix the x domain instead of inferring it from the data — e.g. `[0, 1]` for a metric
+		 *  plane defined by theory, not by where the rows fall. Also via `spec.xDomain`. */
+		xDomain?: unknown[]
+		/** Fix the y domain. Also via `spec.yDomain`. */
+		yDomain?: unknown[]
 		/** Animate marks on data/flip changes (opt-out for e.g. AnimatedPlot, which
 		 *  tweens its own frames). Enabled one frame after the width settles so the
 		 *  initial layout paints un-animated. Default `true`. */
@@ -104,6 +113,8 @@
 		selected = $bindable([]),
 		axisOrigin = undefined,
 		axisOffset = undefined,
+		xDomain = undefined,
+		yDomain = undefined,
 		animate = true,
 		children
 	}: Props = $props()
@@ -145,8 +156,8 @@
 			channels: spec ? { x: spec.x, y: spec.y, color: spec.color ?? spec.fill } : {},
 			labels: spec?.labels ?? {},
 			helpers,
-			xDomain: spec?.xDomain,
-			yDomain: spec?.yDomain,
+			xDomain: spec?.xDomain ?? xDomain,
+			yDomain: spec?.yDomain ?? yDomain,
 			colorDomain: spec?.colorDomain,
 			colorScale: spec?.colorScale,
 			colorScheme: spec?.colorScheme,
@@ -168,8 +179,13 @@
 	const overlayX = $derived(spec?.x ?? x)
 	const overlayY = $derived(spec?.y ?? y)
 
-	// Geom component resolver for spec-driven mode
-	const GEOM_COMPONENTS = {
+	// Geom component resolver for spec-driven mode. Typed as a lookup table, not the union of
+	// its members: a spec names geoms by string at runtime, exactly like `helpers.geoms`, and the
+	// union of every geom's Props has no single shape a generic call site can satisfy.
+	// `any` is the honest type for a heterogeneous table resolved by name — the same one the
+	// public `PlotHelpers.geoms` already declares in lib/plot/types.js.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const GEOM_COMPONENTS: Record<string, Component<any>> = {
 		bar: Bar,
 		line: Line,
 		area: Area,
@@ -184,11 +200,18 @@
 		ribbon: Ribbon,
 		// Radar reads the generic x/y/color this path passes via its own aliases, and takes
 		// its axis order from `options.axes` — see Radar.svelte's Props.
-		radar: Radar
+		radar: Radar,
+		hull: Hull,
+		contour: Contour
 	}
 
+	// Plane annotations read no data, so they take ONLY their own `props` — never the spec's
+	// field channels: a Region's `x`/`y` are ranges, and handing it the field name 'instability'
+	// would be a range of one string.
+	const ANNOTATIONS = { rule: Rule, region: Region }
+
 	function resolveGeomComponent(type: string) {
-		return helpers?.geoms?.[type] ?? GEOM_COMPONENTS[type as keyof typeof GEOM_COMPONENTS]
+		return helpers?.geoms?.[type] ?? GEOM_COMPONENTS[type]
 	}
 </script>
 
@@ -215,10 +238,14 @@
 		<!-- Declarative children (geom components) -->
 		{@render children?.()}
 
-		<!-- Spec-driven geoms -->
-		{#each specGeoms as geomSpec (geomSpec.type)}
+		<!-- Spec-driven geoms. Keyed by position, not type: two regions in one spec are normal, and
+		     a type key would be a duplicate that aborts the whole render. -->
+		{#each specGeoms as geomSpec, i (`${geomSpec.type}-${i}`)}
+			{@const Annotation = ANNOTATIONS[geomSpec.type as keyof typeof ANNOTATIONS]}
 			{@const GeomComponent = resolveGeomComponent(geomSpec.type)}
-			{#if GeomComponent}
+			{#if Annotation && !helpers?.geoms?.[geomSpec.type]}
+				<Annotation {...geomSpec.props ?? {}} />
+			{:else if GeomComponent}
 				<GeomComponent
 					x={geomSpec.x ?? spec?.x}
 					y={geomSpec.y ?? spec?.y}
@@ -233,6 +260,7 @@
 						...(spec?.orientation !== undefined ? { orientation: spec.orientation } : {}),
 						...(geomSpec.options ?? {})
 					}}
+					{...geomSpec.props ?? {}}
 				/>
 			{/if}
 		{/each}

package/dist/Plot.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { Snippet } from 'svelte';
+import type { Component, Snippet } from 'svelte';
 import type { PlotSpec, PlotHelpers } from './lib/plot/types.js';
 type Row = Record<string, unknown>;
 type Method = string | number | {
@@ -48,12 +48,17 @@ type Props = {
     axisOrigin?: [number | undefined, number | undefined];
     /** Nudge an edge-pinned axis outward by N px (Q1 only). Also via `spec.axisOffset`. */
     axisOffset?: number;
+    /** Fix the x domain instead of inferring it from the data — e.g. `[0, 1]` for a metric
+     *  plane defined by theory, not by where the rows fall. Also via `spec.xDomain`. */
+    xDomain?: unknown[];
+    /** Fix the y domain. Also via `spec.yDomain`. */
+    yDomain?: unknown[];
     /** Animate marks on data/flip changes (opt-out for e.g. AnimatedPlot, which
      *  tweens its own frames). Enabled one frame after the width settles so the
      *  initial layout paints un-animated. Default `true`. */
     animate?: boolean;
     children?: Snippet;
 };
-declare const Plot: import("svelte").Component<Props, {}, "selected">;
+declare const Plot: Component<Props, {}, "selected">;
 type Plot = ReturnType<typeof Plot>;
 export default Plot;

package/dist/PlotState.svelte.d.ts

@@ -1,73 +1,41 @@
+/**
+ * The state a `PlotChart` publishes on the `'plot-state'` context — a COMPOSITION of job
+ * classes (`./state/`), each owning one concern and reading only the ones built before it:
+ *
+ *   config → geoms → frame → channels → orientation → interaction → scales → aesthetics → axes
+ *
+ * It derives nothing itself. Everything below the constructor is the contract geoms, axes, the
+ * legend and the tooltip read (`GEOM_CONTRACT` in SparkState.svelte.js is the geom-facing part),
+ * kept as one-line delegations so no consumer changed when the monolith was taken apart. New
+ * code can depend on a job directly — `plotState.scales`, `plotState.interactionState` — instead.
+ */
 export class PlotState {
     constructor(config?: {});
-    axisOrigin: undefined[];
-    orientation: string;
-    colorScaleType: any;
-    continuousColorScale: {
-        scale: (v: number) => string;
-        domain: [number, number];
-        type: "sequential";
-    } | {
-        scale: (v: number) => string;
-        domain: [number, number, number];
-        type: "diverging";
-    } | null;
-    xScale: any;
-    yScale: any;
-    colors: Map<unknown, {
-        fill: string;
-        stroke: string;
-    }>;
-    patterns: Map<unknown, string> | SvelteMap<any, any>;
-    symbols: Map<unknown, string> | SvelteMap<any, any>;
-    colorField: any;
-    fillField: any;
-    patternField: any;
-    symbolField: any;
-    geomTypes: SvelteSet<any>;
-    xAxisY: any;
-    yAxisX: any;
+    /** The plot's inputs — the only thing `update()` writes. */
+    config: PlotConfig;
+    /** The mounted geoms and the rows each draws. */
+    geoms: GeomRegistry;
+    /** The drawing area: size less margin. */
+    frame: PlotFrame;
+    /** Which field feeds each aesthetic. Suffixed: `channels` is the contract's raw map. */
+    channelState: ChannelState;
+    /** Which way the chart reads. Suffixed: `orientation` is the contract's string. */
+    orientationState: OrientationState;
+    /** Hover, selection, zoom. */
+    interactionState: InteractionState;
+    /** The x / y position scales. */
+    scales: ScaleState;
+    /** Palette, patterns, symbols, continuous colour. */
+    aesthetics: AestheticState;
+    /** Where the axes cross. */
+    axes: AxisState;
+    /** Re-apply inputs. Which omitted fields keep and which reset: `CONFIG_FIELDS`. */
     update(config: any): void;
-    registerGeom(config: any): string;
-    updateGeom(id: any, config: any): void;
-    unregisterGeom(id: any): void;
-    geomData(id: any): any[];
-    label(field: any): any;
-    format(field: any): any;
-    tooltip(): any;
-    geomComponent(type: any): any;
-    preset(): {
-        colors: any;
-        patterns: any;
-        symbols: any;
-    };
-    get data(): any[];
-    /** @returns {{ x?: string, y?: string, color?: string, fill?: string, pattern?: string, symbol?: string }} */
-    get channels(): {
-        x?: string;
-        y?: string;
-        color?: string;
-        fill?: string;
-        pattern?: string;
-        symbol?: string;
-    };
-    get isFlipped(): boolean;
-    get continuousCategory(): boolean;
-    place(u: any, v: any): {
-        x: any;
-        y: any;
-    };
-    get bandScale(): any;
-    get valueScale(): any;
-    get margin(): {
-        top: number;
-        right: number;
-        bottom: number;
-        left: number;
-    };
-    get innerWidth(): number;
-    get innerHeight(): number;
-    get mode(): string;
+    /** The rows — the same objects every identity geom is handed, so `indexOf(row)` works. */
+    get data(): import("./state/PlotConfig.svelte.js").Row[];
+    /** The caller's channel map, unmerged. `channelState.effective` is the merged one. */
+    get channels(): import("./state/PlotConfig.svelte.js").Channels;
+    get mode(): "light" | "dark";
     get chartPreset(): {
         colors: string[];
         shades: {
@@ -95,15 +63,85 @@ export class PlotState {
             ribbon: number;
             waterfall: number;
             rule: number;
+            hull: number;
+            contour: number;
             radar: number;
         };
         patterns: string[];
         symbols: string[];
     };
+    /** A continuous category axis (a bar race's tweened rank) rather than a band. */
+    get continuousCategory(): boolean;
+    set axisOrigin(value: [number | undefined, number | undefined]);
+    /** Pin the axis crossing directly — also reachable through `update({ axisOrigin })`. */
+    get axisOrigin(): [number | undefined, number | undefined];
+    label(field: any): string;
+    format(field: any): any;
+    tooltip(): any;
+    geomComponent(type: any): any;
+    preset(): {
+        colors: any;
+        patterns: any;
+        symbols: any;
+    };
+    registerGeom(config: any): string;
+    updateGeom(id: any, config: any): void;
+    unregisterGeom(id: any): void;
+    geomData(id: any): Object[];
+    /** The legend picks a swatch style from these. */
+    get geomTypes(): import("svelte/reactivity").SvelteSet<any>;
+    get margin(): Readonly<{
+        top: 20;
+        right: 20;
+        bottom: 40;
+        left: 50;
+    }> | import("./state/PlotConfig.svelte.js").Margin;
+    get innerWidth(): number;
+    get innerHeight(): number;
+    /** Null for a literal CSS colour — it maps to no field. */
+    get colorField(): any;
+    get fillField(): any;
+    get patternField(): any;
+    get symbolField(): any;
+    get orientation(): string;
+    /** Rendered horizontally: the band axis stands up the screen. Channels are unchanged. */
+    get isFlipped(): boolean;
+    /** Channel space to screen: `const { x, y } = plotState.place(xScale(d[x]), yScale(d[y]))`. */
+    place(u: any, v: any): {
+        x: any;
+        y: any;
+    };
+    get xScale(): any;
+    get yScale(): any;
+    /** The categorical scale, whichever screen axis it is on. */
+    get bandScale(): any;
+    /** The value scale, whichever screen axis it is on. */
+    get valueScale(): any;
+    get colors(): Map<unknown, {
+        fill: string;
+        stroke: string;
+    }> | Map<null, {
+        fill: any;
+        stroke: any;
+    }>;
+    get patterns(): Map<unknown, string> | import("svelte/reactivity").SvelteMap<any, any>;
+    get symbols(): Map<unknown, string> | import("svelte/reactivity").SvelteMap<any, any>;
+    get colorScaleType(): any;
+    get continuousColorScale(): {
+        scale: (v: number) => string;
+        domain: [number, number];
+        type: "sequential";
+    } | {
+        scale: (v: number) => string;
+        domain: [number, number, number];
+        type: "diverging";
+    } | null;
+    get xAxisY(): any;
+    get yAxisX(): any;
     get hovered(): null;
     get interactive(): boolean;
     get selectedRows(): any[];
-    setHovered(data: any): void;
+    setHovered(row: any): void;
     clearHovered(): void;
     isSelected(row: any): boolean;
     setSelected(rows: any): void;
@@ -111,7 +149,13 @@ export class PlotState {
     handleSelect(detail: any): void;
     applyZoom(transform: any): void;
     resetZoom(): void;
-    #private;
 }
-import { SvelteMap } from 'svelte/reactivity';
-import { SvelteSet } from 'svelte/reactivity';
+import { PlotConfig } from './state/PlotConfig.svelte.js';
+import { GeomRegistry } from './state/GeomRegistry.svelte.js';
+import { PlotFrame } from './state/PlotFrame.svelte.js';
+import { ChannelState } from './state/ChannelState.svelte.js';
+import { OrientationState } from './state/OrientationState.svelte.js';
+import { InteractionState } from './state/InteractionState.svelte.js';
+import { ScaleState } from './state/ScaleState.svelte.js';
+import { AestheticState } from './state/AestheticState.svelte.js';
+import { AxisState } from './state/AxisState.svelte.js';