@honeydeck/honeydeck 0.1.0

package/src/runtime/components/Notes.tsx

@@ -0,0 +1,171 @@
+/**
+ * Notes component + context for Honeydeck presenter mode.
+ *
+ * `<Notes>` always renders **nothing** in the DOM — it is purely a vehicle
+ * for surfacing speaker notes to the PresenterView.
+ *
+ * ### How it works
+ *
+ * 1. `NotesContext` provides a `setNotes` callback.
+ * 2. `<PresenterView>` wraps the current slide preview in
+ *    `<NotesContext.Provider value={{ setNotes }}>`.
+ * 3. When a slide containing `<Notes>` renders inside that tree, the Notes
+ *    component fires `useEffect` → calls `setNotes(children)`.
+ * 4. PresenterView reads the collected notes from its own state.
+ *
+ * In audience view (no NotesContext), `<Notes>` simply renders null and the
+ * effect is a no-op.
+ *
+ * ### Authoring
+ * ```mdx
+ * import { Notes } from '@honeydeck/honeydeck'
+ *
+ * # My Slide
+ *
+ * <Notes>
+ *   Remember to demo the sparkle button here!
+ * </Notes>
+ * ```
+ */
+
+import {
+	createContext,
+	isValidElement,
+	type ReactNode,
+	useContext,
+	useEffect,
+	useRef,
+} from "react";
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+export type NotesContextValue = {
+	/** Called by `<Notes>` to push its content into the presenter view. */
+	setNotes: (content: ReactNode) => void;
+};
+
+/**
+ * Provided by PresenterView around the current slide preview.
+ * `null` when rendering in audience view — Notes is a no-op in that case.
+ */
+export const NotesContext = createContext<NotesContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export type NotesProps = {
+	children?: ReactNode;
+};
+
+export function getNotesSignature(node: ReactNode): string {
+	if (node == null || typeof node === "boolean") return "empty";
+	if (
+		typeof node === "string" ||
+		typeof node === "number" ||
+		typeof node === "bigint"
+	) {
+		return `${typeof node}:${String(node)}`;
+	}
+
+	if (Array.isArray(node)) {
+		return `array:[${node.map((child) => getNotesSignature(child)).join(",")}]`;
+	}
+
+	if (isValidElement(node)) {
+		const props = node.props as Record<string, unknown> & {
+			children?: ReactNode;
+		};
+		const propSignature = Object.entries(props)
+			.filter(([key]) => key !== "children")
+			.filter(([, value]) => value == null || isPrimitive(value))
+			.map(([key, value]) => `${key}:${String(value)}`)
+			.sort()
+			.join(",");
+
+		return [
+			"element",
+			getElementTypeSignature(node.type),
+			node.key ?? "",
+			propSignature,
+			getNotesSignature(props.children),
+		].join(":");
+	}
+
+	if (isIterableReactNode(node)) {
+		return `iterable:[${Array.from(node)
+			.map((child) => getNotesSignature(child))
+			.join(",")}]`;
+	}
+
+	return typeof node;
+}
+
+/**
+ * Speaker notes — renders nothing in audience view.
+ * Content is collected via `NotesContext` for display in PresenterView.
+ *
+ * Notes render nothing in audience view, overview thumbnails, and normal PDF
+ * output. Markdown inside `<Notes>` is rendered as formatted speaker notes in
+ * presenter mode, so use notes for delivery cues, demo reminders, and
+ * presenter-only context.
+ *
+ * ```mdx
+ * import { Notes } from '@honeydeck/honeydeck'
+ *
+ * <Notes>
+ *   # Demo cue
+ *
+ *   - Demo the interactive component.
+ *   - Mention PDF export.
+ * </Notes>
+ * ```
+ */
+export function Notes({ children }: NotesProps) {
+	const ctx = useContext(NotesContext);
+	const setNotes = ctx?.setNotes;
+	const previousSignatureRef = useRef<string | null>(null);
+
+	useEffect(() => {
+		if (!setNotes) return;
+		const signature = getNotesSignature(children);
+		if (previousSignatureRef.current === signature) return;
+		previousSignatureRef.current = signature;
+		setNotes(children ?? null);
+	}, [children, setNotes]);
+
+	useEffect(() => {
+		return () => {
+			previousSignatureRef.current = null;
+			setNotes?.(null);
+		};
+	}, [setNotes]);
+
+	return null;
+}
+
+function isPrimitive(value: unknown): boolean {
+	return (
+		value == null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean" ||
+		typeof value === "bigint"
+	);
+}
+
+function getElementTypeSignature(type: unknown): string {
+	if (typeof type === "string") return type;
+	if (typeof type === "function") {
+		const component = type as { displayName?: string; name?: string };
+		return component.displayName ?? component.name ?? "fn";
+	}
+	if (typeof type === "symbol") return type.description ?? String(type);
+	return String(type);
+}
+
+function isIterableReactNode(node: ReactNode): node is Iterable<ReactNode> {
+	return typeof node === "object" && node != null && Symbol.iterator in node;
+}

