@kadal/deck 0.0.0-stage → 0.1.0

package/dist/react/hooks.d.ts

@@ -0,0 +1,33 @@
+import { DeckConfig, SlideMeta, SlideOptions } from "../core/model.js";
+import { ClickRange, ClickSpec } from "../core/clicks.js";
+import { Layout } from "../core/layout.js";
+import { NavState } from "../core/navigation.js";
+import { DeckActions, UiState } from "./context.js";
+import "../index.js";
+//#region src/react/hooks.d.ts
+export declare function useNav<S = NavState>(selector?: (s: NavState) => S): S;
+export declare function useUi<S = UiState>(selector?: (s: UiState) => S): S;
+export declare function useLayout(): Layout;
+export declare function useConfig(): DeckConfig;
+export declare function useActions(): DeckActions;
+/** The current slide's meta and options, or null when nothing is active yet. */
+export declare function useCurrentSlide(): {
+  h: number;
+  v: number;
+  meta: SlideMeta;
+  options: SlideOptions | null;
+};
+/**
+ * Register a click step for the calling element and learn whether it is shown right now.
+ * Registration happens during render so document order is preserved; the range is stable across
+ * re-renders and Strict Mode's double render because it is keyed by `useId`.
+ */
+export declare function useClick(spec?: ClickSpec): {
+  range: ClickRange;
+  shown: boolean;
+  current: boolean;
+  click: number;
+};
+/** Read the current click without registering anything (a code block after its `<pre>` did). */
+export declare function useClickIndex(): number;
+//#endregion

package/dist/react/hooks.js

@@ -0,0 +1,70 @@
+import { useStore } from "../core/store.js";
+import { useDeck, useSlide, useSlideOptional } from "./context.js";
+import { isCurrent, isShown } from "../core/clicks.js";
+import { useId, useLayoutEffect, useMemo } from "react";
+//#region src/react/hooks.ts
+function useNav(selector) {
+	const { nav } = useDeck();
+	return useStore(nav, selector);
+}
+function useUi(selector) {
+	const { ui } = useDeck();
+	return useStore(ui, selector);
+}
+function useLayout() {
+	const { layout } = useDeck();
+	return useStore(layout);
+}
+function useConfig() {
+	return useDeck().config;
+}
+function useActions() {
+	return useDeck().actions;
+}
+/** The current slide's meta and options, or null when nothing is active yet. */
+function useCurrentSlide() {
+	const { columns, options } = useDeck();
+	const { h, v } = useNav((s) => ({
+		h: s.h,
+		v: s.v
+	}));
+	const meta = columns[h]?.slides[v] ?? null;
+	return {
+		h,
+		v,
+		meta,
+		options: meta ? options.get(`${h},${v}`) ?? null : null
+	};
+}
+/**
+* Register a click step for the calling element and learn whether it is shown right now.
+* Registration happens during render so document order is preserved; the range is stable across
+* re-renders and Strict Mode's double render because it is keyed by `useId`.
+*/
+function useClick(spec = {}) {
+	const slide = useSlide();
+	const id = useId();
+	const range = useMemo(() => slide.registry.allocate(id, spec), [
+		slide.registry,
+		id,
+		spec.at,
+		spec.hide,
+		spec.span
+	]);
+	useLayoutEffect(() => {
+		slide.registry.allocate(id, spec);
+		return () => slide.registry.release(id);
+	}, [slide.registry, id]);
+	return {
+		range,
+		shown: isShown(range, slide.click),
+		current: isCurrent(range, slide.click),
+		click: slide.click
+	};
+}
+/** Read the current click without registering anything (a code block after its `<pre>` did). */
+function useClickIndex() {
+	return useSlideOptional()?.click ?? 0;
+}
+//#endregion
+export { useActions, useClick, useClickIndex, useConfig, useCurrentSlide, useLayout, useNav, useUi };

package/dist/react/layouts.d.ts

