@fundar/data-chart-telling 1.19.0 → 1.20.0

package/dist/plots/map/geo/Plot.svelte

@@ -3,7 +3,8 @@
 	import AbstractPlot from '../../../layout/plot/AbstractPlot.svelte';
 	import { merge } from '../../../utils/merge';
 	import { buildGeoDefaults } from './defaults';
-	import { buildGeoSlicing } from './slices';
+	import { buildGeoSlicing, GeoSlices } from './slices';
+	import { Slice } from '../../../layout/plot/Slice';
 	import { GeoFeatures } from './GeoFeatures.svelte';
 	import type { GeoPlotProps, GeoPlotCoreProps } from '../../../types/plots/map/geo/props';
 	import type { GeoFeature } from '../../../types/plots/data/geo';
@@ -19,9 +20,11 @@
 	 * Optional chrome (`title`, `subtitle`, `caption`, `header`, `footer`,
 	 * `legend`) frames it. `timeline` and `facet` slice its features and its
 	 * markers' own rows by a field (a feature's from its `properties`); what
-	 * lacks the field draws in every slice, and the color ramp spans every
-	 * slice. With `coordinates.projection.domain: 'data'`, each facet zooms to
-	 * its own features.
+	 * lacks the field draws in every slice, the color ramp spans every
+	 * slice, and the panels may come from `facet.values` alone (or `rowValues`, `colValues`,
+	 * `timeline.values`), one layer of features serving them all. The callbacks that read a
+	 * feature get the slice as their last argument (`GeoSliceContext`). With
+	 * `coordinates.projection.domain: 'data'`, each facet zooms to its own features.
 	 */
 	let {
 		title,
@@ -54,13 +57,29 @@
 		buildGeoSlicing({ rows: [...features, ...markerRows], timeline, facet })
 	);
 
