@kadal/deck 0.0.0-stage → 0.1.0

package/dist/sketch/dsl.d.ts

@@ -0,0 +1,131 @@
+import { SketchTone } from "./palette.js";
+//#region src/sketch/dsl.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SKETCH DSL  —  draw an Excalidraw diagram in code
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const s = sketch({ width: 1280, height: 640 });
+ *   s.region("edge", { x: 440, y: 40, w: 420, h: 560, title: "Cloudflare Workers", tone: "accent" });
+ *   s.node("w", { x: 470, y: 100, w: 360, h: 90, label: "Next.js 16\nSSR + OG image", tone: "accent", region: "edge" });
+ *   s.node("d1", { x: 470, y: 480, w: 165, h: 90, label: "D1", shape: "cylinder", tone: "pink", region: ["edge", "report"] });
+ *   s.arrow("w", "d1", { label: "only what is on the map" });
+ *   export const architecture = s.build();
+ *
+ * `build()` returns Excalidraw *element skeletons* (the simplified shape the package's
+ * `convertToExcalidrawElements` understands) plus the region of every element, so a slide can
+ * light one region up per click. This file imports nothing from Excalidraw: it is plain data,
+ * safe to ship in a deck's main bundle; the 2.7 MB package loads only when a sketch renders.
+ *
+ * Coordinates are pixels in the sketch's own space. Regions are named areas: a dashed, tinted
+ * rectangle with a title when they have geometry, or purely a label (`region: "report"` on
+ * nodes and arrows) for a path that crosses the drawn boxes.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export type SketchShape = "box" | "pill" | "ellipse" | "diamond" | "cylinder" | "note" | "text";
+export type SketchFont = "hand" | "normal" | "code";
+export type SketchFill = "solid" | "hachure" | "cross-hatch" | "none";
+type Side = "left" | "right" | "top" | "bottom";
+export interface NodeInput {
+  x: number;
+  y: number;
+  w?: number;
+  h?: number;
+  label?: string;
+  shape?: SketchShape;
+  tone?: SketchTone;
+  /** Text colour, when not the ink. */
+  textTone?: SketchTone;
+  fill?: SketchFill;
+  dashed?: boolean;
+  font?: SketchFont;
+  size?: number;
+  /** 0 = ruler-straight, 1 = hand-drawn (default), 2 = wobbly. */
+  rough?: 0 | 1 | 2;
+  strokeWidth?: number;
+  region?: string | string[];
+  align?: "left" | "center" | "right";
+  opacity?: number;
+}
+export interface ArrowInput {
+  label?: string;
+  tone?: SketchTone;
+  dashed?: boolean;
+  dotted?: boolean;
+  /** A plain line instead of an arrow. */
+  line?: boolean;
+  /** Arrowheads at both ends. */
+  both?: boolean;
+  from?: Side;
+  to?: Side;
+  /** Extra corner points (absolute), for an elbow or a detour. */
+  via?: Array<[number, number]>;
+  /** Regions this arrow belongs to, on top of those of its two ends. */
+  region?: string | string[];
+  strokeWidth?: number;
+  size?: number;
+  font?: SketchFont;
+  /** Shift the anchor along its side, −1 … 1 (0 is the middle). */
+  fromShift?: number;
+  toShift?: number;
+}
+export interface RegionInput {
+  x?: number;
+  y?: number;
+  w?: number;
+  h?: number;
+  title?: string;
+  tone?: SketchTone;
+  dashed?: boolean;
+  fill?: boolean;
+  size?: number;
+  /** Where the title sits; "right" keeps it clear of arrows arriving at the left. */
+  titleAt?: "left" | "right";
+}
+export interface TextInput {
+  x: number;
+  y: number;
+  text: string;
+  size?: number;
+  tone?: SketchTone;
+  font?: SketchFont;
+  align?: "left" | "center" | "right";
+  region?: string | string[];
+  w?: number;
+}
+/** What a rendered sketch knows about a region, for the step captions and the canvas. */
+export interface SketchRegionMeta {
+  id: string;
+  title?: string;
+  tone: SketchTone;
+}
+export interface SketchScene {
+  kind: "sketch";
+  width: number;
+  height: number;
+  /** Excalidraw element skeletons, in draw order. Typed loosely: the DSL never imports Excalidraw. */
+  elements: Array<Record<string, unknown>>;
+  /** Element id → the regions it belongs to. */
+  regions: Record<string, string[]>;
+  regionMeta: SketchRegionMeta[];
+  /** The fonts used (Excalidraw ids), so the renderer can warm them up before measuring text. */
+  fonts: number[];
+}
+export declare function sketch(opts?: {
+  width?: number;
+  height?: number;
+  font?: SketchFont;
+  size?: number;
+  rough?: 0 | 1 | 2;
+}): {
+  /** A named area. With geometry it is drawn as a dashed, tinted rectangle with a title. */
+  region(id: string, input?: RegionInput): /*elided*/ any;
+  /** A shape with a label. `shape: "text"` is a bare label with no box. */
+  node(id: string, input: NodeInput): /*elided*/ any;
+  /** Free text. */
+  text(id: string, input: TextInput): /*elided*/ any;
+  /** An arrow between two nodes, anchored on the facing sides unless told otherwise. */
+  arrow(from: string, to: string, input?: ArrowInput): /*elided*/ any;
+  build(): SketchScene;
+};
+//#endregion