package/src/runtime/components/Reveal.tsx

@@ -0,0 +1,82 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useTimeline } from "../TimelineContext.tsx";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type RevealProps = {
+	/**
+	 * The step index at which this content becomes visible.
+	 * Injected by the remark step-numbering plugin; defaults to 1.
+	 */
+	at?: number;
+	/**
+	 * Wrapper element. Injected by the compiler from MDX context:
+	 * flow/block reveals use `div`, text/inline reveals use `span`.
+	 */
+	as?: "div" | "span";
+	/** Additional CSS class for custom transition overrides. */
+	className?: string;
+	children?: ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * Timeline-driven reveal component for progressive slide content.
+ *
+ * Content appears when the slide's current step reaches `at`. Before that it
+ * is invisible while still occupying layout space, so reveals do not cause
+ * nearby content to jump around.
+ *
+ * Reveals are cumulative: once visible, they stay visible as the presenter
+ * advances. The default transition is a simple opacity fade.
+ *
+ * ```mdx
+ * import { Reveal } from '@honeydeck/honeydeck'
+ *
+ * Visible from the start.
+ *
+ * <Reveal>This appears at step 1.</Reveal>
+ *
+ * <Reveal>This appears at step 2.</Reveal>
+ * ```
+ *
+ * Honeydeck normally injects `at` during MDX compilation. It also injects `as`
+ * from the MDX context so block reveals render as `div` and inline reveals
+ * render as `span`.
+ */
+export function Reveal({
+	as: Component = "div",
+	at = 1,
+	className = "",
+	children,
+}: RevealProps) {
+	const { stepIndex, showFutureSteps, futureStepOpacity } = useTimeline();
+	const visible = stepIndex >= at;
+	const previewFuture = !visible && showFutureSteps;
+
+	const style: CSSProperties = {
+		display: Component === "span" ? "inline" : "block",
+		visibility: visible || previewFuture ? "visible" : "hidden",
+		opacity: visible ? 1 : previewFuture ? futureStepOpacity : 0,
+		transition: "opacity 300ms ease",
+	};
+
+	return (
+		<Component
+			className={[
+				"honeydeck-reveal mb-[0.75em] text-[length:var(--honeydeck-font-size-body)] leading-[1.6] [&>:last-child]:mb-0",
+				className,
+			]
+				.filter(Boolean)
+				.join(" ")}
+			style={style}
+		>
+			{children}
+		</Component>
+	);
+}

package/src/runtime/components/RevealGroup.tsx

@@ -0,0 +1,193 @@
+import {
+	Children,
+	type CSSProperties,
+	cloneElement,
+	isValidElement,
+	type Key,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+import { useTimeline } from "../TimelineContext.tsx";
+import { Reveal } from "./Reveal.tsx";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type RevealGroupProps = {
+	/**
+	 * The step index for the first child. Subsequent children increment by 1.
+	 * Injected by the remark step-numbering plugin; defaults to 1.
+	 */
+	at?: number;
+	/**
+	 * Internal compiler-provided absolute steps for each direct reveal target.
+	 * This lets nested timeline entries create gaps before later group targets.
+	 */
+	targetStepsJson?: string;
+	children?: ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type ElementWithCommonProps = ReactElement<{
+	children?: ReactNode;
+	className?: string;
+	style?: CSSProperties;
+}>;
+
+function isMeaningfulReactChild(child: ReactNode): boolean {
+	return typeof child === "string" ? child.trim().length > 0 : child !== null;
+}
+
+function toMeaningfulArray(children: ReactNode): ReactNode[] {
+	return Children.toArray(children).filter(isMeaningfulReactChild);
+}
+
+function isListElement(child: ReactNode): child is ElementWithCommonProps {
+	return (
+		isValidElement(child) &&
+		typeof child.type === "string" &&
+		(child.type === "ul" || child.type === "ol")
+	);
+}
+
+function isElementWithCommonProps(
+	child: ReactNode,
+): child is ElementWithCommonProps {
+	return isValidElement(child);
+}
+
+function childKey(child: ReactNode, fallback: string): Key {
+	return isValidElement(child) && child.key != null ? child.key : fallback;
+}
+
+function revealStyle(
+	stepIndex: number,
+	at: number,
+	showFutureSteps: boolean,
+	futureStepOpacity: number,
+): CSSProperties {
+	const visible = stepIndex >= at;
+	const previewFuture = !visible && showFutureSteps;
+
+	return {
+		visibility: visible || previewFuture ? "visible" : "hidden",
+		opacity: visible ? 1 : previewFuture ? futureStepOpacity : 0,
+		transition: "opacity 300ms ease",
+	};
+}
+
+function parseTargetSteps(targetStepsJson: string | undefined): number[] {
+	if (!targetStepsJson) return [];
+
+	try {
+		const parsed = JSON.parse(targetStepsJson) as unknown;
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((value): value is number => typeof value === "number");
+	} catch {
+		return [];
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * Reveals each meaningful direct child as a separate timeline step.
+ *
+ * Use `RevealGroup` when a short sequence should appear one item at a time.
+ * Direct Markdown lists are preserved as lists, while each list item gets its
+ * own reveal step.
+ *
+ * ```mdx
+ * import { RevealGroup } from '@honeydeck/honeydeck'
+ *
+ * <RevealGroup>
+ *   - First point
+ *   - Second point
+ *   - Third point
+ * </RevealGroup>
+ * ```
+ *
+ * Honeydeck assigns the starting `at` value during MDX compilation and advances
+ * the slide step counter by the number of reveal targets. Nested timeline
+ * entries can provide `targetStepsJson` so later group items keep the correct
+ * absolute step positions.
+ */
+export function RevealGroup({
+	at = 1,
+	targetStepsJson,
+	children,
+}: RevealGroupProps) {
+	const { stepIndex, showFutureSteps, futureStepOpacity } = useTimeline();
+	const revealTargets = toMeaningfulArray(children);
+	const targetSteps = parseTargetSteps(targetStepsJson);
+	let targetIndex = 0;
+	let nextAt = at;
+
+	function nextTargetAt(): number {
+		const explicitAt = targetSteps[targetIndex];
+		targetIndex++;
+
+		if (explicitAt !== undefined) {
+			nextAt = Math.max(nextAt, explicitAt + 1);
+			return explicitAt;
+		}
+
+		const fallbackAt = nextAt;
+		nextAt++;
+		return fallbackAt;
+	}
+
+	return (
+		<>
+			{revealTargets.map((child, _index) => {
+				if (isListElement(child)) {
+					const listItems = toMeaningfulArray(child.props.children);
+					const listKey = childKey(child, `reveal-list-${at}-${targetIndex}`);
+
+					return cloneElement(child, {
+						key: listKey,
+						children: listItems.map((listItem) => {
+							const itemAt = nextTargetAt();
+							const itemKey = childKey(listItem, `reveal-item-${itemAt}`);
+
+							if (!isElementWithCommonProps(listItem)) {
+								return (
+									<Reveal key={itemKey} at={itemAt}>
+										{listItem}
+									</Reveal>
+								);
+							}
+
+							return cloneElement(listItem, {
+								key: itemKey,
+								style: {
+									...listItem.props.style,
+									...revealStyle(
+										stepIndex,
+										itemAt,
+										showFutureSteps,
+										futureStepOpacity,
+									),
+								},
+							});
+						}),
+					});
+				}
+
+				const childAt = nextTargetAt();
+
+				return (
+					<Reveal key={childKey(child, `reveal-child-${childAt}`)} at={childAt}>
+						{child}
+					</Reveal>
+				);
+			})}
+		</>
+	);
+}