-	/** The color ramp's domain over every feature, so each slice colors on the same scale. */
+	/**
+	 * The color ramp's domain over every feature as each slice reads it - a facet panel, a timeline step, each
+	 * with its own context - so every slice colors on the same scale. Not under `scales: 'free'` (the
+	 * facet's, or the timeline's when there is no facet): each slice then fits its own.
+	 */
 	const sharedColor = $derived.by((): GeoScalesConfig | undefined => {
 		const value = core.color;
 		if (!value) return undefined;
-		const values = (resolved.features as GeoFeature<TProps>[])
-			.map((f) => value(f))
-			.filter((v): v is number => typeof v === 'number' && Number.isFinite(v));
+		if ((facet ? facet.scales : timeline?.scales) === 'free') return undefined;
+		const all = resolved.features as GeoFeature<TProps>[];
+		const whole = new Slice({
+			rows: features,
+			timeline: slicing.timeline,
+			facet: slicing.facet,
+			filterMode: undefined
+		});
+		const reads = slicing.slices.length
+			? slicing.slices.flatMap(({ place, context }) => {
+					const keep = whole.keep(place) as unknown as (f: GeoFeature<TProps>) => boolean;
+					return all.filter(keep).map((f) => value(f, context));
+				})
+			: all.map((f) => value(f, {}));
+		const values = reads.filter((v): v is number => typeof v === 'number' && Number.isFinite(v));
 		return values.length
 			? { color: { domain: [Math.min(...values), Math.max(...values)] } }
 			: undefined;
@@ -69,8 +88,16 @@
 	/** The core's props for one slice: the features and marker rows it keeps. */
 	function sliceProps(slice: PlotCellContext<Row>): GeoPlotCoreProps<TProps> {
 		const tip = slice.tooltip as TooltipConfig<GeoFeature<TProps>> | undefined;
+		const sliceContext = GeoSlices.contextOf(slice);
 		if (!sliced)
-			return { ...core, width: slice.width, height: slice.height, margins, tooltip: tip };
+			return {
+				...core,
+				width: slice.width,
+				height: slice.height,
+				margins,
+				tooltip: tip,
+				sliceContext
+			};
 		return {
 			...core,
 			data: features.filter(slice.keep) as unknown as GeoFeature<TProps>[],
@@ -82,7 +109,8 @@
 			height: slice.height,
 			margins: slice.margins ?? margins,
 			scales: merge(sharedColor, core.scales),
-			tooltip: tip
+			tooltip: tip,
+			sliceContext
 		} as GeoPlotCoreProps<TProps>;
 	}
 </script>

package/dist/plots/map/geo/phases/data.d.ts

@@ -1,6 +1,7 @@
 import type { GeoPlotState } from '../../../../types/plots/map/geo/state';
 /**
  * GeoPlot's "data" phase: every feature tagged with its resolved id/centroid,
- * then reduced by `excludeParts`. Reads no env.
+ * then reduced by `excludeParts`. Each carries the slice it is drawn in as its
+ * row context. Reads no env.
  */
 export declare function buildData<TProps extends Record<string, unknown>>(state: GeoPlotState<TProps>): GeoPlotState<TProps>;

package/dist/plots/map/geo/phases/data.js

@@ -1,12 +1,14 @@
 import { resolveAccessor } from '../../../../utils/accessors';
 import { GeoGeometry } from '../GeoGeometry';
 import { GeoFeatures } from '../GeoFeatures.svelte';
+import { ROW_CONTEXT_KEY } from '../../../../phases/context/rowContextKey';
 /**
  * GeoPlot's "data" phase: every feature tagged with its resolved id/centroid,
- * then reduced by `excludeParts`. Reads no env.
+ * then reduced by `excludeParts`. Each carries the slice it is drawn in as its
+ * row context. Reads no env.
  */
 export function buildData(state) {
-    const { rawFeatures, featureId, excludeParts } = state;
+    const { rawFeatures, featureId, excludeParts, slice = {} } = state;
     const getFeatureId = featureId
         ? resolveAccessor(featureId)
         : GeoFeatures.defaultId;
@@ -23,5 +25,9 @@ export function buildData(state) {
             const [cx, cy] = GeoGeometry.centroid(geometry);
             return [{ ...f, geometry, __cx: cx, __cy: cy }];
         });
+    // Kept as the row's context, which a copy of the feature carries along: a tooltip's `format` reads it back.
+    for (const f of new Set([...allFeatures, ...features])) {
+        f[ROW_CONTEXT_KEY] = slice;
+    }
     return { ...state, allFeatures, features };
 }

package/dist/plots/map/geo/phases/scales.js

@@ -61,7 +61,9 @@ export function buildScales(state, env) {
             return colorScale ? colorScale(v) : undefined;
         }
         : undefined;
-    // Every segment ramp is built up front, so the legend can draw each one.
+    // Every segment ramp is built up front, so the legend can draw each one. The plot's own ramp is left out of
+    // the legend when every colored feature has one of its own: nothing is drawn with it.
+    let usesPlotRamp = false;
     if (colorScale) {
         for (const f of features) {
             const featureId = f.__id ?? '';
@@ -69,6 +71,8 @@ export function buildScales(state, env) {
             const segScales = GeoSegments.scales(segments, featureId, groupingValue);
             if (segScales?.color)
                 segmentColorScaleFor(groupingValue ?? featureId, segScales);
+            else if (color?.(f) != null)
+                usesPlotRamp = true;
         }
     }
     // Plot-level only - no segment-scoped opacity ramp (unlike `resolveColor`
@@ -90,7 +94,7 @@ export function buildScales(state, env) {
         : undefined;
     return {
         ...state,
-        colorDomain: valueDomain ?? undefined,
+        colorDomain: (usesPlotRamp || !colorRamps.length ? valueDomain : undefined) ?? undefined,
         colorRamps: colorRamps.length ? colorRamps : undefined,
         opacityDomain: opacityDomain && typeof opacityDomain[0] === 'number'
             ? opacityDomain

package/dist/plots/map/geo/slices.d.ts

@@ -1,10 +1,22 @@
 import type { FacetConfig } from '../../../types/layout/facet';
-import type { TimelineConfig } from '../../../types/layout/timeline';
+import type { TimelineConfig, TimeValue } from '../../../types/layout/timeline';
+import type { SlicePlace } from '../../../types/layout/plot';
+import type { GeoSliceContext } from '../../../types/plots/data/geo';
 type Row = Record<string, unknown>;
+/** One slice of a sliced map: where it sits, and the context its features are read in. */
+export type GeoSlice = {
+    place: SlicePlace;
+    context: GeoSliceContext;
+};
 /**
  * What a GeoPlot hands `Plot` to slice by: one stand-in row per value
- * combination found in the features and markers' rows, and timeline/facet
- * accessors that read a stand-in or a real row.
+ * combination, and timeline/facet accessors that read a stand-in or a real
+ * row. A dimension's values are the ones the timeline or facet names
+ * (`timeline.values`, `facet.values`, `rowValues`, `colValues`), in
+ * their order, then any more found in the features and markers' rows - so
+ * the slices exist even when no feature carries the field. Each combination
+ * is also returned as a `slices` entry: its place and the context its
+ * features are read in.
  */
 export declare function buildGeoSlicing(args: {
     rows: Row[];
@@ -12,7 +24,19 @@ export declare function buildGeoSlicing(args: {
     facet?: FacetConfig<Row>;
 }): {
     rows: Row[];
+    slices: GeoSlice[];
     timeline?: TimelineConfig<Row>;
     facet?: FacetConfig<Row>;
 };
+export declare const GeoSlices: {
+    /** The context a callback reads a feature in, for the slice at `place`: empty when there is none. */
+    contextOf(place: {
+        time?: TimeValue;
+        facet?: {
+            facetValue: string;
+            row?: string;
+            col?: string;
+        };
+    }): GeoSliceContext;
+};
 export {};

package/dist/plots/map/geo/slices.js

@@ -12,8 +12,13 @@ function readField(field, row) {
 }
 /**
  * What a GeoPlot hands `Plot` to slice by: one stand-in row per value
- * combination found in the features and markers' rows, and timeline/facet
- * accessors that read a stand-in or a real row.
+ * combination, and timeline/facet accessors that read a stand-in or a real
+ * row. A dimension's values are the ones the timeline or facet names
+ * (`timeline.values`, `facet.values`, `rowValues`, `colValues`), in
+ * their order, then any more found in the features and markers' rows - so
+ * the slices exist even when no feature carries the field. Each combination
+ * is also returned as a `slices` entry: its place and the context its
+ * features are read in.
  */
 export function buildGeoSlicing(args) {
     const { rows, timeline, facet } = args;
@@ -31,17 +36,47 @@ export function buildGeoSlicing(args) {
     const reader = (dimension) => (row) => SLICE in row
         ? row[SLICE][dimension]
         : readField(fields[dimension], row);
+    /** The values the timeline or facet names for a dimension, ahead of the ones found. */
+    const named = {
+        time: timeline?.values,
+        by: facet && isFacetWrap(facet) ? facet.values : undefined,
+        rows: facet && !isFacetWrap(facet) ? facet.rowValues : undefined,
+        cols: facet && !isFacetWrap(facet) ? facet.colValues : undefined
+    };
+    const time = new TimelineTime(timeline?.dateFormat);
     let combos = [{}];
     for (const dimension of Object.keys(fields)) {
         const read = rows.map((row) => readField(fields[dimension], row)).filter((v) => v != null);
         // Dates on the same step are one value.
-        const time = new TimelineTime(timeline?.dateFormat);
-        const keyOf = (value) => dimension === 'time' ? String(time.toTime(value) ?? value) : value;
-        const values = [...new Map(read.map((value) => [keyOf(value), value])).values()];
+        const keyOf = (value) => dimension === 'time' ? String(time.toTime(value) ?? value) : String(value);
+        const values = [
+            ...new Map([...(named[dimension] ?? []), ...read].map((value) => [keyOf(value), value])).values()
+        ];
         combos = combos.flatMap((combo) => values.map((value) => ({ ...combo, [dimension]: value })));
     }
+    const slices = combos.map((combo) => {
+        const tick = combo.time === undefined ? undefined : time.toTime(combo.time);
+        const by = combo.by === undefined ? undefined : String(combo.by);
+        const row = combo.rows === undefined ? undefined : String(combo.rows);
+        const col = combo.cols === undefined ? undefined : String(combo.cols);
+        const value = by ?? (row !== undefined && col !== undefined ? `${row} · ${col}` : (row ?? col));
+        const place = {
+            ...(tick === undefined ? {} : { time: tick }),
+            ...(value === undefined
+                ? {}
+                : {
+                    facet: {
+                        facetValue: value,
+                        ...(row === undefined ? {} : { row }),
+                        ...(col === undefined ? {} : { col })
+                    }
+                })
+        };
+        return { place, context: GeoSlices.contextOf(place) };
+    });
     return {
         rows: combos.map((combo) => ({ [SLICE]: combo })),
+        slices,
         timeline: timeline && {
             ...timeline,
             accessor: reader('time'),
@@ -57,3 +92,21 @@ export function buildGeoSlicing(args) {
                 })
     };
 }
+export const GeoSlices = {
+    /** The context a callback reads a feature in, for the slice at `place`: empty when there is none. */
+    contextOf(place) {
+        const { time, facet } = place;
+        return {
+            ...(facet
+                ? {
+                    facet: {
+                        value: facet.facetValue,
+                        ...(facet.row === undefined ? {} : { row: facet.row }),
+                        ...(facet.col === undefined ? {} : { col: facet.col })
+                    }
+                }
+                : {}),
+            ...(time === undefined ? {} : { time })
+        };
+    }
+};

package/dist/plots/ranking/bar/markers.js

@@ -57,11 +57,11 @@ hover, env) {
             data: [row],
             category: categoryOf(row),
             hover: hover.active && 'trigger',
-            ...(slice
+            styles: (slice
                 ? isHorizontal
                     ? { insetTop: slice.start, insetBottom: slice.end }
                     : { insetLeft: slice.start, insetRight: slice.end }
-                : {})
+                : undefined)
         };
     });
 }

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

@@ -31,6 +31,8 @@ export type PlotCellContext<TRow extends Record<string, unknown>, TScales extend
     panel?: object;
     /** Where this slice sits among the facet panels - `undefined` when the plot has no facet. */
     facet?: NonNullable<SlicePlace['facet']>;
+    /** The timeline step this slice shows - `undefined` when the plot has no timeline. */
+    time?: TimeValue;
     /** Whether any row - the plot's own or a marker's - belongs in this slice; rows without a slicing field belong in all. */
     keep: (row: TRow) => boolean;
 };

package/dist/types/layout/styles/geo.d.ts

@@ -1,4 +1,4 @@
-import type { GeoFeature } from '../../plots/data/geo';
+import type { GeoFeature, GeoSliceContext } from '../../plots/data/geo';
 import type { FrameProp } from './frame';
 import type { BasePlotStylesConfig } from './base';
 export type GeoTileLayerConfig = {
@@ -26,8 +26,8 @@ export type GeoStylesConfig<TProps extends Record<string, unknown> = Record<stri
     strokeWidth?: number;
     /** Raster XYZ tile basemap under the vector geometry. Mercator-family projections only. */
     tileLayer?: GeoTileLayerConfig;
-    /** Fired when a base-map feature is clicked. */
-    onFeatureClick?: (feature: GeoFeature<TProps>, event: Event) => void;
+    /** Fired when a base-map feature is clicked, with the slice it was drawn in. */
+    onFeatureClick?: (feature: GeoFeature<TProps>, event: Event, slice: GeoSliceContext) => void;
 };
 /**
  * `GeoTileLayerConfig`, plus `features` - never author-facing (the public

package/dist/types/plots/data/geo.d.ts

@@ -1,4 +1,4 @@
-import type { Accessor } from './common';
+import type { TimeValue } from '../../layout/timeline';
 /**
  * One GeoJSON feature, generically typed over its `properties`. Intersected
  * with `Record<string, unknown>` so it satisfies the same generic bound
@@ -7,6 +7,20 @@ import type { Accessor } from './common';
  * index signature on its own.
  */
 export type GeoFeature<TProps extends Record<string, unknown> = Record<string, unknown>> = GeoJSON.Feature<GeoJSON.Geometry, TProps> & Record<string, unknown>;
+/**
+ * Which slice of a `timeline` and `facet` a feature is being read for: the callbacks of a sliced map get it as
+ * their last argument. Empty on a map without either.
+ */
+export type GeoSliceContext = {
+    /** The facet panel: its label (a grid's `row · col`), and the `rows` and `cols` values it sits at. */
+    facet?: {
+        value: string;
+        row?: string;
+        col?: string;
+    };
+    /** The timeline step. */
+    time?: TimeValue;
+};
 export type GeoJsonInput<TProps extends Record<string, unknown>> = GeoJSON.FeatureCollection<GeoJSON.Geometry, TProps> | GeoFeature<TProps>[];
 /**
  * Minimal structural shape of a TopoJSON `Topology` object. Deliberately not
@@ -46,14 +60,14 @@ export type GeoDataProps<TProps extends Record<string, unknown> = Record<string,
      * (e.g. `segments.argentina`) and for hover/click identification. Defaults
      * to `feature.id ?? feature.properties?.id ?? feature.properties?.name`.
      */
-    featureId?: Accessor<GeoFeature<TProps>, string>;
+    featureId?: keyof GeoFeature<TProps> | ((feature: GeoFeature<TProps>, slice: GeoSliceContext) => string);
     /**
      * Optional continuous color-value accessor for choropleth coloring - the
      * channel driving the ramp (mirrors heatmap's `color`), configured via
      * `scales.color`. A feature with no `color` (or when omitted entirely)
      * falls back to `styles.fill`/`segments`.
      */
-    color?: (feature: GeoFeature<TProps>) => number | undefined;
+    color?: (feature: GeoFeature<TProps>, slice: GeoSliceContext) => number | undefined;
     /**
      * Optional structural grouping key - splits features into named buckets
      * for `segments` to address by name (e.g. `segments.global_south`),
@@ -64,9 +78,9 @@ export type GeoDataProps<TProps extends Record<string, unknown> = Record<string,
      * ungrouped. A feature whose `grouping` value has no matching `segments`
      * key simply falls through to `segments.default`/the plot-level ramp.
      */
-    grouping?: (feature: GeoFeature<TProps>) => string | undefined;
+    grouping?: (feature: GeoFeature<TProps>, slice: GeoSliceContext) => string | undefined;
     /** Continuous or categorical opacity-value accessor - configure the ramp via `scales.opacity`. */
-    opacity?: (feature: GeoFeature<TProps>) => number | undefined;
+    opacity?: (feature: GeoFeature<TProps>, slice: GeoSliceContext) => number | undefined;
     /**
      * Excludes matching parts of a feature's geometry from the map's own
      * rendering and hover/click matching - e.g. so a separate `inset` marker

package/dist/types/plots/map/geo/props.d.ts

@@ -1,6 +1,7 @@
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { GeoScalesConfig, CoordinatesConfig } from '../../../layout/coordinates';
-import type { GeoFeature, GeoDataProps } from '../../data/geo';
+import type { GeoFeature, GeoDataProps, GeoSliceContext } from '../../data/geo';
+import type { PlotRowContext } from '../../../layout/context';
 import type { GeoStylesConfig } from '../../../layout/styles';
 import type { GeoSegmentStyle } from '../../segments/common';
 import type { GeoMarkersConfig } from '../../../markers/geo';
@@ -14,10 +15,15 @@ type OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
  * marker's own `data` rows; a feature or row without the field is context,
  * drawn in every slice.
  */
-export type GeoPlotProps<TProps extends Record<string, unknown>> = OmitEach<BasePlotProps<GeoDataProps<TProps>, GeoFeature<TProps>, GeoStylesConfig<TProps>, GeoSegmentStyle, GeoMarkersConfig, GeoScalesConfig, CoordinatesConfig>, 'timeline' | 'facet'> & {
+export type GeoPlotProps<TProps extends Record<string, unknown>> = OmitEach<BasePlotProps<GeoDataProps<TProps>, GeoFeature<TProps>, GeoStylesConfig<TProps>, GeoSegmentStyle, GeoMarkersConfig, GeoScalesConfig, CoordinatesConfig, GeoTooltipContext>, 'timeline' | 'facet'> & {
     timeline?: TimelineConfig<Record<string, unknown>>;
     facet?: FacetConfig<Record<string, unknown>>;
 };
+/** What a tooltip's `format` knows of a hovered feature: the shared row context, and the slice it was drawn in. */
+export type GeoTooltipContext = PlotRowContext & GeoSliceContext;
 /** What `GeoPlot`'s core draws from. */
-export type GeoPlotCoreProps<TProps extends Record<string, unknown>> = PlotCoreProps<GeoDataProps<TProps>, GeoFeature<TProps>, GeoStylesConfig<TProps>, GeoSegmentStyle, GeoMarkersConfig, GeoScalesConfig, CoordinatesConfig>;
+export type GeoPlotCoreProps<TProps extends Record<string, unknown>> = PlotCoreProps<GeoDataProps<TProps>, GeoFeature<TProps>, GeoStylesConfig<TProps>, GeoSegmentStyle, GeoMarkersConfig, GeoScalesConfig, CoordinatesConfig> & {
+    /** The slice of the `timeline` and `facet` this core draws - what its callbacks read its features in. */
+    sliceContext?: GeoSliceContext;
+};
 export {};

package/dist/types/plots/map/geo/state.d.ts

@@ -1,5 +1,5 @@
 import type { Accessor } from '../../data/common';
-import type { GeoFeature } from '../../data/geo';
+import type { GeoFeature, GeoSliceContext } from '../../data/geo';
 import type { ColorScaleConfig } from '../../../layout/scales';
 import type { GeoScalesConfig } from '../../../layout/coordinates';
 import type { SegmentsConfig, MarginConfig, HoverConfig } from '../../props';
@@ -46,6 +46,8 @@ export type GeoPlotState<TProps extends Record<string, unknown>> = {
     }, feature: TaggedGeoFeature<TProps>) => boolean;
     segments: SegmentsConfig<GeoSegmentStyle>;
     scales: GeoScalesConfig;
+    /** The slice of the `timeline` and `facet` this core draws, kept on each of its features for a tooltip's `format` to read. */
+    slice?: GeoSliceContext;
     /** The plot's `tooltip`, which the "hover" phase reads. */
     tooltip?: TooltipProp<TaggedGeoFeature<TProps>>;
     /** The raw `markers` prop - GeoPlot interleaves it with the base map by draw order, not a plain append. */

package/dist/utils/ConfigEquality.d.ts

@@ -0,0 +1,11 @@
+/** Whether two configuration values hold the same, for a plot to tell a new configuration from one built again. */
+export declare class ConfigEquality {
+    #private;
+    /** How many levels of objects and arrays it looks into; a value nested deeper only matches as the same object. */
+    static readonly MAX_DEPTH = 6;
+    /**
+     * Whether `a` and `b` are the same value, or plain objects and arrays alike all the way down, dates of one
+     * time; anything else - a function, a class instance - only if it is the same object.
+     */
+    static same(a: unknown, b: unknown, depth?: number): boolean;
+}

package/dist/utils/ConfigEquality.js

@@ -0,0 +1,37 @@
+/** Whether two configuration values hold the same, for a plot to tell a new configuration from one built again. */
+export class ConfigEquality {
+    /** How many levels of objects and arrays it looks into; a value nested deeper only matches as the same object. */
+    static MAX_DEPTH = 6;
+    /**
+     * Whether `a` and `b` are the same value, or plain objects and arrays alike all the way down, dates of one
+     * time; anything else - a function, a class instance - only if it is the same object.
+     */
+    static same(a, b, depth = 0) {
+        if (Object.is(a, b))
+            return true;
+        if (depth >= ConfigEquality.MAX_DEPTH)
+            return false;
+        if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+            return false;
+        if (a instanceof Date || b instanceof Date) {
+            return a instanceof Date && b instanceof Date && +a === +b;
+        }
+        if (Array.isArray(a) || Array.isArray(b)) {
+            return (Array.isArray(a) &&
+                Array.isArray(b) &&
+                a.length === b.length &&
+                a.every((value, i) => ConfigEquality.same(value, b[i], depth + 1)));
+        }
+        if (!ConfigEquality.#isPlain(a) || !ConfigEquality.#isPlain(b))
+            return false;
+        const keys = Reflect.ownKeys(a);
+        if (keys.length !== Reflect.ownKeys(b).length)
+            return false;
+        return keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) &&
+            ConfigEquality.same(a[key], b[key], depth + 1));
+    }
+    static #isPlain(value) {
+        const proto = Object.getPrototypeOf(value);
+        return proto === Object.prototype || proto === null;
+    }
+}

