@fundar/data-chart-telling 0.0.1

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

@@ -0,0 +1,176 @@
+import type { AxisValue, Series } from './common';
+/**
+ * Unified positional anchor for value labels across all plot kinds.
+ *
+ * - `'outside'` — beyond the tip of the mark (above a vertical bar, to the
+ *   far end of a horizontal bar or line). This is the only value with no
+ *   direct svelteplot equivalent; the plot computes dx/dy internally.
+ * - `'start'` — at the tip of the mark, just inside (top of a bar, far end
+ *   of a pyramid bar from zero, right of a line's last point).
+ * - `'middle'` — centred on the mark.
+ * - `'end'` — at the baseline/zero end of the mark.
+ */
+export type ValueAnchor = 'outside' | 'start' | 'middle' | 'end';
+/**
+ * Controls if and how value labels are rendered on a plot. The high-level
+ * `anchor` sets sensible defaults for placement; the low-level svelteplot
+ * Text-mark fields (`dx`, `dy`, `textAnchor`, `lineAnchor`, `lineHeight`,
+ * `rotate`, `class`, `textClass`) override those defaults when provided.
+ */
+export type ValuesStyle = {
+    show?: boolean;
+    anchor?: ValueAnchor;
+    /** Called with the numeric value and the series name. Return a string to render. */
+    format?: (value: number, seriesName: string) => string;
+    dx?: number;
+    dy?: number;
+    textAnchor?: 'start' | 'end' | 'middle';
+    lineAnchor?: 'top' | 'bottom' | 'middle';
+    lineHeight?: number;
+    rotate?: number;
+    class?: string;
+    textClass?: string;
+};
+/**
+ * Color overrides for plots that derive their palette from data.
+ * Each plot uses only the fields relevant to its kind; unused fields are
+ * silently ignored.
+ *
+ * - `min` / `max` — sequential colour ramp endpoints (heatmap).
+ * - `left` / `right` — diverging bar sides (pyramid).
+ */
+export type ColorsStyle = {
+    min?: string;
+    max?: string;
+    left?: string;
+    right?: string;
+};
+/**
+ * Top-level rendering style overrides shared by all plot kinds. Passed as the
+ * `styles` prop. Each plot reads only the fields it cares about.
+ */
+export type PlotStyles = {
+    values?: ValuesStyle;
+    colors?: ColorsStyle;
+};
+export type SymbolType = 'circle' | 'square' | 'triangle' | 'line';
+export type LineStyle = 'solid' | 'dashed' | 'dotted' | 'dashdot';
+export type LineCap = 'butt' | 'round' | 'square';
+export type LineJoin = 'arcs' | 'bevel' | 'miter' | 'miter-clip' | 'round';
+/** Stroke styling for any line-ish mark — a line, a rule, a marker's connector. */
+export type StrokeStyle = {
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    strokeDasharray?: string | LineStyle;
+    strokeLinecap?: LineCap;
+    strokeLinejoin?: LineJoin;
+};
+/**
+ * Dot styling for any point mark — a line's endpoint dots, a marker's dot.
+ * Carries its own `dotStroke*` fields rather than nesting a {@link StrokeStyle},
+ * because a dot's outline is a distinct style from the stroke of the line (or
+ * other mark) it sits next to — e.g. a {@link LineSegmentStyle} styles its
+ * line's stroke and its dots' outline independently.
+ */
+export type DotStyle = {
+    dotRadius?: number;
+    dotFill?: string;
+    dotFillOpacity?: number;
+    dotSymbol?: SymbolType;
+    dotStroke?: string;
+    dotStrokeWidth?: number;
+    dotStrokeOpacity?: number;
+    dotStrokeDasharray?: string | LineStyle;
+};
+/** Text/label styling for any text mark — a marker's label, an annotation. */
+export type FontStyle = {
+    fill?: string;
+    fontSize?: number;
+    fontWeight?: 'normal' | 'bold';
+    fontStyle?: 'normal' | 'italic';
+    textAnchor?: 'start' | 'middle' | 'end';
+    lineAnchor?: 'top' | 'middle' | 'bottom';
+    stroke?: string;
+    strokeWidth?: number;
+    paintOrder?: string;
+    dx?: number;
+    dy?: number;
+};
+/** Per-segment styling for a line: its stroke and/or its endpoint dots. */
+export type LineSegmentStyle = {
+    stroke?: StrokeStyle;
+    dots?: DotStyle;
+};
+/** Per-segment styling for a bar: its fill. */
+export type BarSegmentStyle = {
+    fill?: string;
+    fillOpacity?: number;
+};
+/** Per-cell styling override for a heatmap cell. */
+export type CellSegmentStyle = {
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+};
+/** A half-open interval on one axis. Both bounds are inclusive; omit either to leave that end open. */
+export type Range = {
+    from?: AxisValue;
+    to?: AxisValue;
+};
+/**
+ * A 2-D rectangular area on the plot, addressed by optional x and y intervals.
+ * Omitting an interval leaves that axis unrestricted (matches all values).
+ *
+ * - For line/bar/pyramid plots only the `x` interval is used (the series' primary
+ *   axis); `y` is evaluated but filters by the series' value axis.
+ * - For heatmaps both `x` (column) and `y` (row) are used to address cells.
+ */
+export type Area = {
+    x?: Range;
+    y?: Range;
+};
+/**
+ * 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}, …).
+ *
+ * Segments are applied in order; later ones are rendered on top of earlier ones.
+ */
+export type Segment<TStyle> = {
+    areas?: Area[];
+    style?: 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.
+ *
+ * - **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.
+ */
+export type SegmentsMap<TStyle> = Segment<TStyle>[] | SeriesAwareSegmentsMap<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[];
+    style: TStyle;
+};
+/**
+ * A series split into its styled visual segments. `S` is the full series
+ * type Series<T> — its row type is read off `S['data']`
+ * rather than taken as a separate parameter, since TypeScript can't reliably
+ * infer a type parameter that only appears inside another parameter's
+ * constraint.
+ */
+export type VisualGroup<S extends Series<any>, TStyle = LineSegmentStyle> = {
+    series: S;
+    visualSegments: VisualSegment<S['data'][number], TStyle>[];
+};

