@fundar/data-chart-telling 1.0.0 → 1.2.0

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

@@ -1,122 +0,0 @@
-import type { ValueAnchor } from '../plots/constants';
-import type { FontStyle, StrokeStyle, AreaStyle } from '../plots/styling';
-import type { GeoFeature } from '../plots/data/geo';
-import type { GapsConfig } from '../plots/gaps';
-/**
- * Controls if and how value labels are rendered on a plot, drawn as a `text`
- * marker over the rows the plot itself draws (after its own `transforms`):
- * one at the end of each series on a line or area plot, one per bar on a bar,
- * pyramid or histogram plot, one per point on a scatter plot and one per cell
- * on a heatmap. The high-level `anchor` sets sensible defaults for placement;
- * `fontStyle` (`dx`, `dy`, `textAnchor`, `lineAnchor`, `lineHeight`, `rotate`,
- * `class`, `textClass`, `fill`, …) overrides those defaults field-by-field when
- * provided - mirrors {@link DeltaConfig}'s `fontStyle`/`strokeStyle` split, so
- * label text and connector-line styling never mix into one flat bag of props.
- */
-export type ValuesStyle = {
-    /** Whether the labels are drawn. Off by default, except on a heatmap. */
-    show?: boolean;
-    /** Where each label sits on its mark - see {@link ValueAnchor}. */
-    anchor?: ValueAnchor;
-    /** A label's text, from its row's own value (a histogram bin's count) and its series. */
-    format?: (value: number, seriesName: string) => string;
-    /** Hovering a label dims every other series, like toggling them off in the legend. */
-    hoverIsolate?: boolean;
-    fontStyle?: FontStyle;
-    /** The connectors a line or area plot routes back from labels that had to move apart. */
-    strokeStyle?: StrokeStyle;
-};
-/**
- * Decorative border around the plot's own content box - svelteplot's
- * `Frame` mark, purely cosmetic (drawn from the box geometry, never from
- * data). `true` enables it with svelteplot's own defaults; an object
- * enables it and overrides its look field-by-field. Insets pull the frame
- * in from the content box's own edges, in pixels.
- */
-export type FrameStyle = AreaStyle & {
-    inset?: number;
-    insetTop?: number;
-    insetRight?: number;
-    insetBottom?: number;
-    insetLeft?: number;
-};
-/** Author-facing `styles.frame` prop - see {@link FrameStyle}. */
-export type FrameProp = boolean | FrameStyle;
-/**
- * The fields every plot kind's own `styles` shape shares - the common parent
- * of {@link AxisBasedStylesConfig} and {@link GeoStylesConfig}.
- */
-export type BasePlotStylesConfig = {
-    /** Decorative border around the plot's content box - see {@link FrameStyle}. Available on every plot kind. */
-    frame?: FrameProp;
-};
-/**
- * Top-level rendering style overrides shared by the non-geo plot kinds.
- * Passed as the `styles` prop. Each plot reads only the fields it cares
- * about.
- */
-export type AxisBasedStylesConfig = BasePlotStylesConfig & {
-    values?: ValuesStyle;
-};
-/**
- * `AxisBasedStylesConfig` extended with `gaps` - the interpolated
- * missing-data bridge fill available to plot kinds with an inherent
- * category/sequence ordering (`LinePlot`, `BarPlot`, `PyramidPlot`).
- * Resolved per series like `segments`, at zone granularity - see
- * {@link GapsConfig}.
- */
-export type GapsAwarePlotStylesConfig<TSegmentStyle extends object> = AxisBasedStylesConfig & {
-    gaps?: GapsConfig<TSegmentStyle>;
-};
-export type GeoTileLayerConfig = {
-    /** XYZ tile URL template, e.g. `'https://tile.openstreetmap.org/{z}/{x}/{y}.png'`. */
-    url: string;
-    attribution?: string;
-    opacity?: number;
-    minZoom?: number;
-    maxZoom?: number;
-    /** Tile edge length in pixels. Defaults to `256`. */
-    tileSize?: number;
-};
-/**
- * `styles` prop for GeoPlot - the geo analog of `AxisBasedStylesConfig`,
- * sharing only {@link BasePlotStylesConfig}'s common ground with it. Unlike
- * the other plot kinds, GeoPlot's styling needs (base map, choropleth ramp,
- * tile background, click handling) are unlike anything x/y plots need, so
- * this is its own type rather than a reuse of `AxisBasedStylesConfig`.
- */
-export type GeoStylesConfig<TProps extends Record<string, unknown> = Record<string, unknown>> = BasePlotStylesConfig & {
-    /** Base map fill, used when a feature isn't styled by `segments` or the choropleth ramp. */
-    fill?: string;
-    fillOpacity?: number;
-    stroke?: string;
-    strokeWidth?: number;
-    /** Raster XYZ tile basemap under the vector geometry. Mercator-family projections only. */
-    tileLayer?: GeoTileLayerConfig;
-    /** Fired when a base-map feature is clicked. */
-    onFeatureClick?: (feature: GeoFeature<TProps>, event: Event) => void;
-};
-/**
- * `GeoTileLayerConfig`, plus `features` - never author-facing (the public
- * `styles.tileLayer` shape, {@link GeoTileLayerConfig}, doesn't declare it).
- * `GeoPlot` tacks it onto its own internal copy of `styles` so `StylesLayout`
- * can compute the tile layer's auto-fit bounds without needing raw geometry
- * threaded through as a separate prop.
- */
-type GeoTileLayerConfigWithFeatures = GeoTileLayerConfig & {
-    features?: {
-        geometry: GeoJSON.Geometry;
-    }[];
-};
-/**
- * The minimal slice of a plot kind's own `styles` prop `StylesLayout` reads -
- * every concrete `styles` type ({@link AxisBasedStylesConfig},
- * {@link GeoStylesConfig}) structurally satisfies this whether or not it
- * declares `tileLayer` at all (a missing optional field type-checks fine).
- */
-export type StylesLayoutConfig = {
-    tileLayer?: GeoTileLayerConfigWithFeatures;
-    frame?: FrameProp;
-    [key: string]: unknown;
-};
-export {};

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