package/dist/sketch/dsl.js

@@ -0,0 +1,281 @@
+import { PALETTE } from "./palette.js";
+//#region src/sketch/dsl.ts
+/** Excalidraw's font ids (FONT_FAMILY in its constants). */
+const FONT = {
+	hand: 5,
+	normal: 6,
+	code: 3
+};
+const list = (r) => r == null ? [] : Array.isArray(r) ? r : [r];
+function sketch(opts = {}) {
+	const width = opts.width ?? 1280;
+	const height = opts.height ?? 640;
+	const baseFont = opts.font ?? "hand";
+	const baseSize = opts.size ?? 20;
+	const baseRough = opts.rough ?? 1;
+	const elements = [];
+	const regions = {};
+	const regionMeta = [];
+	const geoms = /* @__PURE__ */ new Map();
+	const fonts = /* @__PURE__ */ new Set();
+	let seq = 0;
+	const uid = (prefix) => `${prefix}-${++seq}`;
+	const tag = (id, r) => {
+		const rs = list(r);
+		if (rs.length) regions[id] = [.../* @__PURE__ */ new Set([...regions[id] ?? [], ...rs])];
+	};
+	const roundness = (shape) => shape === "box" || shape === "cylinder" ? { type: 3 } : shape === "pill" || shape === "ellipse" || shape === "diamond" ? { type: 2 } : null;
+	const api = {
+		/** A named area. With geometry it is drawn as a dashed, tinted rectangle with a title. */
+		region(id, input = {}) {
+			const tone = input.tone ?? "neutral";
+			regionMeta.push({
+				id,
+				title: input.title,
+				tone
+			});
+			if (input.x != null && input.y != null && input.w && input.h) {
+				const rect = uid("region");
+				elements.push({
+					id: rect,
+					type: "rectangle",
+					x: input.x,
+					y: input.y,
+					width: input.w,
+					height: input.h,
+					strokeColor: PALETTE[tone].stroke,
+					backgroundColor: input.fill === false ? "transparent" : PALETTE[tone].fill,
+					fillStyle: "solid",
+					strokeStyle: input.dashed === false ? "solid" : "dashed",
+					strokeWidth: 1,
+					roughness: baseRough,
+					roundness: { type: 3 },
+					opacity: 70
+				});
+				tag(rect, id);
+				if (input.title) {
+					const size = input.size ?? Math.round(baseSize * .8);
+					const t = uid("region-title");
+					const estimate = input.title.length * size * .56;
+					const right = input.titleAt === "right";
+					elements.push({
+						id: t,
+						type: "text",
+						x: right ? input.x + input.w - 16 - estimate : input.x + 16,
+						y: input.y + 10,
+						text: input.title,
+						fontSize: size,
+						fontFamily: FONT[baseFont],
+						strokeColor: PALETTE[tone].stroke,
+						textAlign: right ? "right" : "left"
+					});
+					fonts.add(FONT[baseFont]);
+					tag(t, id);
+				}
+			}
+			return api;
+		},
+		/** A shape with a label. `shape: "text"` is a bare label with no box. */
+		node(id, input) {
+			const shape = input.shape ?? "box";
+			const tone = input.tone ?? "ink";
+			const font = FONT[input.font ?? baseFont];
+			fonts.add(font);
+			const size = input.size ?? baseSize;
+			const w = input.w ?? 200;
+			const h = input.h ?? 70;
+			geoms.set(id, {
+				x: input.x,
+				y: input.y,
+				w,
+				h,
+				shape
+			});
+			const textColor = PALETTE[input.textTone ?? "ink"].stroke;
+			const common = {
+				strokeColor: PALETTE[tone].stroke,
+				backgroundColor: input.fill === "none" ? "transparent" : PALETTE[tone].fill,
+				fillStyle: input.fill && input.fill !== "none" ? input.fill : "solid",
+				strokeStyle: input.dashed ? "dashed" : "solid",
+				strokeWidth: input.strokeWidth ?? (shape === "note" ? 1 : 2),
+				roughness: input.rough ?? baseRough,
+				opacity: input.opacity ?? 100
+			};
+			if (shape === "text") {
+				elements.push({
+					id,
+					type: "text",
+					x: input.x,
+					y: input.y,
+					width: w,
+					text: input.label ?? "",
+					fontSize: size,
+					fontFamily: font,
+					strokeColor: PALETTE[input.textTone ?? tone].stroke,
+					textAlign: input.align ?? "center"
+				});
+				tag(id, input.region);
+				return api;
+			}
+			const label = input.label ? {
+				text: input.label,
+				fontSize: size,
+				fontFamily: font,
+				strokeColor: textColor,
+				textAlign: input.align ?? "center",
+				verticalAlign: "middle"
+			} : void 0;
+			if (shape === "cylinder") {
+				const lid = Math.max(14, Math.round(h * .22));
+				elements.push({
+					id,
+					type: "rectangle",
+					x: input.x,
+					y: input.y + lid / 2,
+					width: w,
+					height: h - lid / 2,
+					...common,
+					roundness: { type: 3 },
+					label
+				});
+				const top = `${id}-lid`;
+				elements.push({
+					id: top,
+					type: "ellipse",
+					x: input.x,
+					y: input.y,
+					width: w,
+					height: lid,
+					...common,
+					roundness: { type: 2 }
+				});
+				tag(id, input.region);
+				tag(top, input.region);
+				return api;
+			}
+			const type = shape === "ellipse" || shape === "pill" ? "ellipse" : shape === "diamond" ? "diamond" : "rectangle";
+			elements.push({
+				id,
+				type,
+				x: input.x,
+				y: input.y,
+				width: w,
+				height: h,
+				...common,
+				...shape === "note" ? {
+					fillStyle: "solid",
+					roughness: input.rough ?? 0
+				} : {},
+				roundness: shape === "note" ? null : roundness(shape),
+				label
+			});
+			tag(id, input.region);
+			return api;
+		},
+		/** Free text. */
+		text(id, input) {
+			const font = FONT[input.font ?? baseFont];
+			fonts.add(font);
+			elements.push({
+				id,
+				type: "text",
+				x: input.x,
+				y: input.y,
+				...input.w ? { width: input.w } : {},
+				text: input.text,
+				fontSize: input.size ?? baseSize,
+				fontFamily: font,
+				strokeColor: PALETTE[input.tone ?? "ink"].stroke,
+				textAlign: input.align ?? "left"
+			});
+			tag(id, input.region);
+			return api;
+		},
+		/** An arrow between two nodes, anchored on the facing sides unless told otherwise. */
+		arrow(from, to, input = {}) {
+			const a = geoms.get(from);
+			const b = geoms.get(to);
+			if (!a || !b) throw new Error(`sketch: arrow ${from} → ${to} names an unknown node`);
+			const [fromSide, toSide] = pickSides(a, b, input.from, input.to);
+			const p0 = anchor(a, fromSide, input.fromShift ?? 0);
+			const p1 = anchor(b, toSide, input.toShift ?? 0);
+			const pts = [
+				p0,
+				...input.via ?? [],
+				p1
+			];
+			const x = pts[0][0];
+			const y = pts[0][1];
+			const points = pts.map(([px, py]) => [px - x, py - y]);
+			const id = uid("arrow");
+			const tone = input.tone ?? "ink";
+			const font = FONT[input.font ?? baseFont];
+			if (input.label) fonts.add(font);
+			elements.push({
+				id,
+				type: input.line ? "line" : "arrow",
+				x,
+				y,
+				points,
+				strokeColor: PALETTE[tone].stroke,
+				strokeStyle: input.dotted ? "dotted" : input.dashed ? "dashed" : "solid",
+				strokeWidth: input.strokeWidth ?? 2,
+				roughness: baseRough,
+				roundness: pts.length > 2 ? { type: 2 } : null,
+				...input.line ? {} : {
+					endArrowhead: "arrow",
+					startArrowhead: input.both ? "arrow" : null
+				},
+				...input.label ? { label: {
+					text: input.label,
+					fontSize: input.size ?? Math.round(baseSize * .75),
+					fontFamily: font,
+					strokeColor: PALETTE[tone === "ink" ? "muted" : tone].stroke
+				} } : {}
+			});
+			const rs = [
+				...list(input.region),
+				...regions[from] ?? [],
+				...regions[to] ?? []
+			];
+			tag(id, rs);
+			return api;
+		},
+		build() {
+			return {
+				kind: "sketch",
+				width,
+				height,
+				elements: elements.map((e) => ({ ...e })),
+				regions: { ...regions },
+				regionMeta: [...regionMeta],
+				fonts: [...fonts]
+			};
+		}
+	};
+	return api;
+}
+function pickSides(a, b, from, to) {
+	const acx = a.x + a.w / 2;
+	const acy = a.y + a.h / 2;
+	const bcx = b.x + b.w / 2;
+	const bcy = b.y + b.h / 2;
+	const dx = bcx - acx;
+	const dy = bcy - acy;
+	const horizontal = Math.abs(dx) > Math.abs(dy);
+	return [from ?? (horizontal ? dx > 0 ? "right" : "left" : dy > 0 ? "bottom" : "top"), to ?? (horizontal ? dx > 0 ? "left" : "right" : dy > 0 ? "top" : "bottom")];
+}
+/** A point on a node's side, a few pixels off the stroke so the arrowhead breathes. */
+function anchor(g, side, shift) {
+	const gap = 6;
+	const sx = shift * g.w / 2;
+	const sy = shift * g.h / 2;
+	switch (side) {
+		case "left": return [g.x - gap, g.y + g.h / 2 + sy];
+		case "right": return [g.x + g.w + gap, g.y + g.h / 2 + sy];
+		case "top": return [g.x + g.w / 2 + sx, g.y - gap];
+		case "bottom": return [g.x + g.w / 2 + sx, g.y + g.h + gap];
+	}
+}
+//#endregion
+export { sketch };

