@fundar/data-chart-telling 0.0.1

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

@@ -0,0 +1,64 @@
+import type { Snippet } from 'svelte';
+import type { Accessor, AxisValue } from '../plots/common';
+import type { EasingName, EasingFn } from './interpolate';
+export type TimeValue = number;
+export type Orientation = 'horizontal' | 'vertical';
+export type FacetColumns = number | {
+    desktop: number;
+    mobile: number;
+};
+export type ChartBoxContext = {
+    width: number;
+    height: number;
+};
+export type ChartBoxSnippet = Snippet<[ChartBoxContext]>;
+export type FacetCellContext<TRow extends Record<string, unknown>> = {
+    facetValue: string;
+    data: TRow[];
+    width: number;
+    height: number;
+};
+export type FacetCellSnippet<TRow extends Record<string, unknown>> = Snippet<[
+    FacetCellContext<TRow>
+]>;
+export type TimelineChildContext<TRow extends Record<string, unknown>> = {
+    selectedValue: TimeValue;
+    data: TRow[];
+    width: number;
+    height: number;
+};
+export type TimelineChildSnippet<TRow extends Record<string, unknown>> = Snippet<[
+    TimelineChildContext<TRow>
+]>;
+export type ChartPlotContext<TRow extends Record<string, unknown>> = {
+    data: TRow[];
+    width: number;
+    height: number;
+    facetValue?: string;
+    selectedValue?: TimeValue;
+};
+export type ChartPlotSnippet<TRow extends Record<string, unknown>> = Snippet<[
+    ChartPlotContext<TRow>
+]>;
+export type TimelineInterpolation<TRow extends Record<string, unknown>> = {
+    key?: Accessor<TRow, unknown>;
+    value?: Accessor<TRow, AxisValue>;
+    create?: (lower: TRow, upper: TRow, x: TimeValue, value: number) => TRow;
+    progressEasing?: EasingName | EasingFn;
+    segmentEasing?: EasingName | EasingFn;
+};
+export type TimelineConfig<TRow extends Record<string, unknown>> = {
+    accessor: Accessor<TRow, TimeValue>;
+    progress: number;
+    values?: TimeValue[];
+    orientation?: Orientation;
+    thickness?: number;
+    filterMode?: 'exact' | 'upTo';
+    interpolate?: boolean | TimelineInterpolation<TRow>;
+};
+export type FacetConfig<TRow extends Record<string, unknown>> = {
+    by: Accessor<TRow, unknown>;
+    columns?: FacetColumns;
+    values?: string[];
+    gap?: number;
+};

package/dist/types/charts/common.js

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

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

@@ -0,0 +1,2 @@
+export type EasingName = 'linear' | 'quadIn' | 'quadOut' | 'cubicIn' | 'cubicOut' | 'quartIn' | 'quartOut' | 'expoOut';
+export type EasingFn = (t: number) => number;

package/dist/types/charts/interpolate.js

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

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

@@ -0,0 +1,29 @@
+import type { SymbolType, LineStyle } from '../plots/styles';
+export type LegendSectionType = 'discrete' | 'continuous';
+export type LegendItem = {
+    name: string;
+    label?: string;
+    color?: string;
+    symbol?: SymbolType;
+    opacity?: number;
+    lineStyle?: LineStyle;
+};
+export type DiscreteLegendSection = {
+    type: 'discrete';
+    title?: string;
+    items: LegendItem[];
+    columns?: number;
+};
+export type ContinuousLegendSection = {
+    type: 'continuous';
+    title?: string;
+    columns?: number;
+    min: number;
+    max: number;
+    colorMin?: string;
+    colorMax?: string;
+    ticks?: number[];
+    width?: number;
+    format?: (v: number) => string;
+};
+export type LegendSection = DiscreteLegendSection | ContinuousLegendSection;

package/dist/types/charts/legend.js

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

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

@@ -0,0 +1,35 @@
+import type { Accessor, AxisValue, ScalesConfig, MarginConfig } from '../plots/common';
+import type { PlotStyles, SegmentsMap } from '../plots/styles';
+import type { Marker } from '../plots/markers';
+import type { TooltipProp } from '../layout/tooltip';
+import type { LegendSection } from './legend';
+import type { FacetConfig, TimelineConfig } from './common';
+/**
+ * Common props accepted by every chart component (bar, line, heatmap, pyramid,
+ * …). The `TSegmentStyle` parameter lets each chart narrow `segments` to its
+ * own style shape while keeping everything else shared.
+ *
+ * Note: `z` is optional here (bar/line charts) but individual charts may
+ * tighten it to required and/or narrow its value type (e.g. `number` for
+ * heatmap).
+ */
+export type ChartProps<TRow extends Record<string, unknown>, TSegmentStyle extends object = object> = {
+    width: number;
+    height: number;
+    title?: string;
+    subtitle?: string;
+    caption?: string;
+    legend?: LegendSection[];
+    data: TRow[];
+    x: Accessor<TRow, AxisValue>;
+    y: Accessor<TRow, AxisValue>;
+    z?: Accessor<TRow, unknown>;
+    styles?: PlotStyles;
+    segments?: SegmentsMap<TSegmentStyle>;
+    markers?: Marker[];
+    scales?: ScalesConfig;
+    margins?: MarginConfig;
+    facet?: FacetConfig<TRow>;
+    timeline?: TimelineConfig<TRow>;
+    tooltip?: TooltipProp<TRow>;
+};