@@ -1,2 +0,0 @@
-/** Curve interpolation for an area, difference or trail marker - svelteplot's own `CurveName`. */
-export type MarkerCurveName = 'basis' | 'basis-closed' | 'basis-open' | 'bundle' | 'bump-x' | 'bump-y' | 'cardinal' | 'cardinal-closed' | 'cardinal-open' | 'catmull-rom' | 'catmull-rom-closed' | 'catmull-rom-open' | 'linear' | 'linear-closed' | 'monotone-x' | 'monotone-y' | 'natural' | 'step' | 'step-after' | 'step-before';

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

@@ -1,10 +0,0 @@
-import type { BasePlotProps, PlotCoreProps } from '../props';
-import type { AxisBasedScalesConfig } from '../../layout/scales';
-import type { AxisBasedMarkersConfig } from '../../markers/common';
-import type { SeriesProps, DataProps } from '../data/common';
-import type { GapsAwarePlotStylesConfig } from '../../layout/styles';
-import type { LineSegmentStyle } from '../segments/common';
-/** `LinePlot`'s public props. */
-export type LinePlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<LineSegmentStyle>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
-/** What `LinePlot`'s core draws from. */
-export type LinePlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<LineSegmentStyle>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/utils/color/contrast.d.ts

@@ -1,9 +0,0 @@
-/** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
-export declare function contrastRatio(colorA: string, colorB: string): number;
-/**
- * The `candidates` entry with the highest WCAG contrast ratio against
- * `background`. Defaults to plain white/black; pass a grayscale or other
- * palette to widen the choice. Falls back to the first candidate when
- * `background` can't be parsed.
- */
-export declare function contrastTextColor(background: string, candidates?: string[]): string;

package/dist/utils/color/contrast.js

