@kadal/deck 0.0.0-stage → 0.1.0

package/dist/components/Sketch.d.ts

@@ -0,0 +1,44 @@
+import { SketchScene } from "../sketch/dsl.js";
+import { ExcalidrawFile } from "../sketch/render.js";
+import { ReactNode } from "react";
+//#region src/components/Sketch.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * <Sketch>  —  a hand-drawn Excalidraw diagram on a slide
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   <Sketch scene={architecture} />                    drawn in code with the `sketch()` DSL
+ *   <Sketch src="diagrams/flow.excalidraw" />          a file saved from excalidraw.com (public/)
+ *   <Sketch src={fileObject} />                        the same, already loaded
+ *   <Sketch>{`flowchart LR; a --> b`}</Sketch>          Mermaid, converted to a sketch
+ *
+ * The drawing is a static SVG recoloured with the theme's tokens, so it follows the theme menu
+ * and the dark scheme. `steps` turns clicks into a tour: the whole diagram shows first, then
+ * each click lights one region (a `region` from the DSL, a frame or group from a file) and dims
+ * the rest, with an optional caption — the notes' `[click]` markers line up with them. The
+ * corner button (or its F-hint) opens the real Excalidraw canvas in view mode, to pan and zoom.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export type SketchStep = string | null | {
+  focus?: string | string[] | null;
+  caption?: ReactNode;
+};
+export interface SketchProps {
+  scene?: SketchScene;
+  src?: string | ExcalidrawFile;
+  mermaid?: string;
+  children?: ReactNode;
+  /** Regions to light up, one per click, after the whole diagram has shown. */
+  steps?: SketchStep[];
+  /** Shown under the diagram when no step's caption is. */
+  caption?: ReactNode;
+  /** CSS size limits for the drawing. */
+  width?: string;
+  height?: string;
+  /** Font size for Mermaid conversions. */
+  fontSize?: number;
+  zoomable?: boolean;
+  className?: string;
+}
+export declare function Sketch({ scene, src, mermaid, children, steps, caption, width, height, fontSize, zoomable, className }: SketchProps): import("react").JSX.Element;
+//#endregion

package/dist/components/Sketch.js

@@ -0,0 +1,141 @@
+import { useActions, useClick, useUi } from "../react/hooks.js";
+import { hashInput, renderSketch } from "../sketch/render.js";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/Sketch.tsx
+function stepOf(s) {
+	if (s == null) return { focus: null };
+	if (typeof s === "string") return { focus: [s] };
+	const f = s.focus;
+	return {
+		focus: f == null ? null : Array.isArray(f) ? f : [f],
+		caption: s.caption
+	};
+}
+function Sketch({ scene, src, mermaid, children, steps = [], caption, width, height, fontSize, zoomable = true, className }) {
+	const text = mermaid ?? (typeof children === "string" ? children : Array.isArray(children) ? children.join("") : "");
+	const input = useMemo(() => {
+		if (scene) return scene;
+		if (typeof src === "string") return {
+			kind: "url",
+			src
+		};
+		if (src) return {
+			kind: "file",
+			data: src
+		};
+		return {
+			kind: "mermaid",
+			source: text.trim(),
+			fontSize
+		};
+	}, [
+		scene,
+		src,
+		text,
+		fontSize
+	]);
+	const key = useMemo(() => hashInput(input), [input]);
+	const [out, setOut] = useState(null);
+	const [error, setError] = useState(null);
+	useEffect(() => {
+		let alive = true;
+		setError(null);
+		renderSketch(input, key).then((r) => alive && setOut(r), (e) => alive && setError(String(e)));
+		return () => {
+			alive = false;
+		};
+	}, [input, key]);
+	const n = steps.length;
+	const { range, click } = useClick(n ? { span: n } : { at: 0 });
+	const idx = n && click >= range.start ? Math.min(click - range.start, n - 1) : -1;
+	const step = idx >= 0 ? stepOf(steps[idx]) : { focus: null };
+	const focus = step.focus;
+	const shownCaption = step.caption ?? caption;
+	const actions = useActions();
+	const hints = useUi((s) => s.hints);
+	const body = useRef(null);
+	const open = useRef(null);
+	useLayoutEffect(() => {
+		const place = () => {
+			const svg = body.current?.querySelector("svg");
+			const btn = open.current;
+			const fig = btn?.parentElement;
+			if (!svg || !btn || !fig) return;
+			const s = svg.getBoundingClientRect();
+			const f = fig.getBoundingClientRect();
+			const scale = f.width / Math.max(1, fig.offsetWidth);
+			btn.style.left = `${(s.right - f.left) / scale - btn.offsetWidth - 4}px`;
+			btn.style.top = `${(s.top - f.top) / scale + 4}px`;
+		};
+		place();
+		window.addEventListener("resize", place);
+		return () => window.removeEventListener("resize", place);
+	}, [out]);
+	useLayoutEffect(() => {
+		const root = body.current;
+		if (!root) return;
+		for (const g of root.querySelectorAll(".sk-el")) {
+			const rs = (g.getAttribute("data-region") ?? "").split("|").filter(Boolean);
+			const dim = !!focus && rs.length > 0 && !rs.some((r) => focus.includes(r));
+			g.classList.toggle("is-dim", dim);
+			g.classList.toggle("is-lit", !!focus && !dim && rs.length > 0);
+		}
+	}, [out, focus]);
+	return /* @__PURE__ */ jsxs("figure", {
+		className: [
+			"deck-sketch",
+			focus ? "has-focus" : "",
+			hints ? "hints-on" : "",
+			className
+		].filter(Boolean).join(" "),
+		"data-sketch": key,
+		style: {
+			...width ? { maxWidth: width } : {},
+			...height ? { "--sk-max-h": height } : {},
+			...out ? { "--sk-ratio": (out.width / Math.max(1, out.height)).toFixed(4) } : {}
+		},
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				ref: body,
+				className: "deck-sketch-body",
+				dangerouslySetInnerHTML: { __html: out?.svg ?? "" }
+			}),
+			!out && !error ? /* @__PURE__ */ jsx("div", {
+				className: "deck-sketch-loading",
+				children: "drawing…"
+			}) : null,
+			error ? /* @__PURE__ */ jsx("pre", {
+				className: "deck-sketch-error",
+				children: error
+			}) : null,
+			zoomable && out ? /* @__PURE__ */ jsx("button", {
+				ref: open,
+				type: "button",
+				className: "deck-sketch-open",
+				"data-hint": "canvas",
+				title: "Open on the canvas (pan and zoom)",
+				"aria-label": "Open on the canvas",
+				onClick: () => actions.openLightbox("sketch", key, "sketch"),
+				children: /* @__PURE__ */ jsx("svg", {
+					viewBox: "0 0 24 24",
+					width: "16",
+					height: "16",
+					fill: "none",
+					stroke: "currentColor",
+					strokeWidth: "2",
+					strokeLinecap: "round",
+					strokeLinejoin: "round",
+					"aria-hidden": true,
+					children: /* @__PURE__ */ jsx("path", { d: "M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7" })
+				})
+			}) : null,
+			shownCaption ? /* @__PURE__ */ jsx("figcaption", {
+				className: "deck-sketch-caption",
+				children: shownCaption
+			}, idx) : null
+		]
+	});
+}
+//#endregion
+export { Sketch };

