@m0saic/templates 0.2.0

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

@@ -0,0 +1,78 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — Animation timing (pure)
+ * ============================================================================
+ *
+ * Timing math + FFmpeg-safe easing for the line-chart intro. PURE +
+ * deterministic — no side effects, no registration, no wall clock (every value
+ * derives from the resolved `AnimConfig`, itself derived from `ctx.target`).
+ *
+ * v1 intro = a left→right DRAW-ON. `line-series.ts` paints the finished
+ * line/area/markers as STATIC mask atlases and reveals them with ONE curtain
+ * (`buildCurtainColumns` here → `curtainSource`): hide-colored plot columns that
+ * pop open (a free `enable=` gate) on the same ease the cascade used. Value
+ * labels reuse `pointStartSec` as an `overlay.enable` gate. `sliverTiming` /
+ * `sweepInverseEase` are the LEGACY per-sliver schedule — retained (exported)
+ * only for back-compat + the geometry tests; the live path no longer uses them.
+ *
+ * TIME UNITS: seconds (matches FFmpeg `t` / overlay.startAtSec).
+ * ============================================================================
+ */
+import type { AnimConfig, EaseName } from "./types";
+export type SeriesTiming = {
+    startAtSec: number;
+    endAtSec: number;
+};
+/** Absolute start/end timestamps for a series' intro. */
+export declare function computeSeriesTiming(index: number, anim: AnimConfig): SeriesTiming;
+/** Map a normalized progress var u∈[0..1] → eased∈[0..1] (FFmpeg-safe). */
+export declare function easingExpr(ease: EaseName, uVar?: string): string;
+/**
+ * Inverse of the reveal easing: at what normalized time u does the sweep reach
+ * arc-length fraction p? Front-loads `easeOut`; identity for the rest (the
+ * per-sliver `fadeInExpr` already supplies visual easing).
+ */
+export declare function sweepInverseEase(ease: EaseName, p: number): number;
+export type SliverTiming = {
+    startSec: number;
+    fadeDur: number;
+};
+/**
+ * Schedule one sliver: when it starts revealing and how long it fades. With
+ * `fadeDur` ≈ 2.5 sliver-intervals the fades overlap into a continuous draw.
+ */
+export declare function sliverTiming(frac0: number, sliverCount: number, anim: AnimConfig): SliverTiming;
+/** When a point marker reveals (just after the sweep passes its vertex). */
+export declare function pointStartSec(vertexFrac: number, anim: AnimConfig): number;
+/** Chrome (grid/axes/labels) establishing-fade window: quick, before the draw. */
+export declare function chromeFade(anim: AnimConfig): {
+    startSec: number;
+    durSec: number;
+};
+/** One curtain column: an absolute-px box hidden until `revealAtSec`. */
+export type CurtainColumn = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    revealAtSec: number;
+};
+/** When the curtain uncovers x-fraction `xFrac∈[0..1]` of the plot — the same
+ *  ease/pacing as a point-marker reveal at that fraction. */
+export declare function columnRevealSec(xFrac: number, anim: AnimConfig): number;
+/**
+ * Tile the plot rect with `K = clamp(round(plotW/stepPx), 24, 120)` full-height
+ * columns walking left→right, each revealing at `columnRevealSec(centerXFrac)`.
+ * `padPx` bleeds the coverage outward so markers/strokes that overhang the plot
+ * edges (top marker at the max value, first/last marker on the plot border) stay
+ * hidden until their column opens. Pure + deterministic.
+ */
+export declare function buildCurtainColumns(plot: {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}, anim: AnimConfig, opts?: {
+    stepPx?: number;
+    padPx?: number;
+}): CurtainColumn[];

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

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — Animation timing (pure)
+ * ============================================================================
+ *
+ * Timing math + FFmpeg-safe easing for the line-chart intro. PURE +
+ * deterministic — no side effects, no registration, no wall clock (every value
+ * derives from the resolved `AnimConfig`, itself derived from `ctx.target`).
+ *
+ * v1 intro = a left→right DRAW-ON. `line-series.ts` paints the finished
+ * line/area/markers as STATIC mask atlases and reveals them with ONE curtain
+ * (`buildCurtainColumns` here → `curtainSource`): hide-colored plot columns that
+ * pop open (a free `enable=` gate) on the same ease the cascade used. Value
+ * labels reuse `pointStartSec` as an `overlay.enable` gate. `sliverTiming` /
+ * `sweepInverseEase` are the LEGACY per-sliver schedule — retained (exported)
+ * only for back-compat + the geometry tests; the live path no longer uses them.
+ *
+ * TIME UNITS: seconds (matches FFmpeg `t` / overlay.startAtSec).
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSeriesTiming = computeSeriesTiming;
+exports.easingExpr = easingExpr;
+exports.sweepInverseEase = sweepInverseEase;
+exports.sliverTiming = sliverTiming;
+exports.pointStartSec = pointStartSec;
+exports.chromeFade = chromeFade;
+exports.columnRevealSec = columnRevealSec;
+exports.buildCurtainColumns = buildCurtainColumns;
+/** Absolute start/end timestamps for a series' intro. */
+function computeSeriesTiming(index, anim) {
+    const startAtSec = anim.intro.delaySec + index * anim.intro.staggerSec;
+    const endAtSec = startAtSec + anim.intro.durationSec;
+    return { startAtSec, endAtSec };
+}
+/** Map a normalized progress var u∈[0..1] → eased∈[0..1] (FFmpeg-safe). */
+function easingExpr(ease, uVar = "u") {
+    if (ease === "smoothstep" || ease === "easeInOut") {
+        return `(${uVar})*(${uVar})*(3-2*(${uVar}))`;
+    }
+    return `${uVar}`; // linear
+}
+// NOTE: alpha expressions are generated by the canonical `fadeInExpr` from
+// @m0saic/template-utils (min/max + global `t` — the form ffmpeg AND the web
+// preview evaluator both accept). Do NOT hand-roll `clip`/`lt`: `clip` is
+// unsupported by the preview evaluator and silently evaluates to 0 (⇒ invisible
+// layer). Animated alpha works on lavfi/masked-tile + mosaic-ref layers, NOT on
+// media-image overlays.
+// ---------------------------------------------------------------------------
+// Draw-on sweep schedule (LEGACY per-sliver cascade — superseded by the curtain
+// reveal below; kept + exported for back-compat and the geometry tests).
+// ---------------------------------------------------------------------------
+/**
+ * Inverse of the reveal easing: at what normalized time u does the sweep reach
+ * arc-length fraction p? Front-loads `easeOut`; identity for the rest (the
+ * per-sliver `fadeInExpr` already supplies visual easing).
+ */
+function sweepInverseEase(ease, p) {
+    const c = Math.max(0, Math.min(1, p));
+    if (ease === "easeInOut")
+        return 1 - Math.sqrt(1 - c); // gentle front-load
+    return c; // linear / smoothstep ⇒ even pace
+}
+/**
+ * Schedule one sliver: when it starts revealing and how long it fades. With
+ * `fadeDur` ≈ 2.5 sliver-intervals the fades overlap into a continuous draw.
+ */
+function sliverTiming(frac0, sliverCount, anim) {
+    const intro = anim.intro;
+    const startSec = intro.delaySec + intro.durationSec * sweepInverseEase(intro.ease, frac0);
+    const fadeDur = Math.max(0.05, (intro.durationSec / Math.max(1, sliverCount)) * 2.5);
+    return { startSec, fadeDur };
+}
+/** When a point marker reveals (just after the sweep passes its vertex). */
+function pointStartSec(vertexFrac, anim) {
+    const intro = anim.intro;
+    return intro.delaySec + intro.durationSec * sweepInverseEase(intro.ease, vertexFrac);
+}
+/** Chrome (grid/axes/labels) establishing-fade window: quick, before the draw. */
+function chromeFade(anim) {
+    return { startSec: 0, durSec: Math.min(0.35, anim.intro.durationSec * 0.35) };
+}
+/** When the curtain uncovers x-fraction `xFrac∈[0..1]` of the plot — the same
+ *  ease/pacing as a point-marker reveal at that fraction. */
+function columnRevealSec(xFrac, anim) {
+    return pointStartSec(xFrac, anim);
+}
+/**
+ * Tile the plot rect with `K = clamp(round(plotW/stepPx), 24, 120)` full-height
+ * columns walking left→right, each revealing at `columnRevealSec(centerXFrac)`.
+ * `padPx` bleeds the coverage outward so markers/strokes that overhang the plot
+ * edges (top marker at the max value, first/last marker on the plot border) stay
+ * hidden until their column opens. Pure + deterministic.
+ */
+function buildCurtainColumns(plot, anim, opts = {}) {
+    var _a, _b;
+    const stepPx = (_a = opts.stepPx) !== null && _a !== void 0 ? _a : 16;
+    const padPx = Math.max(0, (_b = opts.padPx) !== null && _b !== void 0 ? _b : 0);
+    const plotW = Math.max(1, plot.right - plot.left);
+    const x0 = plot.left - padPx;
+    const x1 = plot.right + padPx;
+    const yTop = Math.round(plot.top - padPx);
+    const h = Math.max(1, Math.round(plot.bottom + padPx) - yTop);
+    const span = x1 - x0;
+    const K = Math.max(24, Math.min(120, Math.round(plotW / stepPx)));
+    const cols = [];
+    for (let k = 0; k < K; k++) {
+        const l = x0 + (span * k) / K;
+        const r = x0 + (span * (k + 1)) / K;
+        const lx = Math.round(l);
+        const w = Math.round(r) - lx;
+        if (w <= 0)
+            continue;
+        const xFrac = Math.max(0, Math.min(1, ((l + r) / 2 - plot.left) / plotW));
+        cols.push({ x: lx, y: yTop, w, h, revealAtSec: columnRevealSec(xFrac, anim) });
+    }
+    return cols;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — Axis docks + background-mode resolution
+ * ============================================================================
+ *
+ * Unlike bar-graph, a line chart does not flip orientation: the x axis is
+ * always docked bottom, the y axis always left, gridlines run both ways. So
+ * "axis config" here is a fixed struct plus the one genuinely variable layout
+ * decision the chart frame needs — which of the three background modes
+ * (transparent / solid / image) applies.
+ *
+ * PURE — no side effects, no rendering, no registration.
+ * ============================================================================
+ */
+import type { MosaicColor } from "@m0saic/types";
+import type { BackgroundMode, LineChartPreset } from "./types";
+/** Canonical line-chart docks. Fixed (no orientation branch). */
+export declare const PLOT_DOCKS: {
+    readonly xLabelDock: "bottom";
+    readonly yLabelDock: "left";
+    readonly baselineEdge: "bottom";
+    readonly valueAxisEdge: "left";
+    readonly gridDirections: readonly ["horizontal", "vertical"];
+};
+export type BackgroundResolution = {
+    mode: BackgroundMode;
+    /** Card color used for the "solid"/"preset" surface. */
+    cardColor: MosaicColor;
+    /** Canvas color stamped on the top document (undefined ⇒ transparent). */
+    canvasColor: MosaicColor | undefined;
+    /** Image ref (data-uri / path) for "image" mode. */
+    backgroundImage?: string;
+};
+/**
+ * Resolve the three-way background requirement into a concrete mode + colors.
+ *
+ *   backgroundColor: "none"   → transparent (composites under card chrome)
+ *   backgroundImage present   → image surface
+ *   backgroundColor: <color>  → solid surface
+ *   otherwise                 → preset card surface
+ *
+ * Precedence: explicit "none" wins; then image; then solid; then preset.
+ */
+export declare function resolveBackground(opts: {
+    preset: LineChartPreset;
+    backgroundColor?: MosaicColor | "none";
+    backgroundImage?: string;
+}): BackgroundResolution;

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

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — Axis docks + background-mode resolution
+ * ============================================================================
+ *
+ * Unlike bar-graph, a line chart does not flip orientation: the x axis is
+ * always docked bottom, the y axis always left, gridlines run both ways. So
+ * "axis config" here is a fixed struct plus the one genuinely variable layout
+ * decision the chart frame needs — which of the three background modes
+ * (transparent / solid / image) applies.
+ *
+ * PURE — no side effects, no rendering, no registration.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLOT_DOCKS = void 0;
+exports.resolveBackground = resolveBackground;
+const defaults_1 = require("./defaults");
+/** Canonical line-chart docks. Fixed (no orientation branch). */
+exports.PLOT_DOCKS = {
+    xLabelDock: "bottom",
+    yLabelDock: "left",
+    baselineEdge: "bottom",
+    valueAxisEdge: "left",
+    gridDirections: ["horizontal", "vertical"],
+};
+/**
+ * Resolve the three-way background requirement into a concrete mode + colors.
+ *
+ *   backgroundColor: "none"   → transparent (composites under card chrome)
+ *   backgroundImage present   → image surface
+ *   backgroundColor: <color>  → solid surface
+ *   otherwise                 → preset card surface
+ *
+ * Precedence: explicit "none" wins; then image; then solid; then preset.
+ */
+function resolveBackground(opts) {
+    const tk = defaults_1.PRESET_TOKENS[opts.preset];
+    if (opts.backgroundColor === "none") {
+        return { mode: "none", cardColor: tk.card, canvasColor: undefined };
+    }
+    if (opts.backgroundImage) {
+        return {
+            mode: "image",
+            cardColor: tk.card,
+            canvasColor: undefined,
+            backgroundImage: opts.backgroundImage,
+        };
+    }
+    if (typeof opts.backgroundColor === "string") {
+        return { mode: "solid", cardColor: opts.backgroundColor, canvasColor: opts.backgroundColor };
+    }
+    return { mode: "preset", cardColor: tk.card, canvasColor: tk.bg };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — card base builder (the 3 background modes)
+ * ============================================================================
+ *
+ * Builds the outermost surface source + any assets it needs:
+ *   - "none"  → transparent (composites under whatever is below)
+ *   - "solid"/"preset" → rounded color card + inner stroke
+ *   - "image" → image surface (data-uri / file path) + rounding + stroke
+ *
+ * Pure builder (no template registration) — the public template stacks the
+ * returned source as the base layer and merges the returned assets.
+ * ============================================================================
+ */
+import type { MosaicAsset, MosaicColor, MosaicSource } from "@m0saic/types";
+import type { BackgroundMode, ResolvedBorder } from "./types";
+export type CardBaseOpts = {
+    mode: BackgroundMode;
+    cardColor: MosaicColor;
+    backgroundImage?: string;
+    cornerRadius: number;
+    border: ResolvedBorder;
+};
+export declare function buildCardBase(opts: CardBaseOpts): {
+    source: MosaicSource;
+    assets: Record<string, MosaicAsset>;
+};

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

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — card base builder (the 3 background modes)
+ * ============================================================================
+ *
+ * Builds the outermost surface source + any assets it needs:
+ *   - "none"  → transparent (composites under whatever is below)
+ *   - "solid"/"preset" → rounded color card + inner stroke
+ *   - "image" → image surface (data-uri / file path) + rounding + stroke
+ *
+ * Pure builder (no template registration) — the public template stacks the
+ * returned source as the base layer and merges the returned assets.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCardBase = buildCardBase;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+function buildCardBase(opts) {
+    const rounding = { cornerStyle: "rounded", borderRadius: opts.cornerRadius };
+    const stroke = { position: "inner", width: 0.002, color: opts.border.color, alpha: opts.border.alpha };
+    if (opts.mode === "none") {
+        return { source: (0, template_utils_1.transparentSlot)(), assets: {} };
+    }
+    if (opts.mode === "image" && opts.backgroundImage) {
+        const isData = opts.backgroundImage.startsWith("data:");
+        const assets = {
+            bg: isData
+                ? { kind: "data-uri", uri: opts.backgroundImage, mediaType: "image" }
+                : { kind: "file", path: opts.backgroundImage, mediaType: "image" },
+        };
+        const source = {
+            type: "media",
+            mediaType: "image",
+            assetId: (0, types_1.asAssetId)("bg"),
+            placement: { fit: "cover" },
+            effects: { rounding, stroke },
+        };
+        return { source, assets };
+    }
+    // "solid" or "preset"
+    return { source: (0, template_utils_1.makeColorTile)(opts.cardColor, { effects: { rounding, stroke } }), assets: {} };
+}

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

@@ -0,0 +1,110 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/line-chart — chrome spec (the REAL-geometry plan)
+ * ============================================================================
+ *
+ * Pure: turns the projected model + resolved axis/title/legend config into a
+ * DECLARATIVE plan of frame REGIONS (header bands, y-gutter tick labels,
+ * x-gutter category labels, gridlines, axis lines). chrome.ts encodes this plan
+ * as REAL m0 geometry (weightedSplit cells + the grid primitive) — NOT a stack
+ * of full-canvas drawtext/mask overlays.
+ *
+ * This file is "JS pixel-math → region intent"; chrome.ts is "intent → m0 DSL".
+ * See the internal rects-not-drawtext-real-geometry notes.
+ * ============================================================================
+ */
+import type { MosaicColor } from "@m0saic/types";
+import type { LineChartModel } from "../../_shared/line";
+import type { ResolvedAxis, ResolvedLegend, ResolvedSeriesStyle, TextAlign } from "./types";
+import type { FrameWeights } from "./frame";
+export type VAlign = "top" | "middle" | "bottom";
+export type FrameText = {
+    text: string;
+    size: number;
+    color: MosaicColor;
+    hAlign: TextAlign;
+    vAlign: VAlign;
+    /** Optional font weight (700 = bold title). */
+    weight?: number;
+    /** Optional CELL weight (half-band units) — set by the x autoskip so a shown
+     *  label's cell spans the skipped neighbors instead of one narrow band. */
+    cellWeight?: number;
+    /** Make inline-edit binding: the PARENT line-chart prop this text DISPLAYS
+     *  (dotted schema path; `index` = element of a list prop). Intent only —
+     *  chrome.ts applies it via `bindProp`; it never touches the m0. */
+    binding?: {
+        propKey: string;
+        index?: number;
+    };
+};
+export type GridSpec = {
+    direction: "horizontal" | "vertical";
+    count: number;
+    color: MosaicColor;
+    opacity: number;
+};
+export type LegendEntry = {
+    swatch: MosaicColor;
+    label: FrameText;
+};
+export type HeaderBandKind = "title" | "subtitle" | "legend";
+export type HeaderBand = {
+    kind: HeaderBandKind;
+    weight: number;
+};
+export type ChromeSpec = {
+    width: number;
+    height: number;
+    frame: FrameWeights;
+    header: {
+        bands: HeaderBand[];
+        title?: FrameText;
+        subtitle?: FrameText;
+        legend?: {
+            entries: LegendEntry[];
+        };
+    };
+    /** legend.position === "bottom": the legend renders as a footer row inside
+     *  the x-gutter band (the parent widens pad.bottom to make room). */
+    footer?: {
+        entries: LegendEntry[];
+        bandPx: number;
+    };
+    /** Y tick labels top→bottom (vAlign already assigned for edge alignment). */
+    yTicks: FrameText[];
+    /** X category labels left→right (hAlign already assigned for edge alignment). */
+    xLabels: FrameText[];
+    /** Gridline sets drawn inside the plot cell via the grid primitive. */
+    grids: GridSpec[];
+    /** Axis-line colors (undefined ⇒ that axis line is hidden). */
+    axis: {
+        y?: MosaicColor;
+        x?: MosaicColor;
+    };
+    /** Tick-mark stubs at each label (undefined ⇒ that axis has no ticks). */
+    tickMarks: {
+        y?: {
+            color: MosaicColor;
+            length: number;
+        };
+        x?: {
+            color: MosaicColor;
+            length: number;
+        };
+    };
+};
+export type ChromeSpecOptions = {
+    xAxis: ResolvedAxis;
+    yAxis: ResolvedAxis;
+    series: ResolvedSeriesStyle[];
+    title?: string;
+    subtitle?: string;
+    titleColor: MosaicColor;
+    titleSize: number;
+    titleAlign: TextAlign;
+    subtitleColor: MosaicColor;
+    legend: ResolvedLegend;
+    /** px the parent added to pad.bottom for a bottom-positioned legend. */
+    legendBandPx?: number;
+};
+export declare function buildChromeSpec(model: LineChartModel, frame: FrameWeights, o: ChromeSpecOptions): ChromeSpec;