@@ -1,40 +0,0 @@
-import { resolveCssColor, parseRgb } from './cssColor';
-function relativeLuminance([r, g, b]) {
-    const [rs, gs, bs] = [r, g, b].map((c) => {
-        const s = c / 255;
-        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
-    });
-    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
-}
-/** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
-export function contrastRatio(colorA, colorB) {
-    const a = parseRgb(resolveCssColor(colorA));
-    const b = parseRgb(resolveCssColor(colorB));
-    if (!a || !b)
-        return 1;
-    const lA = relativeLuminance(a);
-    const lB = relativeLuminance(b);
-    const lighter = Math.max(lA, lB);
-    const darker = Math.min(lA, lB);
-    return (lighter + 0.05) / (darker + 0.05);
-}
-/**
- * The `candidates` entry with the highest WCAG contrast ratio against
- * `background`. Defaults to plain white/black; pass a grayscale or other
- * palette to widen the choice. Falls back to the first candidate when
- * `background` can't be parsed.
- */
-export function contrastTextColor(background, candidates = ['#ffffff', '#000000']) {
-    if (candidates.length === 0)
-        return '#000000';
-    let best = candidates[0];
-    let bestRatio = -Infinity;
-    for (const candidate of candidates) {
-        const ratio = contrastRatio(background, candidate);
-        if (ratio > bestRatio) {
-            bestRatio = ratio;
-            best = candidate;
-        }
-    }
-    return best;
-}

package/dist/utils/color/cssColor.d.ts

@@ -1,4 +0,0 @@
-/** Resolves a `var(--x)` reference to its computed value; any other CSS color string passes through unchanged. */
-export declare function resolveCssColor(color: string): string;
-/** Parses any CSS color syntax (hex, rgb(), oklch(), named colors, hsl(), ...) into an `[r, g, b]` (0-255) triple, or `null` if it can't be resolved. */
-export declare function parseRgb(color: string): [number, number, number] | null;

package/dist/utils/color/cssColor.js

