@m0saic/templates 0.2.0

package/dist/m0saic/charts/bar-graph/v1/internal/plot-area.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/bar-graph/internal/plot-area/v1
+ * ============================================================================
+ *
+ * PlotArea composes:
+ *   - Grid (back)    → GLOBAL primitive: @m0saic/primitives/grid/v2
+ *   - Bars (middle)  → provided by parent via `barsStackRef`
+ *   - Baseline (top) → 1px-ish lavfi strip
+ *
+ * Layering (paint order):
+ *   grid -> bars -> baseline
+ *
+ * Notes:
+ * - Grid baseline edge is excluded from the grid primitive (baseline owned here).
+ * - Chart convention:
+ *   - horizontal gridlines use bottom-origin (y = H*(1-frac))
+ *   - vertical gridlines use left-origin  (x = W*frac)
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlotArea = exports.PLOT_AREA_TEMPLATE_ID = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    axisConfig: {
+        type: "group",
+        required: true,
+        description: "Resolved axis configuration from orientation.",
+    },
+    grid: {
+        type: "group",
+        required: true,
+        description: "Grid display configuration (show, count).",
+    },
+    baseline: {
+        type: "group",
+        required: true,
+        description: "Baseline display configuration (show).",
+    },
+    valueAxis: {
+        type: "group",
+        required: true,
+        description: "Value-axis (top for vertical bars / right for horizontal) display configuration.",
+    },
+    barsStackRef: {
+        type: "string",
+        required: true,
+        description: "Child key for the BarsStack renderable (provided by parent).",
+    },
+});
+/** Return the dock opposite the given edge. The value axis sits opposite the baseline. */
+function oppositeEdge(edge) {
+    switch (edge) {
+        case "top": return "bottom";
+        case "bottom": return "top";
+        case "left": return "right";
+        case "right": return "left";
+    }
+}
+exports.PLOT_AREA_TEMPLATE_ID = (0, types_1.asTemplateId)("@m0saic/charts/bar-graph/internal/plot-area/v1");
+// v1 constants (can be promoted into defaults.ts later)
+const BASELINE_THICKNESS_FRAC = 0.002;
+const BASELINE_COLOR = (0, types_1.toMosaicColor)("#ffffff", "PlotArea.BASELINE_COLOR");
+/**
+ * Canonical 1px-ish baseline strip for a given dock edge.
+ * Uses fitMode:"content" + size exprs to keep thickness stable-ish.
+ */
+function baselineSourceForEdge(edge) {
+    const t = BASELINE_THICKNESS_FRAC;
+    const isHorizontal = edge === "top" || edge === "bottom";
+    return {
+        type: "lavfi",
+        color: BASELINE_COLOR,
+        fitMode: "content",
+        size: isHorizontal
+            ? { wExpr: "TW", hExpr: `max(1, TH*${t})` }
+            : { wExpr: `max(1, TW*${t})`, hExpr: "TH" },
+        placement: {
+            fit: "contain",
+            hAlign: edge === "left" ? "left" : edge === "right" ? "right" : "center",
+            vAlign: edge === "top" ? "top" : edge === "bottom" ? "bottom" : "middle",
+        },
+    };
+}
+exports.PlotArea = {
+    id: exports.PLOT_AREA_TEMPLATE_ID,
+    label: "Bar Graph — Plot Area (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: data rectangle containing gridlines, baseline, and the bars stack.",
+    capabilities: { tier: "core" },
+    tags: ["data-viz", "bar-graph", "internal", "plot-area"],
+    propsSchema,
+    defaultProps: {
+        axisConfig: {
+            fillAxis: "y",
+            layoutAxis: "x",
+            labelDock: "bottom",
+            valueDock: "top",
+            gridDirection: "horizontal",
+            baselineEdge: "bottom",
+        },
+        grid: { show: true, count: 5 },
+        baseline: { show: true },
+        valueAxis: { show: true },
+        barsStackRef: "bars-stack",
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        if (!props.barsStackRef) {
+            return (0, template_utils_1.makeErrorMosaic)("barsStackRef is required", {
+                title: `${this.id} props`,
+                width: ctx.output.width,
+                height: ctx.output.height,
+            });
+        }
+        const sources = [];
+        const children = {};
+        // slot0: grid (back) — global primitive
+        if ((_a = props.grid) === null || _a === void 0 ? void 0 : _a.show) {
+            const gridChildId = "grid";
+            const direction = (_c = (_b = props.axisConfig) === null || _b === void 0 ? void 0 : _b.gridDirection) !== null && _c !== void 0 ? _c : "horizontal";
+            const origin = direction === "horizontal" ? "bottom" : "left";
+            children[gridChildId] = await (0, template_utils_1.renderNestedTemplate)("@m0saic/primitives/grid/v2", {
+                // keep primitive API small + reusable
+                direction,
+                count: Math.max(0, Math.floor((_e = (_d = props.grid) === null || _d === void 0 ? void 0 : _d.count) !== null && _e !== void 0 ? _e : 0)),
+                excludeEdges: true, // baseline owned here
+                origin,
+                // Allow primitive defaults unless you explicitly want to pass styling from hero defaults.
+                // If your resolved grid config contains color/opacity/thickness, map them here.
+                ...props.grid,
+            }, ctx);
+            sources.push({ type: "mosaic", ref: gridChildId });
+        }
+        else {
+            sources.push((0, template_utils_1.transparentSlot)());
+        }
+        // slot1: bars (middle)
+        sources.push({ type: "mosaic", ref: props.barsStackRef });
+        // slot2: baseline (front, at the zero-line edge)
+        if ((_f = props.baseline) === null || _f === void 0 ? void 0 : _f.show) {
+            sources.push(baselineSourceForEdge(props.axisConfig.baselineEdge));
+        }
+        else {
+            sources.push((0, template_utils_1.transparentSlot)());
+        }
+        // slot3: value axis (front, at the max-value edge — top for vertical bars,
+        // right for horizontal bars). Mirrors the baseline so the plot rect has
+        // bounded reference lines on both sides of the data extent. Without this,
+        // the first interior gridline visually reads as "top of plot", making the
+        // gap structure feel uneven.
+        if ((_g = props.valueAxis) === null || _g === void 0 ? void 0 : _g.show) {
+            sources.push(baselineSourceForEdge(oppositeEdge(props.axisConfig.baselineEdge)));
+        }
+        else {
+            sources.push((0, template_utils_1.transparentSlot)());
+        }
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            sources,
+            assets: {},
+            // grid(back) → bars → baseline → value-axis (front)
+            m0: (0, template_utils_1.buildOverlayStack)(sources.length),
+            children: Object.keys(children).length ? children : undefined,
+            durationMs: ctx.target.durationMs,
+        };
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.PlotArea);

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

