@m0saic/templates 0.2.0

package/dist/m0saic/charts/line-chart/v1/line-series.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — line-series data sources (the draw-on layer)
+ * ============================================================================
+ *
+ * Builds the data layer for every series as STATIC mask atlases + ONE reveal —
+ * the R6 idiom (perf rule R6: "for a masked line draw-on, use a curtain wipe
+ * over the static art, not a per-sliver cascade").
+ *
+ *   - Per series, per role (area / line / marker-border / marker-fill), the
+ *     finished silhouette is ONE full-canvas `maskAtlasSource` (absolute-coord
+ *     SVG subpaths, `bounds = W×H`). One source, one overlay layer, at any
+ *     subpath count — no per-sliver shards, no time-varying alpha (no geq fold).
+ *   - The draw-on is a single reveal, chosen by background opacity:
+ *       · opaque (preset/solid) → ONE `curtainSource`: hide-colored columns
+ *         over the plot, each disabling (`enable=lt(t,revealAt)`, a free scalar
+ *         gate) as the sweep reaches its x. Depth O(1); no alpha expr.
+ *       · transparent/image → a group `overlay.alpha` fade on the atlases (a
+ *         few full-canvas layers — the accepted perf cost; the deep chain is
+ *         gone either way).
+ *       · reduceMotion → static atlases, no reveal.
+ *   - Value labels stay one `type:"text"` per point, painted ABOVE the curtain,
+ *     popped in with `overlay.enable = gte(t, …)` (R4-clean) — never animated
+ *     alpha. Each one DISPLAYS a single raw data leaf, so when the parent passes
+ *     `valuesBinding` it is bound for Make inline edit (`editor.binding` only —
+ *     the m0 is untouched): `[j]` for a flat series, `[i, j]` for nested.
+ *
+ * `geometry.ts` is unchanged: its existing path builders are fed ABSOLUTE points
+ * (no `local()`), and the atlas bounds are the full canvas.
+ *
+ * Returned as `{ m0, sources }` (contract unchanged); the parent overlays it on
+ * the card + chrome. The atlases + curtain are full-frame overlapping layers, so
+ * `placeRects` packs them one-per-layer (base→top = area → line → markers →
+ * curtain → labels) — the same emission order the composed m0 expects.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicSource } from "@m0saic/types";
+import type { LineChartModel } from "../../_shared/line";
+import type { AnimConfig, BackgroundMode, ResolvedSeriesStyle, ResolvedValueLabels } from "./types";
+export type DataLayer = {
+    m0: string;
+    sources: MosaicSource[];
+};
+/** Background context the reveal needs: opaque bgs get a curtain, others a fade. */
+export type PlotBg = {
+    mode: BackgroundMode;
+    color: MosaicColor;
+};
+/**
+ * Build the data layer for every series as static full-canvas atlases plus one
+ * reveal. Paint order: areas (bottom) → lines → marker-borders → marker-fills →
+ * curtain (opaque animated path only) → value labels (top). Returns null when
+ * there's nothing to draw.
+ */
+export declare function buildLineSeriesSources(model: LineChartModel, styles: ResolvedSeriesStyle[], anim: AnimConfig, opts?: {
+    highlightIndex?: number;
+    valueLabels?: ResolvedValueLabels;
+    plotBg?: PlotBg;
+    /** Make inline-edit binding for the value labels: the PARENT names the
+     *  structured prop the series came from and whether it is nested
+     *  (`number[][]` → path `[seriesIdx, pointIdx]`) or flat (`number[]` →
+     *  `[pointIdx]`). Indices are the ORIGINAL data positions — the model
+     *  never filters, sorts or truncates `values`; a null/non-finite point
+     *  simply draws no label (and so binds nothing). */
+    valuesBinding?: {
+        propKey: string;
+        nested: boolean;
+    };
+}): DataLayer | null;