@@ -1,77 +0,0 @@
-import { isBrowser } from '../../stores/device';
-/** Resolves a `var(--x)` reference to its computed value; any other CSS color string passes through unchanged. */
-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;
-}
-function clamp01(v) {
-    return Math.max(0, Math.min(1, v));
-}
-function linearToSrgb8(c) {
-    const s = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
-    return clamp01(s) * 255;
-}
-/**
- * Parses `oklch(L C H)` directly instead of round-tripping through the
- * browser's computed style: Chromium/Firefox serialize computed oklch()
- * values back as oklch() (not rgb()), so the generic browser-fallback below
- * sees an unchanged string on the second pass and its infinite-loop guard
- * mistakes that for a parse failure.
- */
-function parseOklch(color) {
-    const match = /^oklch\(\s*([\d.]+)(%)?\s+([\d.]+)\s+([\d.]+)/i.exec(color.trim());
-    if (!match)
-        return null;
-    const L = match[2] ? Number(match[1]) / 100 : Number(match[1]);
-    const C = Number(match[3]);
-    const H = (Number(match[4]) * Math.PI) / 180;
-    const a = C * Math.cos(H);
-    const b = C * Math.sin(H);
-    const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
-    const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
-    const s_ = L - 0.0894841775 * a - 1.291485548 * b;
-    const l = l_ ** 3;
-    const m = m_ ** 3;
-    const s = s_ ** 3;
-    const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
-    const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
-    const bl = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
-    return [linearToSrgb8(r), linearToSrgb8(g), linearToSrgb8(bl)];
-}
-/** Parses any CSS color syntax (hex, rgb(), oklch(), named colors, hsl(), ...) into an `[r, g, b]` (0-255) triple, or `null` if it can't be resolved. */
-export function parseRgb(color) {
-    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
-    if (hex) {
-        const digits = hex[1].length === 3
-            ? hex[1]
-                .split('')
-                .map((c) => c + c)
-                .join('')
-            : hex[1];
-        const num = parseInt(digits, 16);
-        return [(num >> 16) & 255, (num >> 8) & 255, num & 255];
-    }
-    const rgb = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/i.exec(color);
-    if (rgb)
-        return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
-    const oklch = parseOklch(color);
-    if (oklch)
-        return oklch;
-    // Named colors, hsl(), and any other CSS color syntax: resolved to
-    // `rgb(...)` via the browser's computed style, then reparsed.
-    if (!isBrowser)
-        return null;
-    const el = document.createElement('div');
-    el.style.color = color;
-    document.body.appendChild(el);
-    const computed = getComputedStyle(el).color;
-    document.body.removeChild(el);
-    if (!computed || computed === color)
-        return null;
-    return parseRgb(computed);
-}

package/dist/utils/color/ramp.d.ts

@@ -1,17 +0,0 @@
-import type { ColorScaleConfig } from '../../types/layout/scales';
-/** Linearly maps `v` from `[min, max]` onto `[0, 1]`, clamped at both ends. */
-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;
-/** A simple 2-color continuous ramp over `[min, max]`. */
-export declare function makeColorScale(min: number, max: number, colorMin: string, colorMax: string): (v: number) => string;
-/**
- * Resolves a {@link ColorScaleConfig} into a `value => color` function - the
- * one shared implementation for every level the config can appear at
- * (`scales.color`, a `segments` entry, a marker's own `scales`).
- * `computedDomain` is the fallback when `config.domain` is unset;
- * `defaultScheme` is used when `config.scheme` is unset - the theme's own
- * 2-color continuous ramp, or a discrete palette for a categorical domain
- * (e.g. per-series identity colors).
- */
-export declare function resolveColorScale(config: ColorScaleConfig | undefined, computedDomain: [number, number] | string[] | undefined, defaultScheme: NonNullable<ColorScaleConfig['scheme']>): (value: unknown) => string;

package/dist/utils/color/ramp.js

@@ -1,110 +0,0 @@
-import { interpolateRgb, piecewise } from 'd3-interpolate';
-import * as d3Chromatic from 'd3-scale-chromatic';
-import { resolveCssColor } from './cssColor';
-/** Linearly maps `v` from `[min, max]` onto `[0, 1]`, clamped at both ends. */
-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];
-}
-/** A simple 2-color continuous ramp over `[min, max]`. */
-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);
-    };
-}
-/** `{turbo: interpolateTurbo, blues: interpolateBlues, ...}`, built from every `interpolate*` d3-scale-chromatic export. */
-const NAMED_SCHEMES = Object.fromEntries(Object.entries(d3Chromatic)
-    .filter((entry) => entry[0].startsWith('interpolate'))
-    .map(([name, fn]) => [name.slice('interpolate'.length).toLowerCase(), fn]));
-/**
- * Resolves a {@link ColorScaleConfig} into a `value => color` function - the
- * one shared implementation for every level the config can appear at
- * (`scales.color`, a `segments` entry, a marker's own `scales`).
- * `computedDomain` is the fallback when `config.domain` is unset;
- * `defaultScheme` is used when `config.scheme` is unset - the theme's own
- * 2-color continuous ramp, or a discrete palette for a categorical domain
- * (e.g. per-series identity colors).
- */
-export function resolveColorScale(config, computedDomain, defaultScheme) {
-    const domain = config?.domain ?? computedDomain;
-    const scheme = config?.scheme ?? defaultScheme;
-    const unknown = config?.unknown ?? '#ccc';
-    if (!domain || domain.length === 0)
-        return () => unknown;
-    // A category → color map always resolves by direct lookup, regardless of domain shape.
-    if (typeof scheme === 'object' && !Array.isArray(scheme)) {
-        return (v) => (v == null ? unknown : (scheme[String(v)] ?? unknown));
-    }
-    // A named d3-scale-chromatic ramp (e.g. 'turbo') resolves straight to its own interpolator.
-    const namedInterpolator = typeof scheme === 'string' ? NAMED_SCHEMES[scheme.toLowerCase()] : undefined;
-    if (typeof scheme === 'string' && !namedInterpolator)
-        return () => unknown;
-    const resolvedScheme = namedInterpolator ? undefined : scheme.map(resolveCssColor);
-    if (resolvedScheme && resolvedScheme.length === 0)
-        return () => unknown;
-    if (resolvedScheme && resolvedScheme.length === 1) {
-        const only = resolvedScheme[0];
-        return () => only;
-    }
-    // Categorical domain (explicit category list): sample the ramp evenly, one stop per category.
-    if (typeof domain[0] === 'string') {
-        const categories = domain;
-        const swatches = resolvedScheme ??
-            categories.map((_, i) => namedInterpolator(categories.length > 1 ? i / (categories.length - 1) : 0));
-        return (v) => {
-            if (v == null)
-                return unknown;
-            const idx = categories.indexOf(String(v));
-            return idx < 0 ? unknown : swatches[idx % swatches.length];
-        };
-    }
-    // Continuous domain: interpolate smoothly across every scheme stop (or the named ramp directly).
-    const [lo, hi] = domain;
-    let interpolator;
-    if (namedInterpolator) {
-        interpolator = namedInterpolator;
-    }
-    else {
-        try {
-            interpolator = piecewise(interpolateRgb, resolvedScheme);
-        }
-        catch {
-            return () => unknown;
-        }
-    }
-    const pivot = config?.pivot;
-    const stopCount = resolvedScheme?.length ?? Infinity;
-    return (v) => {
-        if (v == null)
-            return unknown;
-        const n = Number(v);
-        if (Number.isNaN(n))
-            return unknown;
-        const t = pivot != null && stopCount >= 3
-            ? n <= pivot
-                ? 0.5 * normalize(n, lo, pivot)
-                : 0.5 + 0.5 * normalize(n, pivot, hi)
-            : normalize(n, lo, hi);
-        return interpolator(t);
-    };
-}

