@fundar/data-chart-telling 0.0.3 → 0.0.5

package/README.md

@@ -116,7 +116,7 @@ Plots accept either `series` (pre-built `Series[]`) or the `data` + `x`/`y`/`z`
 | `x` | `Accessor` | — | ✅ | ✅ | ✅ | ✅ |
 | `y` | `Accessor` | — | ✅ | ✅ | ✅ | ✅ |
 | `z` | `Accessor` | — | ✅ | ✅ | ✅ | ✅ |
-| `segments` | `SegmentsMap<TStyle>` | `{}` / `[]` | ✅ | ✅ | ✅ | ✅ |
+| `segments` | `Segments<TStyle>` | `[]` | ✅ | ✅ | ✅ | ✅ |
 | `markers` | `Marker[]` | `[]` | ✅ | ✅ | ✅ | ✅ |
 | `scales` | `ScalesConfig` | `{}` | ✅ | ✅ | ✅ | ✅ |
 | `margins` | `MarginConfig` | `{}` | ✅ | ✅ | ✅ | ✅ |
@@ -158,7 +158,7 @@ Plots accept either `series` (pre-built `Series[]`) or the `data` + `x`/`y`/`z`
 | `subtitle` | `string` | | ✅ | ✅ | ✅ | ✅ |
 | `caption` | `string` | | ✅ | ✅ | ✅ | ✅ |
 | `legend` | `LegendSection[]` | | ✅ | ✅ | ✅ | ✅ |
-| `segments` | `SegmentsMap<TStyle>` | `{}` / `[]` | ✅ | ✅ | ✅ | ✅ |
+| `segments` | `Segments<TStyle>` | `[]` | ✅ | ✅ | ✅ | ✅ |
 | `markers` | `Marker[]` | `[]` | ✅ | ✅ | ✅ | ✅ |
 | `scales` | `ScalesConfig` | `{}` | ✅ | ✅ | ✅ | ✅ |
 | `margins` | `MarginConfig` | `{}` | ✅ | ✅ | ✅ | ✅ |
@@ -177,49 +177,80 @@ The `segments` prop separates data ranges from visual styling. Every plot kind s
 
 | Plot | `segments` type |
 | ---- | --------------- |
-| `LinePlot` / `LineChart` | `SegmentsMap<LineSegmentStyle>` |
-| `BarPlot` / `BarChart` | `SegmentsMap<BarSegmentStyle>` |
-| `PyramidPlot` / `PyramidChart` | `SegmentsMap<BarSegmentStyle>` |
-| `HeatmapPlot` / `HeatmapChart` | `SegmentsMap<CellSegmentStyle>` (array form only) |
+| `LinePlot` / `LineChart` | `Segments<LineSegmentStyle>` |
+| `BarPlot` / `BarChart` | `Segments<BarSegmentStyle>` |
+| `PyramidPlot` / `PyramidChart` | `Segments<BarSegmentStyle>` |
+| `HeatmapPlot` / `HeatmapChart` | `Segments<CellSegmentStyle>` (`'default'` key only) |
 
 #### Core types
 
 ```ts
-type Range   = { from?: AxisValue; to?: AxisValue };   // half-open on either side
-type Area    = { x?: Range; y?: Range };               // 2-D rectangular region
+type Range           = { from?: AxisValue; to?: AxisValue };  // inclusive on both sides
+type Area            = { x?: Range; y?: Range };              // 2-D rectangular region
 type Segment<TStyle> = { areas?: Area[]; style?: TStyle };
 ```
 
-A **`Segment`** matches a data point (or heatmap cell) when the point falls inside **any** of its `areas`. Omitting `areas` (or providing an empty array) makes the segment match **all** data — useful as a baseline style. Segments are rendered in order; later ones appear on top.
+A **`Segment`** matches a data point (or heatmap cell) when the point falls inside **any** of its `areas`. Omitting `areas` creates a **catch-all** that matches every data point — but catch-alls are always evaluated **last**, regardless of their position in the list, so area-specific segments always win. This lets a catch-all placed first act as a fallback baseline that highlighted ranges override.
 
 An **`Area`** restricts by x, y, or both. Both bounds of a `Range` are **inclusive**. Omitting `x` or `y` leaves that axis unrestricted.
 