@@ -0,0 +1,326 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/bar-graph — Shared Types
+ * ============================================================================
+ *
+ * RESPONSIBILITY:
+ *   Single source of truth for every TypeScript type shared across the
+ *   bar-graph template family (public + all internals).
+ *
+ * WHAT LIVES HERE:
+ *   - Orientation        — "vertical" | "horizontal" discriminant.
+ *   - AxisConfig         — Resolved axis mapping produced by axis.ts.
+ *                          fillAxis vs layoutAxis, label dock positions,
+ *                          grid direction — everything orientation-dependent
+ *                          flows through this single struct.
+ *   - BarGraphProps      — Public props schema type for the top-level template.
+ *   - Internal prop types for each child template (ChartFrameProps, etc.).
+ *   - Animation contract types (intro timing, stagger, easing).
+ *   - Style / theme token types.
+ *
+ * GUIDELINES:
+ *   - Keep types PURE — no runtime code, no imports from template-utils.
+ *   - Types consumed by only ONE internal template may still live here to
+ *     avoid circular dependencies; locality is secondary to single-source.
+ *   - When adding a new prop, add it to BarGraphProps AND to the relevant
+ *     internal props type so the render chain can forward it.
+ *   - MosaicColor must be imported from @m0saic/types for color props.
+ *
+ * CANONICAL DESIGN RULES (HERO TEMPLATE):
+ *   - Vertical + Horizontal are the SAME template with an axis projection.
+ *   - Orientation-dependent behavior must be expressed ONLY via AxisConfig.
+ *   - Animation math must be centralized in BarFill (not scattered).
+ * ============================================================================
+ */
+import type { MosaicColor } from "@m0saic/types";
+/** Discriminant for bar orientation. Drives the entire AxisConfig. */
+export type Orientation = "vertical" | "horizontal";
+/**
+ * Canonical docking positions for labels and baselines.
+ *
+ * NOTE:
+ *   We keep this generic (top/right/bottom/left) so future variants
+ *   (e.g., labels on the right for vertical charts) don’t require type changes.
+ */
+export type Dock = "top" | "right" | "bottom" | "left";
+/**
+ * Public-friendly padding input.
+ *
+ * WHY:
+ *   A single `padding: number` sounds nice, but production charts quickly
+ *   need asymmetry (e.g., more bottom padding when category labels exist,
+ *   more left padding in horizontal mode, etc.).
+ *
+ * RULE:
+ *   - Public props allow `number` (shorthand) OR `{top,right,bottom,left}`.
+ *   - Internals receive a fully-resolved object shape (ResolvedPadding).
+ */
+export type Padding = number | {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** Always the internal canonical form (no unions). */
+export type ResolvedPadding = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/**
+ * AxisConfig is the SINGLE struct that every internal template receives to
+ * know which physical axis plays which logical role.
+ *
+ * PRODUCTION BEHAVIOR:
+ *   - fillAxis: "y" for vertical bars (bars grow upward), "x" for horizontal.
+ *   - layoutAxis: the perpendicular axis along which bars are laid out.
+ *   - labelDock: where category labels sit (usually bottom for vertical, left for horizontal).
+ *   - valueDock: where value labels sit (usually top for vertical, right for horizontal).
+ *   - gridDirection: orientation of grid lines (horizontal for vertical bars; vertical for horizontal bars).
+ *   - baselineEdge: which edge of the plot area is the zero-line (bottom or left).
+ *
+ * DESIGN RULE:
+ *   Everything orientation-dependent MUST be derived from this struct and
+ *   not re-invented ad-hoc in each internal.
+ */
+export type AxisConfig = {
+    fillAxis: "x" | "y";
+    layoutAxis: "x" | "y";
+    labelDock: Dock;
+    valueDock: Dock;
+    gridDirection: "horizontal" | "vertical";
+    baselineEdge: Dock;
+};
+/**
+ * Keep easing names conservative.
+ *
+ * WHY:
+ *   FFmpeg expressions are powerful but not a full physics engine.
+ *   Don’t promise `spring` until you actually ship a spring approximation
+ *   that looks great and is stable.
+ */
+export type EaseName = "linear" | "smoothstep" | "easeInOut";
+/**
+ * Intro timing contract.
+ *
+ * IMPORTANT:
+ *   Use SECONDS not MS.
+ *   FFmpeg expressions, overlay.enable/startAtSec, and your existing template
+ *   examples are all naturally expressed in seconds.
+ */
+export type AnimIntroConfig = {
+    /** Total intro duration in seconds. */
+    durationSec: number;
+    /** Base delay before first bar starts (seconds). */
+    delaySec: number;
+    /** Per-bar stagger offset (seconds). */
+    staggerSec: number;
+    /** Easing function name. */
+    ease: EaseName;
+};
+export type AnimConfig = {
+    intro: AnimIntroConfig;
+    /** If true, skip all motion and snap to final state. */
+    reduceMotion: boolean;
+};
+export type ValueLabelFormat = "raw" | "percent" | "compact";
+export type ValueLabelsConfig = {
+    show: boolean;
+    format: ValueLabelFormat;
+    decimals: number;
+    /** Optional unit appended to each formatted value, e.g. "s", "ms", "fps". */
+    suffix?: string;
+};
+export type TrackConfig = {
+    show: boolean;
+};
+export type GridConfig = {
+    show: boolean;
+    count: number;
+};
+export type BaselineConfig = {
+    show: boolean;
+};
+/**
+ * Presets are intentionally a UNION.
+ *
+ * WHY:
+ *   - Helps editors show a dropdown.
+ *   - Prevents random strings from becoming “themes” accidentally.
+ *   - Forces intentional design additions.
+ */
+export type BarGraphPreset = "neutral" | "dark" | "terminal" | "glass" | "paper";
+/**
+ * The canonical props interface for @m0saic/charts/bar-graph/v1.
+ *
+ * Required:
+ *   values — the numeric data array driving the chart.
+ *
+ * Everything else is optional with sensible defaults in defaults.ts.
+ */
+export type BarGraphProps = {
+    values: number[];
+    orientation?: Orientation;
+    labels?: string[];
+    title?: string;
+    subtitle?: string;
+    minValue?: number;
+    maxValue?: number;
+    highlightIndex?: number;
+    gap?: number;
+    /**
+     * Padding shorthand or explicit edges.
+     * Internals will receive ResolvedPadding.
+     */
+    padding?: Padding;
+    /**
+     * Optional fixed thickness of a bar in pixels.
+     * If omitted, the stack decides thickness from available space.
+     */
+    barThickness?: number;
+    /** Applied to bar corners and (optionally) chart container corners. */
+    cornerRadius?: number;
+    preset?: BarGraphPreset;
+    /**
+     * Single color or per-bar colors.
+     * IMPORTANT: Use MosaicColor for consistency across the ecosystem.
+     */
+    barColor?: MosaicColor | MosaicColor[];
+    track?: TrackConfig;
+    grid?: GridConfig;
+    baseline?: BaselineConfig;
+    /**
+     * Value-axis line: the reference line at the max-value side of the plot
+     * (top for vertical bars, right for horizontal). Mirrors the baseline so
+     * the data extent is bounded by reference lines on both sides.
+     */
+    valueAxis?: BaselineConfig;
+    valueLabels?: ValueLabelsConfig;
+    anim?: AnimConfig;
+};
+/**
+ * Internal props use RESOLVED types and explicit responsibilities.
+ *
+ * RULE:
+ *   Public unions (like Padding) must be resolved by the top-level template.
+ *   Internals should be simple and predictable.
+ */
+/** Props for @m0saic/charts/bar-graph/internal/chart-frame/v1 */
+export type ChartFrameProps = {
+    padding: ResolvedPadding;
+    cornerRadius: number;
+    preset: BarGraphPreset;
+    /** Child renderable ref key for the inner plot area. */
+    plotAreaRef: string;
+};
+/** Props for @m0saic/charts/bar-graph/internal/plot-area/v1 */
+export type PlotAreaProps = {
+    axisConfig: AxisConfig;
+    grid: GridConfig;
+    baseline: BaselineConfig;
+    /** Value-axis line opposite the baseline (top for vertical, right for horizontal). */
+    valueAxis: BaselineConfig;
+    /** Child renderable ref key for the bars stack. */
+    barsStackRef: string;
+};
+/** Props for @m0saic/charts/bar-graph/internal/bars-stack/v1 */
+export type BarsStackProps = {
+    axisConfig: AxisConfig;
+    values: number[];
+    /**
+     * Domain-normalized [0..1] fractions for each bar.
+     * Computed ONCE by the top-level template to ensure canonical behavior.
+     */
+    fractions: number[];
+    /**
+     * Explicit domain values used for label formatting / tick logic later.
+     * Keeping these here prevents “recomputing domain in multiple places”.
+     */
+    minValue: number;
+    maxValue: number;
+    barColor: MosaicColor | MosaicColor[];
+    gap: number;
+    barThickness?: number;
+    highlightIndex?: number;
+    track: TrackConfig;
+    valueLabels: ValueLabelsConfig;
+    labels?: string[];
+    anim: AnimConfig;
+    cornerRadius: number;
+};
+/** Props for @m0saic/charts/bar-graph/internal/bar-cell/v1 */
+export type BarCellProps = {
+    axisConfig: AxisConfig;
+    fraction: number;
+    value: number;
+    label?: string;
+    minValue: number;
+    maxValue: number;
+    color: MosaicColor;
+    cornerRadius: number;
+    index: number;
+    highlighted: boolean;
+    track: TrackConfig;
+    valueLabels: ValueLabelsConfig;
+    anim: AnimConfig;
+};
+/**
+ * Props for @m0saic/charts/bar-graph/internal/bar-fill/v1
+ *
+ * CANONICAL RULE:
+ *   This template is the ONLY place that owns FFmpeg math for fill animation.
+ *   Everyone else gets a “fill fraction” contract and composes around it.
+ */
+export type BarFillProps = {
+    axisConfig: AxisConfig;
+    fraction: number;
+    color: MosaicColor;
+    index: number;
+    anim: AnimConfig;
+    cornerRadius: number;
+};
+/** Props for @m0saic/charts/bar-graph/internal/grid/v1 */
+export type GridProps = {
+    axisConfig: AxisConfig;
+    grid: GridConfig;
+    baseline: BaselineConfig;
+};
+/** Props for @m0saic/charts/bar-graph/internal/labels/v1 */
+export type LabelsProps = {
+    axisConfig: AxisConfig;
+    title?: string;
+    subtitle?: string;
+    labels?: string[];
+    values: number[];
+    minValue: number;
+    maxValue: number;
+    /**
+     * Canvas-relative padding fractions; here, the {top, right, bottom, left}
+     * fractions drive the relative WEIGHTS of the title band, label band,
+     * and (for horizontal) left-rail band in the banded m0 layout.
+     * They are NOT used as inset values — m0 carries the layout.
+     */
+    padding: ResolvedPadding;
+    /** Pixel gap between bars (forwarded for symmetry / future use). */
+    gap: number;
+    /** Theme preset; drives label text color so it stays legible across presets. */
+    preset: BarGraphPreset;
+    valueLabels: ValueLabelsConfig;
+    /**
+     * Grid count — used to size the tick-rail. The tick rail emits
+     * (gridCount + 1) tick labels at evenly-spaced positions from the
+     * baseline (value=minValue) to the value-axis (value=maxValue).
+     */
+    gridCount: number;
+    /**
+     * Whether to render the value-axis tick numbers. When true the body
+     * row gains a tick rail (left side for vertical, bottom for horizontal).
+     */
+    showValueTicks: boolean;
+    /**
+     * Child renderable key for the plot area (BarsStack + grid + baseline).
+     * Labels references this in its plot-band slot.
+     */
+    plotAreaRef: string;
+};

package/dist/m0saic/charts/bar-graph/v1/types.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/bar-graph — Shared Types
+ * ============================================================================
+ *
+ * RESPONSIBILITY:
+ *   Single source of truth for every TypeScript type shared across the
+ *   bar-graph template family (public + all internals).
+ *
+ * WHAT LIVES HERE:
+ *   - Orientation        — "vertical" | "horizontal" discriminant.
+ *   - AxisConfig         — Resolved axis mapping produced by axis.ts.
+ *                          fillAxis vs layoutAxis, label dock positions,
+ *                          grid direction — everything orientation-dependent
+ *                          flows through this single struct.
+ *   - BarGraphProps      — Public props schema type for the top-level template.
+ *   - Internal prop types for each child template (ChartFrameProps, etc.).
+ *   - Animation contract types (intro timing, stagger, easing).
+ *   - Style / theme token types.
+ *
+ * GUIDELINES:
+ *   - Keep types PURE — no runtime code, no imports from template-utils.
+ *   - Types consumed by only ONE internal template may still live here to
+ *     avoid circular dependencies; locality is secondary to single-source.
+ *   - When adding a new prop, add it to BarGraphProps AND to the relevant
+ *     internal props type so the render chain can forward it.
+ *   - MosaicColor must be imported from @m0saic/types for color props.
+ *
+ * CANONICAL DESIGN RULES (HERO TEMPLATE):
+ *   - Vertical + Horizontal are the SAME template with an axis projection.
+ *   - Orientation-dependent behavior must be expressed ONLY via AxisConfig.
+ *   - Animation math must be centralized in BarFill (not scattered).
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/m0saic/charts/bar-graph/v2/bar-graph.d.ts

@@ -0,0 +1,131 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/bar-graph/v2 — Canonical Bar Graph (tight-rect geometry)
+ * ============================================================================
+ *
+ * SAME chart as v1, RIGHT cost structure. v1 was an early template: a deep
+ * nested-template composition (ChartFrame → PlotArea → BarsStack → BarCell →
+ * BarFill) where every bar was a FULL-PLOT-HEIGHT tile and the visible bar was
+ * carved out by a transparent base + an overlay crop. Most of each bar tile was
+ * empty pixels the engine still rasterized, and the five-deep template nesting
+ * paid an overlay-composite tax per layer.
+ *
+ * v2 authors the whole chart as ONE flat MosaicDocument whose geometry lives in
+ * the m0 string. Each bar is a TIGHT rect that hugs its FINAL height (max-Y
+ * extent), anchored at the baseline via a per-column `[emptyTop, bar]` split:
+ * the empty top is a light passthrough (no tile), the bar band is the only
+ * painted cell. The grow-in animation is a single `color=` source with a
+ * translation overlay that slides up to fill its own rect — no transparent base
+ * tile (v1 only needed one because its tiles were oversized). The not-yet-filled
+ * region simply reveals the card beneath. The reveal has two modes (`renderMode`,
+ * see `RenderMode`): `premium` (default) fades the bar in over the slide (premium,
+ * a per-pixel alpha geq); `light` keeps the slide opaque and enable-gates the
+ * labels — no geq, cheap when nested into a longer timeline.
+ *
+ * Compactness (the donut/GCD lesson): geometry is expressed as PROPORTIONAL
+ * structured splits whose weights `weightedSplit` GCD-reduces, and per-bar
+ * height units are nudged to a shared divisor so the DSL count collapses instead
+ * of expanding into per-pixel passthrough cells. Thin lines (baseline / value
+ * axis) are full-cell overlay strips sized by expression + placement — one
+ * source each, no split bands.
+ *
+ * Wins: tight rects read correctly in the render hero, the engine never
+ * rasterizes pixels a bar can't occupy, and a single flat doc drops v1's nested
+ * composite tax. v1's non-functional stubs (`track`, `highlightIndex`) are
+ * dropped. (Gridlines + value-axis tick rail land in the next pass.)
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type ThemeSourceConfig } from "@m0saic/template-utils";
+type Orientation = "vertical" | "horizontal";
+type Preset = "neutral" | "dark" | "terminal" | "glass" | "paper";
+type EaseName = "linear" | "smoothstep" | "easeInOut";
+type ValueLabelFormat = "raw" | "percent" | "compact";
+type ValueLabelsConfig = {
+    show: boolean;
+    format: ValueLabelFormat;
+    decimals: number;
+    suffix?: string;
+};
+type GridConfig = {
+    show: boolean;
+    count: number;
+};
+type ToggleConfig = {
+    show: boolean;
+};
+/**
+ * Reveal strategy (mirrors `charts/donut/v3`'s `renderMode`).
+ * - `premium` (default): bars + value labels FADE in (time-varying `overlay.alpha`)
+ *   over the grow slide — the premium look. The alpha compiles to a per-pixel geq
+ *   that, per the cost model, has NO active window: nested in a long parent it is
+ *   paid on every frame of the WHOLE clip (an outer `enable` hides it but can't skip
+ *   the upstream geq). Fine standalone / for a short head clip; the caller opts into
+ *   this cost.
+ * - `light`: NO alpha — bars grow via the slide only, value labels reveal via a free
+ *   `overlay.enable` gate (a crisp pop). Composable + cheap when nested (no geq;
+ *   gated-off frames cost nothing). The nestable tier.
+ * Both keep the grow slide; both are fully static under `reduceMotion`.
+ */
+type RenderMode = "premium" | "light";
+type AnimConfig = {
+    renderMode?: RenderMode;
+    intro: {
+        durationSec: number;
+        delaySec: number;
+        staggerSec: number;
+        ease: EaseName;
+    };
+    reduceMotion: boolean;
+};
+type DomainConfig = {
+    minValue?: number;
+    maxValue?: number;
+};
+type LayoutConfig = {
+    orientation?: Orientation;
+    gap?: number;
+    padding?: number;
+    barThickness?: number;
+    cornerRadius?: number;
+};
+type AppearanceConfig = {
+    preset?: Preset;
+    barColor?: MosaicColor | MosaicColor[];
+};
+type TitlesConfig = {
+    title?: string;
+    subtitle?: string;
+};
+type BarGraphProps = {
+    /** Numeric data driving the bars (required). */
+    values: number[];
+    /** Category labels, index-aligned to values. */
+    labels?: string[];
+    /** Axis domain overrides — auto-nice when unset. */
+    domain?: DomainConfig;
+    /** Bar geometry: orientation, gap, padding, thickness, corner radius. */
+    layout?: LayoutConfig;
+    /** Color scheme (preset) + bar fill color(s). */
+    appearance?: AppearanceConfig;
+    grid?: GridConfig;
+    baseline?: ToggleConfig;
+    valueAxis?: ToggleConfig;
+    valueLabels?: ValueLabelsConfig;
+    /** Chart title + subtitle. */
+    titles?: TitlesConfig;
+    /** Reveal mode (premium/light) + intro timing + reduceMotion. */
+    anim?: AnimConfig;
+    /**
+     * Opt-in producer theming (mirrors line-chart/v1). The local `preset` selects
+     * the fallback `Tokens` pack; `theme` layers a producer's published tokens over
+     * it via `resolveThemeTokens`. `props.theme` (producer) wins over `appearance.preset`
+     * (the resolver merges `published ← fallback`); explicit color props still win
+     * over both. Absent → the preset pack renders byte-identically.
+     */
+    theme?: ThemeSourceConfig;
+    /** Dev-only layout contract: assert bars equal-thickness + text fits its slot. */
+    debugLayout?: boolean;
+};
+export declare const ChartsBarGraphV2: MosaicTemplate<BarGraphProps>;
+export {};