package/dist/sketch/index.d.ts

@@ -0,0 +1,4 @@
+import { PALETTE, SketchTone } from "./palette.js";
+import { ArrowInput, NodeInput, RegionInput, SketchFill, SketchFont, SketchRegionMeta, SketchScene, SketchShape, TextInput, sketch } from "./dsl.js";
+import { ExcalidrawFile, SketchInput } from "./render.js";
+export { type ArrowInput, type ExcalidrawFile, type NodeInput, PALETTE, type RegionInput, type SketchFill, type SketchFont, type SketchInput, type SketchRegionMeta, type SketchScene, type SketchShape, type SketchTone, type TextInput, sketch };

package/dist/sketch/index.js

@@ -0,0 +1,3 @@
+import { PALETTE } from "./palette.js";
+import { sketch } from "./dsl.js";
+export { PALETTE, sketch };

package/dist/sketch/palette.d.ts

@@ -0,0 +1,21 @@
+//#region src/sketch/palette.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SKETCH PALETTE  —  the colours a sketch is drawn with, and what they become on a slide
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Excalidraw bakes literal colours into its SVG. A deck has themes and a light/dark scheme, so
+ * every sketch is drawn with this fixed palette and, once exported, each literal is rewritten
+ * to the theme token it stands for (`--deck-fg`, `--tone-accent`, …). The literals are picked
+ * to look right on their own too: the interactive canvas shows them as they are.
+ *
+ * Every entry is unique on purpose — the rewrite is a lookup by hex.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export type SketchTone = "ink" | "muted" | "accent" | "accent-2" | "good" | "warn" | "bad" | "info" | "neutral" | "purple" | "pink" | "amber" | "teal";
+export interface TonePair {
+  stroke: string;
+  fill: string;
+}
+export declare const PALETTE: Record<SketchTone, TonePair>;
+//#endregion