package/dist/components/Term.d.ts

@@ -0,0 +1,63 @@
+import { ReactNode } from "react";
+//#region src/components/Term.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * <Term>  —  a key concept or abbreviation that can explain itself
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * At rest a term reads like the text around it, with a faint dotted underline. Rest the pointer
+ * on it and a countdown runs — the cursor becomes a filling pie and the underline draws itself
+ * solid — so sweeping the mouse across a slide never sets cards off; when it completes, the
+ * definition opens in a card anchored to the word. A click, a tap or an `f` hint label opens it
+ * at once and pins it while you talk. Escape, a press elsewhere or the next step closes it.
+ *
+ * Most terms are never written by hand: the compiler wraps the first mention of every glossary
+ * entry on each slide (`compiler/rehype-glossary.ts`). By hand:
+ *
+ *   <Term>UTM</Term>                                   the glossary's entry, found by name or alias
+ *   <Term id="utm">projected metres</Term>            other words, same entry
+ *   <Term def="Root-mean-square error, in metres.">RMSE</Term>      a one-off, no entry needed
+ *   <Term def="…" title="Thiessen polygon" full="…" tag="Geometry" link="https://…">cells</Term>
+ *
+ * The card lives inside the slide's canvas, in stage pixels, so it is part of the picture every
+ * screen shows — and it never lets its type fall below a readable size: on a small window or a
+ * phone the card grows against the canvas's scale instead of shrinking with it.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export interface TermProps {
+  /** The glossary entry (its id, name or alias). Without it the children's text is looked up. */
+  id?: string;
+  /** A one-off definition (inline Markdown). With it, the glossary is not consulted. */
+  def?: string;
+  more?: string;
+  /** The card's title for a one-off; defaults to the children's text. */
+  title?: string;
+  full?: string;
+  tag?: string;
+  link?: string;
+  /** Set by the compiler: `def`/`more` already rendered (with KaTeX), and an automatic link. */
+  html?: string;
+  moreHtml?: string;
+  auto?: boolean;
+  children?: ReactNode;
+}
+export declare function Term({ id, def, more, title, full, tag, link, html, moreHtml, auto, children }: TermProps): import("react").JSX.Element;
+/**
+ * Links the glossary's mentions inside a plain string, at render time — for a component whose
+ * words arrive as a prop (`<Stat label="quantisation RMSE" />`), where the compiler, which only
+ * sees a slide's children, cannot reach. The first mention of each term in the string is linked.
+ *
+ *   <small><Terms>{note}</Terms></small>
+ */
+export declare function Terms({ children }: {
+  children?: string | null;
+}): import("react").JSX.Element;
+/**
+ * The window's open definition as ordinary page content, at reading size — for a page whose slide
+ * is too small to carry a card (the audience's phone). Put the mirror inside an element with
+ * `data-term-cards="off"` and this beside it.
+ */
+export declare function TermReadout({ className }: {
+  className?: string;
+}): import("react").JSX.Element | null;
+//#endregion