@honeydeck/honeydeck 0.1.0

package/src/runtime/sync.ts

@@ -0,0 +1,267 @@
+/**
+ * BroadcastChannel sync for Honeydeck presenter ↔ audience coordination.
+ *
+ * The presenter window is the **controller** — it sends `navigate` messages
+ * whenever its route changes. Audience windows listen and apply them.
+ *
+ * Late-opening audience tabs send a `sync-request` so the presenter can reply
+ * with a `sync-response` containing the current route immediately.
+ *
+ * ### Message types
+ * - `navigate`              — presenter changed slide/step
+ * - `sync-request`          — audience asks for the current presenter route
+ * - `sync-response`         — presenter replies with the current route
+ * - `presenter-connected`   — a presenter window opened
+ * - `presenter-disconnected`— a presenter window closed
+ *
+ * ### Constraints
+ * - Same-origin, same browser profile only (BroadcastChannel limitation).
+ * - If BroadcastChannel is unavailable, the hook is a no-op.
+ *
+ * ### Usage
+ * ```tsx
+ * // In audience Deck:
+ * useSync({ isPresenter: false });
+ *
+ * // In PresenterView:
+ * useSync({ isPresenter: true, currentSlide: slide, currentStep: step });
+ * ```
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { navigate, parseHash, type Route } from "./router.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SyncNavigateMessage = {
+	type: "navigate";
+	slide: number;
+	step: number;
+};
+
+export type SyncRequestMessage = {
+	type: "sync-request";
+};
+
+export type SyncResponseMessage = {
+	type: "sync-response";
+	slide: number;
+	step: number;
+};
+
+export type SyncPresenceMessage =
+	| { type: "presenter-connected" }
+	| { type: "presenter-disconnected" };
+
+export type SyncMessage =
+	| SyncNavigateMessage
+	| SyncRequestMessage
+	| SyncResponseMessage
+	| SyncPresenceMessage;
+
+export type UseSyncOptions = {
+	/** Whether this hook should connect to BroadcastChannel. */
+	enabled?: boolean;
+	/** True when this window is the presenter (controller). */
+	isPresenter: boolean;
+	/** Current 1-based slide number (required when `isPresenter: true`). */
+	currentSlide?: number;
+	/** Current 0-based step index (required when `isPresenter: true`). */
+	currentStep?: number;
+};
+
+type PresenterRoute = {
+	slide: number;
+	step: number;
+};
+
+const CHANNEL_NAME = "honeydeck";
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+export function createSyncRequestMessage(): SyncRequestMessage {
+	return { type: "sync-request" };
+}
+
+export function createSyncResponseMessage(
+	route: PresenterRoute,
+): SyncResponseMessage {
+	return {
+		type: "sync-response",
+		slide: route.slide,
+		step: route.step,
+	};
+}
+
+export function resolveAudienceRouteFromSyncMessage(
+	currentRoute: Route,
+	message: SyncNavigateMessage | SyncResponseMessage,
+): Route | null {
+	if (currentRoute.view === "kit") return null;
+
+	return {
+		view: currentRoute.view === "overview" ? "overview" : "slide",
+		slide: message.slide,
+		step: message.step,
+	};
+}
+
+function isSyncMessage(value: unknown): value is SyncMessage {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("type" in value)) return false;
+
+	const type = (value as { type?: unknown }).type;
+	if (type === "sync-request") return true;
+	if (type === "presenter-connected") return true;
+	if (type === "presenter-disconnected") return true;
+
+	if (type !== "navigate" && type !== "sync-response") return false;
+
+	const slide = (value as { slide?: unknown }).slide;
+	const step = (value as { step?: unknown }).step;
+	return (
+		typeof slide === "number" &&
+		Number.isFinite(slide) &&
+		typeof step === "number" &&
+		Number.isFinite(step)
+	);
+}
+
+function isRouteSyncMessage(
+	message: SyncMessage,
+): message is SyncNavigateMessage | SyncResponseMessage {
+	return message.type === "navigate" || message.type === "sync-response";
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Bidirectional sync hook.
+ *
+ * @returns `{ presenterConnected }` — true when an audience window has
+ * detected that a presenter window is open on the same channel.
+ */
+export function useSync({
+	enabled = true,
+	isPresenter,
+	currentSlide,
+	currentStep,
+}: UseSyncOptions): { presenterConnected: boolean } {
+	const [presenterConnected, setPresenterConnected] = useState(false);
+	const channelRef = useRef<BroadcastChannel | null>(null);
+	const presenterRouteRef = useRef<PresenterRoute>({
+		slide: currentSlide ?? 1,
+		step: currentStep ?? 0,
+	});
+
+	useEffect(() => {
+		if (!isPresenter) return;
+		if (currentSlide === undefined || currentStep === undefined) return;
+
+		presenterRouteRef.current = {
+			slide: currentSlide,
+			step: currentStep,
+		};
+	}, [currentSlide, currentStep, isPresenter]);
+
+	// ── Channel lifecycle ───────────────────────────────────────────────────
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		// BroadcastChannel may not exist in every environment (e.g. node tests).
+		if (typeof BroadcastChannel === "undefined") return;
+
+		const channel = new BroadcastChannel(CHANNEL_NAME);
+		channelRef.current = channel;
+
+		// Announce presence when presenter opens.
+		if (isPresenter) {
+			channel.postMessage({
+				type: "presenter-connected",
+			} satisfies SyncMessage);
+		}
+
+		channel.addEventListener("message", (e: MessageEvent<unknown>) => {
+			if (!isSyncMessage(e.data)) return;
+
+			const msg = e.data;
+
+			if (isPresenter) {
+				// Presenter is controller. It only answers sync requests.
+				if (msg.type === "sync-request") {
+					channel.postMessage(
+						createSyncResponseMessage(
+							presenterRouteRef.current,
+						) satisfies SyncMessage,
+					);
+				}
+				return;
+			}
+
+			if (msg.type === "presenter-disconnected") {
+				setPresenterConnected(false);
+				return;
+			}
+
+			if (msg.type === "presenter-connected") {
+				setPresenterConnected(true);
+				return;
+			}
+
+			if (isRouteSyncMessage(msg)) {
+				setPresenterConnected(true);
+				const currentRoute = parseHash(location.hash);
+				const nextRoute = resolveAudienceRouteFromSyncMessage(
+					currentRoute,
+					msg,
+				);
+				if (nextRoute) {
+					navigate(nextRoute);
+				}
+			}
+		});
+
+		if (!isPresenter) {
+			channel.postMessage(createSyncRequestMessage() satisfies SyncMessage);
+		}
+
+		return () => {
+			if (isPresenter) {
+				channel.postMessage({
+					type: "presenter-disconnected",
+				} satisfies SyncMessage);
+			}
+			channel.close();
+			channelRef.current = null;
+		};
+	}, [enabled, isPresenter]);
+
+	// ── Presenter: broadcast navigation changes ─────────────────────────────
+
+	useEffect(() => {
+		if (!isPresenter) return;
+		if (currentSlide === undefined || currentStep === undefined) return;
+
+		presenterRouteRef.current = {
+			slide: currentSlide,
+			step: currentStep,
+		};
+
+		if (!enabled) return;
+
+		channelRef.current?.postMessage({
+			type: "navigate",
+			slide: currentSlide,
+			step: currentStep,
+		} satisfies SyncMessage);
+	}, [enabled, isPresenter, currentSlide, currentStep]);
+
+	return { presenterConnected };
+}

