@honeydeck/honeydeck 0.4.0 → 0.6.0

package/src/runtime/components/MagicCodeBlock.tsx

@@ -0,0 +1,223 @@
+import type { KeyedTokensInfo } from "@shikijs/magic-move/core";
+import { ShikiMagicMovePrecompiled } from "@shikijs/magic-move/react";
+import { useEffect, useMemo, useState } from "react";
+import { useEffectiveColorMode } from "../EffectiveColorModeContext.tsx";
+import { useSlideScale } from "../SlideScaleContext.tsx";
+import { useTimeline } from "../TimelineContext.tsx";
+import { CodeBlock } from "./CodeBlock.tsx";
+import { parseJsonProp, type StepGroup } from "./CodeBlockShared.ts";
+
+type HoneydeckMagicCodeBlockProps = {
+	/** JSON-encoded unique build-time Shiki Magic Move token states for light mode. */
+	lightTokenStatesJson: string;
+	/** JSON-encoded unique build-time Shiki Magic Move token states for dark mode. */
+	darkTokenStatesJson: string;
+	/** JSON-encoded indexes from Magic Code timeline states to unique token states. */
+	tokenStateIndexesJson: string;
+	/** JSON-encoded StepGroup[] aligned to the Magic Code timeline states. */
+	stepGroupsJson: string;
+	/** JSON-encoded source strings aligned to the unique token states. */
+	sourcesJson: string;
+	/** 1-based timeline step where Magic Code state 1 activates. */
+	startAt: number;
+	/** Magic Move animation duration in milliseconds. */
+	duration: number;
+};
+
+type MagicToken = KeyedTokensInfo["tokens"][number];
+
+export function getActiveCodeStateIndex(
+	stateCount: number,
+	stepIndex: number,
+	startAt: number,
+): number {
+	if (stateCount <= 1) return 0;
+	if (startAt > 0 && stepIndex >= startAt) {
+		return Math.min(stepIndex - startAt + 1, stateCount - 1);
+	}
+	return 0;
+}
+
+const MAGIC_CODE_TOKEN_OPACITY_VAR = "--honeydeck-magic-code-token-opacity";
+
+function withMagicCodeTokenOpacity(
+	token: MagicToken,
+	opacity: string,
+): MagicToken {
+	return {
+		...token,
+		htmlStyle: {
+			...token.htmlStyle,
+			[MAGIC_CODE_TOKEN_OPACITY_VAR]: opacity,
+		},
+	};
+}
+
+export function applyMagicCodeDimming(
+	step: KeyedTokensInfo,
+	group: StepGroup | undefined,
+): KeyedTokensInfo {
+	let lineNumber = 1;
+	return {
+		...step,
+		tokens: step.tokens.map((token) => {
+			if (token.content === "\n") {
+				lineNumber++;
+				return token;
+			}
+
+			const opacity =
+				!group || group === "all" || group.includes(lineNumber)
+					? "1"
+					: "var(--honeydeck-code-line-dim-opacity)";
+			return withMagicCodeTokenOpacity(token, opacity);
+		}),
+	};
+}
+
+function applyMagicCodeStepDimming(
+	steps: KeyedTokensInfo[],
+	groups: StepGroup[],
+): KeyedTokensInfo[] {
+	return steps.map((step, index) => applyMagicCodeDimming(step, groups[index]));
+}
+
+export function isPdfExportRender(): boolean {
+	if (typeof window === "undefined") return false;
+
+	const params = new URLSearchParams(window.location.search);
+	return params.has("honeydeckPdfRender");
+}
+
+export function getMagicCodeTransitionOptions(
+	duration: number,
+	slideScale: number,
+	animate = true,
+) {
+	return {
+		duration,
+		lineNumbers: false,
+		animateContainer: animate,
+		easing: "ease-in",
+		delayMove: 0,
+		delayEnter: 0,
+		delayLeave: 0,
+		delayContainer: 0,
+		// Honeydeck scales slides with CSS transforms; Shiki needs that scale so
+		// measured viewport pixels map back to slide-local CSS pixels.
+		globalScale: slideScale > 0 ? slideScale : 1,
+	};
+}
+
+/** Renders a build-time precompiled Shiki Magic Move code block. */
+export function HoneydeckMagicCodeBlock({
+	lightTokenStatesJson,
+	darkTokenStatesJson,
+	tokenStateIndexesJson,
+	stepGroupsJson,
+	sourcesJson,
+	startAt,
+	duration,
+}: HoneydeckMagicCodeBlockProps) {
+	const { stepIndex } = useTimeline();
+	const slideScale = useSlideScale();
+	const colorMode = useEffectiveColorMode();
+	const isPdfExport = isPdfExportRender();
+	const [isBaselineReady, setIsBaselineReady] = useState(isPdfExport);
+
+	useEffect(() => {
+		if (isPdfExport) {
+			setIsBaselineReady(true);
+			return;
+		}
+
+		let firstFrame = 0;
+		let secondFrame = 0;
+		firstFrame = window.requestAnimationFrame(() => {
+			secondFrame = window.requestAnimationFrame(() =>
+				setIsBaselineReady(true),
+			);
+		});
+
+		return () => {
+			window.cancelAnimationFrame(firstFrame);
+			window.cancelAnimationFrame(secondFrame);
+		};
+	}, [isPdfExport]);
+
+	const tokenStateIndexes = useMemo(
+		() =>
+			parseJsonProp<number[]>(
+				tokenStateIndexesJson,
+				[],
+				"tokenStateIndexesJson",
+			),
+		[tokenStateIndexesJson],
+	);
+	const stepGroups = useMemo(
+		() => parseJsonProp<StepGroup[]>(stepGroupsJson, [], "stepGroupsJson"),
+		[stepGroupsJson],
+	);
+	const sources = useMemo(
+		() => parseJsonProp<string[]>(sourcesJson, [], "sourcesJson"),
+		[sourcesJson],
+	);
+	const tokenStates = useMemo(
+		() =>
+			parseJsonProp<KeyedTokensInfo[]>(
+				colorMode === "dark" ? darkTokenStatesJson : lightTokenStatesJson,
+				[],
+				colorMode === "dark" ? "darkTokenStatesJson" : "lightTokenStatesJson",
+			),
+		[colorMode, darkTokenStatesJson, lightTokenStatesJson],
+	);
+
+	const rawSteps = useMemo(
+		() =>
+			tokenStateIndexes.flatMap((index) => {
+				const state = tokenStates[index];
+				return state ? [state] : [];
+			}),
+		[tokenStateIndexes, tokenStates],
+	);
+	const dimmedSteps = useMemo(
+		() => applyMagicCodeStepDimming(rawSteps, stepGroups),
+		[rawSteps, stepGroups],
+	);
+	const activeStateIndex = getActiveCodeStateIndex(
+		dimmedSteps.length,
+		stepIndex,
+		startAt,
+	);
+	const [renderedStateIndex, setRenderedStateIndex] =
+		useState(activeStateIndex);
+
+	useEffect(() => {
+		if (!isBaselineReady) return;
+		setRenderedStateIndex(activeStateIndex);
+	}, [activeStateIndex, isBaselineReady]);
+
+	const visibleStateIndex = Math.min(
+		renderedStateIndex,
+		Math.max(0, dimmedSteps.length - 1),
+	);
+	const source =
+		sources[tokenStateIndexes[visibleStateIndex] ?? visibleStateIndex];
+	const transitionOptions = useMemo(
+		() => getMagicCodeTransitionOptions(duration, slideScale, !isPdfExport),
+		[duration, isPdfExport, slideScale],
+	);
+
+	if (dimmedSteps.length === 0) return null;
+
+	return (
+		<CodeBlock source={source} className="honeydeck-magic-code-block">
+			<ShikiMagicMovePrecompiled
+				steps={dimmedSteps}
+				step={visibleStateIndex}
+				animate={!isPdfExport}
+				options={transitionOptions}
+			/>
+		</CodeBlock>
+	);
+}

