@mulmocast/deck 0.1.0

package/lib/schema.js

@@ -0,0 +1,434 @@
+import { z } from "zod";
+// ═══════════════════════════════════════════════════════════
+// Foundation: Colors & Typography
+// ═══════════════════════════════════════════════════════════
+/** 6-digit hex without '#' prefix, e.g. "3B82F6" */
+const hexColorSchema = z.string().regex(/^[0-9A-Fa-f]{6}$/);
+/** Semantic accent colors usable on cards, badges, borders, etc. */
+export const accentColorKeySchema = z.enum(["primary", "accent", "success", "warning", "danger", "info", "highlight"]);
+export const slideThemeColorsSchema = z.object({
+    bg: hexColorSchema,
+    bgCard: hexColorSchema,
+    bgCardAlt: hexColorSchema,
+    text: hexColorSchema,
+    textMuted: hexColorSchema,
+    textDim: hexColorSchema,
+    primary: hexColorSchema,
+    accent: hexColorSchema,
+    success: hexColorSchema,
+    warning: hexColorSchema,
+    danger: hexColorSchema,
+    info: hexColorSchema,
+    highlight: hexColorSchema,
+});
+export const slideThemeFontsSchema = z.object({
+    title: z.string(),
+    body: z.string(),
+    mono: z.string(),
+});
+export const slideThemeSchema = z.object({
+    colors: slideThemeColorsSchema,
+    fonts: slideThemeFontsSchema,
+});
+// ═══════════════════════════════════════════════════════════
+// Content Blocks — the atoms of slide content
+// ═══════════════════════════════════════════════════════════
+export const textBlockSchema = z.object({
+    type: z.literal("text"),
+    value: z.string(),
+    align: z.enum(["left", "center", "right"]).optional(),
+    bold: z.boolean().optional(),
+    dim: z.boolean().optional(),
+    fontSize: z.number().optional(),
+    color: accentColorKeySchema.optional(),
+});
+/** Sub-bullet item: plain string or object with text */
+const subBulletItemSchema = z.union([z.string(), z.object({ text: z.string() })]);
+/** Bullet item: plain string or object with text and optional sub-items (2 levels max) */
+export const bulletItemSchema = z.union([
+    z.string(),
+    z.object({
+        text: z.string(),
+        items: z.array(subBulletItemSchema).optional(),
+    }),
+]);
+export const bulletsBlockSchema = z.object({
+    type: z.literal("bullets"),
+    items: z.array(bulletItemSchema),
+    ordered: z.boolean().optional(),
+    icon: z.string().optional(),
+});
+export const codeBlockSchema = z.object({
+    type: z.literal("code"),
+    code: z.string(),
+    language: z.string().optional(),
+});
+export const calloutBlockSchema = z.object({
+    type: z.literal("callout"),
+    text: z.string(),
+    label: z.string().optional(),
+    color: accentColorKeySchema.optional(),
+    style: z.enum(["quote", "info", "warning"]).optional(),
+});
+export const metricBlockSchema = z.object({
+    type: z.literal("metric"),
+    value: z.string(),
+    label: z.string(),
+    color: accentColorKeySchema.optional(),
+    change: z.string().optional(),
+});
+export const dividerBlockSchema = z.object({
+    type: z.literal("divider"),
+    color: accentColorKeySchema.optional(),
+});
+export const imageBlockSchema = z.object({
+    type: z.literal("image"),
+    src: z.string(),
+    alt: z.string().optional(),
+    fit: z.enum(["contain", "cover"]).optional(),
+});
+export const imageRefBlockSchema = z.object({
+    type: z.literal("imageRef"),
+    ref: z.string(),
+    alt: z.string().optional(),
+    fit: z.enum(["contain", "cover"]).optional(),
+});
+export const chartBlockSchema = z.object({
+    type: z.literal("chart"),
+    chartData: z.record(z.string(), z.unknown()),
+    title: z.string().optional(),
+});
+export const mermaidBlockSchema = z.object({
+    type: z.literal("mermaid"),
+    code: z.string(),
+    title: z.string().optional(),
+});
+export const tableCellValueSchema = z.union([
+    z.string(),
+    z.object({
+        text: z.string(),
+        color: accentColorKeySchema.optional(),
+        bold: z.boolean().optional(),
+        badge: z.boolean().optional(),
+    }),
+]);
+export const tableBlockSchema = z.object({
+    type: z.literal("table"),
+    title: z.string().optional(),
+    headers: z.array(z.string()).optional(),
+    rows: z.array(z.array(tableCellValueSchema)),
+    rowHeaders: z.boolean().optional(),
+    striped: z.boolean().optional(),
+});
+/** Block schemas shared between contentBlockSchema and nonSectionContentBlockSchema */
+const baseBlockSchemas = [
+    textBlockSchema,
+    bulletsBlockSchema,
+    codeBlockSchema,
+    calloutBlockSchema,
+    metricBlockSchema,
+    dividerBlockSchema,
+    imageBlockSchema,
+    imageRefBlockSchema,
+    chartBlockSchema,
+    mermaidBlockSchema,
+    tableBlockSchema,
+];
+/** All content block types except section (used inside section to prevent recursion) */
+const nonSectionContentBlockSchema = z.discriminatedUnion("type", [...baseBlockSchemas]);
+export const sectionBlockSchema = z.object({
+    type: z.literal("section"),
+    label: z.string(),
+    color: accentColorKeySchema.optional(),
+    content: z.array(nonSectionContentBlockSchema).optional(),
+    text: z.string().optional(),
+    sidebar: z.boolean().optional(),
+});
+export const contentBlockSchema = z.discriminatedUnion("type", [...baseBlockSchemas, sectionBlockSchema]);
+// ═══════════════════════════════════════════════════════════
+// Shared Components
+// ═══════════════════════════════════════════════════════════
+/** Bottom-of-slide callout bar */
+export const calloutBarSchema = z.object({
+    text: z.string(),
+    label: z.string().optional(),
+    color: accentColorKeySchema.optional(),
+    align: z.enum(["left", "center"]).optional(),
+    leftBar: z.boolean().optional(),
+});
+/** Reusable card definition — used by columns, grid */
+export const cardSchema = z.object({
+    title: z.string(),
+    accentColor: accentColorKeySchema.optional(),
+    content: z.array(contentBlockSchema).optional(),
+    footer: z.string().optional(),
+    label: z.string().optional(),
+    num: z.number().optional(),
+    icon: z.string().optional(),
+});
+// ═══════════════════════════════════════════════════════════
+// Slide-level styling — orthogonal to layout
+// ═══════════════════════════════════════════════════════════
+export const slideStyleSchema = z.object({
+    bgColor: z.string().optional(),
+    decorations: z.boolean().optional(),
+    bgOpacity: z.number().optional(),
+    footer: z.string().optional(),
+});
+/** Common slide properties shared across all layouts */
+const slideBaseFields = {
+    accentColor: accentColorKeySchema.optional(),
+    style: slideStyleSchema.optional(),
+};
+// ═══════════════════════════════════════════════════════════
+// Layouts
+// ═══════════════════════════════════════════════════════════
+// ─── title ───
+export const titleSlideSchema = z.object({
+    layout: z.literal("title"),
+    ...slideBaseFields,
+    title: z.string(),
+    subtitle: z.string().optional(),
+    author: z.string().optional(),
+    note: z.string().optional(),
+});
+// ─── columns ───
+export const columnsSlideSchema = z.object({
+    layout: z.literal("columns"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    columns: z.array(cardSchema),
+    showArrows: z.boolean().optional(),
+    callout: calloutBarSchema.optional(),
+    bottomText: z.string().optional(),
+});
+// ─── comparison ───
+export const comparisonPanelSchema = z.object({
+    title: z.string(),
+    accentColor: accentColorKeySchema.optional(),
+    content: z.array(contentBlockSchema).optional(),
+    footer: z.string().optional(),
+});
+export const comparisonSlideSchema = z.object({
+    layout: z.literal("comparison"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    left: comparisonPanelSchema,
+    right: comparisonPanelSchema,
+    callout: calloutBarSchema.optional(),
+});
+// ─── grid ───
+export const gridItemSchema = z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    accentColor: accentColorKeySchema.optional(),
+    num: z.number().optional(),
+    icon: z.string().optional(),
+    content: z.array(contentBlockSchema).optional(),
+});
+export const gridSlideSchema = z.object({
+    layout: z.literal("grid"),
+    ...slideBaseFields,
+    title: z.string(),
+    subtitle: z.string().optional(),
+    gridColumns: z.number().optional(),
+    items: z.array(gridItemSchema),
+    footer: z.string().optional(),
+});
+// ─── bigQuote ───
+export const bigQuoteSlideSchema = z.object({
+    layout: z.literal("bigQuote"),
+    ...slideBaseFields,
+    quote: z.string(),
+    author: z.string().optional(),
+    role: z.string().optional(),
+});
+// ─── stats ───
+export const statItemSchema = z.object({
+    value: z.string(),
+    label: z.string(),
+    color: accentColorKeySchema.optional(),
+    change: z.string().optional(),
+});
+export const statsSlideSchema = z.object({
+    layout: z.literal("stats"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    stats: z.array(statItemSchema),
+    callout: calloutBarSchema.optional(),
+});
+// ─── timeline ───
+export const timelineItemSchema = z.object({
+    date: z.string(),
+    title: z.string(),
+    description: z.string().optional(),
+    color: accentColorKeySchema.optional(),
+    done: z.boolean().optional(),
+});
+export const timelineSlideSchema = z.object({
+    layout: z.literal("timeline"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    items: z.array(timelineItemSchema),
+});
+// ─── split ───
+export const splitPanelSchema = z.object({
+    title: z.string().optional(),
+    subtitle: z.string().optional(),
+    label: z.string().optional(),
+    labelBadge: z.boolean().optional(),
+    accentColor: accentColorKeySchema.optional(),
+    content: z.array(contentBlockSchema).optional(),
+    dark: z.boolean().optional(),
+    ratio: z.number().optional(),
+    valign: z.enum(["top", "center", "bottom"]).optional(),
+});
+export const splitSlideSchema = z.object({
+    layout: z.literal("split"),
+    ...slideBaseFields,
+    left: splitPanelSchema.optional(),
+    right: splitPanelSchema.optional(),
+});
+// ─── matrix ───
+export const matrixCellSchema = z.object({
+    label: z.string(),
+    items: z.array(z.string()).optional(),
+    content: z.array(contentBlockSchema).optional(),
+    accentColor: accentColorKeySchema.optional(),
+});
+export const matrixSlideSchema = z.object({
+    layout: z.literal("matrix"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    rows: z.number().optional(),
+    cols: z.number().optional(),
+    xAxis: z
+        .object({
+        low: z.string().optional(),
+        high: z.string().optional(),
+        label: z.string().optional(),
+    })
+        .optional(),
+    yAxis: z
+        .object({
+        low: z.string().optional(),
+        high: z.string().optional(),
+        label: z.string().optional(),
+    })
+        .optional(),
+    cells: z.array(matrixCellSchema),
+});
+// ─── table ───
+export const tableSlideSchema = z.object({
+    layout: z.literal("table"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    headers: z.array(z.string()),
+    rows: z.array(z.array(tableCellValueSchema)),
+    rowHeaders: z.boolean().optional(),
+    striped: z.boolean().optional(),
+    callout: calloutBarSchema.optional(),
+});
+// ─── waterfall ───
+export const waterfallItemSchema = z.object({
+    label: z.string(),
+    value: z.number(),
+    isTotal: z.boolean().optional(),
+    color: accentColorKeySchema.optional(),
+});
+export const waterfallSlideSchema = z.object({
+    layout: z.literal("waterfall"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    items: z.array(waterfallItemSchema),
+    unit: z.string().optional(),
+    callout: calloutBarSchema.optional(),
+});
+// ─── funnel ───
+export const funnelStageSchema = z.object({
+    label: z.string(),
+    value: z.string().optional(),
+    description: z.string().optional(),
+    color: accentColorKeySchema.optional(),
+});
+export const funnelSlideSchema = z.object({
+    layout: z.literal("funnel"),
+    ...slideBaseFields,
+    title: z.string(),
+    stepLabel: z.string().optional(),
+    subtitle: z.string().optional(),
+    stages: z.array(funnelStageSchema),
+    callout: calloutBarSchema.optional(),
+});
+// ═══════════════════════════════════════════════════════════
+// Branding — logo & background image overlay
+// ═══════════════════════════════════════════════════════════
+/**
+ * Media source for branding assets (self-contained definition to avoid
+ * circular dependency with src/types/schema.ts).
+ */
+const slideMediaSourceSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("url"), url: z.url() }).strict(),
+    z.object({ kind: z.literal("base64"), data: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal("path"), path: z.string().min(1) }).strict(),
+]);
+const slideBackgroundImageSourceSchema = z.object({
+    source: slideMediaSourceSchema,
+    size: z.enum(["cover", "contain", "fill", "auto"]).optional(),
+    opacity: z.number().min(0).max(1).optional(),
+    bgOpacity: z.number().min(0).max(1).optional(),
+});
+export const slideBrandingLogoSchema = z
+    .object({
+    source: slideMediaSourceSchema,
+    position: z.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).default("top-right"),
+    width: z.number().positive().default(120),
+})
+    .strict();
+export const slideBrandingSchema = z
+    .object({
+    logo: slideBrandingLogoSchema.optional(),
+    backgroundImage: slideBackgroundImageSourceSchema.optional(),
+})
+    .strict();
+// ═══════════════════════════════════════════════════════════
+// Slide Union & Media Schema
+// ═══════════════════════════════════════════════════════════
+export const slideLayoutSchema = z.discriminatedUnion("layout", [
+    titleSlideSchema,
+    columnsSlideSchema,
+    comparisonSlideSchema,
+    gridSlideSchema,
+    bigQuoteSlideSchema,
+    statsSlideSchema,
+    timelineSlideSchema,
+    splitSlideSchema,
+    matrixSlideSchema,
+    tableSlideSchema,
+    funnelSlideSchema,
+    waterfallSlideSchema,
+]);
+/** Media schema registered in mulmoImageAssetSchema */
+export const mulmoSlideMediaSchema = z
+    .object({
+    type: z.literal("slide"),
+    theme: slideThemeSchema.optional(),
+    slide: slideLayoutSchema,
+    reference: z.string().optional(),
+    branding: slideBrandingSchema.nullable().optional(),
+})
+    .strict();