package/src/runtime/types.ts

@@ -0,0 +1,182 @@
+/**
+ * Core type definitions for Honeydeck layouts and reference documentation.
+ *
+ * These types are exported from `@honeydeck/honeydeck/types` for use by kit and layout authors.
+ *
+ * @example
+ * ```ts
+ * import type { LayoutProps, LayoutMap, LayoutDemo } from '@honeydeck/honeydeck/types'
+ *
+ * type CoverFrontmatter = { author?: string }
+ *
+ * export default function CoverLayout({
+ *   title, children, frontmatter
+ * }: LayoutProps<CoverFrontmatter>) { ... }
+ *
+ * export const demo: LayoutDemo<CoverFrontmatter> = {
+ *   mdx: '---\nlayout: Cover\nauthor: Hendrik\n---\n\n# My Talk',
+ * }
+ * ```
+ */
+
+import type { ComponentType, ReactNode } from "react";
+
+// ---------------------------------------------------------------------------
+// LayoutProps
+// ---------------------------------------------------------------------------
+
+/**
+ * Props passed to every layout component.
+ *
+ * The generic parameter `F` types the layout-specific frontmatter fields
+ * (e.g. `author`, `date` for a Cover layout). This enables a future
+ * language server to provide autocomplete for layout-specific frontmatter.
+ *
+ * @example
+ * ```tsx
+ * type CoverFrontmatter = { author?: string }
+ *
+ * export default function CoverLayout({
+ *   title, children, frontmatter,
+ * }: LayoutProps<CoverFrontmatter>) {
+ *   return (
+ *     <div>
+ *       <h1>{title}</h1>
+ *       {children}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export type LayoutProps<
+	F extends Record<string, unknown> = Record<string, unknown>,
+> = {
+	/**
+	 * Text content of the first `h1` in the slide, extracted at build time.
+	 * `null` when the slide has no h1.
+	 */
+	title: ReactNode | null;
+
+	/**
+	 * Slide body — everything after the h1 has been removed.
+	 * This is what most layouts render as the main content area.
+	 */
+	children: ReactNode;
+
+	/**
+	 * Full, unmodified slide content including the original h1.
+	 * Useful for layouts that want to render the slide in one piece.
+	 * Phase 3: same as `children` (improvement planned for Phase 8).
+	 */
+	rawChildren: ReactNode;
+
+	/**
+	 * Parsed slide-level frontmatter fields (YAML block at top of the slide).
+	 */
+	frontmatter: F;
+};
+
+// ---------------------------------------------------------------------------
+// LayoutMap
+// ---------------------------------------------------------------------------
+
+/**
+ * A map of layout names to layout components.
+ *
+ * Used as the value of the `layouts:` frontmatter property.
+ *
+ * @example
+ * ```ts
+ * // layouts/index.ts
+ * import companyLayouts from '@company/honeydeck-kit-brand/layouts'
+ * import { MyCustomCover } from './Cover'
+ *
+ * export default {
+ *   ...companyLayouts,
+ *   Cover: MyCustomCover,
+ * } satisfies LayoutMap
+ * ```
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Layout maps intentionally hold heterogeneous layout components with layout-specific frontmatter.
+export type LayoutMap = Record<string, ComponentType<LayoutProps<any>>>;
+
+// ---------------------------------------------------------------------------
+// LayoutDemo
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional demo data exported from a layout component for the docs reference page.
+ *
+ * When exported as `demo` from a layout module, Honeydeck renders a live preview
+ * of the layout on `/#/layouts` using this data.
+ *
+ * @example
+ * ```ts
+ * export const demo: LayoutDemo<CoverFrontmatter> = {
+ *   mdx: '---\nlayout: Cover\nauthor: Hendrik\n---\n\n# Welcome to My Talk',
+ * }
+ * ```
+ */
+export type LayoutDemo<
+	F extends Record<string, unknown> = Record<string, unknown>,
+> = {
+	/** MDX source used for both the live preview and copyable snippet. */
+	mdx: string;
+} & (F extends Record<string, unknown> ? unknown : never);
+
+export type CompiledLayoutDemo = LayoutDemo & {
+	/** Compiled MDX component for the demo slide body. */
+	Component: ComponentType;
+	/** Number of timeline steps discovered in the demo MDX. */
+	stepCount: number;
+	/** Plain-text content of the first h1 in the demo MDX. */
+	title: string;
+	/** Parsed YAML frontmatter from the demo MDX. */
+	frontmatter: Record<string, unknown>;
+	/** Layout selected by demo frontmatter, or an empty string for the card layout. */
+	layoutName: string;
+};
+
+export type LayoutPropDoc = {
+	/** Frontmatter property name as written in MDX. */
+	name: string;
+	/** TypeScript-style type label. */
+	type: string;
+	/** Whether the frontmatter property is required. */
+	required: boolean;
+	/** Human-readable description from the layout's type comments. */
+	description: string;
+};
+
+// ---------------------------------------------------------------------------
+// ComponentDoc
+// ---------------------------------------------------------------------------
+
+/**
+ * Documentation for one public component prop, extracted from the component's
+ * exported props type.
+ */
+export type ComponentPropDoc = {
+	/** Prop name */
+	name: string;
+	/** TypeScript type text */
+	type: string;
+	/** Whether the prop is required */
+	required: boolean;
+	/** JSDoc description from the prop field */
+	description: string;
+	/** Default value inferred from the component parameter destructuring */
+	defaultValue?: string;
+};
+
+/**
+ * Generated docs entry for one public built-in component.
+ */
+export type ComponentDoc = {
+	/** Compiled Markdown/MDX from the component's exported JSDoc comment */
+	Component: ComponentType;
+	/** Raw Markdown source, useful for tooling and tests */
+	markdown: string;
+	/** Props extracted from the component's exported props type */
+	props: ComponentPropDoc[];
+};