package/dist/types/charts/props.js

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

package/dist/types/configuration/styling.d.ts

@@ -0,0 +1,97 @@
+import type { StrokeStyle, DotStyle, FontStyle } from '../plots/styles';
+export type TextStyle = {
+    /** font-family */
+    font: string;
+    /** font-size (any CSS length) */
+    size: string;
+    /** font-weight */
+    weight: number | string;
+    /** color */
+    color: string;
+    /** line-height */
+    leading: string;
+    /** letter-spacing */
+    spacing: string;
+};
+export type ChartConfig = {
+    font: string;
+    color: string;
+    background: string;
+    border: string;
+    spacing: {
+        headerPadding: string;
+        legendPadding: string;
+        captionPadding: string;
+    };
+    title: TextStyle;
+    subtitle: TextStyle;
+    caption: TextStyle;
+    legend: {
+        font: string;
+        size: string;
+        weight: number | string;
+        color: string;
+        titleSize: string;
+        titleWeight: number | string;
+        /** row/column gap between sections (CSS `gap` shorthand) */
+        gap: string;
+        /** swatch square size */
+        swatchSize: string;
+    };
+    axis: {
+        color: string;
+        fontSize: number;
+        labelFontSize: number;
+        titleFontSize: number;
+        xTickSize: number;
+        yTickSize: number;
+        xTickPadding: number;
+        yTickPadding: number;
+        grid: boolean;
+    };
+    tooltip: {
+        background: string;
+        color: string;
+        fontSize: string;
+        padding: string;
+        radius: string;
+        border: string;
+    };
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Discrete categorical palette (grouped series). */
+    palette: string[];
+    /** Continuous gradient endpoints + on-cell label colour. */
+    continuous: {
+        min: string;
+        max: string;
+        labelColor: string;
+    };
+    /** Default line geometry. */
+    line: {
+        strokeWidth: number;
+        dotRadius: number;
+    };
+    /** Timeline gutter styling. */
+    timeline: {
+        axisColor: string;
+        activeColor: string;
+        thickness: number;
+    };
+    /** In-SVG hover highlight (crosshair rule, dot, and value label). */
+    hover: {
+        rule: StrokeStyle;
+        dot: DotStyle;
+        font: FontStyle;
+    };
+};
+/** Deep-partial input accepted by `setConfiguration`. */
+export type ChartConfigInput = DeepPartial<ChartConfig>;
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends (infer U)[] ? U[] : T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+export {};

package/dist/types/configuration/styling.js

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

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

@@ -0,0 +1,88 @@
+import type { Snippet } from 'svelte';
+import type { AxisValue } from '../plots/common';
+/**
+ * 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).
+ */
+export type HoverStrategy = 'x' | 'y' | 'punctual';
+/** Author-facing tooltip option on the chart kinds. `true` = enable with defaults. */
+export type TooltipOptions<TRow extends Record<string, unknown>> = {
+    /** Matching strategy. Defaults to the chart kind's own default. */
+    strategy?: HoverStrategy;
+    /**
+     * Broadcast the hover to other facets. When `true` every facet with a
+     * matching point highlights it using the same strategy. Defaults to `false`.
+     */
+    sync?: boolean;
+    /** Custom tooltip text for a row (supports `\n`). Defaults per chart kind. */
+    format?: (row: TRow) => string;
+    /** Named subset of crossing series to include. Omitted = all matched. */
+    series?: string[];
+    /** Custom tooltip body; replaces `format` when given. */
+    content?: Snippet<[{
+        rows: TRow[];
+    }]>;
+};
+/** Either a bare on/off flag or the full option object. */
+export type TooltipProp<TRow extends Record<string, unknown>> = boolean | TooltipOptions<TRow>;
+/**
+ * Resolved tooltip config handed from a chart kind down to a plot. Presence of
+ * this object on a plot is what turns hovering on.
+ */
+export type TooltipRuntime<TRow extends Record<string, unknown>> = {
+    format: (row: TRow) => string;
+    /** Identifies the originating facet (`''` when not faceted). */
+    facetId: string;
+    /** Strategy resolved by the chart; omitted → PlotLayout falls back to its own default. */
+    strategy?: HoverStrategy;
+    /** Whether to broadcast to other facets. */
+    sync: boolean;
+    series?: string[];
+    content?: Snippet<[{
+        rows: TRow[];
+    }]>;
+};
+/**
+ * Shared hover state for cross-facet tooltip syncing.
+ *
+ * {@link Chart} provides one store via context; every faceted plot reads the
+ * same instance, so a hover detected in one facet (which writes `activeX/Y` and
+ * stamps itself as `source`) is visible to the others. A standalone plot with no
+ * provider falls back to its own {@link createHover} store.
+ */
+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;
+    /**
+     * Mouse position within the source facet's own box, as a fraction of its
+     * width/height (each in `[0, 1]`). Other facets reproject this onto their
+     * own box so a broadcast tooltip lands at the same *relative* spot the
+     * cursor is actually at, rather than a fixed corner.
+     */
+    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 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;
+};
+/** A candidate point for hover matching/highlighting — also carries its source row. */
+export type HoverPoint<T> = HoverDisplayPoint & {
+    row: T;
+};

