@honeydeck/honeydeck 0.1.0

package/src/runtime/navigation.ts

@@ -0,0 +1,211 @@
+import { rememberSlideRoute } from "./lastSlideRoute.ts";
+import type { Route } from "./router.ts";
+import { navigate, serializeRoute } from "./router.ts";
+
+export type NavigationRoute = Route & {
+	view: "slide" | "presenter" | "overview";
+};
+
+export type StepCountGetter = (slideIndex: number) => number;
+
+export type NavigationOptions = {
+	slideCount?: number;
+	getStepCount?: StepCountGetter;
+};
+
+function getSlideCount(options?: NavigationOptions): number {
+	return options?.slideCount ?? Number.POSITIVE_INFINITY;
+}
+
+function getStepCountForSlide(
+	slideIndex: number,
+	options?: NavigationOptions,
+): number {
+	return options?.getStepCount?.(slideIndex) ?? 0;
+}
+
+function normalizeNavigableRoute(
+	route: Route,
+	options?: NavigationOptions,
+): NavigationRoute | null {
+	if (
+		route.view !== "slide" &&
+		route.view !== "presenter" &&
+		route.view !== "overview"
+	) {
+		return null;
+	}
+	const totalSlides = getSlideCount(options);
+	const slide = Math.max(1, Math.min(route.slide, totalSlides));
+	return { ...route, slide } as NavigationRoute;
+}
+
+function withRoutePosition(
+	route: NavigationRoute,
+	slide: number,
+	step: number,
+): Route {
+	return { ...route, slide, step };
+}
+
+export function getRouteUrl(route: Route, baseUrl?: string): string {
+	const url = new URL(baseUrl ?? location.href);
+	url.hash = serializeRoute(route);
+	return url.toString();
+}
+
+export function openUrlInNewTab(url: string): void {
+	const opened = window.open(url, "_blank", "noopener,noreferrer");
+	if (opened) {
+		opened.opener = null;
+	}
+}
+
+export function getPreviousStepRoute(
+	route: Route,
+	options?: NavigationOptions,
+): Route | null {
+	const navigable = normalizeNavigableRoute(route, options);
+	if (!navigable) return null;
+
+	if (navigable.step > 0) {
+		return withRoutePosition(navigable, navigable.slide, navigable.step - 1);
+	}
+
+	if (navigable.slide > 1) {
+		const prevSlide = navigable.slide - 1;
+		const prevSteps = getStepCountForSlide(prevSlide - 1, options);
+		return withRoutePosition(navigable, prevSlide, prevSteps);
+	}
+
+	return null;
+}
+
+export function getNextStepRoute(
+	route: Route,
+	options?: NavigationOptions,
+): Route | null {
+	const navigable = normalizeNavigableRoute(route, options);
+	if (!navigable) return null;
+
+	const totalSlides = getSlideCount(options);
+	const stepCount = getStepCountForSlide(navigable.slide - 1, options);
+
+	if (navigable.step < stepCount) {
+		return withRoutePosition(navigable, navigable.slide, navigable.step + 1);
+	}
+
+	if (navigable.slide < totalSlides) {
+		return withRoutePosition(navigable, navigable.slide + 1, 0);
+	}
+
+	return null;
+}
+
+export function getPreviousSlideRoute(
+	route: Route,
+	options?: NavigationOptions,
+): Route | null {
+	const navigable = normalizeNavigableRoute(route, options);
+	if (!navigable || navigable.slide <= 1) return null;
+	return withRoutePosition(navigable, navigable.slide - 1, 0);
+}
+
+export function getNextSlideRoute(
+	route: Route,
+	options?: NavigationOptions,
+): Route | null {
+	const navigable = normalizeNavigableRoute(route, options);
+	if (!navigable) return null;
+	const totalSlides = getSlideCount(options);
+	if (navigable.slide >= totalSlides) return null;
+	return withRoutePosition(navigable, navigable.slide + 1, 0);
+}
+
+export function getOverviewRoute(
+	route: Route,
+	options?: NavigationOptions,
+): Route | null {
+	const navigable = normalizeNavigableRoute(route, options);
+	if (!navigable) return null;
+	if (navigable.view === "overview") return navigable;
+	return { view: "overview", slide: navigable.slide, step: navigable.step };
+}
+
+export function getSlideRouteFromRoute(
+	route: Route,
+	options?: NavigationOptions,
+): Route | null {
+	const navigable = normalizeNavigableRoute(route, options);
+	if (!navigable) return null;
+	return { view: "slide", slide: navigable.slide, step: navigable.step };
+}
+
+export function getToggleOverviewRoute(
+	route: Route,
+	options?: NavigationOptions,
+): Route | null {
+	if (route.view === "overview") return getSlideRouteFromRoute(route, options);
+	return getOverviewRoute(route, options);
+}
+
+export function getReferenceRoute(): Route {
+	return { view: "kit", slide: 1, step: 0, kitTab: "layouts" };
+}
+
+export function getDocsWebsiteUrl(): string {
+	return "https://honeydeck.dev";
+}
+
+export function navigateTo(route: Route | null): void {
+	if (route) navigate(route);
+}
+
+export function previousStep(route: Route, options?: NavigationOptions): void {
+	navigateTo(getPreviousStepRoute(route, options));
+}
+
+export function nextStep(route: Route, options?: NavigationOptions): void {
+	navigateTo(getNextStepRoute(route, options));
+}
+
+export function previousSlide(route: Route, options?: NavigationOptions): void {
+	navigateTo(getPreviousSlideRoute(route, options));
+}
+
+export function nextSlide(route: Route, options?: NavigationOptions): void {
+	navigateTo(getNextSlideRoute(route, options));
+}
+
+export function openOverview(route: Route, options?: NavigationOptions): void {
+	navigateTo(getOverviewRoute(route, options));
+}
+
+export function closeOverview(route: Route, options?: NavigationOptions): void {
+	navigateTo(getSlideRouteFromRoute(route, options));
+}
+
+export function toggleOverview(
+	route: Route,
+	options?: NavigationOptions,
+): void {
+	navigateTo(getToggleOverviewRoute(route, options));
+}
+
+export function openReference(route: Route): void {
+	if (route.view === "slide" || route.view === "overview") {
+		rememberSlideRoute({ view: "slide", slide: route.slide, step: route.step });
+	}
+	navigate(getReferenceRoute());
+}
+
+export function openDocsWebsite(): void {
+	openUrlInNewTab(getDocsWebsiteUrl());
+}
+
+export function openPresenter(route: Route): void {
+	if (route.view === "kit") return;
+	openUrlInNewTab(
+		getRouteUrl({ view: "presenter", slide: route.slide, step: route.step }),
+	);
+}