package/docs/facets.md

@@ -168,3 +168,15 @@ Panels line up: each plot reports the margins it settled on, and once all have,
 ## Maps
 
 `GeoPlot` takes `facet` and reads the field from each feature's `properties` (and from each marker row); features without the field are drawn in every panel.
+
+The panels need not come from the features. `values` (or a grid's `rowValues` and `colValues`) name them, and they exist even when no feature carries the field: one layer of features serves every panel, with no copy of it per value. Each callback that reads a feature - `color`, `opacity`, `grouping`, `featureId`, `styles.onFeatureClick` - gets the slice it is drawn in as its last argument, `{ facet?: { value, row?, col? }, time? }`, and a tooltip's `format` finds the same `facet` and `time` in its context:
+
+```svelte
+<GeoPlot
+	data={provinces}
+	facet={{ by: 'sex', values: ['Women', 'Men'] }}
+	color={(f, { facet }) => valueFor(f.properties.name, facet?.value)}
+/>
+```
+
+The ramp spans every panel, each read in its own slice. See [Facets and timeline](geo.md#facets-and-timeline) on maps.

package/docs/geo.md

@@ -19,13 +19,13 @@
 
 ## Data
 
-| Prop           | Meaning                                                                                                                                                                                                      |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `data`         | A GeoJSON `FeatureCollection`, an array of `Feature`s, or a TopoJSON `Topology`                                                                                                                              |
-| `object`       | Required for a `Topology`: the key under `topology.objects` to draw. Needs the optional `topojson-client` package                                                                                            |
-| `featureId`    | Accessor for each feature's stable id. Default: `feature.id ?? properties.id ?? properties.name`. It is the key of `segments`, and identifies features in hover and click                                    |
-| `color`        | `(feature) => number \| undefined` - the value of a choropleth. Features without one use `styles.fill` or their `segments`                                                                                   |
-| `excludeParts` | `(part, feature) => boolean`, where `part` is `{ centroid, geometry }` - drops geometry parts from drawing and hover (a distant territory drawn in an inset instead). `segments` still apply to what remains |
+| Prop           | Meaning                                                                                                                                                                                                                |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`         | A GeoJSON `FeatureCollection`, an array of `Feature`s, or a TopoJSON `Topology`                                                                                                                                        |
+| `object`       | Required for a `Topology`: the key under `topology.objects` to draw. Needs the optional `topojson-client` package                                                                                                      |
+| `featureId`    | Accessor for each feature's stable id. Default: `feature.id ?? properties.id ?? properties.name`. It is the key of `segments`, and identifies features in hover and click                                              |
+| `color`        | `(feature, slice) => number \| undefined` - the value of a choropleth. Features without one use `styles.fill` or their `segments`. `slice` is the [facet panel and timeline step](#facets-and-timeline) it is drawn in |
+| `excludeParts` | `(part, feature) => boolean`, where `part` is `{ centroid, geometry }` - drops geometry parts from drawing and hover (a distant territory drawn in an inset instead). `segments` still apply to what remains           |
 
 ## Styles
 
@@ -146,6 +146,34 @@ An `inset` draws part of the map (or other data) in its own small panel, such as
 
 `location` is one of the 17 anchors (`'top-left'`, `'bottom-right'`, `'middle-left'`, ...); `features` filters by id from the plot's `data` (or give the inset its own `data`); `featurePartsFilter` narrows to geometry parts; `width` and `height` are fractions of the plot; an inset always fits its own content.
 
+## Facets and timeline
+
+`facet` and `timeline` slice the map by a field each feature carries in its `properties` (and each marker's own rows by the same field); what lacks the field is drawn in every slice. To draw one layer of features in every panel, with no field on them, name the panels instead: `facet.values` for `by`, `rowValues` and `colValues` for `rows` and `cols`, or `timeline.values` for the steps. A slice's values are the ones named, in that order, then any more found in the features.
+
+Every callback that reads a feature gets the slice it is drawn in as its last argument - `color`, `opacity`, `grouping`, `featureId` and `styles.onFeatureClick` - and a tooltip's `format` has it in its context:
+
+| Field         | Meaning                                                            |
+| ------------- | ------------------------------------------------------------------ |
+| `facet.value` | The panel: its `by` value, or a grid's `row · col`                 |
+| `facet.row`   | The panel's `rows` value, on a grid                                |
+| `facet.col`   | The panel's `cols` value, on a grid                                |
+| `time`        | The timeline step; the context is empty without `facet`/`timeline` |
+
+```svelte
+<GeoPlot
+	data={provinces}
+	facet={{ by: 'sex', values: ['Women', 'Men'] }}
+	color={(f, { facet }) => valueFor(f.properties.name, facet?.value)}
+	tooltip={{
+		sync: true,
+		format: (f, number, { facet }) => `${f.properties.name} · ${facet?.value}`
+	}}
+	coordinates={{ projection: { type: 'mercator', domain: 'data' } }}
+/>
+```
+
+The color ramp spans every panel and step, each read in its own slice, so colors compare across them; `facet.scales: 'free'` (or `timeline.scales`, with no facet) fits each slice's own instead, for panels that show different variables. To give each panel its own scheme too, return the panel from `grouping` and set `scales.color` in a `segments` entry per panel. With `projection.domain: 'data'`, each panel fits its own features. See also [Facets](facets.md#maps).
+
 ## Tooltip and hover
 
 `tooltip` works as on other plots with the hovered feature as the row (`format: (feature) => string`, or a `content` snippet). Add `{ type: 'geo-hover' }` for an in-map highlight. Hover matches the browser's own SVG hit-testing, so a feature is hovered where it is drawn.

package/docs/legend.md

@@ -86,6 +86,12 @@ A continuous section narrows with `interactive: { enabled: true, mode: 'filter'
 
 Series can be toggled from code too: `useFigure().legend` has `off`, `isOff(name)`, `toggle`, `turnOff`, `turnOn` (see [Reading plot state](state.md)).
 
+The range of a continuous section can be set from code as well: `useFigure().legend.setRange([min, max])` does what dragging the handles does - they move, and the plots filter or rescale to it, in the mode the section was set up with (a second argument, `'filter'` or `'rescale'`, overrides it). `setRange(null)`, or a span that covers the whole ramp, resets it; `legend.range` reads it back. A mini legend per panel can use it to apply its own panel's range to the figure's legend on a click.
+
+```svelte
+<button onclick={() => figure.legend?.setRange([panelMin, panelMax])}>Use this range</button>
+```
+
 ## Adjusting the automatic legend
 
 An object adjusts the automatic legend while keeping what the plots read:

package/docs/plots/ranking/bar.md

@@ -53,7 +53,7 @@ Bars where one axis holds the categories and the other the values. Categories on
 ![Horizontal grouped bars](../../images/horizontal-bars.png)
 
 - Several series sharing a category sit side by side, each in its slice of the category band. The gap between them is `bar.seriesPadding` in the configuration.
-- `transforms={[{ type: 'stackY' }]}` stacks the series instead. Stacking is always `stackY`, also for horizontal bars, because the value channel is the one stacked.
+- `transforms={[{ type: 'stackY' }]}` stacks the series instead of putting them side by side. The stack runs along the value axis: `stackY` for vertical bars (values on `y`), `stackX` for horizontal ones (values on `x`, categories on `y`). The other one turns the category axis into a numeric one and the bars come out empty.
 - `scales.x.paddingInner` / `paddingOuter` set the spacing between category bands.
 - `styles.values.show` labels each bar; `styles.values.anchor` places the label (`'outside'`, `'middle'`, `'top'`, `'bottom'`, `'left'`, `'right'`, a corner such as `'top-left'`, or `'tip'` and `'base'`, the ends of the bar away from zero and on it).
 - The tooltip triggers anywhere over a bar's whole band, not just over the visible bar.

package/docs/state.md

@@ -7,7 +7,7 @@ A plot's state - its hover, legend, timeline, margins, scales, rows and size - c
 Works anywhere inside a figure, including the `header`, `footer` and `content` snippets of a plot or composer. It returns:
 
 - `hover` - `activeX`, `activeY`, `activeSeries`, `strategy`, `sync`, `source` (the id of the plot owning the hover).
-- `legend` (or `null`) - `entries`, `range`, `off` (names of hidden series), `isOff(name)`, `turnOff(name, action)`, `turnOn(name)`, `toggle(name, action)`. `action` is `{ mode: 'dim' | 'hide' | 'omit' | 'rescale' }`; `'omit'` removes the series and refits the axes, and `'rescale'` also makes the parts left of a whole (a stack, a treemap) the new 100%.
+- `legend` (or `null`) - `entries`, `range`, `setRange([min, max] | null, mode?)` (narrows the continuous section as dragging it would, or resets it), `off` (names of hidden series), `isOff(name)`, `turnOff(name, action)`, `turnOn(name)`, `toggle(name, action)`. `action` is `{ mode: 'dim' | 'hide' | 'omit' | 'rescale' }`; `'omit'` removes the series and refits the axes, and `'rescale'` also makes the parts left of a whole (a stack, a treemap) the new 100%.
 - `timeline` (or `null`) - `enabled`, `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, `controls`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`. On a timeline of dates, `steps` and `value` are `Date`s and `seekValue` takes a `Date` or a date string.
 
 A footer that toggles series through the legend:

package/docs/timeline.md

@@ -43,7 +43,7 @@
 | `values`                           | The steps, when not every distinct value of `accessor` - read like `accessor`'s values                                                                                                                                                                                          |
 | `filterMode`                       | `'exact'` shows the rows of the current step; `'upTo'` shows every row up to it (a cumulative reveal). `LinePlot` defaults to `'upTo'`                                                                                                                                          |
 | `interpolate`                      | Tween values between steps so a scrub is smooth: `true`, or `{ key, value, create, progressEasing, segmentEasing }`. Line and bar plots default to interpolating their value channel                                                                                            |
-| `scales`                           | `'shared'` (default): axes span every step, so they hold still while scrubbing; `'free'` refits both to each step; `'free-x'` / `'free-y'` refit one and keep the other still                                                                                                   |
+| `scales`                           | `'shared'` (default): axes span every step (the widest any step reaches on its own rows), so they hold still while scrubbing; `'free'` refits both to each step; `'free-x'` / `'free-y'` refit one and keep the other still                                                     |
 | `onprogress`, `onvalue`            | Called with the new position (`0`-`1`) and with the step it lands on - a `Date` on a timeline of dates, else the number                                                                                                                                                         |
 | `orientation`, `show`, `thickness` | A rule's direction (`'vertical'` default, beside the plot; `'horizontal'`), visibility and size                                                                                                                                                                                 |
 

package/docs/transforms-and-statistics.md

@@ -72,7 +72,7 @@ Both derive rows from the data before drawing. A **transform** reshapes the rows
 | Filter    | `filter`                                                                                      | Keep rows a test holds for                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Select    | `select`, `selectFirst`, `selectLast`, `selectMinX`, `selectMaxX`, `selectMinY`, `selectMaxY` | Keep one row per group, such as each series' last point or peak                                                                                                                                                                                                                                                                                                                                                                                                                |
 
-Bar stacking is always `stackY`, also for horizontal bars. A transform on a `HistogramPlot` is merged over the plot's default binning, so `{ type: 'binX', thresholds: 20 }` changes the bins and the rest stays.
+A bar plot stacks along its value axis: `stackY` for vertical bars, `stackX` for horizontal ones. A transform on a `HistogramPlot` is merged over the plot's default binning, so `{ type: 'binX', thresholds: 20 }` changes the bins and the rest stays.
 
 ## Statistics