@fundar/data-chart-telling 0.0.63 → 1.0.0

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

@@ -0,0 +1,48 @@
+import type { AxisValue } from './mapping';
+/**
+ * How the hover highlight finds related points within a facet.
+ * - `'x'` all points sharing the hovered x (default for line / bar).
+ * - `'y'` all points sharing the hovered y (default for pyramid).
+ * - `'punctual'` exact XY match - one cell at a time (default for heatmap).
+ * - `'series'` all points sharing the hovered series, regardless of x/y.
+ */
+export type HoverStrategy = 'x' | 'y' | 'punctual' | 'series';
+/** Hover state shared by every plot under one figure - see `HoverState`. */
+export type HoverStore = {
+    activeX: AxisValue | null;
+    activeY: AxisValue | null;
+    /** Series of the hovered row, when the plot kind has a series concept (line/bar). */
+    activeSeries: string | null;
+    /** The cursor's position in the source plot's box, as fractions of its width and height. */
+    cursorFrac: {
+        x: number;
+        y: number;
+    } | null;
+    /** Facet id that currently owns the hover (`''` when not faceted). */
+    source: string | null;
+    /** How related points are found within a facet. */
+    strategy: HoverStrategy;
+    /** Whether the hover is broadcast to other facets. */
+    sync: boolean;
+};
+/** A slice of a category band, as start/end fractions (0-1) of the whole band. */
+export type BandSlice = {
+    start: number;
+    end: number;
+};
+/** A point ready to render: its plotted position plus its label. */
+export type HoverDisplayPoint = {
+    x: AxisValue;
+    y: AxisValue;
+    label: string;
+    /** Owning series name; undefined for plot kinds with no series concept (heatmap). */
+    series?: string;
+    /** Resolved series color - used by HoverMarker when dotFill/fill is `'currentColor'`. */
+    color?: string;
+    /** A 'grouped' series' own slice of the category band, as start/end fractions (0-1) of the whole band. `undefined` means the whole band. */
+    areaInset?: BandSlice;
+};
+/** A candidate point for hover matching/highlighting - also carries its source row. */
+export type HoverPoint<T> = HoverDisplayPoint & {
+    row: T;
+};

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

@@ -1,14 +1,12 @@
 import type { Snippet } from 'svelte';
-import type { SvelteMap } from 'svelte/reactivity';
 import type { SymbolType, LineStyle } from '../plots/constants';
 import type { StrokeStyle, DotStyle } from '../plots/styling';