package/dist/m0saic/charts/line-chart/v1/line-series.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — line-series data sources (the draw-on layer)
+ * ============================================================================
+ *
+ * Builds the data layer for every series as STATIC mask atlases + ONE reveal —
+ * the R6 idiom (perf rule R6: "for a masked line draw-on, use a curtain wipe
+ * over the static art, not a per-sliver cascade").
+ *
+ *   - Per series, per role (area / line / marker-border / marker-fill), the
+ *     finished silhouette is ONE full-canvas `maskAtlasSource` (absolute-coord
+ *     SVG subpaths, `bounds = W×H`). One source, one overlay layer, at any
+ *     subpath count — no per-sliver shards, no time-varying alpha (no geq fold).
+ *   - The draw-on is a single reveal, chosen by background opacity:
+ *       · opaque (preset/solid) → ONE `curtainSource`: hide-colored columns
+ *         over the plot, each disabling (`enable=lt(t,revealAt)`, a free scalar
+ *         gate) as the sweep reaches its x. Depth O(1); no alpha expr.
+ *       · transparent/image → a group `overlay.alpha` fade on the atlases (a
+ *         few full-canvas layers — the accepted perf cost; the deep chain is
+ *         gone either way).
+ *       · reduceMotion → static atlases, no reveal.
+ *   - Value labels stay one `type:"text"` per point, painted ABOVE the curtain,
+ *     popped in with `overlay.enable = gte(t, …)` (R4-clean) — never animated
+ *     alpha. Each one DISPLAYS a single raw data leaf, so when the parent passes
+ *     `valuesBinding` it is bound for Make inline edit (`editor.binding` only —
+ *     the m0 is untouched): `[j]` for a flat series, `[i, j]` for nested.
+ *
+ * `geometry.ts` is unchanged: its existing path builders are fed ABSOLUTE points
+ * (no `local()`), and the atlas bounds are the full canvas.
+ *
+ * Returned as `{ m0, sources }` (contract unchanged); the parent overlays it on
+ * the card + chrome. The atlases + curtain are full-frame overlapping layers, so
+ * `placeRects` packs them one-per-layer (base→top = area → line → markers →
+ * curtain → labels) — the same emission order the composed m0 expects.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLineSeriesSources = buildLineSeriesSources;
+const template_utils_1 = require("@m0saic/template-utils");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const format_1 = require("./format");
+const geometry_1 = require("./geometry");
+const frame_1 = require("./frame");
+const anim_1 = require("./anim");
+/** Bbox padding (px) so anti-aliased edges never clip at the cell boundary. */
+const EDGE_PAD = 1.5;
+const clampInt = (v, lo, hi) => Math.max(lo, Math.min(hi, Math.round(v)));
+/** Rough text width estimate (avg glyph ≈ 0.6em). */
+const estTextW = (s, size) => s.length * size * 0.6;
+/** The whole-canvas cell (basis units) every full-frame atlas / curtain occupies. */
+const fullRect = () => ({ x: 0, y: 0, w: frame_1.BASIS_COL, h: frame_1.BASIS_ROW, claimant: "F" });
+/**
+ * Snap a bbox OUTWARD to the frame basis grid (so the cell ⊇ the content, never
+ * clipping it) and let the caller build a source sized to the resulting cell px.
+ * Used for the per-point value labels (tight text cells).
+ */
+function snapAndPlace(W, H, bbox, makeSource) {
+    const qx = clampInt(Math.floor(((bbox.minX - EDGE_PAD) / W) * frame_1.BASIS_COL), 0, frame_1.BASIS_COL - 1);
+    const qy = clampInt(Math.floor(((bbox.minY - EDGE_PAD) / H) * frame_1.BASIS_ROW), 0, frame_1.BASIS_ROW - 1);
+    const qx2 = clampInt(Math.ceil(((bbox.maxX + EDGE_PAD) / W) * frame_1.BASIS_COL), qx + 1, frame_1.BASIS_COL);
+    const qy2 = clampInt(Math.ceil(((bbox.maxY + EDGE_PAD) / H) * frame_1.BASIS_ROW), qy + 1, frame_1.BASIS_ROW);
+    const qw = qx2 - qx;
+    const qh = qy2 - qy;
+    const cellX = (qx / frame_1.BASIS_COL) * W;
+    const cellY = (qy / frame_1.BASIS_ROW) * H;
+    const cellW = (qw / frame_1.BASIS_COL) * W;
+    const cellH = (qh / frame_1.BASIS_ROW) * H;
+    return { rect: { x: qx, y: qy, w: qw, h: qh, claimant: "F" }, source: makeSource(cellX, cellY, cellW, cellH) };
+}
+/**
+ * One full-canvas mask atlas: the given ABSOLUTE-coord subpaths joined into a
+ * single silhouette filled with `color`. Returns null when there's nothing to
+ * draw. Caps the subpath list to {@link MASK_SUBPATH_BUDGET} (the resolver's
+ * argv wall) — the line is subsampled upstream; markers/dashes stride-decimate.
+ */
+function atlasPiece(paths, color, W, H, overlay) {
+    const subs = capStride(paths.filter(Boolean), template_utils_1.MASK_SUBPATH_BUDGET);
+    if (subs.length === 0)
+        return null;
+    const src = (0, template_utils_1.maskAtlasSource)(subs, color, { width: W, height: H });
+    return { rect: fullRect(), source: overlay ? { ...src, overlay } : src };
+}
+/** Even-stride a subpath list down to `cap` when it would overflow the atlas budget. */
+function capStride(paths, cap) {
+    if (paths.length <= cap)
+        return paths;
+    const out = [];
+    const stride = paths.length / cap;
+    for (let i = 0; i < cap; i++)
+        out.push(paths[Math.floor(i * stride)]);
+    return out;
+}
+/**
+ * The line as a list of ribbon-quad subpaths (one per polyline segment). A dense
+ * flattened curve past the atlas budget is resampled to even arc-length chords
+ * (reusing `buildSweepSlivers`) so the silhouette stays smooth and in-budget.
+ */
+function lineQuadPaths(poly, strokeWidth) {
+    if (poly.length < 2)
+        return [];
+    if (poly.length - 1 > template_utils_1.MASK_SUBPATH_BUDGET) {
+        return (0, geometry_1.buildSweepSlivers)(poly, strokeWidth, { maxSlivers: template_utils_1.MASK_SUBPATH_BUDGET }).map((s) => (0, geometry_1.ribbonQuadPath)(s.a, s.b, strokeWidth));
+    }
+    const out = [];
+    for (let i = 0; i < poly.length - 1; i++)
+        out.push((0, geometry_1.ribbonQuadPath)(poly[i], poly[i + 1], strokeWidth));
+    return out;
+}
+/** Place a value label (centered text) in a tight cell whose bottom sits at `topY`. */
+function placeValueLabel(W, H, cx, topY, text, fontSize, color, overlay) {
+    const w = Math.max(fontSize * 1.4, estTextW(text, fontSize));
+    const h = fontSize * 1.5;
+    const bbox = { minX: cx - w / 2, minY: topY - h, maxX: cx + w / 2, maxY: topY };
+    return snapAndPlace(W, H, bbox, () => {
+        const src = {
+            type: "text",
+            visual: { backgroundColor: "black@0" },
+            layers: [
+                {
+                    content: { kind: "literal", text },
+                    style: { fontSize, fontColor: color },
+                    placement: { fit: "contain", hAlign: "center", vAlign: "middle" },
+                },
+            ],
+            ...(overlay ? { overlay } : {}),
+        };
+        return (0, template_utils_1.tag)(src, "value-label");
+    });
+}
+/**
+ * Build the data layer for every series as static full-canvas atlases plus one
+ * reveal. Paint order: areas (bottom) → lines → marker-borders → marker-fills →
+ * curtain (opaque animated path only) → value labels (top). Returns null when
+ * there's nothing to draw.
+ */
+function buildLineSeriesSources(model, styles, anim, opts = {}) {
+    var _a, _b, _c, _d;
+    const highlightIndex = (_a = opts.highlightIndex) !== null && _a !== void 0 ? _a : -1;
+    const valueLabels = opts.valueLabels;
+    const valuesBinding = opts.valuesBinding;
+    const plotBg = opts.plotBg;
+    const { width: W, height: H, plot } = model.layout;
+    const reduce = anim.reduceMotion;
+    const seriesCount = model.series.length;
+    // Opaque card (preset/solid) ⇒ curtain wipe. Transparent/image (or a bare
+    // standalone call with no plotBg) ⇒ group alpha-fade. reduceMotion ⇒ static.
+    const opaque = !!plotBg && (plotBg.mode === "preset" || plotBg.mode === "solid");
+    const useCurtain = !reduce && opaque;
+    const useGroupFade = !reduce && !opaque;
+    const areas = [];
+    const lines = [];
+    const markerBorders = [];
+    const markerFills = [];
+    const labels = [];
+    let maxOverhangPx = 0; // marker radius / stroke half-width that overhangs the plot edge
+    for (let i = 0; i < seriesCount; i++) {
+        const st = styles[i];
+        const pts = model.points[i];
+        if (!st || !pts || pts.length === 0)
+            continue;
+        // The line/area trace this (possibly densified) polyline per `curve`;
+        // markers stay on the original data points, revealing at `vertexFracs`.
+        const { poly, vertexFracs } = (0, geometry_1.curvePolyline)(pts, st.curve);
+        // Group fade (transparent/image animated path) — the same overlay on every
+        // atlas so they ramp in together; opaque path leaves them static (curtain).
+        const groupOverlay = useGroupFade
+            ? { startAtSec: anim.intro.delaySec, alpha: (0, template_utils_1.fadeInExpr)(anim.intro.delaySec, anim.intro.durationSec * 0.85) }
+            : undefined;
+        // ---- area fill (behind the line) ----
+        // Opacity rides overlay.alpha (a constant expr), NOT a color@alpha: the
+        // inline-mask's coverage REPLACES the tile's color alpha, so "@0.2"
+        // rendered fully opaque and buried the series beneath it.
+        if (st.area.show) {
+            const a = clamp01(st.area.opacity);
+            const areaOverlay = a >= 1
+                ? groupOverlay
+                : (groupOverlay === null || groupOverlay === void 0 ? void 0 : groupOverlay.alpha)
+                    ? { ...groupOverlay, alpha: `(${groupOverlay.alpha})*${a}` }
+                    : { ...(groupOverlay !== null && groupOverlay !== void 0 ? groupOverlay : {}), alpha: String(a) };
+            const p = atlasPiece([(0, geometry_1.areaPolygonPath)(poly, plot.bottom)], ((_b = st.area.color) !== null && _b !== void 0 ? _b : st.color), W, H, areaOverlay);
+            if (p)
+                areas.push(p);
+        }
+        // ---- line (solid = ribbon quads; dashed/dotted = filled dash marks) ----
+        const linePaths = st.lineStyle === "dashed" || st.lineStyle === "dotted"
+            ? (0, geometry_1.buildDashMarks)(poly, st.strokeWidth, st.lineStyle, { maxMarks: template_utils_1.MASK_SUBPATH_BUDGET - 8 }).map((m) => (0, geometry_1.dashMarkPath)(m, st.strokeWidth, 0, 0))
+            : lineQuadPaths(poly, st.strokeWidth);
+        const lp = atlasPiece(linePaths, st.color, W, H, groupOverlay);
+        if (lp)
+            lines.push(lp);
+        maxOverhangPx = Math.max(maxOverhangPx, st.strokeWidth / 2);
+        // ---- markers (one border atlas + one fill atlas, per series) ----
+        if (st.showPoints) {
+            const borderPaths = [];
+            const fillPaths = [];
+            const hasBorder = !!st.pointBorder.color && st.pointBorder.width > 0;
+            for (let j = 0; j < pts.length; j++) {
+                const r = j === highlightIndex ? st.pointRadius * 1.7 : st.pointRadius;
+                if (hasBorder)
+                    borderPaths.push((0, geometry_1.markerPath)(pts[j], r + st.pointBorder.width, st.pointShape));
+                fillPaths.push((0, geometry_1.markerPath)(pts[j], r, st.pointShape));
+                maxOverhangPx = Math.max(maxOverhangPx, r + (hasBorder ? st.pointBorder.width : 0));
+            }
+            if (hasBorder) {
+                const bp = atlasPiece(borderPaths, st.pointBorder.color, W, H, groupOverlay);
+                if (bp)
+                    markerBorders.push(bp);
+            }
+            const fp = atlasPiece(fillPaths, ((_c = st.pointColor) !== null && _c !== void 0 ? _c : st.color), W, H, groupOverlay);
+            if (fp)
+                markerFills.push(fp);
+        }
+        // ---- per-point value labels (above the curtain, pop via enable-gate) ----
+        if (valueLabels === null || valueLabels === void 0 ? void 0 : valueLabels.show) {
+            for (let j = 0; j < pts.length; j++) {
+                const raw = model.series[i].values[j];
+                if (raw == null || !Number.isFinite(raw))
+                    continue;
+                const markerR = st.showPoints ? (j === highlightIndex ? st.pointRadius * 1.7 : st.pointRadius) : 0;
+                const text = (0, format_1.formatValueLabel)(raw, valueLabels.format, valueLabels.decimals);
+                const lc = ((_d = valueLabels.color) !== null && _d !== void 0 ? _d : st.color);
+                const overlay = reduce ? undefined : { enable: `gte(t,${(0, anim_1.pointStartSec)(vertexFracs[j], anim).toFixed(3)})` };
+                const label = placeValueLabel(W, H, pts[j].x, pts[j].y - markerR - 4, text, valueLabels.fontSize, lc, overlay);
+                // The rect shows a FORMATTED rendering of one raw leaf — still that
+                // leaf's display (Make seeds the editor from the raw number).
+                if (valuesBinding)
+                    (0, template_utils_1.bindPropPath)(label.source, valuesBinding.propKey, valuesBinding.nested ? [i, j] : [j], "number");
+                labels.push(label);
+            }
+        }
+    }
+    // Assemble bottom→top. The curtain sits ABOVE the data atlases (hides them)
+    // and BELOW the value labels (which pop in independently).
+    const dataPieces = [...areas, ...lines, ...markerBorders, ...markerFills];
+    const pieces = [...dataPieces];
+    if (useCurtain && plotBg && dataPieces.length > 0) {
+        const cols = (0, anim_1.buildCurtainColumns)(plot, anim, { padPx: Math.ceil(maxOverhangPx + EDGE_PAD) });
+        const curtain = (0, template_utils_1.curtainSource)(cols, plotBg.color);
+        if (curtain)
+            pieces.push({ rect: fullRect(), source: curtain });
+    }
+    pieces.push(...labels);
+    if (pieces.length === 0)
+        return null;
+    const placed = (0, dsl_stdlib_1.placeRects)({ rootW: frame_1.BASIS_COL, rootH: frame_1.BASIS_ROW, rects: pieces.map((p) => p.rect) });
+    // Source order must match the composed m0's emission: per layer (base→top),
+    // each rect occupies exactly one band, so sort by (y, x).
+    const sources = [];
+    for (const layer of placed.layers) {
+        const ordered = [...layer.rectIndices].sort((a, b) => pieces[a].rect.y - pieces[b].rect.y || pieces[a].rect.x - pieces[b].rect.x);
+        for (const idx of ordered)
+            sources.push(pieces[idx].source);
+    }
+    return { m0: String(placed.m0), sources };
+}
+function clamp01(v) {
+    return Math.max(0, Math.min(1, v));
+}

package/dist/m0saic/charts/line-chart/v1/types.d.ts

@@ -0,0 +1,328 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — Shared Types
+ * ============================================================================
+ *
+ * Single source of truth for every TypeScript type shared across the
+ * line-chart template family (public + all internals).
+ *
+ * RULE (mirrors bar-graph):
+ *   - Public props (LineChartProps) are PERMISSIVE — unions, single-or-array,
+ *     px shorthands. The top-level template resolves them.
+ *   - Internals receive fully-RESOLVED types (no unions, fractions/px decided).
+ *   - Keep types PURE — no runtime values. Type-only imports are erased at
+ *     compile, so `import type` from template-utils (e.g. ThemeSourceConfig) is fine.
+ * ============================================================================
+ */
+import type { MosaicColor } from "@m0saic/types";
+import type { ThemeSourceConfig } from "@m0saic/template-utils";
+/**
+ * The canonical line-chart look is LIGHT (white card, light grid, dark text,
+ * blue line) — the default Chart.js baseline. `neutral` is therefore light,
+ * unlike bar-graph's dark `neutral`. Dark variants are opt-in.
+ */
+export type LineChartPreset = "neutral" | "dark" | "terminal" | "glass" | "paper";
+/** How the card surface behind the plot is painted. */
+export type BackgroundMode = "preset" | "solid" | "image" | "none";
+export type Padding = number | {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export type ResolvedPadding = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export type AxisTickFormat = "raw" | "compact" | "percent";
+/** Public per-axis config group (xAxis / yAxis). All fields optional. */
+export type AxisConfigInput = {
+    /** Draw the axis line itself. */
+    show?: boolean;
+    color?: MosaicColor;
+    thickness?: number;
+    /** Tick labels. */
+    showLabels?: boolean;
+    labelColor?: MosaicColor;
+    fontSize?: number;
+    format?: AxisTickFormat;
+    decimals?: number;
+    prefix?: string;
+    suffix?: string;
+    /** Tick marks (the little ticks on the axis line). */
+    tickCount?: number;
+    showTicks?: boolean;
+    tickLength?: number;
+    tickColor?: MosaicColor;
+    /** x-label rotation in degrees (x axis only). */
+    rotation?: number;
+    /** Gridlines for this axis. */
+    showGrid?: boolean;
+    gridCount?: number;
+    gridColor?: MosaicColor;
+    gridOpacity?: number;
+    gridDash?: LineStyle;
+};
+/** Fully-resolved per-axis config consumed by the renderer. */
+export type ResolvedAxis = {
+    show: boolean;
+    color: MosaicColor;
+    thickness: number;
+    showLabels: boolean;
+    labelColor: MosaicColor;
+    fontSize: number;
+    format: AxisTickFormat;
+    decimals: number;
+    prefix: string;
+    suffix: string;
+    tickCount: number;
+    showTicks: boolean;
+    tickLength: number;
+    tickColor: MosaicColor;
+    rotation: number;
+    showGrid: boolean;
+    gridCount: number;
+    gridColor: MosaicColor;
+    gridOpacity: number;
+    gridDash: LineStyle;
+};
+export type LineStyle = "solid" | "dashed" | "dotted";
+export type Curve = "linear" | "smooth" | "stepped";
+export type LineCap = "butt" | "round" | "square";
+export type LineJoin = "miter" | "round" | "bevel";
+export type PointShape = "circle" | "square" | "diamond";
+export type AreaConfig = {
+    show?: boolean;
+    color?: MosaicColor;
+    opacity?: number;
+};
+export type ResolvedArea = {
+    show: boolean;
+    color?: MosaicColor;
+    opacity: number;
+};
+export type PointBorder = {
+    color?: MosaicColor;
+    width?: number;
+};
+/** Public line config (single value OR per-series array where noted). */
+export type LineConfigInput = {
+    lineColor?: MosaicColor | MosaicColor[];
+    strokeWidth?: number | number[];
+    lineStyle?: LineStyle;
+    curve?: Curve;
+    lineCap?: LineCap;
+    lineJoin?: LineJoin;
+    area?: AreaConfig;
+};
+export type PointsConfigInput = {
+    showPoints?: boolean;
+    pointRadius?: number;
+    pointColor?: MosaicColor;
+    pointShape?: PointShape;
+    pointBorder?: PointBorder;
+    highlightIndex?: number;
+    highlightLast?: boolean;
+};
+/** Fully-resolved per-series style (the renderer iterates these). */
+export type ResolvedSeriesStyle = {
+    color: MosaicColor;
+    strokeWidth: number;
+    lineStyle: LineStyle;
+    curve: Curve;
+    lineCap: LineCap;
+    lineJoin: LineJoin;
+    area: ResolvedArea;
+    showPoints: boolean;
+    pointRadius: number;
+    pointColor: MosaicColor;
+    pointShape: PointShape;
+    pointBorder: {
+        color?: MosaicColor;
+        width: number;
+    };
+};
+export type TextAlign = "left" | "center" | "right";
+export type LegendPosition = "top" | "bottom";
+export type LegendConfig = {
+    show?: boolean;
+    position?: LegendPosition;
+    color?: MosaicColor;
+    fontSize?: number;
+};
+export type ResolvedLegend = {
+    show: boolean;
+    position: LegendPosition;
+    color: MosaicColor;
+    fontSize: number;
+};
+export type ValueLabelFormat = "raw" | "compact" | "percent";
+export type ValueLabelsConfig = {
+    show?: boolean;
+    format?: ValueLabelFormat;
+    decimals?: number;
+    color?: MosaicColor;
+    fontSize?: number;
+};
+export type ResolvedValueLabels = {
+    show: boolean;
+    format: ValueLabelFormat;
+    decimals: number;
+    color?: MosaicColor;
+    fontSize: number;
+};
+export type EaseName = "linear" | "smoothstep" | "easeInOut";
+export type AnimIntroConfig = {
+    durationSec: number;
+    delaySec: number;
+    staggerSec: number;
+    ease: EaseName;
+};
+export type AnimConfig = {
+    intro: AnimIntroConfig;
+    reduceMotion: boolean;
+};
+export type BorderConfig = {
+    color?: MosaicColor;
+    alpha?: number;
+};
+export type ResolvedBorder = {
+    color: MosaicColor;
+    alpha: number;
+};
+/**
+ * The canonical props interface for @m0saic/charts/line-chart/v1.
+ *
+ * Required:
+ *   values — one series (number[]) OR many series (number[][]).
+ *
+ * Everything else is optional with defaults in defaults.ts.
+ */
+/**
+ * FLAT internal prop shape — what the render pipeline (line-series / geometry /
+ * card / frame …) consumes. The PUBLIC `LineChartProps` (below) groups these into
+ * collapsible sections for the Make panel; `render` flattens grouped → flat once
+ * up front (`flattenLineChartProps`), so the machinery stays flat + untouched.
+ */
+export type LineChartFlat = {
+    /** One series, or many (multi-series core). */
+    values: number[] | number[][];
+    seriesLabels?: string[];
+    labels?: string[];
+    xValues?: number[];
+    minValue?: number;
+    maxValue?: number;
+    minX?: number;
+    maxX?: number;
+    preset?: LineChartPreset;
+    backgroundColor?: MosaicColor | "none";
+    backgroundImage?: string;
+    cornerRadius?: number;
+    border?: BorderConfig;
+    padding?: Padding;
+    xAxis?: AxisConfigInput;
+    yAxis?: AxisConfigInput;
+    lineColor?: MosaicColor | MosaicColor[];
+    strokeWidth?: number | number[];
+    lineStyle?: LineStyle;
+    curve?: Curve;
+    lineCap?: LineCap;
+    lineJoin?: LineJoin;
+    area?: AreaConfig;
+    showPoints?: boolean;
+    pointRadius?: number;
+    pointColor?: MosaicColor;
+    pointShape?: PointShape;
+    pointBorder?: PointBorder;
+    highlightIndex?: number;
+    highlightLast?: boolean;
+    title?: string;
+    subtitle?: string;
+    titleColor?: MosaicColor;
+    titleSize?: number;
+    titleAlign?: TextAlign;
+    legend?: LegendConfig;
+    valueLabels?: ValueLabelsConfig;
+    anim?: AnimConfig;
+    reduceMotion?: boolean;
+    debugLayout?: boolean;
+    theme?: ThemeSourceConfig;
+};
+/**
+ * PUBLIC props — grouped into collapsible sections (flat props first would still
+ * read as a wall; the Make panel only nests via `type:"group"`). Data stays up
+ * top (values / series / x-labels); everything else lives under a labeled group.
+ * `render` maps this onto `LineChartFlat` via `flattenLineChartProps`.
+ */
+export type LineChartProps = {
+    /** One series, or many (multi-series core). Required. */
+    values: number[] | number[][];
+    /** Legend names (index-aligned to series). */
+    seriesLabels?: string[];
+    /** Categorical x tick labels. */
+    labels?: string[];
+    /** Axis domain overrides + explicit numeric x values. */
+    domain?: {
+        xValues?: number[];
+        minValue?: number;
+        maxValue?: number;
+        minX?: number;
+        maxX?: number;
+    };
+    /** Line stroke (single or per-series) + area fill. */
+    line?: {
+        lineColor?: MosaicColor | MosaicColor[];
+        strokeWidth?: number | number[];
+        lineStyle?: LineStyle;
+        curve?: Curve;
+        lineCap?: LineCap;
+        lineJoin?: LineJoin;
+        area?: AreaConfig;
+    };
+    /** Vertex markers + highlight. */
+    points?: {
+        showPoints?: boolean;
+        pointRadius?: number;
+        pointColor?: MosaicColor;
+        pointShape?: PointShape;
+        pointBorder?: PointBorder;
+        highlightIndex?: number;
+        highlightLast?: boolean;
+    };
+    /** X + Y axis lines, labels, grid, ticks. */
+    axes?: {
+        xAxis?: AxisConfigInput;
+        yAxis?: AxisConfigInput;
+    };
+    /** Color scheme (preset) + card surface. */
+    appearance?: {
+        preset?: LineChartPreset;
+        backgroundColor?: MosaicColor | "none";
+        backgroundImage?: string;
+        cornerRadius?: number;
+        padding?: Padding;
+        border?: BorderConfig;
+    };
+    /** Chart title + subtitle. */
+    titles?: {
+        title?: string;
+        subtitle?: string;
+        titleColor?: MosaicColor;
+        titleSize?: number;
+        titleAlign?: TextAlign;
+    };
+    legend?: LegendConfig;
+    valueLabels?: ValueLabelsConfig;
+    /** Intro draw-on animation (+ reduceMotion). */
+    anim?: AnimConfig;
+    /** Dev-only: draw the layout contract instead of the chart. */
+    debugLayout?: boolean;
+    /**
+     * Opt into a theme SOURCE. Omit → reads the default "theme" namespace off ctx
+     * and falls back to the resolved preset's tokens (auto-themes as a child,
+     * byte-identical standalone). Provide a `slug` to self-seed from a producer.
+     */
+    theme?: ThemeSourceConfig;
+};

package/dist/m0saic/charts/line-chart/v1/types.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — Shared Types
+ * ============================================================================
+ *
+ * Single source of truth for every TypeScript type shared across the
+ * line-chart template family (public + all internals).
+ *
+ * RULE (mirrors bar-graph):
+ *   - Public props (LineChartProps) are PERMISSIVE — unions, single-or-array,
+ *     px shorthands. The top-level template resolves them.
+ *   - Internals receive fully-RESOLVED types (no unions, fractions/px decided).
+ *   - Keep types PURE — no runtime values. Type-only imports are erased at
+ *     compile, so `import type` from template-utils (e.g. ThemeSourceConfig) is fine.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// ---------------------------------------------------------------------------
+// Internal template props
+// ---------------------------------------------------------------------------
+// Internal-template props (ChromeProps) live next to their template in
+// chrome.ts; the data layer + card surface are plain builders, not nested
+// templates, so they need no prop types here.