@m0saic/templates 0.2.0

package/dist/m0saic/charts/bar-graph/v1/internal/bars-stack.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BarsStack = exports.BARS_STACK_TEMPLATE_ID = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const defaults_1 = require("../defaults");
+exports.BARS_STACK_TEMPLATE_ID = (0, types_1.asTemplateId)("@m0saic/charts/bar-graph/internal/bars-stack/v1");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    axisConfig: {
+        type: "group",
+        required: true,
+        description: "Resolved axis configuration (layoutAxis determines split direction).",
+    },
+    values: {
+        type: "number[]",
+        required: true,
+        description: "Raw data values (one per bar).",
+    },
+    fractions: {
+        type: "number[]",
+        required: true,
+        description: "Domain-normalized [0..1] fill fractions for each bar.",
+    },
+    minValue: {
+        type: "number",
+        required: true,
+        description: "Resolved domain min (for future label/tick formatting).",
+    },
+    maxValue: {
+        type: "number",
+        required: true,
+        description: "Resolved domain max (for future label/tick formatting).",
+    },
+    barColor: {
+        // `json` (permissive) represents the union string | string[]; the impl
+        // resolves single vs per-bar array.
+        type: "json",
+        required: true,
+        description: "Bar color(s): single color or array (cycled per bar).",
+    },
+    gap: {
+        type: "number",
+        required: true,
+        description: "Gap between bars in pixels.",
+        meta: { constraints: { min: 0, max: 256 } },
+    },
+    barThickness: {
+        type: "number",
+        required: false,
+        description: "Optional fixed bar thickness in pixels (otherwise auto).",
+        meta: { control: { placeholder: "auto (from gap)" }, constraints: { min: 1, max: 4096 } },
+    },
+    highlightIndex: {
+        type: "number",
+        required: false,
+        description: "Optional bar index to highlight.",
+        meta: { control: { placeholder: "none" }, constraints: { min: 0 } },
+    },
+    track: {
+        type: "group",
+        required: true,
+        description: "Track display configuration.",
+    },
+    valueLabels: {
+        type: "group",
+        required: true,
+        description: "Value label display configuration.",
+    },
+    labels: {
+        type: "string[]",
+        required: false,
+        description: "Optional category labels (index-aligned to values).",
+    },
+    anim: {
+        type: "group",
+        required: true,
+        description: "Animation configuration forwarded to BarCell/BarFill.",
+    },
+    cornerRadius: {
+        type: "number",
+        required: true,
+        description: "Geometric radius fraction (0..1) forwarded to BarCell.",
+        meta: { constraints: { min: 0, max: 1 } },
+    },
+});
+exports.BarsStack = {
+    id: exports.BARS_STACK_TEMPLATE_ID,
+    label: "Bar Graph — Bars Stack (internal)",
+    version: 1,
+    internal: true,
+    // Building block of the DEPRECATED @m0saic/charts/bar-graph/v1 composition —
+    // superseded with it (v2 is a flat single document and needs none of these).
+    deprecated: {
+        reason: "Internal piece of the deprecated 5-deep bar-graph/v1 nested composition; bar-graph/v2 renders the same chart as one flat document.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/charts/bar-graph/v2"),
+        since: "2026-09-16",
+    },
+    description: "Internal: layout container that arranges N BarCell children along the layout axis.",
+    capabilities: { tier: "core" },
+    tags: ["data-viz", "bar-graph", "internal", "bars-stack"],
+    propsSchema,
+    defaultProps: {
+        axisConfig: {
+            fillAxis: "y",
+            layoutAxis: "x",
+            labelDock: "bottom",
+            valueDock: "top",
+            gridDirection: "horizontal",
+            baselineEdge: "bottom",
+        },
+        values: [35, 60, 85, 45, 70],
+        fractions: [0.41, 0.71, 1.0, 0.53, 0.82],
+        minValue: 0,
+        maxValue: 85,
+        barColor: "#f97316",
+        gap: defaults_1.DEFAULT_GAP,
+        barThickness: undefined,
+        highlightIndex: undefined,
+        track: defaults_1.DEFAULT_TRACK,
+        valueLabels: defaults_1.DEFAULT_VALUE_LABELS,
+        labels: undefined,
+        anim: defaults_1.DEFAULT_ANIM,
+        cornerRadius: defaults_1.DEFAULT_CORNER_RADIUS,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d;
+        const N = props.values.length;
+        // ---- Validate aligned arrays ----
+        if (N <= 0) {
+            return (0, template_utils_1.makeErrorMosaic)("BarsStack: values[] must be non-empty", {
+                title: `${this.id}`,
+                width: ctx.output.width,
+                height: ctx.output.height,
+            });
+        }
+        if (props.fractions.length !== N) {
+            return (0, template_utils_1.makeErrorMosaic)(`BarsStack: fractions[] length mismatch (values=${N}, fractions=${props.fractions.length})`, { title: `${this.id}`, width: ctx.output.width, height: ctx.output.height });
+        }
+        if (props.labels && props.labels.length !== N) {
+            return (0, template_utils_1.makeErrorMosaic)(`BarsStack: labels[] length mismatch (values=${N}, labels=${props.labels.length})`, { title: `${this.id}`, width: ctx.output.width, height: ctx.output.height });
+        }
+        // ---- Determine axis pixels (prefer tile rect if present) ----
+        const rect = (_b = (_a = ctx.rect) !== null && _a !== void 0 ? _a : ctx.tileRect) !== null && _b !== void 0 ? _b : null;
+        const tileW = (_c = rect === null || rect === void 0 ? void 0 : rect.width) !== null && _c !== void 0 ? _c : ctx.output.width;
+        const tileH = (_d = rect === null || rect === void 0 ? void 0 : rect.height) !== null && _d !== void 0 ? _d : ctx.output.height;
+        const layoutAxis = props.axisConfig.layoutAxis;
+        const isX = layoutAxis !== "y"; // "x" (default) → bars in a row
+        // Gap between bars via a per-bar inset on a gutterless N-cell split — no
+        // spacer tokens (compact m0), pixel-exact gaps. Equal bar widths need an
+        // outer margin on the LAYOUT axis; the CROSS axis gets no inset so each
+        // bar keeps its full extent (height for vertical bars).
+        const barInset = (0, template_utils_1.gridCellInset)({
+            rows: isX ? 1 : N,
+            cols: isX ? N : 1,
+            gridW: tileW,
+            gridH: tileH,
+            gapPx: props.gap,
+            outerMargin: isX ? { x: true, y: false } : { x: false, y: true },
+        });
+        // ---- Build children + sources ----
+        const children = {};
+        const sources = [];
+        const barCellTemplateId = "@m0saic/charts/bar-graph/internal/bar-cell/v1";
+        for (let i = 0; i < N; i++) {
+            const childId = `bar-${i}`;
+            // Resolve per-bar color (string | string[] pattern, runtime-safe)
+            const bc = props.barColor;
+            const color = Array.isArray(bc) && bc.length > 0 ? bc[i % bc.length] : bc;
+            const child = await (0, template_utils_1.renderNestedTemplate)(barCellTemplateId, {
+                axisConfig: props.axisConfig,
+                value: props.values[i],
+                fraction: props.fractions[i],
+                label: props.labels ? props.labels[i] : undefined,
+                index: i,
+                highlighted: props.highlightIndex != null ? i === props.highlightIndex : false,
+                color,
+                barThickness: props.barThickness,
+                track: props.track,
+                valueLabels: props.valueLabels,
+                anim: props.anim,
+                cornerRadius: props.cornerRadius,
+                minValue: props.minValue,
+                maxValue: props.maxValue,
+            }, ctx);
+            children[childId] = child;
+            const inset = barInset(isX ? 0 : i, isX ? i : 0);
+            sources.push({
+                type: "mosaic",
+                ref: childId,
+                ...(inset ? { placement: { inset } } : {}),
+            });
+        }
+        // Gutterless N-cell split; the gap lives in each bar's inset (above).
+        const containerAxis = isX ? "col" : "row";
+        const raw = (0, dsl_stdlib_1.container)(Array.from({ length: N }, () => "1"), containerAxis);
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            sources,
+            assets: {},
+            m0: raw,
+            fps: ctx.target.fps, durationMs: ctx.target.durationMs,
+            children,
+        };
+    }
+};
+(0, template_utils_1.registerTemplate)(exports.BarsStack);

package/dist/m0saic/charts/bar-graph/v1/internal/chart-frame.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/bar-graph/internal/chart-frame/v1
+ * ============================================================================
+ *
+ * RESPONSIBILITY:
+ *   The outermost visual container (card surface) of the bar graph.
+ *
+ *   Owns:
+ *     - Card surface fill (theme preset → tokens.card)
+ *     - Rounded container mask + inner stroke
+ *     - Outer padding for PlotArea via placement.inset (fractions of tile size)
+ *     - Preset token resolution (preset → colors)
+ *
+ *   Does NOT own:
+ *     - Canvas/background fill (tokens.bg is applied by the parent scene/template)
+ *
+ * COMPOSITION:
+ *   ChartFrame receives a child ref (plotAreaRef) pointing to PlotArea.
+ *   It composes:
+ *     - base:  Card surface (rounded + stroke)
+ *     - overlay: PlotArea (inset into card)
+ *
+ * NOTES:
+ *   - All padding values are fractions of the tile size (0..1). No pixels.
+ *   - Guardrails enforce that padding does not consume the entire plot rect.
+ * ============================================================================
+ */
+import type { MosaicTemplate } from "@m0saic/types";
+import type { ChartFrameProps } from "../types";
+export declare const CHART_FRAME_TEMPLATE_ID: import("@m0saic/types").TemplateId;
+export declare const ChartFrame: MosaicTemplate<ChartFrameProps>;

package/dist/m0saic/charts/bar-graph/v1/internal/chart-frame.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChartFrame = exports.CHART_FRAME_TEMPLATE_ID = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+exports.CHART_FRAME_TEMPLATE_ID = (0, types_1.asTemplateId)("@m0saic/charts/bar-graph/internal/chart-frame/v1");
+function tokensForPreset(preset) {
+    switch (preset) {
+        case "dark":
+            return { bg: "#0b0f14", card: "#0f172a", border: "#ffffff", borderAlpha: 0.08 };
+        case "terminal":
+            return { bg: "#050505", card: "#0b0b0b", border: "#22c55e", borderAlpha: 0.18 };
+        case "glass":
+            return { bg: "#0b0f14", card: "#111827", border: "#ffffff", borderAlpha: 0.10 };
+        case "paper":
+            return { bg: "#f8fafc", card: "#ffffff", border: "#0f172a", borderAlpha: 0.10 };
+        case "neutral":
+        default:
+            return { bg: "#0b0f14", card: "#0f172a", border: "#ffffff", borderAlpha: 0.08 };
+    }
+}
+// ---------------------------------------------------------------------------
+// Props schema
+// ---------------------------------------------------------------------------
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    padding: {
+        type: "group",
+        required: true,
+        description: "Outer padding as fractions of tile size (0..1): {top,right,bottom,left}.",
+    },
+    cornerRadius: {
+        type: "number",
+        required: true,
+        description: "Geometric radius fraction (0..1) for the container.",
+        meta: { constraints: { min: 0, max: 1 } },
+    },
+    preset: {
+        type: "string",
+        required: true,
+        description: "Theme preset name (neutral|dark|terminal|glass|paper).",
+    },
+    plotAreaRef: {
+        type: "string",
+        required: true,
+        description: "Child renderable key for the inner PlotArea.",
+    },
+});
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+exports.ChartFrame = {
+    id: exports.CHART_FRAME_TEMPLATE_ID,
+    label: "Bar Graph — Chart Frame (internal)",
+    version: 1,
+    internal: true,
+    // Building block of the DEPRECATED @m0saic/charts/bar-graph/v1 composition —
+    // superseded with it (v2 is a flat single document and needs none of these).
+    deprecated: {
+        reason: "Internal piece of the deprecated 5-deep bar-graph/v1 nested composition; bar-graph/v2 renders the same chart as one flat document.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/charts/bar-graph/v2"),
+        since: "2026-09-16",
+    },
+    description: "Internal: rounded card surface + inset PlotArea, with preset token resolution.",
+    capabilities: { tier: "core" },
+    tags: ["data-viz", "bar-graph", "internal", "frame"],
+    propsSchema,
+    defaultProps: {
+        padding: { top: 0.04, right: 0.04, bottom: 0.04, left: 0.04 },
+        cornerRadius: 0.18,
+        preset: "neutral",
+        plotAreaRef: "plot-area",
+    },
+    async render(props, ctx) {
+        const tokens = tokensForPreset(props.preset);
+        // If parent forgot to provide the child, make it obvious.
+        if (!props.plotAreaRef) {
+            return (0, template_utils_1.makeErrorMosaic)("plotAreaRef is required", {
+                title: `${this.id} props`,
+                width: ctx.output.width,
+                height: ctx.output.height,
+            });
+        }
+        const p = props.padding;
+        const sides = [p.top, p.right, p.bottom, p.left];
+        const hasNegative = sides.some((v) => typeof v !== "number" || Number.isNaN(v) || v < 0);
+        const consumesWidth = (p.left + p.right) >= 1;
+        const consumesHeight = (p.top + p.bottom) >= 1;
+        if (hasNegative || consumesWidth || consumesHeight) {
+            return (0, template_utils_1.makeErrorMosaic)(`Invalid padding. Expected fractions (0..1) and (left+right)<1, (top+bottom)<1. Got: ${JSON.stringify(props.padding)}`, { title: `${this.id} props`, width: ctx.output.width, height: ctx.output.height });
+        }
+        const doc = {
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: (0, dsl_stdlib_1.toM0String)("F{F}", "ChartFrame"),
+            children: {},
+            sources: [
+                // Card surface (base): owns rounding + stroke
+                {
+                    type: "lavfi",
+                    color: tokens.card,
+                    effects: {
+                        rounding: { cornerStyle: "rounded", borderRadius: props.cornerRadius },
+                        stroke: {
+                            position: "inner",
+                            width: 0.002,
+                            color: tokens.border,
+                            alpha: tokens.borderAlpha + 0.02,
+                        },
+                    },
+                },
+                // PlotArea (overlay): inset into the card
+                {
+                    type: "mosaic",
+                    ref: props.plotAreaRef,
+                    placement: { inset: props.padding },
+                },
+            ],
+        };
+        return doc;
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.ChartFrame);