package/dist/sketch/palette.js

@@ -0,0 +1,66 @@
+//#region src/sketch/palette.ts
+const PALETTE = {
+	ink: {
+		stroke: "#1e1e1e",
+		fill: "#f8f9fa"
+	},
+	muted: {
+		stroke: "#6b7280",
+		fill: "#f3f4f6"
+	},
+	accent: {
+		stroke: "#059669",
+		fill: "#d1fae5"
+	},
+	"accent-2": {
+		stroke: "#0891b2",
+		fill: "#cffafe"
+	},
+	good: {
+		stroke: "#16a34a",
+		fill: "#dcfce7"
+	},
+	warn: {
+		stroke: "#d97706",
+		fill: "#fef3c7"
+	},
+	bad: {
+		stroke: "#dc2626",
+		fill: "#fee2e2"
+	},
+	info: {
+		stroke: "#2563eb",
+		fill: "#dbeafe"
+	},
+	neutral: {
+		stroke: "#64748b",
+		fill: "#f1f5f9"
+	},
+	purple: {
+		stroke: "#7c3aed",
+		fill: "#ede9fe"
+	},
+	pink: {
+		stroke: "#db2777",
+		fill: "#fce7f3"
+	},
+	amber: {
+		stroke: "#f59e0b",
+		fill: "#ffedd5"
+	},
+	teal: {
+		stroke: "#0d9488",
+		fill: "#ccfbf1"
+	}
+};
+/** The CSS a literal becomes on the slide. Strokes take the token; fills are a tint of it. */
+function cssFor(tone, role) {
+	if (tone === "ink") return role === "stroke" ? "var(--deck-fg)" : "var(--deck-surface)";
+	if (tone === "muted") return role === "stroke" ? "var(--deck-muted)" : "color-mix(in oklab, var(--deck-muted) 12%, transparent)";
+	const token = `var(--tone-${tone})`;
+	return role === "stroke" ? token : `color-mix(in oklab, ${token} 16%, transparent)`;
+}
+/** hex (lower-case) → CSS, for the rewrite pass. */
+const COLOR_MAP = new Map(Object.keys(PALETTE).flatMap((tone) => [[PALETTE[tone].stroke, cssFor(tone, "stroke")], [PALETTE[tone].fill, cssFor(tone, "fill")]]));
+//#endregion
+export { COLOR_MAP, PALETTE, cssFor };