-#### `SegmentsMap` forms
+#### `Segments` structure
+
+`segments` is always an **array of groups**. Each group is a plain object whose keys map to `Segment[]` lists:
 
 ```ts
-// Array form — same segments apply to every series (required for heatmaps)
-type SegmentsMap<TStyle> = Segment<TStyle>[];
+// 'default' key — applies its segments to every series
+type DefaultSegmentsMap<TStyle>     = { default: Segment<TStyle>[] };
+
+// named keys — applies segments only to the named series
+type SeriesAwareSegmentsMap<TStyle> = Record<string, Segment<TStyle>[]>;
 
-// Record form — segments keyed by series name (line / bar / pyramid)
-type SegmentsMap<TStyle> = SeriesAwareSegmentsMap<TStyle>;
-                         = Record<string, Segment<TStyle>[]>;
+// one element of the array — either form, or a mix of both key types
+type SegmentsStyle<TStyle> = DefaultSegmentsMap<TStyle> | SeriesAwareSegmentsMap<TStyle>;
+
+// the prop type: an ordered list of groups
+type Segments<TStyle> = SegmentsStyle<TStyle>[];
 ```
 
+Having multiple groups lets you organise segments by concern — for example one group for per-series stroke colours and a second for shared dot markers applied via `'default'`. Groups are processed in order and their resolved segments are concatenated per series before evaluation.
+
 #### Examples
 
-**Line chart — colour a period and leave the rest as the palette default:**
+**Line chart — baseline colour with a highlighted range (catch-all as fallback):**
 
 ```svelte
 <LinePlot
   {width} {height}
   series={[{ name: 'gdp', x: 'year', y: 'value', data: GDP }]}
-  segments={{
-    gdp: [
-      { style: { stroke: { stroke: '#94a3b8', strokeWidth: 1 } } },
-      { areas: [{ x: { from: 2008, to: 2010 } }],
-        style: { stroke: { stroke: '#ef4444', strokeWidth: 3 } } },
-    ],
-  }}
+  segments={[
+    {
+      gdp: [
+        { style: { stroke: { stroke: '#94a3b8', strokeWidth: 1 } } },
+        { areas: [{ x: { from: 2008, to: 2010 } }],
+          style: { stroke: { stroke: '#ef4444', strokeWidth: 3 } } },
+      ],
+    },
+  ]}
+/>
+```
+
+**Line chart — per-series baseline colours + shared dot markers (two-group approach):**
+
+```svelte
+<LinePlot
+  {width} {height}
+  data={LIFE_EXPECTANCY} x="year" y="value" z="sex"
+  segments={[
+    // Group 1: per-series catch-all stroke colours
+    { female: [{ style: { stroke: { stroke: 'steelblue' } } }],
+      male:   [{ style: { stroke: { stroke: 'tomato'    } } }] },
+    // Group 2: dots for all series in a specific range
+    { default: [
+        { areas: [{ x: { from: 2010, to: 2012 } }],
+          style: { dots: { dotRadius: 5, dotSymbol: 'circle' } } },
+      ],
+    },
+  ]}
 />
 ```
 
