@fundar/data-chart-telling 1.2.0 → 1.4.0

package/dist/markers/delta/Delta.d.ts

@@ -1,5 +1,5 @@
 import type { Series } from '../../types/plots/data/common';
-import type { DeltaConfig } from '../../types/markers/axis/delta';
+import type { DeltaConfig, DeltaMarkerConfig, DeltaPointConfig } from '../../types/markers/axis/delta';
 /** A delta, measured: where it sits (`at`), its two ends and what lies between. */
 export type ResolvedDelta = {
     cfg: DeltaConfig;
@@ -16,6 +16,11 @@ export type ResolvedDelta = {
  */
 export declare class Delta {
     #private;
+    /**
+     * The deltas a marker draws: one for its `at`, or one for each position of a list, each with the
+     * `line`, `text` and `dot` its style functions give for that position.
+     */
+    static points(marker: DeltaMarkerConfig): DeltaPointConfig[];
     /** The delta `config` asks for over `allSeries`, or `undefined` while an end has no value there. */
     static build<T extends Record<string, unknown>>(axis: 'x' | 'y', allSeries: Series<T>[], config: DeltaConfig): ResolvedDelta | undefined;
 }

package/dist/markers/delta/Delta.js

@@ -5,6 +5,21 @@ import { resolveAccessor } from '../../utils/accessors';
  * it crosses that position, interpolated linearly between its two nearest points.
  */
 export class Delta {
+    /**
+     * The deltas a marker draws: one for its `at`, or one for each position of a list, each with the
+     * `line`, `text` and `dot` its style functions give for that position.
+     */
+    static points(marker) {
+        const positions = Array.isArray(marker.at) ? marker.at : [marker.at];
+        const own = (style, at) => typeof style === 'function' ? style(at) : style;
+        return positions.map((at) => ({
+            ...marker,
+            at,
+            line: own(marker.line, at),
+            text: own(marker.text, at),
+            dot: own(marker.dot, at)
+        }));
+    }
     /** The delta `config` asks for over `allSeries`, or `undefined` while an end has no value there. */
     static build(axis, allSeries, config) {
         const at = Number(config.at);

package/dist/markers/delta/DeltaMarker.svelte

@@ -1,96 +1,18 @@
 <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 DeltaPoint from './DeltaPoint.svelte';
 	import { Delta } from './Delta';
-	import { getConfiguration } from '../../configuration/config.svelte';
 	import type { Series } from '../../types/plots/data/common';
 	import type { DeltaMarkerConfig } from '../../types/markers/axis/delta';
 
+	/**
+	 * A delta annotation: one at `marker.at`, or, when it is a list, one at each position - all with the
+	 * same ends. `line`, `text` and `dot` can be functions of the position.
+	 */
 	let { marker, data = [] }: { marker: DeltaMarkerConfig; 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
-	});
+	const points = $derived(Delta.points(marker));
 </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}
+{#each points as point (String(point.at))}
+	<DeltaPoint marker={point} {data} />
+{/each}

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;
@@ -290,6 +292,20 @@ export type ColorOverride = Omit<ContinuousLegendSection, 'type' | 'min' | 'max'
  * ramp `interactive`, and only its first ramp is.
  */
 export type LegendExtension = {
+    /**
+     * Series to turn off from code, as if the reader had clicked them: a list
+     * of names (each dimmed, to `legend.disabledOpacity`), or a name → what
+     * turning it off does map - an opacity to dim to, or a full
+     * {@link LegendDisabledAction} (`dim`, `hide` or `omit`). It follows the
+     * value it is given: a series left out is turned back on. One the reader
+     * turned off themselves is left as it is.
+     */
+    off?: string[] | Record<string, number | LegendDisabledAction>;
+    /**
+     * The series to keep on: every other series is dimmed, the inverse of
+     * listing the rest in `off`. An entry of `off` for a series wins.
+     */
+    highlight?: string | string[];
     items?: LegendItem[];
     sections?: LegendSection[];
     series?: Omit<DiscreteLegendSection, 'type' | 'items'>;

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;