package/dist/types/plots/styles.js

@@ -0,0 +1 @@
+export {};

package/dist/types/viewport.d.ts

@@ -0,0 +1,4 @@
+export type Viewport = {
+    width: number;
+    height: number;
+};

package/dist/types/viewport.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/color.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveCssColor(color: string): string;
+export declare function normalize(v: number, min: number, max: number): number;
+/** Cycles through a discrete palette by series index — the default colour for an unstyled series. */
+export declare function paletteColor(index: number, palette: string[]): string;
+export declare function makeColorScale(min: number, max: number, colorMin: string, colorMax: string): (v: number) => string;

package/dist/utils/color.js

@@ -0,0 +1,42 @@
+import { interpolateRgb } from 'd3-interpolate';
+import { isBrowser } from '../stores/device';
+export function resolveCssColor(color) {
+    if (!isBrowser)
+        return color;
+    if (!color.startsWith('var('))
+        return color;
+    const varName = color.slice(4, -1).trim();
+    const value = getComputedStyle(document.documentElement)
+        .getPropertyValue(varName)
+        .trim();
+    return value || color;
+}
+export function normalize(v, min, max) {
+    if (v == null)
+        return 0;
+    const denom = max - min || 1;
+    return Math.max(0, Math.min(1, (v - min) / denom));
+}
+/** Cycles through a discrete palette by series index — the default colour for an unstyled series. */
+export function paletteColor(index, palette) {
+    if (palette.length === 0)
+        return 'currentColor';
+    return palette[index % palette.length];
+}
+export function makeColorScale(min, max, colorMin, colorMax) {
+    const resolvedMin = resolveCssColor(colorMin);
+    const resolvedMax = resolveCssColor(colorMax);
+    let interpolator;
+    try {
+        interpolator = interpolateRgb(resolvedMin, resolvedMax);
+    }
+    catch {
+        return () => '#ccc';
+    }
+    return (v) => {
+        if (v == null)
+            return '#ccc';
+        const t = normalize(v, min, max);
+        return interpolator(t);
+    };
+}