package/dist/types/layout/tooltip.js

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

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

@@ -0,0 +1,100 @@
+export type AxisValue = number | string | Date;
+/** Partial margin override — only the sides you specify are overridden; the rest come from the theme. */
+export type MarginConfig = Partial<{
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}>;
+/**
+ * Author-facing scale overrides for a plot axis. Mirrors svelteplot's
+ * `ScaleOptions` + `XScaleOptions` in full — `type`, `padding`, `domain`,
+ * `nice`, `reverse`, `label`, `tickFormat`, `labelAnchor`, etc.
+ *
+ * Used for both `x` and `y` entries in {@link ScalesConfig}. X-specific
+ * fields (`labelAnchor`, `tickRotate`) are accepted on `y` too; svelteplot
+ * silently ignores any inapplicable options.
+ */
+export type AxisScale = {
+    type?: 'auto' | 'linear' | 'pow' | 'sqrt' | 'log' | 'symlog' | 'time' | 'utc' | 'point' | 'ordinal' | 'sequential' | 'band' | 'categorical' | 'cyclical' | 'threshold' | 'quantile-cont' | 'quantile' | 'quantize' | 'diverging' | 'diverging-log' | 'diverging-pow' | 'diverging-sqrt' | 'diverging-symlog';
+    domain?: (number | string | boolean | Date | null)[];
+    range?: (number | string | boolean | Date | null)[];
+    reverse?: boolean;
+    label?: string | false;
+    interval?: string | number;
+    clamp?: boolean;
+    nice?: boolean;
+    zero?: boolean;
+    round?: boolean;
+    percent?: boolean;
+    padding?: number;
+    align?: number;
+    paddingInner?: number;
+    paddingOuter?: number;
+    insetLeft?: number;
+    insetRight?: number;
+    insetTop?: number;
+    insetBottom?: number;
+    ticks?: (number | string | boolean | Date | null)[];
+    tickSpacing?: number;
+    tickSize?: number;
+    tickPadding?: number;
+    titleFontSize?: number;
+    base?: number;
+    constant?: number;
+    sort?: ((a: unknown, b: unknown) => number) | {
+        channel: string;
+        order: 'ascending' | 'descending';
+    };
+    grid?: boolean;
+    tickRotate?: number;
+    tickFormat?: false | Intl.NumberFormatOptions | Intl.DateTimeFormatOptions | ((d: unknown, index: number, ticks: unknown[]) => string | string[]);
+};
+/**
+ * Per-axis scale overrides, passed as a single `scales` prop to every plot
+ * kind.
+ */
+export type ScalesConfig = {
+    x?: AxisScale;
+    y?: AxisScale;
+    z?: AxisScale;
+};
+/**
+ * A field key or accessor function. Mirrors the shorthand used across plots
+ * so chart-level encodings (`x`, `y`, `z`, facet, timeline) feel consistent
+ * with the plot-level series definitions.
+ */
+export type Accessor<TRow extends Record<string, unknown>, V> = keyof TRow | ((d: TRow) => V);
+/**
+ * A plot series: a name, x/y accessors and the rows it draws. Shared as-is by
+ * every mark (line, bar, …) — none of them need anything beyond this shape;
+ * visual styling lives separately in `segments`.
+ */
+export type Series<T extends Record<string, unknown> = Record<string, unknown>> = {
+    name: string;
+    x: Accessor<T, AxisValue>;
+    y: Accessor<T, AxisValue>;
+    z?: Accessor<T, unknown>;
+    data: T[];
+};
+/**
+ * Pre-built series. Mutually exclusive with {@link DataProps} — takes
+ * precedence when both could apply.
+ */
+export type SeriesProps<T extends Record<string, unknown>> = {
+    series: Series<T>[];
+    data?: never;
+    x?: never;
+    y?: never;
+    z?: never;
+};
+/**
+ * Flat rows to group into series, as an alternative to {@link SeriesProps}.
+ */
+export type DataProps<T extends Record<string, unknown>> = {
+    series?: never;
+    data: T[];
+    x: Accessor<T, AxisValue>;
+    y: Accessor<T, AxisValue>;
+    z?: Accessor<T, unknown>;
+};