package/lib/utils.d.ts

@@ -0,0 +1,76 @@
+import type { SlideTheme, SlideLayout, CalloutBar } from "./schema.js";
+/** Escape HTML special characters */
+export declare const escapeHtml: (s: string) => string;
+/** Escape HTML and convert newlines to <br> */
+export declare const nl2br: (s: string) => string;
+/**
+ * Render inline markup: escape HTML first, then parse **bold** and {color:text}.
+ * Also converts newlines to <br>.
+ * Safe: escapeHtml runs before any markup parsing, so XSS is impossible.
+ */
+export declare const renderInlineMarkup: (s: string) => string;
+/** Sanitize a hex color value (hex digits only) */
+export declare const sanitizeHex: (s: string) => string;
+/** Accent color key → Tailwind class segment: "primary" → "d-primary" */
+export declare const c: (key: string) => string;
+/** Resolve accent color key with "primary" as fallback */
+export declare const resolveAccent: (color: string | undefined) => string;
+/** Resolve item-level color with slide-level fallback then "primary" */
+export declare const resolveItemColor: (itemColor: string | undefined, slideAccent: string | undefined) => string;
+/** Render a horizontal accent bar (3px full-width). Pass extraClass for width/margin variants. */
+export declare const accentBar: (colorKey: string, extraClass?: string) => string;
+/** Render an optional block title (chart, mermaid, table) */
+export declare const blockTitle: (title: string | undefined) => string;
+/** Resolve change indicator color: "success" for positive (+), "danger" for negative */
+export declare const resolveChangeColor: (change: string) => string;
+/** Render the optional callout bar at the bottom of a slide, or empty string */
+export declare const renderOptionalCallout: (callout: CalloutBar | undefined) => string;
+/** Build the Tailwind config JSON string for theme colors and fonts */
+export declare const buildTailwindConfig: (theme: SlideTheme) => string;
+/** Render a numbered circle badge */
+export declare const numBadge: (num: number, colorKey: string) => string;
+/** Render an icon in a square container */
+export declare const iconSquare: (icon: string, colorKey: string) => string;
+/** Render a card wrapper with accent top bar */
+export declare const cardWrap: (accentColor: string, innerHtml: string, extraClass?: string) => string;
+/** Render a callout bar at the bottom of a slide */
+export declare const renderCalloutBar: (obj: {
+    text: string;
+    label?: string;
+    color?: string;
+    align?: string;
+    leftBar?: boolean;
+}) => string;
+/** Render header text elements (stepLabel + title + subtitle) without wrapping div */
+export declare const renderHeaderText: (data: {
+    accentColor?: string;
+    stepLabel?: string;
+    title: string;
+    subtitle?: string;
+}) => string;
+/** Render the common slide header (accent bar + title + subtitle) */
+export declare const slideHeader: (data: {
+    accentColor?: string;
+    stepLabel?: string;
+    title: string;
+    subtitle?: string;
+}) => string;
+/** Render accent bar + vertically-centered wrapper with header text (used by stats, timeline) */
+export declare const centeredSlideHeader: (data: {
+    accentColor?: string;
+    stepLabel?: string;
+    title: string;
+    subtitle?: string;
+}) => string;
+/** Generate a unique ID with the given prefix (e.g. "chart-0", "mermaid-1") */
+export declare const generateSlideId: (prefix: string) => string;
+/** Reset the ID counter (for testing) */
+export declare const resetSlideIdCounter: () => void;
+type BlockTypeFlags = {
+    hasChart: boolean;
+    hasMermaid: boolean;
+    chartPlugins: string[];
+};
+/** Detect whether chart or mermaid content blocks exist in a slide */
+export declare const detectBlockTypes: (slide: SlideLayout) => BlockTypeFlags;
+export {};