package/dist/utils/grouping.d.ts

@@ -0,0 +1,14 @@
+import type { Series, AxisValue, Accessor } from '../types/plots/common';
+/**
+ * Splits rows into ordered groups keyed by the stringified accessor value.
+ * Insertion order of first appearance is preserved, which keeps colours stable
+ * across re-renders without forcing the caller to pre-sort.
+ */
+export declare function groupBy<TRow extends Record<string, unknown>>(data: TRow[], by: Accessor<TRow, unknown>): Map<string, TRow[]>;
+/**
+ * Adapts flat rows into the `Series[]` shape the plot expects.
+ * When `z` is given, one series is produced per group (series `name` = group
+ * value), which is exactly how the plot's `segments` map is keyed — so the
+ * caller styles each group by its `z` value.
+ */
+export declare function buildSeries<TRow extends Record<string, unknown>>(data: TRow[], x: Accessor<TRow, AxisValue>, y: Accessor<TRow, AxisValue>, z: Accessor<TRow, unknown> | undefined, defaultName?: string): Series<TRow>[];

package/dist/utils/grouping.js

@@ -0,0 +1,36 @@
+import { resolveAccessor } from '../plots/utils/accessors';
+/**
+ * Splits rows into ordered groups keyed by the stringified accessor value.
+ * Insertion order of first appearance is preserved, which keeps colours stable
+ * across re-renders without forcing the caller to pre-sort.
+ */
+export function groupBy(data, by) {
+    const get = resolveAccessor(by);
+    const groups = new Map();
+    for (const row of data) {
+        const key = String(get(row));
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(row);
+        else
+            groups.set(key, [row]);
+    }
+    return groups;
+}
+/**
+ * Adapts flat rows into the `Series[]` shape the plot expects.
+ * When `z` is given, one series is produced per group (series `name` = group
+ * value), which is exactly how the plot's `segments` map is keyed — so the
+ * caller styles each group by its `z` value.
+ */
+export function buildSeries(data, x, y, z, defaultName = 'series') {
+    if (z === undefined) {
+        return [{ name: defaultName, x, y, data }];
+    }
+    return [...groupBy(data, z).entries()].map(([name, rows]) => ({
+        name,
+        x,
+        y,
+        data: rows,
+    }));
+}

package/dist/utils/interpolate.d.ts

@@ -0,0 +1,30 @@
+import type { EasingName, EasingFn } from '../types/charts/interpolate';
+import type { TimeValue, TimelineInterpolation } from '../types/charts/common';
+import type { Accessor, AxisValue } from '../types/plots/common';
+export declare function resolveEasing(easing?: EasingName | EasingFn): EasingFn;
+/**
+ * Brackets a continuous target position `x` within one key-group's sorted
+ * rows and tweens between the two real rows it falls between — the leading
+ * edge moves continuously instead of snapping between steps. Returns every
+ * already-passed real row plus the synthetic tween row (or just the clamped
+ * first/last row when `x` is outside the group's range). A caller that wants
+ * a single replacing "frame" (e.g. a bar snapshot) takes just the last entry.
+ */
+export declare function interpolateSeries<TRow>({ rows, x, getTime, getValue, create, segmentEasing, }: {
+    rows: TRow[];
+    x: TimeValue;
+    getTime: (row: TRow) => TimeValue;
+    getValue: (row: TRow) => number;
+    create: (lower: TRow, upper: TRow, x: TimeValue, value: number) => TRow;
+    segmentEasing: EasingFn;
+}): TRow[];
+/**
+ * Resolves `TimelineConfig.interpolate` (`true` | a partial config | unset)
+ * into a fully-populated {@link TimelineInterpolation}, falling back to the
+ * chart-supplied `value`/`key` defaults — used by `LineChart`/`BarChart` so
+ * consumers can write `interpolate: true` instead of repeating their own `y`/`z`.
+ */
+export declare function resolveTimelineInterpolation<TRow extends Record<string, unknown>>(interpolate: boolean | TimelineInterpolation<TRow> | undefined, defaults: {
+    value: Accessor<TRow, AxisValue>;
+    key?: Accessor<TRow, unknown>;
+}): TimelineInterpolation<TRow> | undefined;