package/dist/utils/opacity.d.ts

@@ -1,9 +0,0 @@
-import type { OpacityScaleConfig } from '../types/layout/scales';
-/**
- * Resolves an {@link OpacityScaleConfig} into a `value => opacity` function -
- * mirrors `resolveColorScale`'s shape, but the output is always a number in
- * roughly `[0,1]` instead of a CSS color string. Callers must apply the
- * result as a literal constant per mark instance (never a per-row function
- * handed straight to svelteplot) - see the type's own doc comment for why.
- */
-export declare function resolveOpacityScale(config: OpacityScaleConfig | undefined, computedDomain: [number, number] | string[] | undefined, defaultRange: [number, number]): (value: unknown) => number;

package/dist/utils/opacity.js

@@ -1,38 +0,0 @@
-import { normalize } from './color';
-/**
- * Resolves an {@link OpacityScaleConfig} into a `value => opacity` function -
- * mirrors `resolveColorScale`'s shape, but the output is always a number in
- * roughly `[0,1]` instead of a CSS color string. Callers must apply the
- * result as a literal constant per mark instance (never a per-row function
- * handed straight to svelteplot) - see the type's own doc comment for why.
- */
-export function resolveOpacityScale(config, computedDomain, defaultRange) {
-    const domain = config?.domain ?? computedDomain;
-    const range = config?.range ?? defaultRange;
-    const unknown = config?.unknown ?? 1;
-    if (!domain || domain.length === 0)
-        return () => unknown;
-    if (typeof range === 'object' && !Array.isArray(range)) {
-        return (v) => (v == null ? unknown : (range[String(v)] ?? unknown));
-    }
-    if (typeof domain[0] === 'string') {
-        const categories = domain;
-        const [lo, hi] = range;
-        return (v) => {
-            if (v == null)
-                return unknown;
-            const idx = categories.indexOf(String(v));
-            if (idx < 0)
-                return unknown;
-            return categories.length > 1 ? lo + ((hi - lo) * idx) / (categories.length - 1) : lo;
-        };
-    }
-    const [dLo, dHi] = domain;
-    const [rLo, rHi] = range;
-    return (v) => {
-        if (v == null)
-            return unknown;
-        const t = normalize(Number(v), dLo, dHi);
-        return rLo + (rHi - rLo) * t;
-    };
-}

package/examples/data.ts

@@ -1,12 +0,0 @@
-export type Row = { year: number; region: string; value: number };
-
-const REGIONS = ['North', 'Center', 'South'];
-
-/** Tiny deterministic dataset shared by the examples: one value per region and year. */
-export const ROWS: Row[] = REGIONS.flatMap((region, r) =>
-	Array.from({ length: 8 }, (_, i) => ({
-		year: 2016 + i,
-		region,
-		value: 100 + (r + 1) * 4 * i + (i % 3) * 2
-	}))
-);