@m0saic/templates 0.2.0

package/dist/m0saic/alpine/donut/v2/donut.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlpineDonutV2 = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const geometry_1 = require("../../../charts/donut/v3/geometry");
+const anim_1 = require("../../../charts/donut/v3/anim");
+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_THICKNESS = 0.42;
+const DEFAULT_SEG_LABELS = "percent";
+const DEFAULT_LEGEND = "right";
+const DEFAULT_ANIM = { renderMode: DEFAULT_RENDER_MODE, introFrac: 0.7, countUp: true, easing: "easeOut", reduceMotion: false };
+const RADIUS_SCALE = 0.9;
+const GAP_DEG = 2;
+const VALUE_FONT_FRAC = 0.26;
+const CAPTION_FONT_FRAC = 0.1;
+const SEG_LABEL_FONT_FRAC = 0.42;
+const SEG_LABEL_MIN_SWEEP_DEG = 16;
+const RING_FRAC_WITH_LEGEND = 0.56;
+// ---------------------------------------------------------------------------
+// Text helpers
+// ---------------------------------------------------------------------------
+function cellText(text, fontSize, color) {
+    return { type: "text", visual: { backgroundColor: "black@0" }, layers: [{ content: { kind: "literal", text: text || " " }, style: { fontSize, fontColor: color }, placement: { hAlign: "center", vAlign: "middle" } }] };
+}
+function cellExprText(expr, fontSize, color) {
+    return { type: "text", renderMode: { kind: "video" }, visual: { backgroundColor: "black@0" }, layers: [{ content: { kind: "expr", expr, eval: "frame" }, style: { fontSize, fontColor: color }, placement: { hAlign: "center", vAlign: "middle" } }] };
+}
+function textBBox(cxp, cyp, text, font) {
+    const w = Math.max(font, text.length * font * 0.85 + font);
+    const h = font * 1.6;
+    return { minX: cxp - w / 2, minY: cyp - h / 2, maxX: cxp + w / 2, maxY: cyp + h / 2 };
+}
+function labelColorFor(hex, light, dark) {
+    const m = /^#?([0-9a-f]{6})/i.exec(String(hex));
+    if (!m)
+        return light;
+    const v = parseInt(m[1], 16);
+    const lum = (0.2126 * ((v >> 16) & 0xff) + 0.7152 * ((v >> 8) & 0xff) + 0.0722 * (v & 0xff)) / 255;
+    return lum > 0.6 ? dark : light;
+}
+const clampI = (v, lo, hi) => Math.max(lo, Math.min(hi, Math.round(v)));
+// ---------------------------------------------------------------------------
+// Ring as a RATIO cell: every mark fills the `cw×ch` ring cell in ring-local
+// coords, so the sectors + labels + center text register around the shared
+// center. (Same single-coordinate-system idea v1 got from full-canvas placeRects,
+// now scoped to a ratio cell → bounded precision.)
+// ---------------------------------------------------------------------------
+function buildRingNode(opts) {
+    const { cw, ch, values, colors, theme } = opts;
+    const light = opts.renderMode === "light";
+    const revealText = (src, startSec, durSec) => opts.reduceMotion ? src : light ? (0, alpine_anim_1.revealGate)(src, startSec) : (0, alpine_anim_1.revealFade)(src, startSec, durSec);
+    const cx = cw / 2, cy = ch / 2;
+    const rOuter = (Math.min(cw, ch) / 2) * RADIUS_SCALE;
+    const rInner = rOuter * (1 - Math.max(0.05, Math.min(0.9, opts.thicknessFrac)));
+    const holeDia = rInner * 2;
+    const bounds = { x: 0, y: 0, width: cw, height: ch };
+    // Place a node at a ring-local bbox by insetting it inside the ring cell.
+    const placeAt = (node, bb) => {
+        const l = clampI(bb.minX, 0, cw - 2);
+        const t = clampI(bb.minY, 0, ch - 2);
+        const r = clampI(cw - bb.maxX, 0, cw - l - 1);
+        const b = clampI(ch - bb.maxY, 0, ch - t - 1);
+        return (0, alpine_card_1.insetNode)(node, t, r, b, l, cw, ch);
+    };
+    const angles = (0, geometry_1.segmentsToAngles)(values, { gapDeg: values.length > 1 ? GAP_DEG : 0 });
+    const segColor = (i) => colors[i % colors.length];
+    // ── Sectors (BACK): one static annular-sector mask per segment; the sweep is
+    //    the staggered OVERLAY (alpha fade / enable-gate), not a per-frame path. ──
+    const sectorLayers = [];
+    const fadeDur = Math.max(0.1, opts.introSec * 0.32);
+    for (let i = 0; i < angles.length; i++) {
+        const a = angles[i];
+        let rev;
+        if (!opts.reduceMotion) {
+            const startAtSec = Math.max(0, (opts.introSec - fadeDur) * (0, anim_1.sweepInverseEase)(opts.ease, a.startDeg / 360));
+            rev = light ? { startAtSec, enable: `gte(t,${startAtSec.toFixed(3)})` } : { startAtSec, alpha: (0, template_utils_1.fadeInExpr)(startAtSec, fadeDur) };
+        }
+        const tile = (0, template_utils_1.makeColorTile)(segColor(i), {
+            mask: { kind: "inline-mask", localPath: (0, geometry_1.annularSectorPath)({ cx, cy, rOuter, rInner, startDeg: a.startDeg, endDeg: a.endDeg }), bounds },
+            ...(rev ? { overlay: rev } : {}),
+        });
+        sectorLayers.push((0, alpine_card_1.paint)(tile));
+    }
+    // ── Per-segment % labels (FRONT), each at its sector centroid. ──
+    const labelLayers = [];
+    if (opts.segLabels === "percent") {
+        const ringPx = rOuter - rInner;
+        const segFont = Math.max(9, Math.round(ringPx * SEG_LABEL_FONT_FRAC));
+        for (let i = 0; i < angles.length; i++) {
+            const a = angles[i];
+            if (a.endDeg - a.startDeg < SEG_LABEL_MIN_SWEEP_DEG)
+                continue;
+            const { x, y } = (0, geometry_1.sectorCentroid)({ cx, cy, rOuter, rInner, startDeg: a.startDeg, endDeg: a.endDeg });
+            const pct = `${Math.round(a.frac * 100)}%`;
+            const color = labelColorFor(segColor(i), theme.card, theme.title);
+            labelLayers.push(placeAt((0, alpine_card_1.paint)(revealText(cellText(pct, segFont, color), opts.introSec * 0.6, Math.max(0.1, opts.introSec * 0.3))), textBBox(x, y, pct, segFont)));
+        }
+    }
+    // ── Center value + caption (FRONT). ──
+    const valueText = opts.centerValue;
+    const hasCaption = !!(opts.centerLabel && opts.centerLabel.trim());
+    const valueFont = Math.max(10, Math.round(Math.min(holeDia * VALUE_FONT_FRAC, (holeDia * 0.72) / Math.max(1, valueText.length * 0.62))));
+    const captionFont = Math.max(9, Math.round(holeDia * CAPTION_FONT_FRAC));
+    const valueCy = hasCaption ? cy - rInner * 0.12 : cy;
+    const animateValue = opts.countUp && !opts.reduceMotion && /\d/.test(valueText);
+    const centerLayers = [];
+    centerLayers.push(placeAt((0, alpine_card_1.paint)(animateValue
+        ? cellExprText((0, template_utils_1.animateNumbersInText)(valueText, { durationSec: opts.introSec, ease: opts.ease }), valueFont, theme.title)
+        : cellText(valueText, valueFont, theme.title)), textBBox(cx, valueCy, valueText, valueFont)));
+    if (hasCaption) {
+        centerLayers.push(placeAt((0, alpine_card_1.paint)(revealText(cellText(opts.centerLabel, captionFont, theme.subtitle), opts.introSec * 0.7, Math.max(0.1, opts.introSec * 0.3))), textBBox(cx, cy + rInner * 0.44, opts.centerLabel, captionFont)));
+    }
+    return (0, alpine_card_1.overlay)([...sectorLayers, ...labelLayers, ...centerLayers]);
+}
+// ---------------------------------------------------------------------------
+// Legend (Node) — colored dot + label + percent (ratio splits; unchanged from v1)
+// ---------------------------------------------------------------------------
+function legendNode(opts) {
+    var _a, _b;
+    const { labels, percents, colors, theme, font, cellH } = opts;
+    const N = labels.length;
+    const rowH = Math.max(font, Math.round(font * 1.7));
+    const rowGap = Math.round(font * 0.5);
+    const stackH = N * rowH + (N - 1) * rowGap;
+    const margin = Math.max(0, Math.round((cellH - stackH) / 2));
+    const bands = [];
+    if (margin > 0)
+        bands.push({ weight: margin, node: alpine_card_1.EMPTY });
+    for (let i = 0; i < N; i++) {
+        const dot = (0, alpine_card_1.rowSplit)([
+            { weight: 1, node: alpine_card_1.EMPTY },
+            { weight: 2, node: (0, alpine_card_1.paint)((0, template_utils_1.makeColorTile)(colors[i % colors.length], { effects: { rounding: { cornerStyle: "rounded", borderRadius: 0.4 } } })) },
+            { weight: 1, node: alpine_card_1.EMPTY },
+        ]);
+        const row = (0, alpine_card_1.colSplit)([
+            { weight: 1, node: alpine_card_1.EMPTY },
+            { weight: 2, node: dot },
+            { weight: 1, node: alpine_card_1.EMPTY },
+            { weight: 11, node: (0, alpine_card_1.paint)((0, alpine_card_1.textCell)((_a = labels[i]) !== null && _a !== void 0 ? _a : "", font, theme.label, "left", "middle")) },
+            { weight: 5, node: (0, alpine_card_1.paint)((0, alpine_card_1.textCell)((_b = percents[i]) !== null && _b !== void 0 ? _b : "", font, theme.subtitle, "right", "middle", { right: 0.1 })) },
+        ]);
+        bands.push({ weight: rowH, node: row });
+        if (i < N - 1)
+            bands.push({ weight: rowGap, node: alpine_card_1.EMPTY });
+    }
+    if (margin > 0)
+        bands.push({ weight: margin, node: alpine_card_1.EMPTY });
+    return (0, alpine_card_1.rowSplit)(bands);
+}
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    segments: { type: "array", required: true, description: "Ring segments (clockwise from 12 o'clock). Raw weights — normalized internally.", 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" }], palette: alpine_theme_1.ALPINE_PALETTE }, ui: { label: "Segments", order: 1 } } },
+    title: { type: "string", required: false, description: "Card title.", meta: { control: { placeholder: "e.g., DONUT CHART" }, ui: { label: "Title", order: 2 } } },
+    subtitle: { type: "string", required: false, description: "Card subtitle.", meta: { control: { placeholder: "e.g., Revenue Mix" }, ui: { label: "Subtitle", order: 3 } } },
+    centerValue: { type: "string", required: false, description: "Pre-formatted hole value (e.g. \"$12,480\"). Omit to derive the sum.", meta: { control: { placeholder: "e.g. $12,480" }, ui: { label: "Center value", order: 4 } } },
+    centerLabel: { type: "string", required: false, description: "Small caption under the center value (e.g. \"Total\").", meta: { control: { placeholder: "e.g. Total" }, ui: { label: "Center label", order: 5 } } },
+    legend: { type: "string", required: false, description: "Side legend: right or none.", meta: { constraints: { oneOf: ["right", "none"] }, ui: { label: "Legend", order: 6 } } },
+    segmentLabels: { type: "string", required: false, description: "Per-segment labels: none or percent.", meta: { constraints: { oneOf: ["none", "percent"] }, ui: { label: "Segment Labels", order: 7 } } },
+    preset: { type: "string", required: false, description: "Alpine theme variant.", meta: { constraints: { oneOf: ["light", "dark"] }, ui: { label: "Preset", order: 8 } } },
+    ringThicknessFrac: { type: "number", required: false, description: "Ring thickness as a fraction of the outer radius.", meta: { constraints: { min: 0.05, max: 0.9 }, control: { flavor: "slider", step: 0.02 }, ui: { label: "Ring thickness", order: 9 } } },
+    anim: {
+        type: "group", required: false, description: "Reveal mode + clockwise sweep intro.",
+        meta: { ui: { label: "Animation", order: 10, collapsedByDefault: true } },
+        fields: {
+            renderMode: (0, alpine_anim_1.fEnum)("Render mode", ["premium", "light"], "\"premium\" (default): clockwise alpha-fade sweep — the softest look, but a per-pixel geq paid on every frame of a nesting parent's whole timeline. \"light\": clockwise enable-gate pop — no geq, composable, cheap when nested."),
+            reduceMotion: alpine_anim_1.ALPINE_ANIM_FIELDS.reduceMotion,
+            introFrac: alpine_anim_1.ALPINE_ANIM_FIELDS.introFrac,
+            countUp: (0, alpine_anim_1.fBool)("Count up", "Count the center value up during the intro."),
+            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 segment colors still win.",
+        meta: { ui: { label: "Theme", order: 11, 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.AlpineDonutV2 = {
+    id: (0, types_1.asTemplateId)("@m0saic/alpine/donut/v2"),
+    label: "Alpine Donut Chart",
+    version: 2,
+    description: "Alpine donut chart — friendly mobile-marketing card: proportional ring, center value + label, side legend, sweep + count-up animation. v2 rebuilds the ring as a ratio cell (sectors are masks filling the cell in ring-local coords) so it composes at any canvas without the absolute-placement precision blowup.",
+    capabilities: { tier: "core" },
+    primitive: true,
+    deprecated: {
+        reason: "Superseded by v3, which keeps this exact ratio ring but upgrades premium from a per-segment fade to the FULL clockwise radial SWEEP (self-framed coarse-quantize — smooth draw-on that still composes at any canvas). v2's per-segment mask-in-a-cell path lives on as v3's 'light' mode.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/alpine/donut/v3"),
+        since: "2026-07-09",
+    },
+    tags: ["alpine", "donut", "distribution", "data-viz"],
+    outputHints: { width: 1280, height: 800, fps: 30, durationMs: 2000 },
+    propsSchema,
+    defaultProps: {
+        theme: { forceFetch: false },
+        segments: [
+            { label: "Enterprise", value: 42, color: alpine_theme_1.ALPINE_PALETTE[0] },
+            { label: "Pro", value: 33, color: alpine_theme_1.ALPINE_PALETTE[1] },
+            { label: "Free", value: 25, color: alpine_theme_1.ALPINE_PALETTE[2] },
+        ],
+        title: "DONUT CHART",
+        subtitle: "Revenue Mix",
+        centerValue: "$12,480",
+        centerLabel: "Total",
+        preset: DEFAULT_PRESET,
+        ringThicknessFrac: DEFAULT_THICKNESS,
+        segmentLabels: DEFAULT_SEG_LABELS,
+        legend: DEFAULT_LEGEND,
+        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 segments = ((_a = props.segments) !== null && _a !== void 0 ? _a : []).slice(0, geometry_1.MAX_SEGMENTS).filter((s) => s && Number.isFinite(s.value) && s.value > 0);
+        if (segments.length === 0) {
+            return (0, template_utils_1.makeErrorMosaic)("segments[] must have at least one positive value", { title: `${this.id}`, width: W, height: H });
+        }
+        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 renderMode = (_d = anim.renderMode) !== null && _d !== void 0 ? _d : DEFAULT_RENDER_MODE;
+        const legend = (_e = props.legend) !== null && _e !== void 0 ? _e : DEFAULT_LEGEND;
+        const values = segments.map((s) => s.value);
+        const total = values.reduce((a, b) => a + b, 0);
+        const colors = segments.map((s, i) => (0, alpine_card_1.resolveColor)(s.color, alpine_theme_1.ALPINE_PALETTE[i % alpine_theme_1.ALPINE_PALETTE.length]));
+        const percents = values.map((v) => `${Math.round((v / total) * 100)}%`);
+        const clipSec = Math.max(0.1, ((_f = ctx.target.durationMs) !== null && _f !== void 0 ? _f : 2000) / 1000);
+        const introSec = Math.max(0.1, Math.min(1, anim.introFrac) * clipSec);
+        const card = (0, alpine_card_1.alpineCard)({ theme, W, H, title: props.title, subtitle: props.subtitle });
+        const cr = card.contentRect;
+        const showLegend = legend === "right" && segments.length > 0;
+        const ringW = showLegend ? Math.max(16, Math.round(cr.w * RING_FRAC_WITH_LEGEND)) : cr.w;
+        const legendW = cr.w - ringW;
+        const ringNode = buildRingNode({
+            cw: ringW, ch: cr.h, values, colors,
+            thicknessFrac: (_g = props.ringThicknessFrac) !== null && _g !== void 0 ? _g : DEFAULT_THICKNESS,
+            segLabels: (_h = props.segmentLabels) !== null && _h !== void 0 ? _h : DEFAULT_SEG_LABELS,
+            centerValue: (_j = props.centerValue) !== null && _j !== void 0 ? _j : String(Math.round(total)),
+            centerLabel: props.centerLabel,
+            theme, introSec, ease: anim.easing, countUp: anim.countUp, reduceMotion: anim.reduceMotion, renderMode,
+        });
+        const legendFont = Math.max(11, Math.round(H * 0.024));
+        const content = showLegend
+            ? (0, alpine_card_1.colSplit)([
+                { weight: ringW, node: ringNode },
+                { weight: legendW, node: legendNode({ labels: segments.map((s) => s.label), percents, colors, theme, font: legendFont, cellH: cr.h }) },
+            ])
+            : ringNode;
+        const root = card.compose(content);
+        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.AlpineDonutV2);

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

@@ -0,0 +1 @@
+export { AlpineDonutV2 } from "./donut";

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

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

package/dist/m0saic/alpine/donut/v3/donut.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ============================================================================
+ * @m0saic/alpine/donut/v3 — Alpine Donut Chart (RATIO, per-segment masks)
+ * ============================================================================
+ *
+ * Same picture as v2 — a proportional ring + center value/label + side legend in
+ * the Alpine card. Every mask is a FULL-CELL inline-mask — seam-free by
+ * construction. (The old premium sweep bbox-snapped slivers to a coarse grid;
+ * the snap corners printed white squares at the segment gaps on every frame.
+ * Gate-4 fail 2026-08-20 — the crop machinery is gone; the piecewise FEEL
+ * stays via budgeted full-cell slivers.)
+ *
+ * Reveals:
+ *   - "premium" (animated): PIECEWISE clockwise draw-on — each segment
+ *     subdivides into a few slivers (slivers + labels + center budgeted to the
+ *     engine's 20-layer overlay comfort zone, well under the ~25-overlay mask
+ *     cliff), every sliver a full-cell mask overlapped 2° backward so
+ *     boundaries composite invisibly; each piece fades as the eased front
+ *     reaches it, duration proportional to its arc.
+ *   - "light": per-segment enable-gate pops (geq-free, composable).
+ *   - reduceMotion: the static per-segment ring.
+ *
+ * The legend, center value, and % labels are the Alpine chrome (unchanged from
+ * v2). Composes at any canvas.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type EaseName, type ThemeSourceConfig } from "@m0saic/template-utils";
+import { type AlpinePreset } from "../../_shared/alpine-theme";
+type DonutSegment = {
+    label: string;
+    value: number;
+    color?: MosaicColor;
+};
+type LegendPosition = "right" | "none";
+type SegLabels = "none" | "percent";
+/** Reveal cost/quality dial. "premium" (default): piecewise clockwise
+ *  draw-on (budgeted full-cell slivers). "light": per-segment pops. */
+type RenderMode = "premium" | "light";
+type DonutAnim = {
+    renderMode: RenderMode;
+    reduceMotion: boolean;
+    introFrac: number;
+    countUp: boolean;
+    easing: EaseName;
+};
+type AlpineDonutV3Props = {
+    segments: DonutSegment[];
+    title?: string;
+    subtitle?: string;
+    centerValue?: string;
+    centerLabel?: string;
+    legend?: LegendPosition;
+    segmentLabels?: SegLabels;
+    preset?: AlpinePreset;
+    ringThicknessFrac?: number;
+    anim?: DonutAnim;
+    /** 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 every legend swatch rendered the same size. */
+    debugLayout?: boolean;
+};
+export declare const AlpineDonutV3: MosaicTemplate<AlpineDonutV3Props>;
+export {};