-export type LegendSectionType = 'discrete' | 'continuous';
+import type { ColorScaleConfig, OpacityScaleConfig, SymbolScaleConfig } from './scales';
+export type LegendSectionType = 'discrete' | 'continuous' | 'size' | 'symbol';
 /**
- * Style applied to whatever a legend interaction has turned "off" — a
- * toggled-off discrete series, or a datapoint/cell/feature outside an active
- * continuous range filter. `opacity` is a blanket convenience: any
- * `*Opacity` field a consumer doesn't set falls back to it, so
- * `{ opacity: 0.1 }` alone is enough to read as "disabled" everywhere.
+ * Style for whatever a legend has turned off: a toggled-off series, or a row
+ * outside a continuous range. `opacity` is the fallback for every
+ * `*Opacity` field left unset.
  */
 export type LegendDisabledStyle = {
     opacity?: number;
@@ -17,10 +15,17 @@ export type LegendDisabledStyle = {
     fill?: string;
     fillOpacity?: number;
 };
-/** What a legend toggle does to a series once it's off: `'style'` dims it in place, `'omit'` removes it from the plot entirely. */
+/**
+ * What a legend toggle does to a series once it's off: `'dim'` dims it in
+ * place (styled by `style`), `'hide'` makes it fully transparent while the
+ * axes keep its range, `'omit'` removes it from the plot entirely, rescaling
+ * the axes to what's left.
+ */
 export type LegendDisabledAction = {
-    mode: 'style';
+    mode: 'dim';
     style?: LegendDisabledStyle;
+} | {
+    mode: 'hide';
 } | {
     mode: 'omit';
 };
@@ -29,21 +34,25 @@ export type LegendItem = {
     label?: string;
     color?: string;
     symbol?: SymbolType;
+    /** Whether the symbol is filled, or drawn as an outline. Defaults to `true`. */
+    filled?: boolean;
     opacity?: number;
     lineStyle?: LineStyle;
-    /** Initial toggled-off state (uncontrolled — the user can still click it back on). */
+    /** Initial toggled-off state (uncontrolled - the user can still click it back on). */
     disabled?: boolean;
 };
 /**
- * How a discrete section's items flow. `'vertical'` stacks them in a
- * `columns`-wide grid; `'horizontal'` flows them left to right, paginating
- * past `maxRows` (default 1) with prev/next arrows.
+ * How a discrete section's items flow: `'vertical'` in a `columns`-wide grid,
+ * `'horizontal'` in rows paginated past `maxRows` (default 1), `'flex'` in
+ * wrapping rows.
  */
 export type LegendItemsLayout = {
     type: 'vertical';
 } | {
     type: 'horizontal';
     maxRows?: number;
+} | {
+    type: 'flex';
 };
 export type LegendNavDirection = 'prev' | 'next';
 export type LegendNavContext = {
@@ -65,14 +74,7 @@ export type LegendHandleContext = {
 };
 /** Custom drag-handle renderer for an interactive continuous section. */
 export type LegendHandleSnippet = Snippet<[LegendHandleContext]>;
-/**
- * Item look for an interactive discrete section. `'badge'` (the default once
- * `interactive.enabled` is on) draws each item as a pill filled with its
- * series color, with the symbol icon and label auto-contrasted against that
- * fill and an eye icon on the right — crossed out once the item is toggled
- * off. `'basic'` keeps the plain swatch + label, same as a non-interactive
- * section.
- */
+/** Item look of an interactive discrete section: `'badge'` (default) pills with an eye toggle, or `'basic'` swatches. */
 export type LegendInteractiveStyle = 'badge' | 'basic';
 /** Click-to-toggle configuration for a discrete section: whether it's on, how toggled items look, and the style applied to a toggled-off one. */
 export type DiscreteInteractiveConfig = {
@@ -80,7 +82,7 @@ export type DiscreteInteractiveConfig = {
     enabled?: boolean;
     /** Item look while `enabled`. Defaults to `'badge'`. */
     legendStyle?: LegendInteractiveStyle;
-    /** What happens to a toggled-off item. Defaults to `{ mode: 'style' }`. */
+    /** What happens to a toggled-off item. Defaults to `{ mode: 'dim' }`. */
     disabled?: LegendDisabledAction;
     /** Shows the symbol icon inside a `'badge'` pill. Defaults to `true`; ignored by `'basic'`, which always shows it. */
     showIcon?: boolean;
@@ -99,11 +101,7 @@ export type DiscreteLegendSection = {
 export type ContinuousInteractiveConfig = {
     /** Turns drag-to-narrow on, adding lo/hi handles at the edges of the excluded range. */
     enabled?: boolean;
-    /**
-     * How the color ramp responds to a narrowed range: `'rescale'` reprojects
-     * it onto the new bounds, `'filter'` keeps the original domain and only
-     * excludes out-of-range values. Defaults to `'filter'`.
-     */
+    /** `'rescale'` refits the color ramp to the narrowed range; `'filter'` (default) keeps it and hides what's outside. */
     mode?: 'rescale' | 'filter';
     /** Style applied to the excluded (narrowed-out) range. Defaults to `{ opacity: cfg.legend.disabledOpacity }`. */
     disabledStyle?: LegendDisabledStyle;
@@ -118,38 +116,244 @@ export type ContinuousLegendSection = {
     max: number;
     colorMin?: string;
     colorMax?: string;
+    /** A named ramp (e.g. `'turbo'`) or 2+ colors to draw the bar in, over `colorMin`/`colorMax`. */
+    scheme?: string | string[];
+    /** Splits an array `scheme` into two halves meeting at this value (diverging). */
+    pivot?: number;
+    /** Draws the bar in one color (`colorMin`, the text color by default) fading across this opacity range, instead of a color ramp. */
+    opacity?: [number, number];
     ticks?: number[];
     width?: number;
     format?: (v: number) => string;
     interactive?: ContinuousInteractiveConfig;
 };
-export type LegendSection = DiscreteLegendSection | ContinuousLegendSection;
 /**
- * Shared legend-interaction state for cross-cutting legend → plot wiring.
- *
- * {@link BaseChart} provides one store via context (mirrors {@link HoverStore});
- * `DiscreteSection`/`ContinuousSection` write to it on click/drag, and every
- * plot kind (line/bar/pyramid/heatmap/geo) reads the same instance to know
- * what to dim. A standalone legend/plot with no provider falls back to its
- * own private store via `createLegendInteraction`.
+ * A continuous size scale - the `r` channel of a plot's dots: a few dots of
+ * the radius each value draws at, its value under each. `domain` maps to
+ * `range` (px) on a square-root scale, so a dot's area follows its value.
+ */
+export type SizeLegendSection = {
+    type: 'size';
+    title?: string;
+    columns?: number;
+    domain: [number, number];
+    range: [number, number];
+    /** The values shown, one dot each. Defaults to a few round values across `domain`. */
+    values?: number[];
+    /** The dots' color. Defaults to the text color. */
+    color?: string;
+    /** Whether the dots are filled, or drawn as rings. Defaults to `true`. */
+    filled?: boolean;
+    /** The dots' shape. Defaults to `'circle'`. */
+    symbol?: SymbolType;
+    /** How each value reads. Defaults to the axes' own format (`axis.locale`, `axis.compactDisplay`). */
+    format?: (v: number) => string;
+};
+/**
+ * A categorical shape scale - the `symbol` channel of a plot's dots: each
+ * category next to the shape it draws as. Unlike a discrete section, its
+ * items name categories, not series, so they never toggle.
+ */
+export type SymbolLegendSection = {
+    type: 'symbol';
+    title?: string;
+    columns?: number;
+    /** Item flow direction, as in a discrete section. */
+    layout?: LegendItemsLayout;
+    items: {
+        name: string;
+        label?: string;
+        symbol: SymbolType;
+    }[];
+    /** The shapes' color. Defaults to the text color. */
+    color?: string;
+    /** Whether the shapes are filled, or drawn as outlines. Defaults to `true`. */
+    filled?: boolean;
+};
+export type LegendSection = DiscreteLegendSection | ContinuousLegendSection | SizeLegendSection | SymbolLegendSection;
+/** The narrowed range of an interactive continuous section: rows outside it dim, or the ramp refits to it. */
+export type LegendRange = {
+    min: number;
+    max: number;
+    mode: 'rescale' | 'filter';
+    disabledStyle: LegendDisabledStyle;
+};
+/** How a series draws, as a legend shows it: the plot's own mark for it. */
+export type LegendMark = 'line' | 'dot' | 'area' | 'bar' | 'cell' | 'rect' | 'geo';
+/**
+ * What a plot draws that a legend can show - registered on the figure's
+ * `LegendState` as the plot resolves: a series (its name, color and how it
+ * draws), a segment or marker that names itself on the legend (`'mark'`), a
+ * continuous color scale (the domain its colors span), the opacity scale
+ * its marks fade across, the size scale its
+ * dots' `r` channel draws with, or the shapes its dots' `symbol` channel
+ * draws each category as.
  */
-export type LegendInteractionStore = {
-    /** Legend item name → action to apply. Presence in the map means "disabled". */
-    disabledSeries: SvelteMap<string, LegendDisabledAction>;
-    /**
-     * The active drag state of the (first) interactive continuous section, or
-     * `null` when none is interactive or the user hasn't narrowed it yet (full
-     * range — nothing hidden).
-     */
-    continuousRange: {
-        min: number;
-        max: number;
-        mode: 'rescale' | 'filter';
-        disabledStyle: LegendDisabledStyle;
-    } | null;
-};
-/** Read-only view of which series a legend has toggled off, resolved from {@link BaseChart}'s legend-interaction store. */
-export type LegendPlotContext = {
-    disabledSeries: ReadonlySet<string>;
-    isDisabled: (name: string) => boolean;
+export type LegendEntry = {
+    type: 'series' | 'mark';
+    name: string;
+    label?: string;
+    color?: string;
+    mark?: LegendMark;
+    symbol?: SymbolType;
+    filled?: boolean;
+    lineStyle?: LineStyle;
+} | {
+    type: 'size';
+    channel: 'r';
+    title?: string;
+    domain: [number, number];
+    range: [number, number];
+    color?: string;
+    filled: boolean;
+    symbol?: SymbolType;
+} | {
+    type: 'symbol';
+    channel: 'symbol';
+    title?: string;
+    items: {
+        name: string;
+        symbol: SymbolType;
+    }[];
+    color?: string;
+    filled: boolean;
+} | {
+    type: 'scale';
+    channel: 'color';
+    title?: string;
+    min: number;
+    max: number;
+    colorMin?: string;
+    colorMax?: string;
+    scheme?: string | string[];
+    pivot?: number;
+} | {
+    type: 'opacity';
+    channel: 'opacity';
+    title?: string;
+    min: number;
+    max: number;
+    /** The opacity at `min` and at `max`. */
+    opacityMin: number;
+    opacityMax: number;
+    /** The color the marks draw in. Defaults to the text color. */
+    color?: string;
+};
+/**
+ * How a segment or marker shows on its plot's automatic legend: its label, or
+ * the item itself. What the item leaves out - its color, its symbol, its line
+ * style - comes from how the segment or marker draws.
+ */
+export type MarkLegend = string | (Omit<LegendItem, 'name' | 'disabled'> & {
+    label: string;
+});
+/** What a legend reads each automatic section from: the series, or the channel a scale encodes. */
+export type LegendChannel = 'series' | 'color' | 'opacity' | 'size' | 'symbol';
+/**
+ * How to adjust one automatic section: its own configuration, minus what the
+ * plots compute for it. An entry with a `match` (one, or several in a list) adjusts
+ * only the sections titled so - by the field or function name, or as the
+ * legend shows it - and one without adjusts all of that channel's.
+ */
+export type LegendOverride<TSection extends {
+    type: string;
+}, TComputed extends string> = (Omit<TSection, 'type' | TComputed> & {
+    match?: string;
+}) | (Omit<TSection, 'type' | TComputed> & {
+    match?: string;
+})[];
+/**
+ * How to adjust what a `color` channel draws: the continuous section of a
+ * numeric one, or the discrete section of series a categorical one makes. It
+ * takes what both sections share, plus each one's own - what a section lacks
+ * is ignored. `interactive` takes either section's options.
+ */
+export type ColorOverride = Omit<ContinuousLegendSection, 'type' | 'min' | 'max' | 'colorMin' | 'colorMax' | 'scheme' | 'pivot' | 'opacity' | 'interactive'> & Pick<DiscreteLegendSection, 'layout' | 'navButton'> & {
+    interactive?: ContinuousInteractiveConfig & DiscreteInteractiveConfig;
+    /** Adjusts only the continuous section titled so. */
+    match?: string;
+};
+/**
+ * What a figure adds to, or changes in, its automatic legend, keeping what
+ * its plots read as: `items` after the plots' own series, in the same
+ * section, `sections` after the automatic ones, and one key per channel to
+ * adjust the section that channel draws - `series` the discrete section,
+ * `color` and `opacity` the continuous ones, `size` and `symbol` theirs. A
+ * categorical `color` is the series, so `color` adjusts the discrete section
+ * too (`series` wins where both set the same). Only `color` can make a
+ * ramp `interactive`, and only its first ramp is.
+ */
+export type LegendExtension = {
+    items?: LegendItem[];
+    sections?: LegendSection[];
+    series?: Omit<DiscreteLegendSection, 'type' | 'items'>;
+    color?: ColorOverride | ColorOverride[];
+    opacity?: LegendOverride<ContinuousLegendSection, 'min' | 'max' | 'colorMin' | 'colorMax' | 'scheme' | 'pivot' | 'opacity' | 'interactive'>;
+    size?: LegendOverride<SizeLegendSection, 'domain' | 'range' | 'color' | 'filled' | 'symbol'>;
+    symbol?: LegendOverride<SymbolLegendSection, 'items' | 'color' | 'filled'>;
+};
+/** A segment or marker as the legend reads it: whether it names itself, the channels it draws with and the colors it draws in. */
+export type LegendSource = {
+    type?: string;
+    series?: string;
+    data?: unknown[];
+    color?: unknown;
+    opacity?: unknown;
+    r?: unknown;
+    symbol?: unknown;
+    scales?: {
+        color?: ColorScaleConfig;
+        opacity?: OpacityScaleConfig;
+        symbol?: SymbolScaleConfig;
+    };
+    legend?: MarkLegend;
+    fill?: unknown;
+    stroke?: unknown;
+    styles?: {
+        fill?: unknown;
+        stroke?: unknown;
+        dotFill?: unknown;
+        dotStroke?: unknown;
+        dotSymbol?: unknown;
+        strokeDasharray?: unknown;
+    };
+};
+/** What a plot hands the legend to read its entries from. */
+export type LegendPlot = {
+    resolvedSeries?: {
+        name: string;
+    }[];
+    colorForSeries?: (name: string) => string;
+    markers?: LegendSource[];
+    segments?: Record<string, LegendSource[] | undefined>;
+    /** The `[min, max]` a plot-level color ramp spans, when the plot has no `color` channel to read it from. */
+    colorDomain?: [number, number];
+    /** The `[min, max]` of a plot-level numeric `opacity` channel. */
+    opacityDomain?: [number, number];
+    channels?: {
+        r?: {
+            source?: unknown;
+        };
+        symbol?: {
+            source?: unknown;
+        };
+        color?: {
+            source?: unknown;
+        };
+        opacity?: {
+            source?: unknown;
+        };
+    };
+    scales?: {
+        r?: {
+            domain?: [number, number];
+            range?: [number, number];
+        };
+        color?: {
+            domain?: unknown;
+            scheme?: unknown;
+            pivot?: number;
+        };
+        opacity?: OpacityScaleConfig;
+    };
 };

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

@@ -0,0 +1,68 @@
+import type { Accessor } from '../plots/data/common';
+export type AxisValue = number | string | Date;
+/**
+ * Every channel a plot maps from its rows, and what its accessor yields per
+ * row. Every channel is available on every plot kind; a kind with no use for
+ * one ignores it.
+ */
+export type ChannelValue = {
+    /** Horizontal position - configure its axis via `scales.x`. */
+    x: AxisValue;
+    /** Vertical position - configure its axis via `scales.y`. */
+    y: AxisValue;
+    /**
+     * Splits `data` into one series per distinct value - the structural
+     * grouping key. Defaults to `color` when omitted, so a single `color`
+     * accessor groups *and* colors series; pass both to split by one field
+     * while coloring by another.
+     */
+    grouping: unknown;
+    /**
+     * Color value - splits `data` into one series per distinct value when
+     * `grouping` is unset. Configure the ramp via `scales.color`.
+     */
+    color: unknown;
+    /** Continuous or categorical opacity value - configure the ramp via `scales.opacity`. */
+    opacity: unknown;
+    /** Categorical shape value - configure the mapping via `scales.symbol`. */
+    symbol: unknown;
+    /**
+     * Radius - bound to an auto sqrt scale, so *area* ends up proportional to
+     * the raw values (an already-scaled value gets double-scaled). A literal
+     * number is a fixed pixel radius instead. Configure via `scales.r`.
+     */
+    r: number;
+    /** Vector/spike magnitude - a literal number is a fixed pixel length. Configure via `scales.length`. */
+    length: number;
+};
+/** Every channel a plot maps from its rows. */
+export type ChannelName = keyof ChannelValue;
+/** The position channels, each bound to the one axis scale every mark shares. */
+export type AxisChannelName = 'x' | 'y';
+/**
+ * The channels each consumer scales on its own - a plot's `scales.color` and
+ * a marker's own `scales.color` can disagree on purpose.
+ */
+export type IndependentChannelName = 'color' | 'grouping' | 'opacity' | 'symbol';
+/** The size channels, which also take a literal number as a fixed pixel size that bypasses their scale. */
+export type SizeChannelName = 'r' | 'length';
+/** Every channel as a plot prop: a field key or accessor function (or a literal size, for a size channel). */
+export type ChannelAccessors<TData extends Record<string, unknown>> = {
+    [K in keyof ChannelValue]?: Accessor<TData, ChannelValue[K]> | (K extends SizeChannelName ? number : never);
+};
+/** One channel's own resolved data accessor - mirrors svelteplot's own `ChannelAccessor`. */
+export type ResolvedChannel<TData, TValue = AxisValue> = {
+    accessor: (row: TData) => TValue;
+    /** The channel as given - a field key or a function - unset when the channel falls back to a default. */
+    source?: string | ((row: TData) => TValue);
+};
+/**
+ * Every channel as the "mapping" phase resolves it. `x`/`y` are always
+ * resolved; any other channel only when its prop is set, and a size channel
+ * stays a literal number when given one.
+ */
+export type ResolvedChannels<TData> = {
+    [K in keyof ChannelValue]?: ResolvedChannel<TData, ChannelValue[K]> | (K extends SizeChannelName ? number : never);
+} & {
+    [K in AxisChannelName]: ResolvedChannel<TData, ChannelValue[K]>;
+};

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

@@ -0,0 +1,41 @@
+import type { Snippet } from 'svelte';
+import type { TimeValue } from './timeline';
+import type { GridPlacement } from './grid';
+import type { MarginConfig, TooltipConfig } from '../plots/props';
+/** Where one cell sits among the slices: the timeline step and the facet it shows. */
+export type SlicePlace = {
+    time?: TimeValue;
+    facet?: {
+        facetValue: string;
+        row?: string;
+        col?: string;
+    };
+};
+/** What `Plot` hands each core it renders: one slice's rows and box. */
+export type PlotCellContext<TRow extends Record<string, unknown>, TScales extends object = object> = {
+    /** This slice's rows - `undefined` when the plot draws from pre-built `series`. */
+    data: TRow[] | undefined;
+    width: number;
+    height: number;
+    /** Shared margin for every facet, when the facet config sizes one. */
+    margins?: MarginConfig;
+    tooltip?: TooltipConfig<TRow>;
+    /** Scales every slice shares, to merge under the author's own. */
+    scales?: TScales;
+    /** This slice's facet panel, as a {@link Pipeline.runData} over every panel resolved it. */
+    panel?: object;
+    /** 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;
+};
+export type PlotCellSnippet<TRow extends Record<string, unknown>, TScales extends object = object> = Snippet<[PlotCellContext<TRow, TScales>]>;
+/** What `Plot` reads off a plot kind's core props. */
+export type PlotCoreBase = GridPlacement & {
+    width: number;
+    height: number;
+    data?: unknown;
+    markers?: {
+        type: string;
+    }[];
+    scales?: object;
+    margins?: MarginConfig;
+};