package/dist/utils/interpolate.js

@@ -0,0 +1,71 @@
+const EASINGS = {
+    linear: (t) => t,
+    quadIn: (t) => t * t,
+    quadOut: (t) => 1 - (1 - t) * (1 - t),
+    cubicIn: (t) => t * t * t,
+    cubicOut: (t) => 1 - Math.pow(1 - t, 3),
+    quartIn: (t) => t * t * t * t,
+    quartOut: (t) => 1 - Math.pow(1 - t, 4),
+    expoOut: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+};
+export function resolveEasing(easing) {
+    if (!easing)
+        return EASINGS.linear;
+    if (typeof easing === 'function')
+        return easing;
+    return EASINGS[easing] ?? EASINGS.linear;
+}
+/**
+ * Brackets a continuous target position `x` within one key-group's sorted
+ * rows and tweens between the two real rows it falls between — the leading
+ * edge moves continuously instead of snapping between steps. Returns every
+ * already-passed real row plus the synthetic tween row (or just the clamped
+ * first/last row when `x` is outside the group's range). A caller that wants
+ * a single replacing "frame" (e.g. a bar snapshot) takes just the last entry.
+ */
+export function interpolateSeries({ rows, x, getTime, getValue, create, segmentEasing, }) {
+    if (!rows.length)
+        return [];
+    const sorted = [...rows].sort((a, b) => Number(getTime(a)) - Number(getTime(b)));
+    if (x <= getTime(sorted[0]))
+        return [sorted[0]];
+    const result = [];
+    for (let i = 0; i < sorted.length - 1; i++) {
+        const d0 = sorted[i];
+        const d1 = sorted[i + 1];
+        const t0 = getTime(d0);
+        const t1 = getTime(d1);
+        if (x >= t1) {
+            result.push(d0);
+            continue;
+        }
+        if (x >= t0 && x < t1) {
+            const tRaw = (Number(x) - Number(t0)) / (Number(t1) - Number(t0));
+            const t = segmentEasing(tRaw);
+            const value = getValue(d0) + (getValue(d1) - getValue(d0)) * t;
+            result.push(d0);
+            result.push(create(d0, d1, x, value));
+            return result;
+        }
+    }
+    const last = sorted[sorted.length - 1];
+    if (x >= getTime(last))
+        result.push(last);
+    return result;
+}
+/**
+ * Resolves `TimelineConfig.interpolate` (`true` | a partial config | unset)
+ * into a fully-populated {@link TimelineInterpolation}, falling back to the
+ * chart-supplied `value`/`key` defaults — used by `LineChart`/`BarChart` so
+ * consumers can write `interpolate: true` instead of repeating their own `y`/`z`.
+ */
+export function resolveTimelineInterpolation(interpolate, defaults) {
+    if (!interpolate)
+        return undefined;
+    const config = interpolate === true ? {} : interpolate;
+    return {
+        ...config,
+        value: config.value ?? defaults.value,
+        key: config.key ?? defaults.key,
+    };
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@fundar/data-chart-telling",
+  "version": "0.0.1",
+  "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"
+  }
+}