@@ -229,15 +260,19 @@ type SegmentsMap<TStyle> = SeriesAwareSegmentsMap<TStyle>;
 <HeatmapChart
   {width} {height} {data} {x} {y} {z}
   segments={[
-    { areas: [{ x: { from: 'Q1', to: 'Q1' } }, { x: { from: 'Q3', to: 'Q3' } }],
-      style: { stroke: '#f59e0b', strokeWidth: 2 } },
-    { areas: [{ x: { from: 'Q2', to: 'Q2' }, y: { from: 1, to: 2 } }],
-      style: { fill: '#ef4444', fillOpacity: 0.8 } },
+    {
+      default: [
+        { areas: [{ x: { from: 'Q1', to: 'Q1' } }, { x: { from: 'Q3', to: 'Q3' } }],
+          style: { stroke: '#f59e0b', strokeWidth: 2 } },
+        { areas: [{ x: { from: 'Q2', to: 'Q2' }, y: { from: 1, to: 2 } }],
+          style: { fill: '#ef4444', fillOpacity: 0.8 } },
+      ],
+    },
   ]}
 />
 ```
 
-Omitting `segments` renders every mark in its default palette colour.
+Omitting `segments` (or passing `[]`) renders every mark in its default palette colour.
 
 ---
 

package/dist/index.d.ts

@@ -26,7 +26,7 @@ export { groupBy, buildSeries } from './utils/grouping';
 export { makeColorScale, normalize, resolveCssColor, paletteColor } from './utils/color';
 export type { AxisValue, Accessor, AxisScale, ScalesConfig, Series, SeriesProps, DataProps } from './types/plots/common';
 export type { DeltaConfig, } from './types/plots/delta';
-export type { SymbolType, LineStyle, StrokeStyle, DotStyle, FontStyle, LineSegmentStyle, BarSegmentStyle, CellSegmentStyle, Range, Area, Segment, SeriesAwareSegmentsMap, SegmentsMap, ValueAnchor, ValuesStyle, ColorsStyle, PlotStyles, } from './types/plots/styles';
+export type { SymbolType, LineStyle, StrokeStyle, DotStyle, FontStyle, LineSegmentStyle, BarSegmentStyle, CellSegmentStyle, Range, Area, Segment, SeriesAwareSegmentsMap, DefaultSegmentsMap, SegmentsStyle, Segments, ValueAnchor, ValuesStyle, ColorsStyle, PlotStyles, } from './types/plots/styles';
 export type { Marker, MarkerProps } from './types/plots/markers';
 export type { PlotProps } from './types/plots/props';
 export type { TimeValue, Orientation, FacetColumns, FacetConfig, TimelineConfig, ChartPlotContext, ChartPlotSnippet, } from './types/charts/common';

package/dist/layout/plot/PlotLayout.svelte

@@ -218,7 +218,7 @@
   </Plot>
 
   {#if tooltip && ctrl.showTooltip && ctrl.tooltipPosition}
-    <Tooltip x={ctrl.tooltipPosition.x} y={ctrl.tooltipPosition.y}>
+    <Tooltip x={ctrl.tooltipPosition?.x ?? 0} y={ctrl.tooltipPosition?.y ?? 0}>
       {#if tooltip.content}
         {@render tooltip.content({ rows: ctrl.matchedRows.map((p) => p.row) })}
       {:else}

package/dist/plots/bar/Plot.svelte

@@ -30,7 +30,7 @@
     y,
     z,
     styles = {},
-    segments = {},
+    segments = [],
     markers = [],
     scales = {},
     margins,

package/dist/plots/heatmap/Plot.svelte

@@ -43,9 +43,12 @@
         'HeatmapPlot: markers scoped to a `series` are ignored — heatmaps have no series concept.',
       );
     }
-    if (!Array.isArray(segments) && Object.keys(segments).length > 0) {
+    const seriesKeys = segments.flatMap((g) =>
+      Object.keys(g as Record<string, unknown>).filter((k) => k !== 'default'),
+    );
+    if (seriesKeys.length > 0) {
       console.warn(
-        'HeatmapPlot: `segments` was passed as a record (SeriesAwareSegmentsMap) but heatmaps have no named series — use the array form (Segment[]) instead.',
+        `HeatmapPlot: segment groups have series-specific keys (${[...new Set(seriesKeys)].join(', ')}) — heatmaps have no named series. Use the 'default' key instead.`,
       );
     }
   });
@@ -87,7 +90,7 @@
     makeColorScale(valueDomain[0], valueDomain[1], minColor, maxColor),
   );
 
-  const segList = $derived(Array.isArray(segments) ? segments : []);
+  const segList = $derived(segments.flatMap((g) => (g as Record<string, CellSegmentStyle[]>)['default'] ?? []));
 
   const segStyleMap = $derived.by(() => {
     const map = new Map<string, CellSegmentStyle>();

package/dist/plots/line/Plot.svelte

@@ -25,7 +25,7 @@
     y,
     z,
     styles = {},
-    segments = {},
+    segments = [],
     markers = [],
     scales = {},
     margins,

package/dist/plots/markers/DeltaMarker.svelte

@@ -59,15 +59,27 @@
       ? Math.min(fromVis, toVis)
       : (fromVis + toVis) / 2;
   }
-</script>
 
-{#if resolved}
-  {@const fromVis = clamp(resolved?.from ?? 0)}
-  {@const toVis = clamp(resolved?.to ?? 0)}
-  {@const textPt = pt(resolved?.at ?? 0, textVaryCoord(fromVis, toVis))}
+  // 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,
+    };
+  });
+</script>
 
+{#if coords}
   <Line
-    data={[pt(resolved?.at ?? 0, fromVis), pt(resolved?.at ?? 0, toVis)]}
+    data={coords.lineData}
     x={(p) => p.x}
     y={(p) => p.y}
     stroke={strokeStyle?.stroke ?? 'currentColor'}
@@ -77,19 +89,19 @@
     strokeLinecap={strokeStyle?.strokeLinecap ?? 'round'}
   />
   <DotMarker
-    x={pt(resolved?.at ?? 0, fromVis).x}
-    y={pt(resolved?.at ?? 0, fromVis).y}
+    x={coords?.fromPt?.x ?? 0}
+    y={coords?.fromPt?.y ?? 0}
     style={{ dotRadius: 4, dotFill: strokeStyle?.stroke, dotStroke: strokeStyle?.stroke, dotStrokeWidth: 2, ...dotStyle }}
   />
   <DotMarker
-    x={pt(resolved?.at ?? 0, toVis).x}
-    y={pt(resolved?.at ?? 0, toVis).y}
+    x={coords?.toPt?.x ?? 0}
+    y={coords?.toPt?.y ?? 0}
     style={{ dotRadius: 4, dotFill: strokeStyle?.stroke, dotStroke: strokeStyle?.stroke, dotStrokeWidth: 2, ...dotStyle }}
   />
   <TextMarker
-    x={textPt.x}
-    y={textPt.y}
-    text={(formatDiff ?? ((v: number) => v.toFixed(1)))(resolved?.diff ?? 0)}
+    x={coords?.textPt?.x ?? 0}
+    y={coords?.textPt?.y ?? 0}
+    text={(formatDiff ?? ((v: number) => v.toFixed(1)))(coords?.diff ?? 0)}
     style={{
       fontWeight: 'bold',
       fontSize: 14,

package/dist/plots/pyramid/Plot.svelte

@@ -40,7 +40,7 @@
     styles = {},
     scales = {},
     margins,
-    segments = {},
+    segments = [],
     markers = [],
     tooltip = undefined,
   }: PlotProps<TData, BarSegmentStyle> = $props();

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

@@ -1,13 +1,11 @@
 import type { AxisValue, Series } from '../../types/plots/common';
-import type { Segment, SegmentsMap, SeriesAwareSegmentsMap, LineSegmentStyle, VisualGroup } from '../../types/plots/styles';
-/** Narrows a {@link SegmentsMap} to its per-series record form. */
-export declare function isSeriesAware<TStyle>(segments: SegmentsMap<TStyle>): segments is SeriesAwareSegmentsMap<TStyle>;
+import type { Segment, Segments, LineSegmentStyle, VisualGroup } from '../../types/plots/styles';
 /**
- * Returns the {@link Segment} list relevant for one series. If `segments` is
- * the global array form every series gets the same list; if it is the record
- * form only the entry keyed by `seriesName` is used (falling back to `[]`).
+ * Returns the flat {@link Segment} list for one series by merging all groups.
+ * Within each group, series-specific segments are added before `'default'`
+ * segments, so series-specific rules win on tie-breaks.
  */
-export declare function resolveSegmentsForSeries<TStyle>(segments: SegmentsMap<TStyle>, seriesName: string): Segment<TStyle>[];
+export declare function resolveSegmentsForSeries<TStyle>(segments: Segments<TStyle>, seriesName: string): 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;
 /**
@@ -20,14 +18,14 @@ export declare function matchesSegmentX<TStyle>(xVal: AxisValue, seg: Segment<TS
  */
 export declare function getDataForSegments<TData, TStyle>(data: TData[], xAccessor: (d: TData) => AxisValue, segs: Segment<TStyle>[]): TData[][];
 /**
- * Warns about obvious configuration mistakes:
- * - Multiple segments with no `areas` in the same series (they all match
- *   everything; only the last style will be visible).
+ * Warns about obvious configuration mistakes: multiple catch-all segments
+ * (no `areas`) in the same series list. Since catch-alls are evaluated last
+ * and in order, only the first one can ever match; later ones are dead code.
  */
-export declare function validateSegments<TStyle>(segments: SegmentsMap<TStyle>): void;
+export declare function validateSegments<TStyle>(segments: Segments<TStyle>): void;
 /**
  * Builds the full list of visual groups — one per series — ready to render.
- * Each group's `visualSegments` is derived from the series' entry in
- * `segments` (or the global array when `segments` is in array form).
+ * Each group's `visualSegments` is derived by resolving the flat segment list
+ * for that series from all groups in `segments`.
  */
-export declare function buildGroupedSeries<S extends Series<any>, TStyle = LineSegmentStyle>(seriesList: S[], segments: SegmentsMap<TStyle>): VisualGroup<S, TStyle>[];
+export declare function buildGroupedSeries<S extends Series<any>, TStyle = LineSegmentStyle>(seriesList: S[], segments: Segments<TStyle>): VisualGroup<S, TStyle>[];

package/dist/plots/utils/segments.js

@@ -1,15 +1,21 @@
 import { resolveAccessor } from './accessors';
-/** Narrows a {@link SegmentsMap} to its per-series record form. */
-export function isSeriesAware(segments) {
-    return !Array.isArray(segments);
-}
+const DEFAULT_KEY = 'default';
 /**
- * Returns the {@link Segment} list relevant for one series. If `segments` is
- * the global array form every series gets the same list; if it is the record
- * form only the entry keyed by `seriesName` is used (falling back to `[]`).
+ * Returns the flat {@link Segment} list for one series by merging all groups.
+ * Within each group, series-specific segments are added before `'default'`
+ * segments, so series-specific rules win on tie-breaks.
  */
 export function resolveSegmentsForSeries(segments, seriesName) {
-    return Array.isArray(segments) ? segments : (segments[seriesName] ?? []);
+    const result = [];
+    for (const group of segments) {
+        const specific = group[seriesName];
+        const defaults = group[DEFAULT_KEY];
+        if (specific)
+            result.push(...specific);
+        if (defaults)
+            result.push(...defaults);
+    }
+    return result;
 }
 /** Returns true when `xVal` falls inside any of a segment's x ranges. */
 export function matchesSegmentX(xVal, seg) {
@@ -53,24 +59,21 @@ export function getDataForSegments(data, xAccessor, segs) {
     });
 }
 /**
- * Warns about obvious configuration mistakes:
- * - Multiple segments with no `areas` in the same series (they all match
- *   everything; only the last style will be visible).
+ * Warns about obvious configuration mistakes: multiple catch-all segments
+ * (no `areas`) in the same series list. Since catch-alls are evaluated last
+ * and in order, only the first one can ever match; later ones are dead code.
  */
 export function validateSegments(segments) {
     const check = (label, segs) => {
         const catchAlls = segs.filter((s) => !s.areas || s.areas.length === 0).length;
         if (catchAlls > 1) {
             console.warn(`segments ${label}: ${catchAlls} entries have no areas — ` +
-                `they each match every data point; only the last one's style will be visible.`);
+                `only the first catch-all's style will be used.`);
         }
     };
