@kadal/deck 0.0.0-stage → 0.1.0

package/dist/core/model.d.ts

@@ -0,0 +1,259 @@
+import { Frontmatter } from "../compiler/split.js";
+import { GlossaryEntry, GlossaryOptions } from "../glossary/model.js";
+import { ComponentType } from "react";
+//#region src/core/model.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE DECK MODEL
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * A deck is a row of columns. Each column is a vertical stack whose first slide is the one you
+ * reach by moving right; the others sit beneath it (reveal.js's vertical slides). Every slide has a
+ * flat index in authored order too, which is what the progress bar, the table of contents and the
+ * scroll view use. Nothing here touches the DOM.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export interface SlideModule {
+  default: ComponentType<Record<string, unknown>>;
+}
+export interface MagicMoveStepData {
+  lang: string;
+  lines: boolean;
+  highlight: string | null;
+  tokens: {
+    light: unknown;
+    dark: unknown;
+  };
+}
+export interface MagicMoveData {
+  options: Record<string, string>;
+  title: string | null;
+  steps: MagicMoveStepData[];
+}
+/** One entry of the manifest the Vite plugin emits. */
+export interface SlideMeta {
+  index: number;
+  h: number;
+  v: number;
+  id: string;
+  title: string | null;
+  level: number;
+  frontmatter: Frontmatter;
+  hasNotes: boolean;
+  source: {
+    file: string;
+    line: number;
+  };
+  load: () => Promise<SlideModule>;
+  loadNotes: (() => Promise<SlideModule>) | null;
+  loadMagic: (() => Promise<{
+    default: MagicMoveData[];
+  }>) | null;
+}
+export interface DeckManifest {
+  headmatter: Frontmatter;
+  slides: SlideMeta[];
+  /** The deck's `glossary.yaml`, parsed at build time; absent in a deck without one. */
+  glossary?: GlossaryEntry[];
+}
+export type Transition = "none" | "fade" | "slide" | "convex" | "concave" | "zoom" | "view-transition";
+export type TransitionSpeed = "default" | "fast" | "slow";
+export type SlideNumberFormat = "h.v" | "h/v" | "c" | "c/t";
+export type NavigationMode = "default" | "linear" | "grid";
+export type ColorScheme = "auto" | "light" | "dark";
+/** Every option, with the same names reveal.js and Slidev use wherever the idea is the same. */
+export interface DeckConfig {
+  title: string;
+  author: string;
+  info: string;
+  /** The authored size; the stage scales uniformly to fit any viewport. */
+  width: number;
+  height: number;
+  /**
+   * Fraction of the viewport left empty around the stage. 0 by default: a 16:9 window shows the
+   * slide edge to edge, any other shape gets bars on two sides — the content never reflows.
+   */
+  margin: number;
+  minScale: number;
+  maxScale: number;
+  /** Vertically centre each slide's content. */
+  center: boolean;
+  controls: boolean | "speaker";
+  controlsLayout: "bottom-right" | "edges";
+  controlsTutorial: boolean;
+  controlsBackArrows: "faded" | "hidden" | "visible";
+  progress: boolean;
+  slideNumber: boolean | SlideNumberFormat;
+  showSlideNumber: "all" | "print" | "speaker";
+  hash: boolean;
+  hashOneBasedIndex: boolean;
+  history: boolean;
+  keyboard: boolean;
+  overview: boolean;
+  touch: boolean;
+  loop: boolean;
+  rtl: boolean;
+  navigationMode: NavigationMode;
+  shuffle: boolean;
+  fragments: boolean;
+  fragmentInURL: boolean;
+  embedded: boolean;
+  help: boolean;
+  pause: boolean;
+  showNotes: boolean | "separate-page";
+  autoPlayMedia: boolean | null;
+  autoAnimate: boolean;
+  autoAnimateEasing: string;
+  autoAnimateDuration: number;
+  autoAnimateUnmatched: boolean;
+  /** Milliseconds between automatic steps; 0 disables. */
+  autoSlide: number;
+  autoSlideStoppable: boolean;
+  /** Seconds per slide for the pacing timer, or null. */
+  defaultTiming: number | null;
+  /** Total seconds for the pacing timer, or null. */
+  totalTime: number | null;
+  mouseWheel: boolean;
+  previewLinks: boolean;
+  transition: Transition;
+  transitionSpeed: TransitionSpeed;
+  backgroundTransition: Transition;
+  viewDistance: number;
+  mobileViewDistance: number;
+  hideInactiveCursor: boolean;
+  hideCursorTime: number;
+  view: "slide" | "scroll";
+  scrollProgress: "auto" | boolean;
+  scrollSnap: "mandatory" | "proximity" | false;
+  /**
+   * Viewport width under which the scroll view switches on by itself; 0 (the default) never does
+   * — a phone gets the same stage, letterboxed, and `?view=scroll` stays an explicit choice.
+   */
+  scrollActivationWidth: number;
+  theme: string;
+  /** Themes this deck ships (their CSS is imported by main.tsx); the theme menu lists them. */
+  themes: string[];
+  colorScheme: ColorScheme;
+  pdfSeparateFragments: boolean;
+  pdfMaxPagesPerSlide: number;
+  jumpToSlide: boolean;
+  search: boolean;
+  zoom: boolean;
+  wakeLock: boolean;
+  selectable: boolean;
+  lineNumbers: boolean;
+  /** Scale a slide whose content overflows so it fits (measured after render). */
+  autoFit: boolean;
+  magicMoveDuration: number;
+  /** Live room: the backend base (same origin `/api` on the host), or null for an offline deck. */
+  live: {
+    api: string | null;
+    room: string | null;
+    turnstile: string | null;
+  };
+  drawings: {
+    enabled: boolean;
+    persist: boolean;
+    presenterOnly: boolean;
+    syncAll: boolean;
+  };
+  /**
+   * Term cards. The runtime reads `delay` and `sync`; the rest steers the compiler, which sees
+   * the headmatter only — set those there. `glossary: false` or a path are shorthands.
+   */
+  glossary: GlossaryOptions;
+  reactions: boolean;
+  qa: boolean;
+  polls: boolean;
+  /** Show every slide's notes to anyone on the audience page (after the talk, for instance). */
+  audienceNotes: boolean;
+  /** The deck's slug on the host, from the Vite base — decks/<slug>. */
+  slug: string;
+  /** Show the "Made with Kadal Deck" link in the corner (set by the host, see `withHostOverride`). */
+  badge: boolean;
+  /** Google Fonts families to load, e.g. ["Inter:wght@400;600"]. */
+  fonts: string[];
+  seoMeta: Record<string, string>;
+}
+export declare const DEFAULT_CONFIG: DeckConfig;
+/** Headmatter and deck.config.ts both layer over the defaults; nested objects merge one level. */
+/** What a deck.config.ts or headmatter may set: any option, with the nested groups partial too. */
+export type DeckConfigInput = Partial<Omit<DeckConfig, "live" | "drawings" | "seoMeta" | "glossary">> & {
+  glossary?: Partial<GlossaryOptions> | string | false;
+  live?: Partial<DeckConfig["live"]>;
+  drawings?: Partial<DeckConfig["drawings"]>;
+  seoMeta?: Partial<DeckConfig["seoMeta"]>;
+};
+export declare function resolveConfig(...layers: Array<DeckConfigInput | Frontmatter | undefined>): DeckConfig;
+/** Per-slide options read from frontmatter, normalised. */
+export interface SlideOptions {
+  layout: string;
+  className: string;
+  hidden: boolean;
+  uncounted: boolean;
+  hideInToc: boolean;
+  transition: string | null;
+  transitionSpeed: TransitionSpeed | null;
+  backgroundTransition: Transition | null;
+  autoAnimate: boolean;
+  autoAnimateId: string | null;
+  autoAnimateRestart: boolean;
+  autoSlide: number | null;
+  clicks: number | null;
+  clicksStart: number;
+  preload: boolean;
+  timing: number | null;
+  state: string[];
+  /** Force dark or light tokens on this slide (a dark background under a light theme). */
+  colorScheme: "dark" | "light" | null;
+  zoom: number;
+  background: SlideBackground | null;
+}
+export interface SlideBackground {
+  color: string | null;
+  gradient: string | null;
+  image: string | null;
+  size: string;
+  position: string;
+  repeat: string;
+  opacity: number;
+  video: string | null;
+  videoLoop: boolean;
+  videoMuted: boolean;
+  iframe: string | null;
+  iframeInteractive: boolean;
+  /**
+   * A soft wash of one colour over the layer — a diagonal gradient from the colour to a paler
+   * tint of it, with a little more light in one corner — under a component background or on
+   * its own (`fill:` / `tint:` in frontmatter). `color` is the flat fill reveal.js has.
+   */
+  tint: string | null;
+  /** A registered component background, by name, with its props. */
+  component: string | null;
+  props: Record<string, unknown>;
+}
+/** `background: "#fff"`, `background: "/img.png"`, `background: { image, size }`, `background: { component: "aurora", … }`. */
+export declare function resolveBackground(fm: Frontmatter): SlideBackground | null;
+export declare function resolveSlideOptions(fm: Frontmatter, config: DeckConfig, isFirst: boolean): SlideOptions;
+/** The slides grouped into columns, with hidden slides dropped. */
+export interface Column {
+  h: number;
+  slides: SlideMeta[];
+}
+export declare function columnsOf(slides: SlideMeta[], config: DeckConfig): Column[];
+/** What a host may say about a deck it serves. */
+export interface HostOverride {
+  room?: string;
+  api?: string;
+  badge?: boolean;
+}
+/** The global a host sets, validated: anything malformed is ignored rather than trusted. */
+export declare function readHostOverride(scope?: unknown): HostOverride | null;
+/** The config with the host's word laid over it. Returns the same object when there is none. */
+export declare function withHostOverride(config: DeckConfig, override: HostOverride | null): DeckConfig;
+/**
+ * The id every host call is keyed by — the room, presenter login, stats, beacons, share links and
+ * exports. A published deck's is the room the host assigned; a self-hosted one's is its slug.
+ */
+export declare function roomIdOf(config: Pick<DeckConfig, "live" | "slug">): string;
+//#endregion

package/dist/core/model.js

@@ -0,0 +1,377 @@
+import { DEFAULT_GLOSSARY, glossaryOptions } from "../glossary/model.js";
+//#region src/core/model.ts
+const DEFAULT_CONFIG = {
+	title: "Untitled deck",
+	author: "",
+	info: "",
+	width: 1920,
+	height: 1080,
+	margin: 0,
+	minScale: .2,
+	maxScale: 2,
+	center: true,
+	controls: true,
+	controlsLayout: "bottom-right",
+	controlsTutorial: true,
+	controlsBackArrows: "faded",
+	progress: true,
+	slideNumber: false,
+	showSlideNumber: "all",
+	hash: true,
+	hashOneBasedIndex: false,
+	history: false,
+	keyboard: true,
+	overview: true,
+	touch: true,
+	loop: false,
+	rtl: false,
+	navigationMode: "default",
+	shuffle: false,
+	fragments: true,
+	fragmentInURL: true,
+	embedded: false,
+	help: true,
+	pause: true,
+	showNotes: false,
+	autoPlayMedia: null,
+	autoAnimate: true,
+	autoAnimateEasing: "ease",
+	autoAnimateDuration: 1,
+	autoAnimateUnmatched: true,
+	autoSlide: 0,
+	autoSlideStoppable: true,
+	defaultTiming: null,
+	totalTime: null,
+	mouseWheel: false,
+	previewLinks: false,
+	transition: "slide",
+	transitionSpeed: "default",
+	backgroundTransition: "fade",
+	viewDistance: 3,
+	mobileViewDistance: 2,
+	hideInactiveCursor: true,
+	hideCursorTime: 5e3,
+	view: "slide",
+	scrollProgress: "auto",
+	scrollSnap: "mandatory",
+	scrollActivationWidth: 0,
+	theme: "minimal",
+	themes: [
+		"minimal",
+		"rla",
+		"stack"
+	],
+	colorScheme: "auto",
+	pdfSeparateFragments: true,
+	pdfMaxPagesPerSlide: 1,
+	jumpToSlide: true,
+	search: true,
+	zoom: true,
+	wakeLock: true,
+	selectable: true,
+	lineNumbers: false,
+	autoFit: true,
+	magicMoveDuration: 800,
+	live: {
+		api: "/api",
+		room: null,
+		turnstile: null
+	},
+	drawings: {
+		enabled: true,
+		persist: true,
+		presenterOnly: false,
+		syncAll: true
+	},
+	glossary: DEFAULT_GLOSSARY,
+	reactions: true,
+	qa: true,
+	polls: true,
+	audienceNotes: false,
+	slug: "",
+	badge: false,
+	fonts: [],
+	seoMeta: {}
+};
+function resolveConfig(...layers) {
+	const out = {
+		...DEFAULT_CONFIG,
+		live: { ...DEFAULT_CONFIG.live },
+		drawings: { ...DEFAULT_CONFIG.drawings }
+	};
+	for (const layer of layers) {
+		if (!layer) continue;
+		for (const [key, value] of Object.entries(layer)) {
+			if (value === void 0) continue;
+			if (key === "glossary") out.glossary = glossaryOptions(value, out.glossary);
+			else if ((key === "live" || key === "drawings" || key === "seoMeta") && value && typeof value === "object") out[key] = {
+				...out[key],
+				...value
+			};
+			else out[key] = value;
+		}
+	}
+	const fm = Object.assign({}, ...layers.filter(Boolean));
+	if (typeof fm.aspectRatio === "number" && typeof fm.canvasWidth === "number") {
+		out.width = fm.canvasWidth;
+		out.height = Math.round(fm.canvasWidth / fm.aspectRatio);
+	}
+	return out;
+}
+function str(v) {
+	return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function bool(v, fallback) {
+	return typeof v === "boolean" ? v : fallback;
+}
+function num(v) {
+	return typeof v === "number" && Number.isFinite(v) ? v : typeof v === "string" && v.trim() && Number.isFinite(Number(v)) ? Number(v) : null;
+}
+const COLOR = /^(#|rgb|hsl|oklch|oklab|lab|lch|transparent|[a-z]+$)/i;
+const GRADIENT = /gradient\(/i;
+/** `background: "#fff"`, `background: "/img.png"`, `background: { image, size }`, `background: { component: "aurora", … }`. */
+function resolveBackground(fm) {
+	const raw = fm.background ?? fm.backgroundColor ?? fm.backgroundImage;
+	const base = {
+		color: null,
+		gradient: null,
+		image: null,
+		size: "cover",
+		position: "center",
+		repeat: "no-repeat",
+		opacity: 1,
+		video: null,
+		videoLoop: false,
+		videoMuted: true,
+		iframe: null,
+		iframeInteractive: false,
+		tint: null,
+		component: null,
+		props: {}
+	};
+	let any = false;
+	const apply = (obj) => {
+		if (str(obj.fill) || str(obj.tint)) {
+			base.tint = str(obj.fill) ?? str(obj.tint);
+			any = true;
+		} else if (str(obj.color) && !str(obj.component)) {
+			base.color = str(obj.color);
+			any = true;
+		}
+		if (str(obj.gradient)) {
+			base.gradient = str(obj.gradient);
+			any = true;
+		}
+		if (str(obj.image)) {
+			base.image = str(obj.image);
+			any = true;
+		}
+		if (str(obj.size)) base.size = str(obj.size);
+		if (str(obj.position)) base.position = str(obj.position);
+		if (str(obj.repeat)) base.repeat = str(obj.repeat);
+		if (num(obj.opacity) !== null) base.opacity = num(obj.opacity);
+		if (str(obj.video)) {
+			base.video = str(obj.video);
+			any = true;
+		}
+		base.videoLoop = bool(obj.videoLoop ?? obj.loop, base.videoLoop);
+		base.videoMuted = bool(obj.videoMuted ?? obj.muted, base.videoMuted);
+		if (str(obj.iframe)) {
+			base.iframe = str(obj.iframe);
+			any = true;
+		}
+		base.iframeInteractive = bool(obj.interactive, base.iframeInteractive);
+		if (str(obj.component)) {
+			base.component = str(obj.component);
+			any = true;
+			const { component: _c, fill: _f, tint: _t, ...props } = obj;
+			base.props = props;
+		}
+	};
+	if (typeof raw === "string") {
+		const s = raw.trim();
+		if (GRADIENT.test(s)) base.gradient = s;
+		else if (/\.(mp4|webm|mov|ogv)(\?|$)/i.test(s)) base.video = s;
+		else if (/^(https?:)?\/\/|\/|\.\/|\.(png|jpe?g|gif|webp|svg|avif)(\?|$)/i.test(s) && !COLOR.test(s)) base.image = s;
+		else if (/^[a-z][\w-]*$/i.test(s) && !isCssColorKeyword(s)) base.component = s;
+		else base.color = s;
+		any = true;
+	} else if (raw && typeof raw === "object") apply(raw);
+	apply({
+		color: fm.backgroundColor,
+		gradient: fm.backgroundGradient,
+		image: fm.backgroundImage,
+		size: fm.backgroundSize,
+		position: fm.backgroundPosition,
+		repeat: fm.backgroundRepeat,
+		opacity: fm.backgroundOpacity,
+		video: fm.backgroundVideo,
+		videoLoop: fm.backgroundVideoLoop,
+		videoMuted: fm.backgroundVideoMuted,
+		iframe: fm.backgroundIframe,
+		interactive: fm.backgroundInteractive
+	});
+	return any ? base : null;
+}
+const CSS_COLORS = /* @__PURE__ */ new Set([
+	"black",
+	"white",
+	"red",
+	"green",
+	"blue",
+	"yellow",
+	"orange",
+	"purple",
+	"pink",
+	"gray",
+	"grey",
+	"silver",
+	"gold",
+	"navy",
+	"teal",
+	"aqua",
+	"lime",
+	"maroon",
+	"olive",
+	"fuchsia",
+	"coral",
+	"salmon",
+	"crimson",
+	"indigo",
+	"violet",
+	"cyan",
+	"magenta",
+	"aquamarine",
+	"transparent",
+	"currentcolor",
+	"beige",
+	"ivory",
+	"khaki",
+	"lavender",
+	"linen",
+	"mint",
+	"peach",
+	"plum",
+	"tan",
+	"tomato",
+	"turquoise",
+	"wheat",
+	"azure",
+	"brown",
+	"chocolate",
+	"darkblue",
+	"darkgreen",
+	"darkred",
+	"lightblue",
+	"lightgreen",
+	"orchid",
+	"sienna",
+	"slategray",
+	"snow",
+	"steelblue"
+]);
+function isCssColorKeyword(s) {
+	return CSS_COLORS.has(s.toLowerCase());
+}
+function resolveSlideOptions(fm, config, isFirst) {
+	const state = fm.state;
+	const visibility = str(fm.visibility);
+	const transition = str(fm.transition);
+	const transitionSpeed = str(fm.transitionSpeed);
+	return {
+		layout: str(fm.layout) ?? (isFirst ? "cover" : "default"),
+		className: Array.isArray(fm.class) ? fm.class.join(" ") : str(fm.class) ?? "",
+		hidden: bool(fm.hide, false) || bool(fm.disabled, false) || visibility === "hidden",
+		uncounted: visibility === "uncounted",
+		hideInToc: bool(fm.hideInToc, false),
+		transition,
+		transitionSpeed,
+		backgroundTransition: str(fm.backgroundTransition),
+		autoAnimate: fm.autoAnimate === true || typeof fm.autoAnimate === "object" && fm.autoAnimate !== null,
+		autoAnimateId: str(fm.autoAnimateId) ?? (typeof fm.autoAnimate === "object" && fm.autoAnimate ? str(fm.autoAnimate.id) ?? null : null),
+		autoAnimateRestart: bool(fm.autoAnimateRestart, false),
+		autoSlide: num(fm.autoslide ?? fm.autoSlide),
+		clicks: num(fm.clicks),
+		clicksStart: num(fm.clicksStart) ?? 0,
+		preload: bool(fm.preload, true),
+		timing: num(fm.timing) ?? config.defaultTiming,
+		state: Array.isArray(state) ? state.map(String) : str(state) ? [str(state)] : [],
+		colorScheme: fm.colorScheme === "dark" || fm.colorScheme === "light" ? fm.colorScheme : null,
+		zoom: num(fm.zoom) ?? 1,
+		background: resolveBackground(fm)
+	};
+}
+function columnsOf(slides, config) {
+	const visible = slides.filter((s) => !resolveSlideOptions(s.frontmatter, config, s.index === 0).hidden);
+	const byH = /* @__PURE__ */ new Map();
+	for (const s of visible) {
+		const list = byH.get(s.h) ?? [];
+		list.push(s);
+		byH.set(s.h, list);
+	}
+	return [...byH.entries()].sort((a, b) => a[0] - b[0]).map(([, list], i) => ({
+		h: i,
+		slides: list.sort((a, b) => a.v - b.v)
+	}));
+}
+/** Column and row of the visible slide with this flat index. */
+function fromFlat(columns, flat) {
+	let left = Math.max(0, flat);
+	for (let h = 0; h < columns.length; h++) {
+		const len = columns[h].slides.length;
+		if (left < len) return {
+			h,
+			v: left
+		};
+		left -= len;
+	}
+	const h = Math.max(0, columns.length - 1);
+	return {
+		h,
+		v: Math.max(0, (columns[h]?.slides.length ?? 1) - 1)
+	};
+}
+/** Find a slide by its id (frontmatter `id`, `routeAlias`, or the generated `sN`). */
+function findById(columns, id) {
+	for (const c of columns) for (let v = 0; v < c.slides.length; v++) {
+		const s = c.slides[v];
+		if (s.id === id || s.frontmatter.routeAlias === id) return {
+			h: c.h,
+			v
+		};
+	}
+	return null;
+}
+/** The global a host sets, validated: anything malformed is ignored rather than trusted. */
+function readHostOverride(scope = globalThis) {
+	const raw = scope?.__KADAL_DECK__;
+	if (!raw || typeof raw !== "object") return null;
+	const o = raw;
+	const out = {};
+	if (typeof o.room === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(o.room)) out.room = o.room;
+	if (typeof o.api === "string" && o.api.length > 0) out.api = o.api;
+	if (typeof o.badge === "boolean") out.badge = o.badge;
+	return out;
+}
+/** The config with the host's word laid over it. Returns the same object when there is none. */
+function withHostOverride(config, override) {
+	if (!override || !override.room && !override.api && override.badge === void 0) return config;
+	return {
+		...config,
+		live: {
+			...config.live,
+			...override.room ? { room: override.room } : {},
+			...override.api ? { api: override.api } : {}
+		},
+		...override.badge !== void 0 ? { badge: override.badge } : {}
+	};
+}
+/**
+* The id every host call is keyed by — the room, presenter login, stats, beacons, share links and
+* exports. A published deck's is the room the host assigned; a self-hosted one's is its slug.
+*/
+function roomIdOf(config) {
+	return config.live.room || config.slug || "deck";
+}
+//#endregion
+export { DEFAULT_CONFIG, columnsOf, findById, fromFlat, readHostOverride, resolveBackground, resolveConfig, resolveSlideOptions, roomIdOf, withHostOverride };