package/src/runtime/router.ts

@@ -0,0 +1,157 @@
+/**
+ * Hash-based router for Honeydeck.
+ *
+ * URL format:
+ *   Audience:   /#/slideNumber/stepIndex
+ *   Overview:   /#/overview/slideNumber/stepIndex
+ *   Presenter:  /#/presenter/slideNumber/stepIndex
+ *   Reference:  /#/theme, /#/layouts, /#/components
+ *
+ *   - slideNumber is 1-based
+ *   - stepIndex is 0-based
+ *
+ * Examples:
+ *   /#/1/0              → slide 1, initial state
+ *   /#/1/2              → slide 1, step 2 active
+ *   /#/3/0              → slide 3, initial state
+ *   /#/presenter/2/1    → presenter view, slide 2, step 1
+ *   /#/theme        → runtime reference (theme tab)
+ *   /#/layouts      → runtime reference (layouts tab)
+ *   /#/components   → runtime reference (components tab)
+ */
+
+import { useEffect, useState } from "react";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type KitTab = "theme" | "layouts" | "components";
+
+export type Route = {
+	/** Which view is active. */
+	view: "slide" | "overview" | "presenter" | "kit";
+	/** 1-based slide number (unused / defaults to 1 for reference routes) */
+	slide: number;
+	/** 0-based step index (unused / defaults to 0 for reference routes) */
+	step: number;
+	/** Active tab when view === 'kit' */
+	kitTab?: KitTab;
+};
+
+// ---------------------------------------------------------------------------
+// Pure helpers — no side effects, no browser globals
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a `location.hash` string into a `Route`.
+ *
+ * Handles:
+ *  - `""` or `"#"`              → default slide route
+ *  - `"#/1/0"`                  → { view: 'slide', slide: 1, step: 0 }
+ *  - `"#/overview/2/1"`         → { view: 'overview', slide: 2, step: 1 }
+ *  - `"#/presenter/2/1"`        → { view: 'presenter', slide: 2, step: 1 }
+ *  - `"#/theme"`                → { view: 'kit', kitTab: 'theme', slide: 1, step: 0 }
+ *  - `"#/layouts"`              → { view: 'kit', kitTab: 'layouts', slide: 1, step: 0 }
+ *  - `"#/components"`           → { view: 'kit', kitTab: 'components', slide: 1, step: 0 }
+ *  - `"#/2"`                    → { view: 'slide', slide: 2, step: 0 }
+ *  - NaN / negative values      → clamp to valid range
+ */
+export function parseHash(hash: string): Route {
+	// Strip leading '#' then split on '/'
+	const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+	const parts = raw.split("/").filter(Boolean);
+
+	if (
+		parts[0] === "theme" ||
+		parts[0] === "layouts" ||
+		parts[0] === "components"
+	) {
+		return { view: "kit", slide: 1, step: 0, kitTab: parts[0] };
+	}
+
+	// Overview route: /overview/slide/step
+	if (parts[0] === "overview") {
+		const rawSlide = parseInt(parts[1] ?? "1", 10);
+		const rawStep = parseInt(parts[2] ?? "0", 10);
+		return {
+			view: "overview",
+			slide: Number.isNaN(rawSlide) || rawSlide < 1 ? 1 : rawSlide,
+			step: Number.isNaN(rawStep) || rawStep < 0 ? 0 : rawStep,
+		};
+	}
+
+	// Presenter route: /presenter/slide/step
+	if (parts[0] === "presenter") {
+		const rawSlide = parseInt(parts[1] ?? "1", 10);
+		const rawStep = parseInt(parts[2] ?? "0", 10);
+		return {
+			view: "presenter",
+			slide: Number.isNaN(rawSlide) || rawSlide < 1 ? 1 : rawSlide,
+			step: Number.isNaN(rawStep) || rawStep < 0 ? 0 : rawStep,
+		};
+	}
+
+	// Regular slide route: /slide/step
+	const rawSlide = parseInt(parts[0] ?? "1", 10);
+	const rawStep = parseInt(parts[1] ?? "0", 10);
+	return {
+		view: "slide",
+		slide: Number.isNaN(rawSlide) || rawSlide < 1 ? 1 : rawSlide,
+		step: Number.isNaN(rawStep) || rawStep < 0 ? 0 : rawStep,
+	};
+}
+
+/**
+ * Convert a `Route` into a hash string suitable for `location.hash`.
+ *
+ * @example serializeRoute({ view: 'slide', slide: 2, step: 3 })       → '#/2/3'
+ * @example serializeRoute({ view: 'presenter', slide: 2, step: 3 })  → '#/presenter/2/3'
+ */
+export function serializeRoute(route: Route): string {
+	if (route.view === "kit") {
+		if (route.kitTab === "theme") return "#/theme";
+		if (route.kitTab === "layouts") return "#/layouts";
+		if (route.kitTab === "components") return "#/components";
+		return "#/theme";
+	}
+	if (route.view === "overview") {
+		return `#/overview/${route.slide}/${route.step}`;
+	}
+	if (route.view === "presenter") {
+		return `#/presenter/${route.slide}/${route.step}`;
+	}
+	return `#/${route.slide}/${route.step}`;
+}
+
+// ---------------------------------------------------------------------------
+// Browser-side API
+// ---------------------------------------------------------------------------
+
+/**
+ * Navigate to a route by updating `location.hash`.
+ * Triggers a `hashchange` event picked up by `useRoute()`.
+ */
+export function navigate(route: Route): void {
+	location.hash = serializeRoute(route);
+}
+
+/**
+ * React hook that returns the current route and re-renders on navigation.
+ *
+ * Uses the `hashchange` window event as the reactive signal.
+ * Initial value is parsed from `location.hash` synchronously, so
+ * server-side rendering or test environments without `location` will need
+ * the pure helpers instead.
+ */
+export function useRoute(): Route {
+	const [route, setRoute] = useState<Route>(() => parseHash(location.hash));
+
+	useEffect(() => {
+		const handler = () => setRoute(parseHash(location.hash));
+		window.addEventListener("hashchange", handler);
+		return () => window.removeEventListener("hashchange", handler);
+	}, []);
+
+	return route;
+}