package/src/runtime/useKeyboardNav.ts

@@ -0,0 +1,138 @@
+import { useEffect, useRef } from "react";
+import { isEditableKeyboardTarget } from "./keyboardTarget.ts";
+import {
+	nextSlide,
+	nextStep,
+	openPresenter,
+	previousSlide,
+	previousStep,
+	toggleOverview,
+} from "./navigation.ts";
+import type { Route } from "./router.ts";
+import { parseHash } from "./router.ts";
+
+export type UseKeyboardNavOptions = {
+	/** Whether this hook should register keyboard navigation. */
+	enabled?: boolean;
+	/** Total number of slides in the deck. */
+	slideCount: number;
+	/** Returns the total step count for a given 0-based slide index. */
+	getStepCount: (slideIndex: number) => number;
+	/** Called when the user presses `o` or `Escape` while in overview. */
+	onToggleOverview?: () => void;
+	/** Whether overview mode is currently active. */
+	isOverview?: boolean;
+};
+
+export function useKeyboardNav({
+	enabled = true,
+	slideCount,
+	getStepCount,
+	onToggleOverview,
+	isOverview,
+}: UseKeyboardNavOptions): void {
+	const slideCountRef = useRef(slideCount);
+	slideCountRef.current = slideCount;
+
+	const getStepCountRef = useRef(getStepCount);
+	getStepCountRef.current = getStepCount;
+
+	const onToggleOverviewRef = useRef(onToggleOverview);
+	onToggleOverviewRef.current = onToggleOverview;
+
+	const isOverviewRef = useRef(isOverview ?? false);
+	isOverviewRef.current = isOverview ?? false;
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		const handler = (e: KeyboardEvent) => {
+			if (isEditableKeyboardTarget(e.target)) return;
+
+			const route: Route = parseHash(location.hash);
+			if (route.view === "kit") return;
+
+			const total = slideCountRef.current;
+			const options = {
+				slideCount: total,
+				getStepCount: getStepCountRef.current,
+			};
+			const inOverview = isOverviewRef.current;
+
+			switch (e.key) {
+				case "ArrowRight":
+				case "d": {
+					e.preventDefault();
+					if (!inOverview) nextStep(route, options);
+					break;
+				}
+
+				case "ArrowLeft":
+				case "a": {
+					e.preventDefault();
+					if (!inOverview) previousStep(route, options);
+					break;
+				}
+
+				case "ArrowDown":
+				case "s": {
+					e.preventDefault();
+					if (!inOverview) nextSlide(route, { slideCount: total });
+					break;
+				}
+
+				case "ArrowUp":
+				case "w": {
+					e.preventDefault();
+					if (!inOverview) previousSlide(route);
+					break;
+				}
+
+				case "o": {
+					e.preventDefault();
+					if (onToggleOverviewRef.current) {
+						onToggleOverviewRef.current();
+					} else {
+						toggleOverview(route);
+					}
+					break;
+				}
+
+				case "p": {
+					if (route.view !== "presenter") {
+						e.preventDefault();
+						openPresenter(route);
+					}
+					break;
+				}
+
+				case "f": {
+					e.preventDefault();
+					if (document.fullscreenElement) {
+						document.exitFullscreen();
+					} else {
+						document.documentElement.requestFullscreen().catch(() => {
+							// Fullscreen may be blocked (e.g. in iframes).
+						});
+					}
+					break;
+				}
+
+				case "Escape": {
+					if (isOverviewRef.current) {
+						e.preventDefault();
+						if (onToggleOverviewRef.current) {
+							onToggleOverviewRef.current();
+						} else {
+							toggleOverview(route);
+						}
+					}
+					break;
+				}
+			}
+		};
+
+		window.addEventListener("keydown", handler);
+		return () => window.removeEventListener("keydown", handler);
+	}, [enabled]);
+}