-    if (Array.isArray(segments)) {
-        check('(global)', segments);
-    }
-    else {
-        for (const [name, segs] of Object.entries(segments)) {
-            check(`"${name}"`, segs);
+    for (const group of segments) {
+        for (const [key, segs] of Object.entries(group)) {
+            check(key === DEFAULT_KEY ? '(default)' : `"${key}"`, segs);
         }
     }
 }
@@ -81,16 +84,29 @@ function resolveSeriesSegments(series, segs) {
     }
     const getX = resolveAccessor(series.x);
     const getY = resolveAccessor(series.y);
+    // Evaluate area-specific segments before catch-alls (no areas), preserving
+    // relative order within each group. This lets a catch-all placed first in
+    // the list act as a fallback baseline rather than matching everything.
+    const evalOrder = segs
+        .map((seg, i) => ({ seg, i }))
+        .sort((a, b) => {
+        const aSpecific = a.seg.areas != null && a.seg.areas.length > 0;
+        const bSpecific = b.seg.areas != null && b.seg.areas.length > 0;
+        if (aSpecific === bSpecific)
+            return a.i - b.i;
+        return aSpecific ? -1 : 1;
+    });
     // For each data point, find the first matching segment index (-1 = unmatched).
     const matchIdx = series.data.map((d) => {
         const xVal = getX(d);
         const yVal = getY(d);
-        return segs.findIndex((seg) => {
+        const found = evalOrder.find(({ seg }) => {
             const areas = seg.areas;
             if (!areas || areas.length === 0)
                 return true;
             return areas.some((area) => areaMatchesXY(xVal, yVal, area));
         });
+        return found !== undefined ? found.i : -1;
     });
     const runs = [];
     for (let i = 0; i < series.data.length; i++) {
@@ -103,6 +119,16 @@ function resolveSeriesSegments(series, segs) {
             runs.push({ data: [series.data[i]], segIdx: idx });
         }
     }
+    // Connector lines need to match the catch-all's stroke so they don't reveal
+    // the default palette color when the user has set a baseline via catch-all.
+    // Dots are excluded to avoid duplicate marks at the shared boundary points.
+    const catchAll = segs.find((s) => !s.areas || s.areas.length === 0);
+    const connectorStyle = (() => {
+        if (!catchAll?.style)
+            return {};
+        const { dots: _, ...rest } = catchAll.style;
+        return rest;
+    })();
     const defaultVisual = [];
     const connectors = [];
     const userVisual = [];
@@ -129,7 +155,7 @@ function resolveSeriesSegments(series, segs) {
             if (nextRun && nextRun.segIdx !== -1) {
                 connectors.push({
                     data: [run.data[run.data.length - 1], nextRun.data[0]],
-                    style: {},
+                    style: connectorStyle,
                 });
             }
         }
@@ -142,8 +168,8 @@ function resolveSeriesSegments(series, segs) {
 }
 /**
  * Builds the full list of visual groups — one per series — ready to render.
- * Each group's `visualSegments` is derived from the series' entry in
- * `segments` (or the global array when `segments` is in array form).
+ * Each group's `visualSegments` is derived by resolving the flat segment list
+ * for that series from all groups in `segments`.
  */
 export function buildGroupedSeries(seriesList, segments) {
     return seriesList.map((s) => ({

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

@@ -1,5 +1,5 @@
 import type { Accessor, AxisValue, ScalesConfig, MarginConfig } from '../plots/common';
-import type { PlotStyles, SegmentsMap } from '../plots/styles';
+import type { PlotStyles, Segments } from '../plots/styles';
 import type { Marker } from '../plots/markers';
 import type { TooltipProp } from '../layout/tooltip';
 import type { LegendSection } from './legend';
@@ -25,7 +25,7 @@ export type ChartProps<TRow extends Record<string, unknown>, TSegmentStyle exten
     y: Accessor<TRow, AxisValue>;
     z?: Accessor<TRow, unknown>;
     styles?: PlotStyles;
-    segments?: SegmentsMap<TSegmentStyle>;
+    segments?: Segments<TSegmentStyle>;
     markers?: Marker[];
     scales?: ScalesConfig;
     margins?: MarginConfig;

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

@@ -1,6 +1,6 @@
 import type { Marker } from './markers';
 import type { TooltipRuntime } from '../layout/tooltip';
-import type { PlotStyles, SegmentsMap } from './styles';
+import type { PlotStyles, Segments } from './styles';
 import type { SeriesProps, DataProps, ScalesConfig, MarginConfig } from './common';
 /**
  * Common props accepted by every plot component (bar, line, heatmap, pyramid,
@@ -15,7 +15,7 @@ export type PlotProps<TData extends Record<string, unknown>, TSegmentStyle exten
     width: number;
     height: number;
     styles?: PlotStyles;
-    segments?: SegmentsMap<TSegmentStyle>;
+    segments?: Segments<TSegmentStyle>;
     markers?: Marker[];
     scales?: ScalesConfig;
     margins?: MarginConfig;

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

@@ -134,11 +134,13 @@ 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
- * array) makes the segment match **all** data — useful as a baseline style.
- * `TStyle` is the per-mark shape ({@link LineSegmentStyle}, {@link BarSegmentStyle},
- * {@link CellSegmentStyle}, …).
+ * 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}, …).
  *
- * Segments are applied in order; later ones are rendered on top of earlier ones.
+ * Catch-alls are evaluated last so that area-specific segments always take
+ * 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> = {
     areas?: Area[];
@@ -147,17 +149,47 @@ export type Segment<TStyle> = {
 /** Per-series list of {@link Segment}s, keyed by series name. */
 export type SeriesAwareSegmentsMap<TStyle> = Record<string, Segment<TStyle>[]>;
 /**
- * Unified segments prop accepted by every plot kind.
+ * A segment group that applies its segments to **every** series. Use the
+ * `'default'` key to target all series at once.
  *
- * - **Array form** (`Segment<TStyle>[]`): segments are applied to **all** series
- *   (or to the implicit single dataset of a heatmap). Only form supported by
- *   `HeatmapPlot` / `HeatmapChart`.
- * - **Record form** (`SeriesAwareSegmentsMap<TStyle>`): each key is a series
- *   name; segments apply only to that series. Supported by line, bar, and
- *   pyramid plots; when an array is passed to those plots the same segments
- *   apply to every series.
+ * @example
+ * ```ts
+ * const group: DefaultSegmentsMap<LineSegmentStyle> = {
+ *   default: [{ areas: [{ x: { from: 2012, to: 2014 } }], style: { dots: { dotSymbol: 'circle' } } }],
+ * };
+ * ```
  */
-export type SegmentsMap<TStyle> = Segment<TStyle>[] | SeriesAwareSegmentsMap<TStyle>;
+export type DefaultSegmentsMap<TStyle> = {
+    default: Segment<TStyle>[];
+};
+/**
+ * One element of a {@link Segments} array. Either a {@link DefaultSegmentsMap}
+ * (applies its segments to every series via the `'default'` key) or a
+ * {@link SeriesAwareSegmentsMap} (applies segments only to the named series).
+ * Both forms can be mixed in the same array.
+ */
+export type SegmentsStyle<TStyle> = DefaultSegmentsMap<TStyle> | SeriesAwareSegmentsMap<TStyle>;
+/**
+ * The `segments` prop accepted by every plot kind.
+ *
+ * An array of {@link SegmentsStyle} groups processed in order. Each group maps
+ * either `'default'` (all series) or specific series names to lists of
+ * {@link Segment}s. Multiple groups let you organise segments by concern:
+ *
+ * ```ts
+ * segments: [
+ *   // Group 1 – per-series stroke colours (catch-all baseline)
+ *   { female: [{ style: { stroke: { stroke: 'steelblue' } } }],
+ *     male:   [{ style: { stroke: { stroke: 'tomato'    } } }] },
+ *   // Group 2 – shared dot symbols for every series
+ *   { default: [{ areas: [{ x: { from: 2012, to: 2014 } }], style: { dots: { dotSymbol: 'circle' } } }] },
+ * ]
+ * ```
+ *
+ * Within each resolved series list, catch-alls (no `areas`) are evaluated last
+ * so that area-specific segments always override them, regardless of position.
+ */
+export type Segments<TStyle> = SegmentsStyle<TStyle>[];
 /** One contiguous, styled slice of a series' data — ready to draw as its own mark. */
 export type VisualSegment<T extends Record<string, unknown>, TStyle = LineSegmentStyle> = {
     data: T[];

package/package.json

@@ -1,77 +1,76 @@
 {
-	"name": "@fundar/data-chart-telling",
-	"version": "0.0.3",
-	"type": "module",
-	"scripts": {
-		"build": "svelte-package",
-		"prepack": "svelte-package && publint",
-		"check": "svelte-check --tsconfig ./tsconfig.json",
-		"check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
-		"lint": "prettier --check . && eslint .",
-		"format": "prettier --write .",
-		"test": "vitest run --project=unit --project=browser",
-		"test:stories": "vitest run --project=storybook",
-		"storybook": "storybook dev -p 6006",
-		"build-storybook": "storybook build"
-	},
-	"files": [
-		"dist"
-	],
-	"sideEffects": [
-		"**/*.css"
-	],
-	"svelte": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"svelte": "./dist/index.js",
-			"default": "./dist/index.js"
-		}
-	},
-	"dependencies": {
-		"d3-interpolate": "^3.0.1"
-	},
-	"peerDependencies": {
-		"svelte": "^5.0.0",
-		"svelteplot": "^0.14.0"
-	},
-	"devDependencies": {
-		"@eslint/compat": "^2.0.4",
-		"@eslint/js": "^10.0.1",
-		"@sveltejs/package": "^2.5.7",
-		"@sveltejs/vite-plugin-svelte": "^7.0.0",
-		"@types/d3-interpolate": "^3.0.4",
-		"@types/node": "^22",
-		"@vitest/browser": "^4.1.7",
-		"@vitest/browser-playwright": "^4.1.7",
-		"eslint": "^10.2.0",
-		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-svelte": "^3.17.0",
-		"globals": "^17.4.0",
-		"playwright": "^1.60.0",
-		"prettier": "^3.8.1",
-		"prettier-plugin-svelte": "^3.5.1",
-		"publint": "^0.3.18",
-		"svelte": "^5.55.2",
-		"svelte-check": "^4.4.6",
-		"svelteplot": "^0.14.0",
-		"typescript": "^6.0.2",
-		"typescript-eslint": "^8.58.1",
-		"vite": "^8.0.7",
-		"vitest": "^4.1.3",
-		"vitest-browser-svelte": "^2.1.1",
-		"storybook": "^10.4.1",
-		"@storybook/svelte-vite": "^10.4.1",
-		"@storybook/addon-svelte-csf": "^5.1.2",
-		"@chromatic-com/storybook": "^5.2.1",
-		"@storybook/addon-vitest": "^10.4.1",
-		"@storybook/addon-a11y": "^10.4.1",
-		"@storybook/addon-docs": "^10.4.1",
-		"eslint-plugin-storybook": "^10.4.1",
-		"@vitest/coverage-v8": "4.1.7"
-	},
-	"keywords": [
-		"svelte"
-	]
-}
+  "name": "@fundar/data-chart-telling",
+  "version": "0.0.5",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "d3-interpolate": "^3.0.1"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0",
+    "svelteplot": "^0.14.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.0.4",
+    "@eslint/js": "^10.0.1",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@types/d3-interpolate": "^3.0.4",
+    "@types/node": "^22",
+    "@vitest/browser": "^4.1.7",
+    "@vitest/browser-playwright": "^4.1.7",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-svelte": "^3.17.0",
+    "globals": "^17.4.0",
+    "playwright": "^1.60.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-svelte": "^3.5.1",
+    "publint": "^0.3.18",
+    "svelte": "^5.55.2",
+    "svelte-check": "^4.4.6",
+    "svelteplot": "^0.14.0",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
+    "vite": "^8.0.7",
+    "vitest": "^4.1.3",
+    "vitest-browser-svelte": "^2.1.1",
+    "storybook": "^10.4.1",
+    "@storybook/svelte-vite": "^10.4.1",
+    "@storybook/addon-svelte-csf": "^5.1.2",
+    "@chromatic-com/storybook": "^5.2.1",
+    "@storybook/addon-vitest": "^10.4.1",
+    "@storybook/addon-a11y": "^10.4.1",
+    "@storybook/addon-docs": "^10.4.1",
+    "eslint-plugin-storybook": "^10.4.1",
+    "@vitest/coverage-v8": "4.1.7"
+  },
+  "keywords": [
+    "svelte"
+  ],
+  "scripts": {
+    "build": "svelte-package",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
+    "lint": "prettier --check . && eslint .",
+    "format": "prettier --write .",
+    "test": "vitest run --project=unit --project=browser",
+    "test:stories": "vitest run --project=storybook",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  }
+}