package/src/runtime/slideData.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared slide data for Honeydeck runtime.
+ *
+ * Extracts and exposes all slide metadata from `virtual:honeydeck/slides` in a
+ * single place so that Deck, PresenterView, and OverviewView can all import
+ * from here instead of duplicating the assembly logic.
+ *
+ * Also exports `resolveLayout` — the layout-lookup helper with dev-mode
+ * fallback warning.
+ */
+
+import { config } from "virtual:honeydeck/config";
+import { layoutMap } from "virtual:honeydeck/layouts";
+import * as slideModules from "virtual:honeydeck/slides";
+import type { ComponentType } from "react";
+import { parseAspectRatio } from "./aspectRatio.ts";
+import type { LayoutProps } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Constants — derived from config.aspectRatio (default 16:9 → 1920×1080)
+// ---------------------------------------------------------------------------
+
+const _dimensions = parseAspectRatio(config.aspectRatio);
+export const BASE_WIDTH: number = _dimensions.width;
+export const BASE_HEIGHT: number = _dimensions.height;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SlideData = {
+	/** Stable slide id derived from the virtual module export name. */
+	id: string;
+	/** Compiled slide React component. */
+	Component: ComponentType;
+	/** Number of timeline steps on this slide. */
+	stepCount: number;
+	/** Plain-text content of the extracted h1. */
+	title: string;
+	/** Parsed YAML frontmatter. */
+	frontmatter: Record<string, unknown>;
+	/** Layout name from frontmatter.layout, or 'Default' when absent. */
+	layoutName: string;
+};
+
+// ---------------------------------------------------------------------------
+// Assembly
+// ---------------------------------------------------------------------------
+
+const { slideCount } = slideModules;
+const _allExports = slideModules as unknown as Record<string, unknown>;
+
+function buildSlideData(): SlideData[] {
+	return Array.from({ length: slideCount }, (_, i) => {
+		const Component = _allExports[`Slide${i}`] as ComponentType | undefined;
+		if (!Component) {
+			throw new Error(
+				`[honeydeck] Slide${i} not found in virtual:honeydeck/slides — ` +
+					`deck reports slideCount=${slideCount}. ` +
+					`This is a bug in the virtual module plugin.`,
+			);
+		}
+		return {
+			id: `Slide${i}`,
+			Component,
+			stepCount: (_allExports[`stepCount${i}`] as number | undefined) ?? 0,
+			title: (_allExports[`slideTitle${i}`] as string | undefined) ?? "",
+			frontmatter:
+				(_allExports[`slideFrontmatter${i}`] as
+					| Record<string, unknown>
+					| undefined) ?? {},
+			layoutName:
+				(_allExports[`slideLayout${i}`] as string | undefined) ||
+				(config.defaultLayout as string | undefined) ||
+				"Default",
+		};
+	});
+}
+
+/** All slide data in deck order. Singleton — assembled once at import time. */
+export const slideData: SlideData[] = buildSlideData();
+
+// ---------------------------------------------------------------------------
+// Layout resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up a layout component by name.
+ * Falls back to Default with a console warning in dev when the name isn't
+ * registered. Build/PDF hard-error behavior is enforced when Vite runs in
+ * production mode.
+ */
+export function resolveLayout(
+	layoutName: string,
+): ComponentType<LayoutProps<Record<string, unknown>>> {
+	const availableLayouts = Object.keys(layoutMap);
+	const layout = layoutMap[layoutName];
+	if (layout)
+		return layout as ComponentType<LayoutProps<Record<string, unknown>>>;
+
+	const fallbackName =
+		(config.defaultLayout as string | undefined) || "Default";
+	const fallbackEntry = layoutMap[fallbackName]
+		? { name: fallbackName, Component: layoutMap[fallbackName] }
+		: layoutMap.Default
+			? { name: "Default", Component: layoutMap.Default }
+			: availableLayouts
+					.map((name) => ({ name, Component: layoutMap[name] }))
+					.find((entry) => entry.Component);
+	const fallback = fallbackEntry?.Component;
+
+	if (layoutName) {
+		const message =
+			`Layout "${layoutName}" not found in layout map.\n` +
+			`Available layouts: ${availableLayouts.join(", ") || "(none)"}`;
+
+		const isProduction =
+			(import.meta as unknown as { env?: { PROD?: boolean } }).env?.PROD ??
+			false;
+		if (isProduction) {
+			throw new Error(message);
+		}
+
+		console.warn(
+			`[honeydeck] ⚠️  Layout "${layoutName}" not found. Falling back to ${fallbackEntry?.name ?? "nothing"}. ` +
+				`Available: ${availableLayouts.join(", ") || "(none)"}`,
+		);
+	}
+
+	if (!fallback) {
+		throw new Error(
+			"[honeydeck] No layouts are available in the active layout map.",
+		);
+	}
+
+	return fallback as ComponentType<LayoutProps<Record<string, unknown>>>;
+}