package/dist/types/plots/common.js

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

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

@@ -0,0 +1,19 @@
+import type { AxisValue } from './common';
+import type { StrokeStyle, FontStyle, DotStyle } from './styles';
+export type DeltaTarget = {
+    type: 'series';
+    series: string;
+} | {
+    type: 'axis';
+    value?: number;
+};
+export type DeltaConfig = {
+    axis: 'x' | 'y';
+    at: AxisValue;
+    from: DeltaTarget;
+    to?: DeltaTarget;
+    formatDiff?: (diff: number) => string;
+    strokeStyle?: StrokeStyle;
+    fontStyle?: FontStyle;
+    dotStyle?: DotStyle;
+};

package/dist/types/plots/delta.js

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

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

@@ -0,0 +1,56 @@
+import type { AxisValue } from './common';
+import type { DotStyle, FontStyle, StrokeStyle } from './styles';
+import type { HoverStrategy } from '../layout/tooltip';
+/**
+ * Baseline props every marker component receives when mounted by a plot:
+ * `data` for the points/values it draws, plus `series`/`seriesColor` when
+ * mounted per-series via a `CustomComponentMarker`. Marker components extend
+ * this with whatever else they need (e.g. PeakMarker's `mode`, `label`).
+ */
+export interface MarkerProps<TData = Record<string, unknown>> {
+    data?: TData[];
+    series?: string;
+    seriesColor?: string;
+}
+export type RuleXMarker = {
+    type: 'ruleX';
+    x: AxisValue;
+    style?: StrokeStyle;
+};
+export type RuleYMarker = {
+    type: 'ruleY';
+    y: AxisValue;
+    style?: StrokeStyle;
+};
+/**
+ * The in-SVG hover highlight (crosshair + dot + label), opt-in via `markers`
+ * so it can be combined freely with — or used entirely without — the HTML
+ * tooltip. Omitting `series` mounts it unscoped (all series); scoping it to
+ * one series follows the same targeting fields as {@link CustomComponentMarker}.
+ */
+export type HoverMarkerConfig = {
+    type: 'hover';
+    series?: string;
+    /** Whether to render per segment or for the full series. Defaults to `'series'`. */
+    scope?: 'series' | 'segment';
+    /** Matching strategy — how related points are found. Defaults to the plot kind's own default. */
+    strategy?: HoverStrategy;
+    /** Broadcast the hover to other facets. Defaults to `false`. */
+    sync?: boolean;
+    ruleX?: boolean;
+    ruleY?: boolean;
+    showLabels?: boolean;
+    ruleStyle?: StrokeStyle;
+    dotStyle?: DotStyle;
+    fontStyle?: FontStyle;
+};
+export type CustomComponentMarker = {
+    type: 'component';
+    series?: string;
+    component: any;
+    props?: Record<string, unknown>;
+    data?: any[];
+    /** Whether to render per segment or for the full series. Defaults to `'series'`. */
+    scope?: 'series' | 'segment';
+};
+export type Marker = RuleXMarker | RuleYMarker | HoverMarkerConfig | CustomComponentMarker;

package/dist/types/plots/markers.js

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

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

@@ -0,0 +1,23 @@
+import type { Marker } from './markers';
+import type { TooltipRuntime } from '../layout/tooltip';
+import type { PlotStyles, SegmentsMap } from './styles';
+import type { SeriesProps, DataProps, ScalesConfig, MarginConfig } from './common';
+/**
+ * Common props accepted by every plot component (bar, line, heatmap, pyramid,
+ * …). The `TSegmentStyle` parameter lets each plot narrow `segments` to its
+ * own style shape ({@link BarSegmentStyle}, {@link LineSegmentStyle}, etc.)
+ * while keeping everything else shared.
+ *
+ * Data can be provided either as pre-built {@link SeriesProps} or as flat
+ * rows via {@link DataProps}.
+ */
+export type PlotProps<TData extends Record<string, unknown>, TSegmentStyle extends object = object> = (SeriesProps<TData> | DataProps<TData>) & {
+    width: number;
+    height: number;
+    styles?: PlotStyles;
+    segments?: SegmentsMap<TSegmentStyle>;
+    markers?: Marker[];
+    scales?: ScalesConfig;
+    margins?: MarginConfig;
+    tooltip?: TooltipRuntime<TData>;
+};

package/dist/types/plots/props.js

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