package/src/runtime/components/NavBar.tsx

@@ -13,7 +13,7 @@
  * - Overview grid toggle
  * - Layouts reference
  * - Docs website (opens new window)
- * - Presenter mode (opens new window)
+ * - Presenter mode (opens current tab)
  * - Fullscreen toggle
  * - Mobile slide text selection toggle
  * - Color mode cycle (system → light → dark → system)

package/src/runtime/components/NormalCodeBlock.tsx

@@ -0,0 +1,128 @@
+import { useMemo } from "react";
+import { useTimeline } from "../TimelineContext.tsx";
+import { CodeBlock } from "./CodeBlock.tsx";
+import { parseJsonProp, type StepGroup } from "./CodeBlockShared.ts";
+
+type HoneydeckCodeBlockProps = {
+	/** Full shiki HTML output (includes the `<pre>` element). */
+	html: string;
+	/** JSON-encoded StepGroup[] — empty array = no step-through. */
+	stepsJson: string;
+	/** 1-based timeline step where group 1 activates (0 = no step-through). */
+	startAt: number;
+	/** Original fenced code text copied by the hover/focus copy control. */
+	source?: string;
+};
+
+const DATA_DIM_ATTR = /\sdata-dim=(["'])1\1/g;
+const DATA_HIGHLIGHT_ATTR = /\sdata-highlight=(["'])1\1/g;
+const LINE_SPAN = /<span\b([^>]*)>/g;
+const LINE_CLASS = /\bclass=(["'])[^"']*\bline\b[^"']*\1/;
+const DATA_LINE = /\bdata-line=(["'])(\d+)\1/;
+const STYLE_ATTR = /\sstyle=(["'])(.*?)\1/g;
+const DIM_STYLE_DECL = "opacity: var(--honeydeck-code-line-dim-opacity);";
+
+function removeDimStyle(html: string): string {
+	return html.replace(STYLE_ATTR, (match, quote: string, style: string) => {
+		if (!style.includes(DIM_STYLE_DECL)) return match;
+
+		const cleanedStyle = style
+			.replace(DIM_STYLE_DECL, "")
+			.replace(/\s{2,}/g, " ")
+			.trim();
+
+		return cleanedStyle ? ` style=${quote}${cleanedStyle}${quote}` : "";
+	});
+}
+
+function addHighlightAttributes(attrs: string): string {
+	return `${attrs} data-highlight="1"`;
+}
+
+function addDimAttributes(attrs: string): string {
+	if (attrs.includes(DIM_STYLE_DECL)) return `${attrs} data-dim="1"`;
+
+	const withStyle = attrs.replace(
+		STYLE_ATTR,
+		(_match, quote: string, style: string) =>
+			` style=${quote}${style.trim()}${style.trim().endsWith(";") ? "" : ";"} ${DIM_STYLE_DECL}${quote}`,
+	);
+
+	if (withStyle !== attrs) return `${withStyle} data-dim="1"`;
+
+	return `${attrs} data-dim="1" style="${DIM_STYLE_DECL}"`;
+}
+
+export function applyCodeStepDimming(
+	html: string,
+	steps: StepGroup[],
+	stepIndex: number,
+	startAt: number,
+): string {
+	const cleanHtml = removeDimStyle(
+		html.replace(DATA_DIM_ATTR, "").replace(DATA_HIGHLIGHT_ATTR, ""),
+	);
+
+	if (steps.length === 0) return cleanHtml;
+
+	let activeGroupIndex = 0;
+	if (startAt > 0 && stepIndex >= startAt) {
+		activeGroupIndex = Math.min(stepIndex - startAt + 1, steps.length - 1);
+	}
+
+	const activeGroup = steps[activeGroupIndex];
+	if (!activeGroup || activeGroup === "all") return cleanHtml;
+
+	return cleanHtml.replace(LINE_SPAN, (match, attrs: string) => {
+		if (!LINE_CLASS.test(attrs)) return match;
+
+		const dataLine = attrs.match(DATA_LINE);
+		if (!dataLine) return match;
+
+		const lineNumber = parseInt(dataLine[2] ?? "", 10);
+		if (activeGroup.includes(lineNumber)) {
+			return `<span${addHighlightAttributes(attrs)}>`;
+		}
+
+		return `<span${addDimAttributes(attrs)}>`;
+	});
+}
+
+/**
+ * Renders a pre-highlighted code block and applies timeline-driven line
+ * dimming for step-through walkthroughs.
+ *
+ * Export name matches the identifier injected by `remarkShikiCodeBlocks`:
+ * `import { HoneydeckCodeBlock } from '@honeydeck/honeydeck/components/code-block/normal'`
+ */
+export function HoneydeckCodeBlock({
+	html,
+	stepsJson,
+	startAt,
+	source,
+}: HoneydeckCodeBlockProps) {
+	const { stepIndex } = useTimeline();
+
+	// Parse step groups once (stepsJson is static — set at compile time)
+	const steps = useMemo(
+		() => parseJsonProp<StepGroup[]>(stepsJson, []),
+		[stepsJson],
+	);
+
+	const dimmedHtml = useMemo(
+		() => applyCodeStepDimming(html, steps, stepIndex, startAt),
+		[html, startAt, stepIndex, steps],
+	);
+
+	return (
+		<CodeBlock
+			source={source}
+			className="[&_.line]:transition-opacity [&_.line]:duration-150 [&_.line]:ease-in"
+		>
+			<div
+				// biome-ignore lint/security/noDangerouslySetInnerHtml: Shiki generates this highlighted HTML during MDX compilation.
+				dangerouslySetInnerHTML={{ __html: dimmedHtml }}
+			/>
+		</CodeBlock>
+	);
+}

package/src/runtime/components/Reveal.tsx

@@ -1,5 +1,8 @@
-import type { CSSProperties, ReactNode } from "react";
-import { useTimeline } from "../TimelineContext.tsx";
+import type { ReactNode } from "react";
+import {
+	TimelineReveal,
+	type TimelineRevealElement,
+} from "./TimelineReveal.tsx";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -15,9 +18,13 @@ export type RevealProps = {
 	 * Wrapper element. Injected by the compiler from MDX context:
 	 * flow/block reveals use `div`, text/inline reveals use `span`.
 	 */
-	as?: "div" | "span";
+	as?: TimelineRevealElement;
+	/** Slide-local target name for <RevealWith target="..."> synchronization. */
+	name?: string;
 	/** Additional CSS class for custom transition overrides. */
 	className?: string;
+	/** Remove hidden content from the DOM/layout instead of reserving space. */
+	ephemeral?: boolean;
 	children?: ReactNode;
 };
 
@@ -30,7 +37,8 @@ export type RevealProps = {
  *
  * 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.
+ * nearby content to jump around. With `ephemeral`, hidden content is not
+ * rendered and does not reserve layout space.
  *
  * Reveals are cumulative: once visible, they stay visible as the presenter
  * advances. The default transition is a simple opacity fade.
@@ -40,43 +48,35 @@ export type RevealProps = {
  *
  * Visible from the start.
  *
- * <Reveal>This appears at step 1.</Reveal>
+ * <Reveal name="intro">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`.
+ * render as `span`. Optional `name` values are slide-local targets for
+ * `<RevealWith target="...">`.
  */
 export function Reveal({
-	as: Component = "div",
+	as = "div",
 	at = 1,
+	name,
 	className = "",
+	ephemeral = false,
 	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}
+		<TimelineReveal
+			as={as}
+			at={at}
+			className={className}
+			ephemeral={ephemeral}
+			dataAttributes={{
+				"data-honeydeck-reveal-id": name,
+			}}
 		>
 			{children}
-		</Component>
+		</TimelineReveal>
 	);
 }