@fundar/data-chart-telling 1.2.0 → 1.3.0

package/dist/markers/delta/DeltaPoint.svelte

@@ -0,0 +1,97 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import { Line } from 'svelteplot';
+	import DotMarker from '../dot/DotMarker.svelte';
+	import TextMarker from '../text/TextMarker.svelte';
+	import { Delta } from './Delta';
+	import { getConfiguration } from '../../configuration/config.svelte';
+	import type { Series } from '../../types/plots/data/common';
+	import type { DeltaPointConfig } from '../../types/markers/axis/delta';
+
+	/** One delta, at the one position `marker.at` names. See {@link DeltaMarker} for a list of them. */
+	let { marker, data = [] }: { marker: DeltaPointConfig; data?: Series<TData>[] } = $props();
+
+	const resolved = $derived(Delta.build(marker.axis, data, marker));
+	const label = $derived(getConfiguration().delta.text[marker.axis]);
+	const lineAnchor = $derived(marker.text?.lineAnchor ?? label.lineAnchor);
+
+	const clampRange = $derived.by((): [number, number] | undefined => {
+		const domain = marker.axis === 'x' ? marker.yDomain : marker.xDomain;
+		if (!domain || domain.length < 2) return undefined;
+		const lo = Number(domain[0]);
+		const hi = Number(domain[domain.length - 1]);
+		return isNaN(lo) || isNaN(hi) ? undefined : [Math.min(lo, hi), Math.max(lo, hi)];
+	});
+
+	function clamp(v: number): number {
+		return clampRange ? Math.max(clampRange[0], Math.min(clampRange[1], v)) : v;
+	}
+
+	function pt(fixed: number, varying: number) {
+		return marker.axis === 'x' ? { x: fixed, y: varying } : { x: varying, y: fixed };
+	}
+
+	function textVaryCoord(fromVis: number, toVis: number) {
+		return lineAnchor === 'top'
+			? Math.max(fromVis, toVis)
+			: lineAnchor === 'bottom'
+				? Math.min(fromVis, toVis)
+				: (fromVis + toVis) / 2;
+	}
+
+	// Pre-derive all coordinates as script-level signals so prop getters read safe
+	// values during Svelte 5 teardown, before the {#if} guard finishes unmounting.
+	const coords = $derived.by(() => {
+		if (!resolved) return null;
+		const fromVis = clamp(resolved.from ?? 0);
+		const toVis = clamp(resolved.to ?? 0);
+		const at = resolved.at ?? 0;
+		return {
+			fromPt: pt(at, fromVis),
+			toPt: pt(at, toVis),
+			textPt: pt(at, textVaryCoord(fromVis, toVis)),
+			lineData: [pt(at, fromVis), pt(at, toVis)],
+			diff: resolved.diff ?? 0
+		};
+	});
+
+	const dotStyles = $derived({
+		dotRadius: 4,
+		dotFill: marker.line?.stroke,
+		dotStroke: marker.line?.stroke,
+		dotStrokeWidth: 2,
+		...marker.dot
+	});
+</script>
+
+{#if coords}
+	<Line
+		data={coords.lineData}
+		x={(p) => p.x}
+		y={(p) => p.y}
+		stroke={marker.line?.stroke ?? 'currentColor'}
+		strokeWidth={marker.line?.strokeWidth ?? 2}
+		strokeOpacity={marker.line?.strokeOpacity ?? 0.8}
+		strokeDasharray={marker.line?.strokeDasharray ?? '6 6'}
+		strokeLinecap={marker.line?.strokeLinecap ?? 'round'}
+	/>
+	<DotMarker marker={{ type: 'dot', x: coords.fromPt.x, y: coords.fromPt.y, styles: dotStyles }} />
+	<DotMarker marker={{ type: 'dot', x: coords.toPt.x, y: coords.toPt.y, styles: dotStyles }} />
+	<TextMarker
+		marker={{
+			type: 'text',
+			x: coords.textPt.x,
+			y: coords.textPt.y,
+			text: (marker.formatDiff ?? ((v: number) => v.toFixed(1)))(coords.diff),
+			styles: {
+				fontWeight: 'bold',
+				fontSize: 14,
+				textAnchor: label.textAnchor,
+				fill: marker.line?.stroke ?? 'currentColor',
+				...marker.text,
+				dx: marker.text?.dx ?? label.dx,
+				dy: marker.text?.dy ?? label.dy,
+				lineAnchor
+			}
+		}}
+	/>
+{/if}

package/dist/markers/delta/DeltaPoint.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { Series } from '../../types/plots/data/common';
+import type { DeltaPointConfig } from '../../types/markers/axis/delta';
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: {
+        marker: DeltaPointConfig;
+        data?: Series<TData>[];
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData extends Record<string, unknown>> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData extends Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const DeltaPoint: $$IsomorphicComponent;
+type DeltaPoint<TData extends Record<string, unknown>> = InstanceType<typeof DeltaPoint<TData>>;
+export default DeltaPoint;

package/dist/markers/rule/RuleMarker.svelte

@@ -6,7 +6,7 @@
 
 	/**
 	 * A single vertical (`axis: 'x'`) or horizontal (`axis: 'y'`) reference
-	 * line - or, with `data`, one line per row. Shared by author-configured
+	 * line - or, with `data`, one line per row, or, with a list as `value`, one per value. Shared by author-configured
 	 * `'rule'` markers and `HoverMarker`'s crosshair (which always calls it
 	 * with a literal `value` and no `data`). Falls back to `'currentColor'`/`1`
 	 * when the caller supplies no style. See `RuleMarkerConfig`'s own doc
@@ -21,7 +21,10 @@
 	const styles = $derived(marker.styles);
 
 	const RuleMark = $derived(axis === 'x' ? RuleX : RuleY);
-	const rows = $derived(data ?? [{ v: value }]);
+	/** Without `data`, one row per position: a list of values draws a line at each. */
+	const rows = $derived(
+		data ?? (Array.isArray(value) ? value : [value]).map((v) => ({ v: v as AxisValue }))
+	);
 	/**
 	 * With `data`, `value` is forwarded raw (a field key resolves per row via
 	 * svelteplot's own `resolve()`, same as every other mark, and lets its

package/dist/phases/facet/FacetPhase.d.ts

@@ -3,7 +3,8 @@ import type { FacetStageState, PhaseStage } from '../../types/phases';
  * The "facet" phase: the panels the plot's `facet` lays its rows out in, and
  * which panel each row belongs to. It runs first, so the "data" phase builds
  * every series already split by panel. A plot drawn from pre-built `series`
- * has no rows to split, so its facet is ignored.
+ * has no rows to split, so its facet is ignored. The plot's `segments` and markers that name a facet
+ * are handed to the panels they name here, once, for every later phase.
  */
 export declare class FacetPhase<TState extends FacetStageState> implements PhaseStage<TState> {
     readonly phase: "facet";

package/dist/phases/facet/FacetPhase.js

@@ -1,18 +1,26 @@
 import { buildFacetKeyOf, buildFacetPanels } from '../../layout/facet/config';
 import { PANEL_KEY } from './FacetPanels';
+import { FacetScope } from '../../layout/facet/scope';
 /**
  * The "facet" phase: the panels the plot's `facet` lays its rows out in, and
  * which panel each row belongs to. It runs first, so the "data" phase builds
  * every series already split by panel. A plot drawn from pre-built `series`
- * has no rows to split, so its facet is ignored.
+ * has no rows to split, so its facet is ignored. The plot's `segments` and markers that name a facet
+ * are handed to the panels they name here, once, for every later phase.
  */
 export class FacetPhase {
     phase = 'facet';
     run = (state) => {
         const { data, series } = state;
         const facet = state.facet;
-        if (!facet || series || !data)
-            return state;
+        // Without panels, a segment or a marker that names a facet has none to be drawn in.
+        if (!facet || series || !data) {
+            return {
+                ...state,
+                segments: FacetScope.scopeSegments(state.segments, undefined),
+                authorMarkers: FacetScope.scope(state.authorMarkers, undefined)
+            };
+        }
         const panels = buildFacetPanels(facet, data).map(({ rows: _rows, ...panel }) => panel);
         const keys = new Set(panels.map((p) => p.key));
         const keyOf = buildFacetKeyOf(facet);
@@ -23,6 +31,13 @@ export class FacetPhase {
             const key = keyOf(row);
             return keys.has(key) ? key : undefined;
         };
-        return { ...state, panels, panelOf };
+        // Every later phase reads each panel's own segments and markers: nothing past here knows of `facet`.
+        return {
+            ...state,
+            panels,
+            panelOf,
+            segments: FacetScope.distributeSegments(state.segments, panels),
+            authorMarkers: FacetScope.distributeMarkers(state.authorMarkers, panels)
+        };
     };
 }

package/dist/phases/statistics/StatisticsPhase.js

@@ -24,9 +24,17 @@ export class StatisticsPhase {
     run = (state) => {
         if (!state.panels)
             return { ...state, markers: this.#resolve(state) };
-        const markers = state.panels.flatMap((panel) => this.#resolve(FacetPanels.narrowToPanel(state, panel.key)).map((marker) => ({ ...marker, [PANEL_KEY]: panel.key })));
+        const markers = state.panels.flatMap((panel) => this.#resolve(this.#ownTo(FacetPanels.narrowToPanel(state, panel.key), panel.key)).map((marker) => ({ ...marker, [PANEL_KEY]: panel.key })));
         return { ...state, markers };
     };
+    /** `state` with the author's markers that the "facet" phase tagged for another panel left out. */
+    #ownTo(state, panel) {
+        const authorMarkers = state.authorMarkers?.filter((marker) => {
+            const tagged = marker[PANEL_KEY];
+            return tagged === undefined || tagged === panel;
+        });
+        return { ...state, authorMarkers };
+    }
     #resolve(state) {
         const options = this.#options;
         const { resolvedSeries = [], flat = [], colorForSeries, statistics, authorMarkers = [] } = state;

package/dist/plots/utils/segments.d.ts

@@ -8,8 +8,11 @@ import type { ScopedMarkerGroup } from '../../types/layout/geometry';
  * Returns the flat {@link Segment} list for one series.
  * Series-specific segments are added before `'default'` segments so that
  * series-specific catch-alls win over default catch-alls on tie-breaks.
+ * A series split by facet panel also reads the segments its panel was given
+ * for it - under its id - and for every series of the panel - under the
+ * panel's own `'default'` - ahead of the plot's own, as the more specific.
  */
-export declare function resolveSegmentsForSeries<TStyle>(segments: SegmentsConfig<TStyle>, seriesName: string): Segment<TStyle>[];
+export declare function resolveSegmentsForSeries<TStyle>(segments: SegmentsConfig<TStyle>, series: Pick<Series, 'name' | 'id' | 'panel'>): Segment<TStyle>[];
 /** Returns true when `xVal` falls inside any of a segment's x ranges. */
 export declare function matchesSegmentX<TStyle>(xVal: AxisValue, seg: Segment<TStyle>): boolean;
 /**

package/dist/plots/utils/segments.js

@@ -1,15 +1,28 @@
 import { resolveAccessor } from '../../utils/accessors';
 import { merge } from '../../utils/merge';
+import { seriesIdOf } from '../../utils/grouping';
+import { FacetPanels } from '../../phases/facet/FacetPanels';
 const DEFAULT_KEY = 'default';
 /**
  * Returns the flat {@link Segment} list for one series.
  * Series-specific segments are added before `'default'` segments so that
  * series-specific catch-alls win over default catch-alls on tie-breaks.
+ * A series split by facet panel also reads the segments its panel was given
+ * for it - under its id - and for every series of the panel - under the
+ * panel's own `'default'` - ahead of the plot's own, as the more specific.
  */
-export function resolveSegmentsForSeries(segments, seriesName) {
-    const specific = segments[seriesName] ?? [];
-    const defaults = segments[DEFAULT_KEY] ?? [];
-    return [...specific, ...defaults];
+export function resolveSegmentsForSeries(segments, series) {
+    const noPanel = series.panel === undefined;
+    const own = noPanel ? [] : (segments[seriesIdOf(series)] ?? []);
+    const panelDefaults = noPanel
+        ? []
+        : (segments[FacetPanels.buildSeriesId(series.panel, DEFAULT_KEY)] ?? []);
+    return [
+        ...own,
+        ...(segments[series.name] ?? []),
+        ...panelDefaults,
+        ...(segments[DEFAULT_KEY] ?? [])
+    ];
 }
 /** Returns true when `xVal` falls inside any of a segment's x ranges. */
 export function matchesSegmentX(xVal, seg) {
@@ -176,7 +189,7 @@ function readChannel(accessor) {
 export function buildGroupedSeries(seriesList, segments = {}, connect = true) {
     return seriesList.map((s) => ({
         series: s,
-        visualSegments: resolveSeriesSegments(s, resolveSegmentsForSeries(segments, s.name), connect)
+        visualSegments: resolveSeriesSegments(s, resolveSegmentsForSeries(segments, s), connect)
     }));
 }
 /**
@@ -193,7 +206,7 @@ export function buildScopedMarkerGroups(args) {
     return groupedSeries.map((group, seriesIndex) => {
         const defaultColor = colorFor(group.series, seriesIndex);
         const xFor = readChannel(group.series.x);
-        const segs = resolveSegmentsForSeries(segments, group.series.name);
+        const segs = resolveSegmentsForSeries(segments, group.series);
         return {
             name: group.series.name,
             ...(group.series.id !== undefined ? { id: group.series.id } : {}),

package/dist/types/configuration/styling.d.ts

@@ -1,6 +1,7 @@
 import type { StrokeStyle, DotStyle, FontStyle, AreaStyle } from '../plots/styling';
 import type { LineAnchor, SymbolType, TextAnchor } from '../plots/constants';
 import type { PlotChromeEntry } from '../plots/props';
+import type { LegendMark } from '../layout/legend';
 import type { EdgeTicksOptions } from '../layout/scales';
 import type { CurveName } from '../layout/styles/curve';
 export type TextStyle = {
@@ -133,6 +134,13 @@ export type PlotStylesConfig = {
         gap: string;
         /** swatch square size */
         swatchSize: string;
+        /** The icon a discrete legend item draws for its series. */
+        icon: {
+            /** Draws the icons with rounded corners. */
+            rounded: boolean;
+            /** The shape a series icon takes by how the series draws, unless the series sets its own `symbol`. */
+            marks: Record<LegendMark, SymbolType>;
+        };
         /** Fallback opacity for a legend-disabled series/value when a section doesn't set its own style. */
         disabledOpacity: number;
         /**

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

@@ -40,6 +40,24 @@ export type FacetCellContext<TRow extends Record<string, unknown>> = {
 export type FacetCellSnippet<TRow extends Record<string, unknown>> = Snippet<[
     FacetCellContext<TRow>
 ]>;
+/** A facet value as the panel's label reads it: a number or a boolean matches by the text it prints as. */
+export type FacetValue = string | number | boolean;
+/**
+ * The facet panels a segment or a marker applies to. A value, or a list of them, names panels by their
+ * label - the `by` value; in a `rows`/`cols` grid, `{ row, col }` name the panels by the grid's own
+ * values, and a side left out matches every value of it.
+ */
+export type FacetTarget = FacetValue | FacetValue[] | {
+    row?: FacetValue | FacetValue[];
+    col?: FacetValue | FacetValue[];
+};
+/**
+ * A segment or a marker that can be limited to some facet panels. Without `facet` it applies to every
+ * panel, as before; with it, only to the panels it names - and to none of a plot that has no facet.
+ */
+export type FacetScoped = {
+    facet?: FacetTarget;
+};
 export type FacetIndicatorContext = {
     current: number;
     total: number;

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

@@ -33,6 +33,8 @@ export type LegendItem = {
     name: string;
     label?: string;
     color?: string;
+    /** How the series draws; with no `symbol`, `legend.icon.marks` picks the icon from it. */
+    mark?: LegendMark;
     symbol?: SymbolType;
     /** Whether the symbol is filled, or drawn as an outline. Defaults to `true`. */
     filled?: boolean;

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

@@ -29,6 +29,8 @@ export type PlotCellContext<TRow extends Record<string, unknown>, TScales extend
     scales?: TScales;
     /** This slice's facet panel, as a {@link Pipeline.runData} over every panel resolved it. */
     panel?: object;
+    /** Where this slice sits among the facet panels - `undefined` when the plot has no facet. */
+    facet?: NonNullable<SlicePlace['facet']>;
     /** 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/markers/axis/delta.d.ts

@@ -19,9 +19,22 @@ export type DeltaConfig = {
     text?: FontStyle;
     dot?: DotStyle;
 };
-/** A delta annotation between two points on a line chart. */
-export type DeltaMarkerConfig = {
+/** One delta annotation, at one position, between two points on a line chart. */
+export type DeltaPointConfig = {
     type: 'delta';
     xDomain?: (number | string | Date)[];
     yDomain?: (number | string | Date)[];
 } & DeltaConfig;
+/** A style as it is, or as a function of the position the delta is drawn at. */
+export type PerPosition<T> = T | ((at: AxisValue) => T);
+/**
+ * A delta annotation between two points on a line chart. `at` can be a list of positions: one delta is
+ * drawn at each, with the same ends. `line`, `text` and `dot` can be functions of the position, to style
+ * each delta on its own - a label to the left of the last one, say, so it stays inside the plot.
+ */
+export type DeltaMarkerConfig = Omit<DeltaPointConfig, 'at' | 'line' | 'text' | 'dot'> & {
+    at: AxisValue | AxisValue[];
+    line?: PerPosition<StrokeStyle>;
+    text?: PerPosition<FontStyle>;
+    dot?: PerPosition<DotStyle>;
+};

package/dist/types/markers/axis/rule.d.ts

@@ -1,11 +1,18 @@
 import type { AxisValue } from '../../layout/mapping';
 import type { StrokeStyle } from '../../plots/styling';
 import type { CommonMarkerConfigWithInterval } from '../channels/commonMarkerConfigWithInterval';
-/** A vertical or horizontal reference line, or one line per row when `data` is given. */
+/**
+ * A vertical or horizontal reference line, one line per row when `data` is given, or one per value
+ * when `value` is a list - all with the same style.
+ */
 export type RuleMarkerConfig = {
     type: 'rule';
     axis: 'x' | 'y';
-    value: AxisValue | string | ((d: any) => AxisValue);
+    /**
+     * Where the line goes along `axis`. A list draws a line at each value (without `data`); with `data`,
+     * a field key or a function of the row gives each row's own.
+     */
+    value: AxisValue | string | (AxisValue | string)[] | ((d: any) => AxisValue);
     inset?: number;
     insetTop?: number;
     insetBottom?: number;

package/dist/types/phases/facet/phase.d.ts

@@ -15,4 +15,8 @@ export type FacetStageState = {
     panels?: FacetPanel[];
     /** The panel a row belongs to: its own panel tag, or its facet values. `undefined` for a row no panel shows. */
     panelOf?: (row: Record<string | symbol, unknown>) => string | undefined;
+    /** The plot's `segments`. The phase moves those that name a facet to the panels they name, or drops them without panels. */
+    segments?: Record<string, object[]>;
+    /** The plot's own markers. The phase tags those that name a facet with the panels they name, or drops them without panels. */
+    authorMarkers?: object[];
 };

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

@@ -3,7 +3,7 @@ import type { Snippet } from 'svelte';
 import type { TooltipOptions, TooltipProp } from '../layout/tooltip';
 import type { HoverPoint, HoverStrategy } from '../layout/hover';
 import type { LegendExtension, LegendSection } from '../layout/legend';
-import type { FacetConfig } from '../layout/facet';
+import type { FacetConfig, FacetScoped } from '../layout/facet';
 import type { GridPlacement } from '../layout/grid';
 import type { TimelineConfig } from '../layout/timeline';
 import type { Segment } from './segments/config';
@@ -14,8 +14,11 @@ import type { MarkerTransform } from '../transforms';
 /** The `styles` prop accepted by every plot kind - its own
  * styles shape ({@link AxisBasedStylesConfig}, `GeoStylesConfig`, …). */
 export type StylesConfig<TStyles extends object> = TStyles;
-/** The `markers` prop accepted by every plot kind - a list of that kind's own marker union. */
-export type MarkersConfig<TMarker> = TMarker[];
+/**
+ * The `markers` prop accepted by every plot kind - a list of that kind's own marker union, each of
+ * which can be limited to some facet panels with `facet`.
+ */
+export type MarkersConfig<TMarker> = (TMarker & FacetScoped)[];
 /**
  * The `segments` prop - series name (or `'default'`) to its {@link Segment}s.
  * Area-specific segments win over catch-all ones.

package/dist/types/plots/segments/config.d.ts

@@ -3,6 +3,7 @@ import type { AxisValue } from '../../layout/mapping';
 import type { Series } from '../data/common';
 import type { LineSegmentStyle } from './common';
 import type { MarkLegend } from '../../layout/legend';
+import type { FacetScoped } from '../../layout/facet';
 /** A half-open interval on one axis. Both bounds are inclusive; omit either to leave that end open. */
 export type Range = {
     from?: AxisValue;
@@ -22,7 +23,8 @@ export type Area = {
 };
 /**
  * One styled rule for a plot. A data point (or cell) is styled when it falls
- * inside **any** of the listed `areas`. Omitting `areas` (or passing an empty
+ * inside **any** of the listed `areas`. With a `facet`, the rule exists only in
+ * the facet panels it names. Omitting `areas` (or passing an empty
  * array) makes the segment a catch-all that matches every data point - useful
  * as a baseline style. `TStyle` is the per-mark shape ({@link LineSegmentStyle},
  * {@link BarSegmentStyle}, {@link CellSegmentStyle}, …).
@@ -31,7 +33,7 @@ export type Area = {
  * priority, regardless of their position in the list. A catch-all placed first
  * therefore acts as a fallback baseline that area-specific segments override.
  */
-export type Segment<TStyle> = {
+export type Segment<TStyle> = FacetScoped & {
     areas?: Area[];
     scales?: ChannelScalesConfig;
     styles?: TStyle;

package/docs/facets.md

@@ -106,6 +106,53 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
 
 ![Panels for each combination of region and sector](images/facets-rows-cols.png)
 
+## Markers and segments in some panels
+
+Every panel draws the plot's `markers` and `segments`. Add `facet` to one to limit it to the panels it names: the value of its `by` field, or a list of them. Without `facet` it applies to every panel, as before.
+
+<!-- example: examples/FacetsScoped.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './datasets';
+
+	// Each region's value split into two sectors.
+	const SECTORS = [
+		{ sector: 'Goods', share: 0.8 },
+		{ sector: 'Services', share: 1.4 }
+	];
+	const rows = REGION_VALUES.flatMap((row) =>
+		SECTORS.map(({ sector, share }) => ({ ...row, sector, value: row.value * share }))
+	);
+</script>
+
+<!-- One panel per region. `facet` on a marker or a segment limits it to the panels it names: the rule is drawn in GBA only, and Services is dashed in Cuyo only. -->
+<LinePlot
+	width={900}
+	height={360}
+	data={rows}
+	x="date"
+	y="value"
+	color="sector"
+	facet={{ by: 'region', columns: 3 }}
+	markers={[{ type: 'rule', axis: 'y', value: 10, facet: 'GBA' }]}
+	segments={{ Services: [{ facet: 'Cuyo', styles: { stroke: { strokeDasharray: '4 4' } } }] }}
+/>
+```
+
+<!-- /example -->
+
+![Markers and segments in some panels](images/facets-scoped.png)
+
+| `facet`                              | Applies to                                                                                                                                  |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| _not set_                            | Every panel, and a plot with no facet                                                                                                       |
+| `'GBA'` or `['GBA', 'Cuyo']`         | The panels with that `by` value (numbers and booleans match the text they print as)                                                         |
+| `{ row: 'GBA' }`, `{ col: 'Goods' }` | In a `rows`/`cols` grid, the panels with that row or column value; `{ row, col }` takes both, and a side left out matches every value of it |
+
+A marker or a segment that names a facet is not drawn by a plot that has none. It works on every plot kind: a `GeoPlot` map takes it the same way, on top of slicing its marker rows by the facet field.
+
 ## Alignment
 
 Panels line up: each plot reports the margins it settled on, and once all have, every column and row pins its widest ones, so the plot areas align whatever their tick labels need.

package/docs/markers.md

@@ -58,32 +58,60 @@ Many markers also take channel fields (`color`, `fill`, `opacity`, `r`, `symbol`
 
 ## Catalog for axis-based plots
 
-| `type`                                                   | Draws                                                                                                                                                                               |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dot`                                                    | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`)                                                                                                                      |
-| `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins`                                                                        |
-| `line`                                                   | A line through the rows                                                                                                                                                             |
-| `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (or a function with `data`), `styles`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
-| `tick`                                                   | A short tick per row along one axis                                                                                                                                                 |
-| `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                                                                                                 |
-| `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges                                                                                                          |
-| `area`                                                   | A filled area under a curve, or between `y1` and `y2`; `curve`                                                                                                                      |
-| `difference`                                             | The area between two series, colored by which one is on top                                                                                                                         |
-| `arrow`                                                  | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row                 |
-| `trail`                                                  | A variable-width ribbon along a path, its width set by `r`                                                                                                                          |
-| `delta`                                                  | The distance between two series (or a series and a fixed value) at a position, as a line and a label                                                                                |
-| `hull`                                                   | The convex hull around a cluster of points                                                                                                                                          |
-| `density`                                                | 2D density contour bands                                                                                                                                                            |
-| `box`                                                    | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`; `thickness` sets its width in pixels, `slot` its share of a band                             |
-| `violin`                                                 | A violin per category of its rows: the mirrored density of `y` (or `x`), `kernel`, `bandwidth`, `trim`, `peak`, `slot`; add a narrow `box` over the same rows for the box inside    |
-| `regression`, `bollinger`                                | A fitted curve, a moving-average band                                                                                                                                               |
-| `waffle`                                                 | The value as a grid of unit squares; `unit`, `multiple`, `gap`                                                                                                                      |
-| `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation                                                                                                                                            |
-| `image`                                                  | An image per row; `src`, `width`, `height`                                                                                                                                          |
-| `raster`                                                 | A field sampled over a rectangle, drawn to a canvas                                                                                                                                 |
-| `brush`                                                  | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend`                                                                                                             |
-| `hover`                                                  | The in-plot hover highlight (see below)                                                                                                                                             |
-| `component`                                              | Your own Svelte component (see below)                                                                                                                                               |
+| `type`                                                   | Draws                                                                                                                                                                                                            |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dot`                                                    | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`)                                                                                                                                                   |
+| `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins`                                                                                                     |
+| `line`                                                   | A line through the rows                                                                                                                                                                                          |
+| `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (a list draws a line at each, or a function with `data`), `styles`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
+| `tick`                                                   | A short tick per row along one axis                                                                                                                                                                              |
+| `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                                                                                                                              |
+| `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges                                                                                                                                       |
+| `area`                                                   | A filled area under a curve, or between `y1` and `y2`; `curve`                                                                                                                                                   |
+| `difference`                                             | The area between two series, colored by which one is on top                                                                                                                                                      |
+| `arrow`                                                  | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row                                              |
+| `trail`                                                  | A variable-width ribbon along a path, its width set by `r`                                                                                                                                                       |
+| `delta`                                                  | The distance between two series (or a series and a fixed value) at a position - or at each of a list of them, `at: [1980, 2000]` - as a line and a label                                                         |
+| `hull`                                                   | The convex hull around a cluster of points                                                                                                                                                                       |
+| `density`                                                | 2D density contour bands                                                                                                                                                                                         |
+| `box`                                                    | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`; `thickness` sets its width in pixels, `slot` its share of a band                                                          |
+| `violin`                                                 | A violin per category of its rows: the mirrored density of `y` (or `x`), `kernel`, `bandwidth`, `trim`, `peak`, `slot`; add a narrow `box` over the same rows for the box inside                                 |
+| `regression`, `bollinger`                                | A fitted curve, a moving-average band                                                                                                                                                                            |
+| `waffle`                                                 | The value as a grid of unit squares; `unit`, `multiple`, `gap`                                                                                                                                                   |
+| `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation                                                                                                                                                                         |
+| `image`                                                  | An image per row; `src`, `width`, `height`                                                                                                                                                                       |
+| `raster`                                                 | A field sampled over a rectangle, drawn to a canvas                                                                                                                                                              |
+| `brush`                                                  | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend`                                                                                                                                          |
+| `hover`                                                  | The in-plot hover highlight (see below)                                                                                                                                                                          |
+| `component`                                              | Your own Svelte component (see below)                                                                                                                                                                            |
+
+## Markers in some facets
+
+On a plot with a [`facet`](facets.md#markers-and-segments-in-some-panels), every marker is drawn in every panel. A marker takes `facet`, a panel's value or a list of them, to be drawn only in the panels it names.
+
+## Several positions at once
+
+A `rule` takes a list as its `value`, and a `delta` a list as its `at`. One marker then draws one line, or one delta, at each position, all with the same style and the same ends - instead of one marker for each.
+
+```ts
+markers={[
+	// A rule at each of the three years.
+	{ type: 'rule', axis: 'x', value: [1991, 2001, 2010], styles: { strokeDasharray: '4 4' } },
+	// The gap between the two series at each of the three.
+	{ type: 'delta', axis: 'x', at: [1991, 2001, 2010], from: { type: 'series', series: 'female' }, to: { type: 'series', series: 'male' } }
+]}
+```
+
+A delta's `line`, `text` and `dot` can be functions of the position, to style each one on its own - a label to the left of the last one, say, so it stays inside the plot:
+
+```ts
+{
+	type: 'delta', axis: 'x', at: [1991, 2001, 2022], from: { type: 'series', series: 'female' }, to: { type: 'series', series: 'male' },
+	text: (at) => (at === 2022 ? { dx: -20, textAnchor: 'end' } : { dx: 20 })
+}
+```
+
+Every other marker draws from `data` rows, one mark per row, so it already takes many positions.
 
 ## Hover highlight
 

package/docs/styles-and-segments.md

@@ -119,6 +119,7 @@ type Range = { from?: AxisValue; to?: AxisValue }; // inclusive on both ends
 - A segment without `areas` is a **catch-all**: it matches every point, is evaluated last, and is overridden by any area-specific segment. A catch-all placed first is a baseline that highlighted ranges override.
 - `'default'` applies to every series; a named key applies to that series only, and wins over `'default'` where both match.
 - `legend` names the segment on the automatic [legend](legend.md).
+- `facet` limits the segment to the [facet panels](facets.md#markers-and-segments-in-some-panels) it names - a `by` value or a list of them. Without it the segment applies to every panel.
 
 The style shape depends on the plot: