@m0saic/templates 0.2.0

package/dist/m0saic/alpine/treemap/v1/treemap.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlpineTreemap = 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 alpine_card_1 = require("../../_shared/alpine-card");
+const alpine_theme_1 = require("../../_shared/alpine-theme");
+const alpine_anim_1 = require("../../_shared/alpine-anim");
+const DEFAULT_PRESET = "light";
+const DEFAULT_RENDER_MODE = "premium";
+const DEFAULT_ANIM = { renderMode: DEFAULT_RENDER_MODE, introFrac: 0.7, easing: "easeOut", reduceMotion: false };
+const DEFAULT_VALUE_MODE = "percent";
+const MAX_ITEMS = 12;
+const SNAP_PX = 4;
+const EDGE_PAD = 1.5;
+// ---------------------------------------------------------------------------
+// Color / format helpers
+// ---------------------------------------------------------------------------
+function luminance(hex) {
+    const m = /^#?([0-9a-f]{6})/i.exec(String(hex));
+    if (!m)
+        return 0;
+    const v = parseInt(m[1], 16);
+    return (0.2126 * ((v >> 16) & 0xff) + 0.7152 * ((v >> 8) & 0xff) + 0.0722 * (v & 0xff)) / 255;
+}
+function onColor(hex, light, dark) {
+    return luminance(hex) > 0.62 ? dark : light;
+}
+function compactNum(v) {
+    const n = Math.round(v);
+    const abs = Math.abs(n);
+    const fmt = (x, suf) => `${x.toFixed(1).replace(/\.0$/, "")}${suf}`;
+    if (abs < 1000)
+        return String(n);
+    if (abs < 1e6)
+        return fmt(n / 1e3, "K");
+    if (abs < 1e9)
+        return fmt(n / 1e6, "M");
+    return fmt(n / 1e9, "B");
+}
+const clampInt = (v, lo, hi) => Math.max(lo, Math.min(hi, Math.round(v)));
+const snapGrid = (v) => Math.round(v / SNAP_PX) * SNAP_PX;
+function rectPiece(W, H, x, y, w, h, source, importance) {
+    const x0 = clampInt(snapGrid(x), 0, W - SNAP_PX);
+    const y0 = clampInt(snapGrid(y), 0, H - SNAP_PX);
+    const x1 = clampInt(snapGrid(x + w), x0 + SNAP_PX, W);
+    const y1 = clampInt(snapGrid(y + h), y0 + SNAP_PX, H);
+    return { rect: { x: x0, y: y0, w: x1 - x0, h: y1 - y0, claimant: "F", importance }, source };
+}
+function placeText(W, H, bbox, source, importance) {
+    const snapDown = (v) => Math.floor((v - EDGE_PAD) / SNAP_PX) * SNAP_PX;
+    const snapUp = (v) => Math.ceil((v + EDGE_PAD) / SNAP_PX) * SNAP_PX;
+    const x = clampInt(snapDown(bbox.minX), 0, W - 1);
+    const y = clampInt(snapDown(bbox.minY), 0, H - 1);
+    const x2 = clampInt(snapUp(bbox.maxX), x + SNAP_PX, W);
+    const y2 = clampInt(snapUp(bbox.maxY), y + SNAP_PX, H);
+    return { rect: { x, y, w: x2 - x, h: y2 - y, claimant: "F", importance }, source };
+}
+function cellText(text, fontSize, color, hAlign = "left") {
+    return { type: "text", visual: { backgroundColor: "black@0" }, layers: [{ content: { kind: "literal", text: text || " " }, style: { fontSize, fontColor: color }, placement: { hAlign, vAlign: "middle" } }] };
+}
+function fadeIn(src, startSec, durSec, on) {
+    var _a;
+    if (!on)
+        return src;
+    const prev = (_a = src.overlay) !== null && _a !== void 0 ? _a : {};
+    return { ...src, overlay: { ...prev, alpha: (0, template_utils_1.fadeInExpr)(startSec, durSec) } };
+}
+/** Left-anchored text bbox (starts AT x). */
+function leftTextBBox(x, cy, text, font) {
+    const w = Math.max(font, text.length * font * 0.6 + font * 0.4);
+    const h = font * 1.5;
+    return { minX: x, minY: cy - h / 2, maxX: x + w, maxY: cy + h / 2 };
+}
+/** Clip a line to maxW px with an ellipsis so a long name never spills its tile. */
+function truncateToWidth(text, font, maxW) {
+    const maxChars = Math.max(1, Math.floor(maxW / (font * 0.6)));
+    if (text.length <= maxChars)
+        return text;
+    if (maxChars <= 1)
+        return "…";
+    return `${text.slice(0, maxChars - 1).trimEnd()}…`;
+}
+// ---------------------------------------------------------------------------
+// Squarified treemap (Bruls/Huizing/van Wijk). Returns one rect per input area,
+// in the SAME order as `areas`. `areas` must be pre-scaled to the rect's area.
+// ---------------------------------------------------------------------------
+function squarify(areas, rect) {
+    const out = new Array(areas.length);
+    const sum = (a) => a.reduce((s, v) => s + v, 0);
+    // worst aspect ratio of a row laid along a side of length `side`.
+    const worst = (row, side) => {
+        if (row.length === 0)
+            return Infinity;
+        const s = sum(row);
+        const rmax = Math.max(...row), rmin = Math.min(...row);
+        return Math.max((side * side * rmax) / (s * s), (s * s) / (side * side * rmin));
+    };
+    let x = rect.x, y = rect.y, w = rect.w, h = rect.h;
+    let i = 0;
+    const n = areas.length;
+    // Lay a finished row into [x,y,w,h]; write rects to `out[startIdx..]`; return the leftover rect.
+    const layoutRow = (row, startIdx) => {
+        const s = sum(row);
+        if (w >= h) {
+            const rw = s / h; // column of width rw down the left edge
+            let yy = y;
+            for (let k = 0; k < row.length; k++) {
+                const rh = row[k] / rw;
+                out[startIdx + k] = { x, y: yy, w: rw, h: rh };
+                yy += rh;
+            }
+            x += rw;
+            w -= rw;
+        }
+        else {
+            const rh = s / w; // row of height rh across the top
+            let xx = x;
+            for (let k = 0; k < row.length; k++) {
+                const rw = row[k] / rh;
+                out[startIdx + k] = { x: xx, y, w: rw, h: rh };
+                xx += rw;
+            }
+            y += rh;
+            h -= rh;
+        }
+    };
+    let row = [];
+    let rowStart = 0;
+    while (i < n) {
+        const side = Math.min(w, h);
+        const next = areas[i];
+        if (row.length === 0 || worst([...row, next], side) <= worst(row, side)) {
+            row.push(next);
+            i++;
+        }
+        else {
+            layoutRow(row, rowStart);
+            rowStart += row.length;
+            row = [];
+        }
+    }
+    if (row.length)
+        layoutRow(row, rowStart);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    items: { type: "array", required: true, description: "Treemap items. Each: a label, a value (sizes the tile), an optional color.", meta: { control: { flavor: "objectRows", columns: [{ label: "Label", key: "label", kind: "text", placeholder: "Segment" }, { label: "Value", key: "value", kind: "number" }, { label: "Color", key: "color", kind: "color" }] }, ui: { label: "Items", order: 1 } } },
+    // ── Flat props grouped by control type (text → enum → toggle). ──
+    title: { type: "string", required: false, description: "Card title.", meta: { control: { placeholder: "e.g., MARKET SHARE" }, ui: { label: "Title", order: 2 } } },
+    subtitle: { type: "string", required: false, description: "Card subtitle.", meta: { ui: { label: "Subtitle", order: 3 } } },
+    valueMode: { type: "string", required: false, description: "Second label line: percent share, raw value, or none.", meta: { constraints: { oneOf: ["percent", "value", "none"] }, ui: { label: "Value mode", order: 4 } } },
+    preset: { type: "string", required: false, description: "Alpine theme variant.", meta: { constraints: { oneOf: ["light", "dark"] }, ui: { label: "Preset", order: 5 } } },
+    showValue: { type: "boolean", required: false, description: "Show the value / share line in each tile.", meta: { ui: { label: "Show value", order: 6 } } },
+    // ── Canonical (agent) ──
+    // ── Collapsible groups (the slider lives here, not intermixed with the flat props). ──
+    tiles: {
+        type: "group", required: false, description: "Tile geometry.",
+        meta: { ui: { label: "Tiles", order: 7, collapsedByDefault: true } },
+        fields: { cornerRadius: (0, alpine_anim_1.fFrac)("Tile radius", "Tile corner radius (0..0.5).") },
+    },
+    anim: {
+        type: "group", required: false, description: "Reveal mode + tile-cascade intro.",
+        meta: { ui: { label: "Animation", order: 8, collapsedByDefault: true } },
+        fields: {
+            renderMode: (0, alpine_anim_1.fEnum)("Render mode", ["premium", "light"], "\"premium\" (default): tiles + text fade in — a geq each. \"light\": the same cascade via free enable-gate pops — no geq, composable, cheap when nested."),
+            reduceMotion: alpine_anim_1.ALPINE_ANIM_FIELDS.reduceMotion,
+            introFrac: alpine_anim_1.ALPINE_ANIM_FIELDS.introFrac,
+            easing: alpine_anim_1.ALPINE_ANIM_FIELDS.easing,
+        },
+    },
+    theme: {
+        type: "group", required: false, description: "Opt into a theme source. Uses the alpine preset by default; set a producer slug + namespace to pull shared design tokens. Explicit color props still win.",
+        meta: { ui: { label: "Theme", order: 9, collapsedByDefault: true } },
+        fields: { slug: (0, alpine_anim_1.fStr)("Producer slug", "Producer template to seed tokens from (e.g. \"@m0saic/theming/v1\").", "preset palette (no producer)"), preset: (0, alpine_anim_1.fStr)("Preset", "Producer preset/variant (light | dark | high-contrast; producer-defined).", "producer default"), namespace: (0, alpine_anim_1.fStr)("Namespace", "Upstream alias to read tokens from. Default \"theme\".", "theme"), forceFetch: (0, alpine_anim_1.fBool)("Force fetch", "Re-seed via the slug even if the namespace is populated.") },
+    },
+});
+exports.AlpineTreemap = {
+    id: (0, types_1.asTemplateId)("@m0saic/alpine/treemap/v1"),
+    label: "Alpine Treemap",
+    version: 1,
+    description: "Alpine treemap — friendly mobile-marketing card: value-sized rounded tiles (squarified) filling the card, each labelled with its name + share, tiles fading in biggest→smallest. Standalone Alpine brand flavor.",
+    capabilities: { tier: "core" },
+    primitive: true,
+    deprecated: {
+        reason: "Absolute-placement antipattern: the squarified algorithm's natural nested structure is flattened to a flat rect list packed full-canvas via placeRects, so precision tracks the canvas (audit: ABSOLUTE, slope 1.04) and it pins its parent when nested. Use v2 — the SAME squarified layout emitted as its natural NESTED row/col splits (auto-quantized to a small basis → bounded precision), with the gap as a per-tile placement.inset. Composes at any canvas.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/alpine/treemap/v2"),
+        since: "2026-07-09",
+    },
+    tags: ["alpine", "treemap", "proportion", "data-viz"],
+    outputHints: { width: 1280, height: 800, fps: 30, durationMs: 2000 },
+    propsSchema,
+    defaultProps: {
+        theme: { forceFetch: false },
+        items: [
+            { label: "Engineering", value: 42 },
+            { label: "Sales", value: 26 },
+            { label: "Marketing", value: 16 },
+            { label: "Support", value: 9 },
+            { label: "Design", value: 7 },
+        ],
+        title: "HEADCOUNT",
+        subtitle: "By department",
+        preset: DEFAULT_PRESET,
+        valueMode: DEFAULT_VALUE_MODE,
+        tiles: { cornerRadius: 0.06 },
+        showValue: true,
+        anim: DEFAULT_ANIM,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        const raw = ((_a = props.items) !== null && _a !== void 0 ? _a : [])
+            .filter((it) => it && typeof it.label === "string" && Number.isFinite(it.value) && it.value > 0)
+            .slice(0, MAX_ITEMS);
+        if (raw.length === 0) {
+            return (0, template_utils_1.makeErrorMosaic)("items[] must have at least one item with value > 0", { title: `${this.id} props`, width: W, height: H });
+        }
+        // Theming: the shared alpine theme (light default). A producer overrides tokens
+        // via props.theme; explicit colors still win. Unthemed → byte-identical.
+        const theme = await (0, alpine_theme_1.resolveAlpineTheme)((_b = props.preset) !== null && _b !== void 0 ? _b : DEFAULT_PRESET, ctx, props.theme);
+        const anim = { ...DEFAULT_ANIM, ...((_c = props.anim) !== null && _c !== void 0 ? _c : {}) };
+        const animate = !anim.reduceMotion;
+        const light = ((_d = anim.renderMode) !== null && _d !== void 0 ? _d : DEFAULT_RENDER_MODE) === "light";
+        // Mode-aware reveals: premium fades (geq); light enable-gates (no geq).
+        const revealOv = (s, dur) => light ? { startAtSec: s, enable: `gte(t,${s.toFixed(3)})` } : { startAtSec: s, alpha: (0, template_utils_1.fadeInExpr)(s, dur) };
+        const ffText = (src, s, dur) => !animate ? src : light ? (0, alpine_anim_1.revealGate)(src, s) : fadeIn(src, s, dur, true);
+        const showValue = (_e = props.showValue) !== null && _e !== void 0 ? _e : true;
+        const valueMode = (_f = props.valueMode) !== null && _f !== void 0 ? _f : DEFAULT_VALUE_MODE;
+        const cornerRadius = Math.max(0, Math.min(0.5, (_h = (_g = props.tiles) === null || _g === void 0 ? void 0 : _g.cornerRadius) !== null && _h !== void 0 ? _h : 0.06));
+        // Sort biggest→smallest (squarify expects descending) but remember the original
+        // index so per-item color overrides + palette cycling track the input order.
+        const order = raw.map((_, i) => i).sort((a, b) => raw[b].value - raw[a].value);
+        const total = raw.reduce((s, it) => s + it.value, 0);
+        const tileColor = (origIdx) => (0, alpine_card_1.resolveColor)(raw[origIdx].color, alpine_theme_1.ALPINE_PALETTE[origIdx % alpine_theme_1.ALPINE_PALETTE.length]);
+        const card = (0, alpine_card_1.alpineCard)({ theme, W, H, title: props.title, subtitle: props.subtitle });
+        const cr = card.contentRect;
+        // Squarify the sorted values into the content rect (areas scaled to its area).
+        const areaPx = cr.w * cr.h;
+        const areas = order.map((oi) => (raw[oi].value / total) * areaPx);
+        const tiles = squarify(areas, { x: cr.x, y: cr.y, w: cr.w, h: cr.h });
+        const gap = Math.max(SNAP_PX, snapGrid(Math.min(cr.w, cr.h) * 0.012));
+        // Label fonts SHRINK-TO-FIT per tile: each tile picks the largest font (≤ base)
+        // that fits its full name, floored at a minimum below which the name truncates.
+        // So medium tiles show their whole label instead of clipping at one global size.
+        const baseNameFont = Math.max(12, Math.round(H * 0.028));
+        const baseValFont = Math.max(10, Math.round(H * 0.022));
+        const minNameFont = Math.max(10, Math.round(H * 0.018));
+        const clipSec = Math.max(0.1, ((_j = ctx.target.durationMs) !== null && _j !== void 0 ? _j : 2000) / 1000);
+        const introT = Math.max(0.1, Math.min(1, anim.introFrac) * clipSec);
+        const fadeDur = Math.max(0.08, introT * 0.45);
+        const N = order.length;
+        const startAt = (rank) => (animate ? (introT - fadeDur) * (N > 1 ? rank / (N - 1) : 0) : 0);
+        const pieces = [];
+        for (let rank = 0; rank < N; rank++) {
+            const oi = order[rank];
+            const t = tiles[rank];
+            // inset by the gap so tiles read as separated cards.
+            const tx = t.x + gap / 2, ty = t.y + gap / 2, tw = t.w - gap, th = t.h - gap;
+            if (tw < SNAP_PX || th < SNAP_PX)
+                continue;
+            const fill = tileColor(oi);
+            const s = startAt(rank);
+            const tile = (0, template_utils_1.makeColorTile)(fill, {
+                effects: { rounding: { cornerStyle: "rounded", borderRadius: cornerRadius } },
+                ...(animate ? { overlay: revealOv(s, fadeDur) } : {}),
+            });
+            pieces.push(rectPiece(W, H, tx, ty, tw, th, tile, 0));
+            // Labels (top-left), shown only when the tile is big enough to hold them.
+            // pad also clears the rounded CORNER (radius·minSide) so the label never
+            // crowds the curve at a high cornerRadius.
+            const cornerPx = cornerRadius * Math.min(tw, th);
+            const pad = Math.max(SNAP_PX, Math.round(Math.min(tw, th) * 0.1), Math.round(cornerPx * 0.5));
+            const innerW = tw - pad * 2;
+            // Shrink-to-fit: largest font (≤ base) that fits the full name in innerW,
+            // floored at minNameFont (below which truncateToWidth clips it).
+            const nameLen = Math.max(1, raw[oi].label.length);
+            const nameFont = Math.max(minNameFont, Math.min(baseNameFont, Math.floor(innerW / (nameLen * 0.6))));
+            const valFont = Math.max(8, Math.round(nameFont * (baseValFont / baseNameFont)));
+            const txtColor = onColor(fill, "#FFFFFF", theme.title);
+            const subColor = onColor(fill, "#FFFFFF", theme.subtitle);
+            const wantValue = showValue && valueMode !== "none";
+            const fitsName = innerW >= nameFont * 2 && th >= nameFont * 1.9;
+            const fitsValue = wantValue && th >= pad * 2 + nameFont * 1.7 + valFont * 1.2;
+            if (fitsName) {
+                const name = truncateToWidth(raw[oi].label, nameFont, innerW);
+                const nameCy = ty + pad + nameFont * 0.6;
+                pieces.push(placeText(W, H, leftTextBBox(tx + pad, nameCy, name, nameFont), ffText(cellText(name, nameFont, txtColor, "left"), s + fadeDur * 0.3, fadeDur), 1));
+                if (fitsValue) {
+                    const vText = valueMode === "percent" ? `${Math.round((raw[oi].value / total) * 100)}%` : compactNum(raw[oi].value);
+                    // Clear gap between the name and the value line (was cramped at ~0.7·font).
+                    const valCy = nameCy + nameFont * 0.62 + Math.round(nameFont * 0.42) + valFont * 0.5;
+                    pieces.push(placeText(W, H, leftTextBBox(tx + pad, valCy, vText, valFont), ffText(cellText(vText, valFont, subColor, "left"), s + fadeDur * 0.4, fadeDur), 1));
+                }
+            }
+        }
+        // Pack full-canvas → one { m0, sources }.
+        const placed = (0, dsl_stdlib_1.placeRects)({ rootW: W, rootH: H, rects: pieces.map((p) => p.rect) });
+        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);
+        }
+        const body = { m0: String(placed.m0), sources };
+        // Full-canvas absolute geometry → extraLayer (NOT scaled content) so it renders
+        // at exact canvas pixels and is never re-quantized by insetNode.
+        const root = card.compose(alpine_card_1.EMPTY, body);
+        return Promise.resolve({
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: root.m0,
+            sources: root.sources,
+            backgroundColor: card.backgroundColor,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+        });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.AlpineTreemap);

package/dist/m0saic/alpine/treemap/v2/index.d.ts

@@ -0,0 +1 @@
+export { AlpineTreemapV2 } from "./treemap";

package/dist/m0saic/alpine/treemap/v2/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlpineTreemapV2 = void 0;
+var treemap_1 = require("./treemap");
+Object.defineProperty(exports, "AlpineTreemapV2", { enumerable: true, get: function () { return treemap_1.AlpineTreemapV2; } });

package/dist/m0saic/alpine/treemap/v2/treemap.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ============================================================================
+ * @m0saic/alpine/treemap/v2 — Alpine Treemap (RATIO rebuild)
+ * ============================================================================
+ *
+ * Same picture as v1 — a squarified treemap of value-sized rounded tiles filling
+ * the Alpine card, each labelled with its name + share — but rebuilt as a RATIO
+ * layout instead of absolute full-canvas `placeRects`.
+ *
+ * The insight: the squarified algorithm is ALREADY a nested structure — it carves
+ * a row/column off a shrinking rect and recurses on the remainder. v1 flattened
+ * that to a flat rect list packed via `placeRects`, so precision tracked the
+ * canvas (audit: ABSOLUTE, slope 1.04). v2 emits the algorithm's natural NESTED
+ * `rowSplit`/`colSplit` tree: each split's weights are auto-normalized to a small
+ * basis by the alpine `split()` kit, so precision is bounded and it composes at
+ * any canvas (audit: RATIO). The inter-tile GAP rides as a per-tile
+ * `placement.inset` (zero DSL tokens, axis-even pixels — the heatmap move), and
+ * each tile's labels live inside its own cell. borderRadius rounds the tiles
+ * (rounded rectangles — no mask needed). Tiles fade in biggest→smallest;
+ * reduceMotion → the static map.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type EaseName, type ThemeSourceConfig } from "@m0saic/template-utils";
+import { type AlpinePreset } from "../../_shared/alpine-theme";
+type TreeItem = {
+    label: string;
+    value: number;
+    color?: MosaicColor;
+};
+type ValueMode = "percent" | "value" | "none";
+/** Reveal cost/quality dial. "premium" (default): tiles + text fade in (a geq each).
+ *  "light": the same cascade via free enable-gate pops — no geq, composable. */
+type RenderMode = "premium" | "light";
+type AnimConfig = {
+    renderMode: RenderMode;
+    reduceMotion: boolean;
+    introFrac: number;
+    easing: EaseName;
+};
+type AlpineTreemapV2Props = {
+    items: TreeItem[];
+    title?: string;
+    subtitle?: string;
+    valueMode?: ValueMode;
+    preset?: AlpinePreset;
+    showValue?: boolean;
+    tiles?: {
+        cornerRadius?: number;
+    };
+    anim?: AnimConfig;
+    /** Opt-in producer theming. The preset is the fallback; a producer's published
+     *  tokens override it. Explicit color props still win. */
+    theme?: ThemeSourceConfig;
+    /** Dev-only layout contract: assert tile text fits its slot. */
+    debugLayout?: boolean;
+};
+export declare const AlpineTreemapV2: MosaicTemplate<AlpineTreemapV2Props>;
+export {};