package/dist/sketch/render.d.ts

@@ -0,0 +1,43 @@
+import { SketchScene } from "./dsl.js";
+//#region src/sketch/render.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SKETCH RENDERER  —  Excalidraw elements in, a theme-aware SVG out
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Three inputs, one pipeline:
+ *
+ *   DSL scene            skeletons ──► convertToExcalidrawElements
+ *   .excalidraw file     elements  ──► restoreElements                  ──► exportToSvg ──► rewrite
+ *   Mermaid text         parseMermaidToExcalidraw ──► convertToExcalidrawElements
+ *
+ * The rewrite is what makes the drawing belong to the deck: every element gets a `link` before
+ * export (Excalidraw wraps linked elements in `<a>`, the only per-element hook its exporter
+ * offers), which becomes a `<g data-id data-region>` so a slide can light regions up per click;
+ * and every palette literal becomes the theme token it stands for, so the sketch follows the
+ * theme menu and the dark scheme like everything else.
+ *
+ * Fonts are self-hosted: the Vite plugin serves `dist/prod/fonts` under `<base>excalidraw/`
+ * and this module points `EXCALIDRAW_ASSET_PATH` there. A warm-up export registers the faces
+ * in `document.fonts` before any text is measured, so boxes are sized for the real font.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export type SketchInput = SketchScene | {
+  kind: "file";
+  data: ExcalidrawFile;
+} | {
+  kind: "url";
+  src: string;
+} | {
+  kind: "mermaid";
+  source: string;
+  fontSize?: number;
+};
+/** The shape of a `.excalidraw` document (what excalidraw.com saves). */
+export interface ExcalidrawFile {
+  type?: string;
+  elements: readonly Record<string, unknown>[];
+  appState?: Record<string, unknown>;
+  files?: Record<string, unknown>;
+}
+//#endregion