package/dist/m0saic/charts/bar-graph/v1/internal/labels.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/bar-graph/internal/labels/v1
+ * ============================================================================
+ *
+ * Labels owns the chart's BANDED CONTENT LAYOUT — title band, plot region,
+ * category-label band, and value-axis tick rail. All structure is expressed
+ * through m0 (weightedSplit + container); no FFmpeg xExpr/yExpr positioning,
+ * no placement.inset gymnastics. The layout is described the way a human
+ * would describe it ("title on top, ticks on the left, bars in the middle,
+ * day labels on the bottom"); m0 carries the geometry.
+ *
+ * Vertical orientation (labelDock="bottom"):
+ *
+ *   row split (3 bands, weights derived from chart padding):
+ *     ├── title-band:    "2[1,1]" if subtitle exists, else "1"
+ *     │                     title text  (top sub-row)
+ *     │                     subtitle    (bottom sub-row)
+ *     ├── body:          2-col split  [tick-rail | plot]   when ticks on
+ *     │                  else just     "1"                  (plot only)
+ *     │                  tick rail = row split (M ticks + gaps)
+ *     └── label-band:    2-col split  [empty | N-cat-rail]  when ticks on
+ *                        else         "N(1,1,...)"           (labels span full width)
+ *
+ * Horizontal orientation (labelDock="left"):
+ *
+ *   row split (3 bands):
+ *     ├── title-band:    same as vertical
+ *     ├── body:          2-col split  [category-rail | plot]   if labels
+ *     │                  else         "1"                       (plot only)
+ *     └── tick-band:     2-col split  [empty | tick-rail]       when ticks on
+ *                        (matches body's category-rail / plot weights so the
+ *                         tick rail aligns under the plot, not the cat rail)
+ *
+ * Bands collapse out when their content is absent (no title → no title band,
+ * no labels → no label band, no ticks → no tick rail in body / no tick band).
+ *
+ * Tick values are computed deterministically from props.minValue / maxValue /
+ * gridCount: tickCount = gridCount + 1, evenly spaced from min..max. For
+ * vertical bars the rail is ordered top-down (max → min). For horizontal,
+ * left-to-right (min → max). Formatting honors props.valueLabels.format and
+ * decimals (same surface as the per-bar value labels for consistency).
+ *
+ * NOTE — future builder candidate. The "banded split with optional before /
+ * after sections" idiom keeps recurring; extract `bandedSplit({ before,
+ * content, after, axis })` to dsl-stdlib once a second consumer arrives.
+ * ============================================================================
+ */
+import type { MosaicTemplate } from "@m0saic/types";
+import type { LabelsProps } from "../types";
+export declare const LABELS_TEMPLATE_ID: import("@m0saic/types").TemplateId;
+export declare const Labels: MosaicTemplate<LabelsProps>;