@@ -0,0 +1,21 @@
+import { Frontmatter } from "../compiler/split.js";
+import { SlideOptions } from "../core/model.js";
+import { ComponentType, ReactNode } from "react";
+//#region src/react/layouts.d.ts
+/**
+ * Layouts, the Slidev set, as React components a slide's frontmatter picks by name:
+ *
+ *   default · center · cover · intro · section · end · fact · quote · statement · full · none ·
+ *   two-cols · image · image-left · image-right · iframe · iframe-left · iframe-right
+ *
+ * Every layout wraps the slide's MDX in `.deck-layout` with a modifier class the theme styles;
+ * the image/iframe ones read `image` / `url` / `backgroundSize` from the frontmatter. A deck adds
+ * its own by passing `components={{ "layout:name": Component }}` to `<Deck>`.
+ */
+export interface LayoutProps {
+  frontmatter: Frontmatter;
+  options: SlideOptions;
+  children: ReactNode;
+}
+export declare const LAYOUTS: Record<string, ComponentType<LayoutProps>>;
+//#endregion

package/dist/react/layouts.js

@@ -0,0 +1,104 @@
+import { useDeck } from "./context.js";
+import { FrameShell } from "./Frame.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/layouts.tsx
+function str(v) {
+	return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+const simple = (name) => function Layout({ children }) {
+	return /* @__PURE__ */ jsx("div", {
+		className: `deck-layout deck-layout-${name}`,
+		children
+	});
+};
+function TwoCols({ children }) {
+	return /* @__PURE__ */ jsx("div", {
+		className: "deck-layout deck-layout-two-cols",
+		children
+	});
+}
+function makeImage(side) {
+	return function ImageLayout({ frontmatter, children }) {
+		const image = str(frontmatter.image) ?? "";
+		const size = str(frontmatter.backgroundSize) ?? "cover";
+		const figure = /* @__PURE__ */ jsx("div", {
+			className: "deck-layout-image-pane",
+			style: {
+				backgroundImage: `url(${image})`,
+				backgroundSize: size
+			}
+		});
+		if (side === "full") return /* @__PURE__ */ jsxs("div", {
+			className: "deck-layout deck-layout-image",
+			children: [figure, /* @__PURE__ */ jsx("div", {
+				className: "deck-layout-image-content",
+				children
+			})]
+		});
+		return /* @__PURE__ */ jsxs("div", {
+			className: `deck-layout deck-layout-image-${side}`,
+			children: [
+				side === "left" ? figure : null,
+				/* @__PURE__ */ jsx("div", {
+					className: "deck-layout-image-content",
+					children
+				}),
+				side === "right" ? figure : null
+			]
+		});
+	};
+}
+function makeIframe(side) {
+	return function IframeLayout({ frontmatter, children }) {
+		const deck = useDeck();
+		const poster = str(frontmatter.poster) ?? void 0;
+		const posterSize = side === "full" ? [deck.config.width, deck.config.height] : [Math.round(deck.config.width / 2), deck.config.height];
+		const url = str(frontmatter.url) ?? "about:blank";
+		const frame = /* @__PURE__ */ jsx(FrameShell, {
+			url,
+			className: "deck-layout-iframe-pane",
+			poster,
+			posterSize
+		});
+		if (side === "full") return /* @__PURE__ */ jsx("div", {
+			className: "deck-layout deck-layout-iframe",
+			children: frame
+		});
+		return /* @__PURE__ */ jsxs("div", {
+			className: `deck-layout deck-layout-iframe-${side}`,
+			children: [
+				side === "left" ? frame : null,
+				/* @__PURE__ */ jsx("div", {
+					className: "deck-layout-iframe-content",
+					children
+				}),
+				side === "right" ? frame : null
+			]
+		});
+	};
+}
+const LAYOUTS = {
+	default: simple("default"),
+	center: simple("center"),
+	cover: simple("cover"),
+	intro: simple("intro"),
+	section: simple("section"),
+	end: simple("end"),
+	fact: simple("fact"),
+	quote: simple("quote"),
+	statement: simple("statement"),
+	full: simple("full"),
+	none: ({ children }) => /* @__PURE__ */ jsx(Fragment, { children }),
+	"two-cols": TwoCols,
+	image: makeImage("full"),
+	"image-left": makeImage("left"),
+	"image-right": makeImage("right"),
+	iframe: makeIframe("full"),
+	"iframe-left": makeIframe("left"),
+	"iframe-right": makeIframe("right")
+};
+function layoutFor(name, components) {
+	return components[`layout:`] ?? LAYOUTS[name] ?? LAYOUTS.default;
+}
+//#endregion
+export { LAYOUTS, layoutFor };

package/dist/react/mdx.d.ts

@@ -0,0 +1,4 @@
+import { ComponentType, ReactNode } from "react";
+//#region src/react/mdx.d.ts
+export declare function useMDXComponents(): Record<string, ComponentType<Record<string, unknown>>>;
+//#endregion

package/dist/react/mdx.js

@@ -0,0 +1,33 @@
+import { useDeck } from "./context.js";
+import { Code } from "../components/Code.js";
+import { Anchor, Image } from "../components/content.js";
+import { components_exports } from "../components/index.js";
+import { Fragment, jsx } from "react/jsx-runtime";
+//#region src/react/mdx.tsx
+/**
+* The components every slide sees without importing anything: the engine's own (`Click`, `Code`,
+* `Cols`, `Poll`…), the deck's custom ones (passed to `<Deck components>`), and the Markdown
+* element mappings — `pre` becomes the stepping code block, `img` the lightbox-aware image, `a`
+* the slide-aware link. MDX's `providerImportSource` resolves to `useMDXComponents` below.
+*/
+let current = {};
+function useMDXComponents() {
+	return current;
+}
+function MDXProvider({ children }) {
+	const custom = useDeck().components;
+	if (cachedFor !== custom) {
+		cachedFor = custom;
+		current = {
+			...components_exports,
+			pre: Code,
+			img: Image,
+			a: Anchor,
+			...Object.fromEntries(Object.entries(custom).filter(([k]) => !k.startsWith("layout:")))
+		};
+	}
+	return /* @__PURE__ */ jsx(Fragment, { children });
+}
+let cachedFor = null;
+//#endregion
+export { MDXProvider, useMDXComponents };

package/dist/react/terms.d.ts

@@ -0,0 +1,6 @@
+import { DeckRuntime, TermReveal } from "./context.js";
+//#region src/react/terms.d.ts
+export declare function openTerm(deck: DeckRuntime, reveal: TermReveal): void;
+/** Close the card; with `only`, just when it is that kind (a relayed "off" spares a local card). */
+export declare function closeTerm(deck: DeckRuntime, only?: TermReveal["from"]): void;
+//#endregion

package/dist/react/terms.js

@@ -0,0 +1,66 @@
+import { termId } from "../glossary/model.js";
+import { useEffect } from "react";
+//#region src/react/terms.ts
+/**
+* The window's one term card, as plain functions over `deck.terms`. A reveal names a mention —
+* slide, term id, which occurrence — rather than carrying a definition or a position: every
+* screen runs the same build, so each resolves the words from its own glossary and anchors the
+* card to its own copy of the element. That is what lets the presenter's reveal travel through
+* the room as three small values and land correctly on a projector and a phone alike.
+*/
+/** "h,v" of the slide an element sits in, or null outside one. */
+function slideKeyOf(el) {
+	const slide = el.closest(".deck-slide");
+	if (!slide || slide.dataset.h === void 0) return null;
+	return `${slide.dataset.h},${slide.dataset.v ?? "0"}`;
+}
+/** Which of its slide's mentions of `id` this element is, in document order. */
+function mentionIndex(el, id) {
+	const slide = el.closest(".deck-slide");
+	if (!slide) return 0;
+	const all = slide.querySelectorAll(`[data-term="${CSS.escape(id)}"]`);
+	return Math.max(0, Array.prototype.indexOf.call(all, el));
+}
+function entryFor(deck, id) {
+	return deck.glossary.get(id) ?? deck.glossary.get(termId(id));
+}
+function openTerm(deck, reveal) {
+	deck.terms.set(reveal);
+}
+/** Close the card; with `only`, just when it is that kind (a relayed "off" spares a local card). */
+function closeTerm(deck, only) {
+	const now = deck.terms.get();
+	if (now && (!only || now.from === only)) deck.terms.set(null);
+}
+/**
+* What dismisses a card besides its own term: moving through the deck, Escape, the overview, and
+* a press anywhere that is not the card or a term. Escape is taken in the capture phase and kept
+* from the deck's bindings, where it would open the overview.
+*/
+function useTermEffects(deck) {
+	useEffect(() => {
+		const offNav = deck.nav.subscribe((s, prev) => {
+			if (s.h !== prev.h || s.v !== prev.v || s.click !== prev.click || s.overview !== prev.overview) deck.terms.set(null);
+		});
+		const onKey = (e) => {
+			if (e.key !== "Escape" || !deck.terms.get()) return;
+			e.preventDefault();
+			e.stopImmediatePropagation();
+			deck.terms.set(null);
+		};
+		const onPress = (e) => {
+			if (!deck.terms.get()) return;
+			if (e.target?.closest?.(".deck-term, .deck-term-card, .deck-term-readout, .deck-hints")) return;
+			deck.terms.set(null);
+		};
+		window.addEventListener("keydown", onKey, true);
+		document.addEventListener("pointerdown", onPress, true);
+		return () => {
+			offNav();
+			window.removeEventListener("keydown", onKey, true);
+			document.removeEventListener("pointerdown", onPress, true);
+		};
+	}, [deck]);
+}
+//#endregion
+export { closeTerm, entryFor, mentionIndex, openTerm, slideKeyOf, useTermEffects };

package/dist/renderers/Island.d.ts

@@ -0,0 +1,57 @@
+import { IslandComponent, IslandProps } from "./contract.js";
+import { ReactNode } from "react";
+//#region src/renderers/Island.d.ts
+/**
+ * When an island comes alive.
+ *
+ *   slide    when its slide is the one being shown, and torn down when it is left  (the default)
+ *   load     as soon as it is rendered
+ *   visible  when it scrolls into view — for the scroll view and long slides
+ *   idle     when the browser next has nothing better to do
+ *   none     never: the static fallback is the whole story
+ *
+ * `slide` is the default and is the one a deck actually wants. Astro's strategies all assume a page
+ * you scroll; a deck is twenty pages deep where nineteen are off-screen but mounted — the engine
+ * keeps neighbours ready so transitions do not stall. Hydrating all of them is how a phone runs out
+ * of memory on slide three. This way a live map exists for exactly as long as it is being looked at.
+ */
+export type ClientStrategy = "slide" | "load" | "visible" | "idle" | "none";
+/** A dynamic import of a component, in whatever shape the module exports it. */
+export type IslandLoader = () => Promise<IslandComponent | {
+  default: IslandComponent;
+}>;
+export interface IslandOwnProps {
+  /** The component, in whatever framework wrote it. Omit when passing `load`. */
+  component?: IslandComponent;
+  /**
+   * Fetch the component when the island arms, instead of importing it with the slide.
+   *
+   *     <Island framework="vue" load={() => import("./chart.ts").then((m) => m.Chart)} />
+   *
+   * This is the half of islands that is about bytes rather than lifetime: with `load`, neither the
+   * component nor — paired with `registerLazyRenderer` — its framework's runtime is in the deck's
+   * first chunk. Read once, when the island first arms; the component it names is the island's
+   * identity for as long as the island lives.
+   */
+  load?: IslandLoader;
+  /** Name the renderer explicitly. Otherwise the build's stamp decides, then `owns()`. */
+  framework?: string;
+  client?: ClientStrategy;
+  /** Passed through to the component. Compared shallowly: new identities alone do not remount. */
+  props?: IslandProps;
+  /** Shown before the island is alive, and instead of it where it never will be. */
+  fallback?: ReactNode;
+  className?: string;
+  /** Rendered to HTML and handed over as `context.slot`. */
+  children?: ReactNode;
+}
+/**
+ * One piece of another framework, living inside a slide.
+ *
+ * The React case is deliberately NOT an island: when the resolved renderer is the one the deck
+ * runtime draws with, the component is rendered straight into the tree. An island would work, but
+ * it would open a second React root, and everything the deck puts in context — the click state, the
+ * theme, the live room, the glossary — stops at a root boundary. Native stays native.
+ */
+export declare function Island({ component, load, framework, client, props, fallback, className, children }: IslandOwnProps): import("react").JSX.Element;
+//#endregion

package/dist/renderers/Island.js

@@ -0,0 +1,223 @@
+import { useDeck, useSlideOptional } from "../react/context.js";
+import { resolveRenderer, resolveRendererAsync } from "./contract.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/renderers/Island.tsx
+function shallowEqual(a, b) {
+	const ak = Object.keys(a);
+	if (ak.length !== Object.keys(b).length) return false;
+	return ak.every((k) => Object.is(a[k], b[k]));
+}
+/**
+* A thunk may resolve to a module or to a component. For every framework whose component is a
+* value, the module's `default` IS the component, so that is what is taken.
+*
+* The exception worth naming: a module whose `default` is an *initialiser* rather than a component
+* — `wasm-bindgen --target web` emits exactly that. Unwrapping one yields the init function and the
+* failure is silent, so such a module is adapted by its own renderer before it gets here. See
+* `wasmBindgenModule` in `@kadal/deck-wasm`.
+*/
+function unwrap(module) {
+	return module && typeof module === "object" && "default" in module ? module.default : module;
+}
+/**
+* One piece of another framework, living inside a slide.
+*
+* The React case is deliberately NOT an island: when the resolved renderer is the one the deck
+* runtime draws with, the component is rendered straight into the tree. An island would work, but
+* it would open a second React root, and everything the deck puts in context — the click state, the
+* theme, the live room, the glossary — stops at a root boundary. Native stays native.
+*/
+function Island({ component, load, framework, client = "slide", props = {}, fallback = null, className, children }) {
+	const deck = useDeck();
+	const slide = useSlideOptional();
+	const host = useRef(null);
+	const slotHost = useRef(null);
+	const mounted = useRef(null);
+	const lastProps = useRef(props);
+	const loader = useRef(load);
+	loader.current = load;
+	const printing = deck.mode === "print";
+	const slideWants = printing || (slide?.active ?? true);
+	const [armed, setArmed] = useState(() => client === "load" || client === "slide" && slideWants);
+	useEffect(() => {
+		if (client === "none") return;
+		if (client === "load") return setArmed(true);
+		if (client === "slide") return setArmed(slideWants);
+		if (client === "idle") {
+			const hasIdle = typeof window.requestIdleCallback === "function";
+			const id = hasIdle ? window.requestIdleCallback(() => setArmed(true)) : window.setTimeout(() => setArmed(true), 200);
+			return () => {
+				if (hasIdle) window.cancelIdleCallback?.(id);
+				else clearTimeout(id);
+			};
+		}
+		const el = host.current;
+		if (!el) return;
+		if (typeof IntersectionObserver === "undefined") return setArmed(true);
+		const io = new IntersectionObserver((entries) => entries.some((e) => e.isIntersecting) && setArmed(true), { rootMargin: "200px" });
+		io.observe(el);
+		return () => io.disconnect();
+	}, [client, slideWants]);
+	const [fetched, setFetched] = useState(null);
+	const target = component ?? fetched?.component;
+	useEffect(() => {
+		if (component !== void 0 || !armed) return;
+		const fetch = loader.current;
+		if (!fetch) return;
+		let live = true;
+		fetch().then((module) => live && setFetched({ component: unwrap(module) })).catch((error) => {
+			console.error("[deck] an island's component failed to load:", error);
+		});
+		return () => {
+			live = false;
+		};
+	}, [component, armed]);
+	const immediate = useMemo(() => target === void 0 ? null : resolveRenderer(target, framework), [target, framework]);
+	const [arrived, setArrived] = useState(null);
+	useEffect(() => {
+		if (!immediate || immediate.how !== "deferred" || !armed) return;
+		let live = true;
+		resolveRendererAsync(target, framework).then((r) => live && setArrived(r));
+		return () => {
+			live = false;
+		};
+	}, [
+		immediate,
+		armed,
+		target,
+		framework
+	]);
+	const resolution = immediate?.how === "deferred" && arrived?.renderer ? arrived : immediate ?? null;
+	const renderer = resolution?.renderer ?? null;
+	const native = renderer?.native ?? false;
+	useEffect(() => {
+		if (native || !renderer || !armed || target === void 0) return;
+		const el = host.current;
+		if (!el) return;
+		const context = {
+			slot: slotHost.current?.innerHTML || void 0,
+			scheme: document.documentElement.dataset.colorScheme === "dark" ? "dark" : "light",
+			animate: !printing && !(slide?.preview ?? false)
+		};
+		let live = null;
+		try {
+			live = renderer.mount(el, target, lastProps.current, context);
+			mounted.current = live;
+		} catch (error) {
+			console.error(`[deck] island “${renderer.name}” failed to mount:`, error);
+			el.dataset.islandError = error instanceof Error ? error.message : String(error);
+		}
+		return () => {
+			mounted.current = null;
+			try {
+				live?.destroy();
+			} catch (error) {
+				console.error(`[deck] island “${renderer.name}” failed to tear down:`, error);
+			}
+			el.replaceChildren();
+			delete el.dataset.islandError;
+		};
+	}, [
+		native,
+		renderer,
+		armed,
+		target,
+		printing,
+		slide?.preview
+	]);
+	useEffect(() => {
+		if (shallowEqual(lastProps.current, props)) return;
+		lastProps.current = props;
+		const live = mounted.current;
+		if (!live) return;
+		if (live.update) {
+			try {
+				live.update(props);
+			} catch (error) {
+				console.error("[deck] island refused new props:", error);
+			}
+			return;
+		}
+		const el = host.current;
+		if (!el || !renderer || target === void 0) return;
+		try {
+			live.destroy();
+			el.replaceChildren();
+			mounted.current = renderer.mount(el, target, props, {
+				slot: slotHost.current?.innerHTML || void 0,
+				animate: !printing
+			});
+		} catch (error) {
+			console.error("[deck] island failed to remount with new props:", error);
+		}
+	}, [
+		props,
+		renderer,
+		target,
+		printing
+	]);
+	if (component === void 0 && !load) return /* @__PURE__ */ jsx("div", {
+		className: [
+			"deck-island",
+			"is-unresolved",
+			className
+		].filter(Boolean).join(" "),
+		children: /* @__PURE__ */ jsx("span", {
+			className: "deck-island-error",
+			children: "Island: pass a component, or load to fetch one"
+		})
+	});
+	if (resolution?.how === "unknown") return /* @__PURE__ */ jsx("div", {
+		className: [
+			"deck-island",
+			"is-unresolved",
+			className
+		].filter(Boolean).join(" "),
+		children: /* @__PURE__ */ jsxs("span", {
+			className: "deck-island-error",
+			children: ["Island: ", resolution.reason]
+		})
+	});
+	if (native) {
+		const Component = target;
+		return /* @__PURE__ */ jsx("div", {
+			className: [
+				"deck-island",
+				"is-native",
+				className
+			].filter(Boolean).join(" "),
+			children: /* @__PURE__ */ jsx(Component, {
+				...props,
+				children
+			})
+		});
+	}
+	const pending = renderer === null;
+	const name = renderer?.name ?? (resolution?.how === "deferred" ? resolution.name : framework);
+	return /* @__PURE__ */ jsxs("div", {
+		className: [
+			"deck-island",
+			name ? `is-${name}` : null,
+			pending ? "is-pending" : armed ? "is-live" : "is-waiting",
+			className
+		].filter(Boolean).join(" "),
+		"data-framework": name,
+		"data-client": client,
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				className: "deck-island-slot",
+				hidden: true,
+				ref: slotHost,
+				children
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "deck-island-host",
+				ref: host
+			}),
+			armed && !pending ? null : fallback
+		]
+	});
+}
+//#endregion
+export { Island };