@honeydeck/honeydeck 0.4.0 → 0.5.0

package/src/runtime/components/CodeBlock.tsx

@@ -1,210 +1,27 @@
-/**
- * HoneydeckCodeBlock — runtime code block component with syntax highlighting
- * and timeline-driven step-through.
- *
- * ### Usage
- * This component is **not imported directly by slide authors**. The
- * `remarkShikiCodeBlocks` remark plugin automatically replaces fenced code
- * blocks in MDX with `<HoneydeckCodeBlock>` elements at compile time.
- *
- * ### Props
- * - `html`       — Pre-highlighted HTML string from shiki (full `<pre>…</pre>`).
- * - `stepsJson`  — JSON-encoded `StepGroup[]` (e.g. `[[2],[4,5],"all"]`).
- *                  Empty array = no step-through.
- * - `startAt`    — 1-based timeline step at which group 1 activates.
- *                  Group 0 is the baseline active highlight; 0 for non-stepped blocks.
- * - `source`     — Original fenced code text for clipboard copying.
- *
- * ### Step-through mechanics
- * The component reads `stepIndex` from `useTimeline()` and computes the active
- * group index: group 0 before `startAt`, then later groups from `startAt`.
- * It then adds `data-dim="1"` and an inline opacity style to non-highlighted
- * `.line` spans in the rendered HTML.
- * Base CSS also targets the attribute as a fallback.
- *
- * The highlighted HTML is injected via `dangerouslySetInnerHTML`, so the
- * step-specific `data-dim` attributes are computed as part of the HTML string
- * before React writes it to the DOM.
- */
+import type { ReactNode } from "react";
+import { CodeBlockCopyButton } from "./CodeBlockCopyButton.tsx";
 
-import { CheckIcon, CopyIcon } from "lucide-react";
-import { useMemo, useState } from "react";
-import { useTimeline } from "../TimelineContext.tsx";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** A single step-through group: line numbers (1-based) or 'all'. */
-export type StepGroup = number[] | "all";
-
-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. */
+type CodeBlockProps = {
+	/** Original source copied by the hover/focus copy control. */
 	source?: string;
+	/** Extra classes for a specific code block implementation. */
+	className?: string;
+	children: ReactNode;
 };
 
-const DATA_DIM_ATTR = /\sdata-dim=(["'])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);";
-
-async function writeClipboardText(text: string): Promise<boolean> {
-	try {
-		if (navigator.clipboard) {
-			await navigator.clipboard.writeText(text);
-			return true;
-		}
-	} catch {
-		// Fall back to the textarea path below.
-	}
-
-	try {
-		const textarea = document.createElement("textarea");
-		textarea.value = text;
-		textarea.setAttribute("readonly", "");
-		textarea.style.position = "fixed";
-		textarea.style.inset = "0";
-		textarea.style.opacity = "0";
-		document.body.appendChild(textarea);
-		textarea.select();
-		const didCopy = document.execCommand("copy");
-		document.body.removeChild(textarea);
-		return didCopy;
-	} catch {
-		return false;
-	}
-}
-
-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 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, ""));
-
-	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 match;
-
-		return `<span${addDimAttributes(attrs)}>`;
-	});
-}
-
-// ---------------------------------------------------------------------------
-// Component
-// ---------------------------------------------------------------------------
-
-/**
- * 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'`
- */
-export function HoneydeckCodeBlock({
-	html,
-	stepsJson,
-	startAt,
-	source,
-}: HoneydeckCodeBlockProps) {
-	const { stepIndex } = useTimeline();
-	const [copied, setCopied] = useState(false);
-
-	// Parse step groups once (stepsJson is static — set at compile time)
-	const steps = useMemo((): StepGroup[] => {
-		try {
-			return JSON.parse(stepsJson) as StepGroup[];
-		} catch {
-			return [];
-		}
-	}, [stepsJson]);
-
-	const dimmedHtml = useMemo(
-		() => applyCodeStepDimming(html, steps, stepIndex, startAt),
-		[html, startAt, stepIndex, steps],
-	);
-
-	async function copySource() {
-		if (!source) return;
-
-		if (await writeClipboardText(source)) {
-			setCopied(true);
-			window.setTimeout(() => setCopied(false), 1600);
-		}
-	}
-
+/** Shared frame for Honeydeck code block implementations. */
+export function CodeBlock({ source, className, children }: CodeBlockProps) {
 	return (
-		<div className="honeydeck-code-block group relative mb-[0.75em] overflow-hidden rounded-honeydeck font-mono text-[length:var(--honeydeck-font-size-code)] [&_.line]:transition-opacity [&_.line]:duration-150 [&_.line]:ease-in">
-			{source ? (
-				<button
-					className="honeydeck-code-copy-button"
-					type="button"
-					aria-label={copied ? "Code copied" : "Copy code"}
-					title={copied ? "Copied" : "Copy code"}
-					onClick={copySource}
-				>
-					{copied ? (
-						<CheckIcon aria-hidden="true" />
-					) : (
-						<CopyIcon aria-hidden="true" />
-					)}
-				</button>
-			) : null}
-			<div
-				// biome-ignore lint/security/noDangerouslySetInnerHtml: Shiki generates this highlighted HTML during MDX compilation.
-				dangerouslySetInnerHTML={{ __html: dimmedHtml }}
-			/>
+		<div
+			className={[
+				"honeydeck-code-block group relative mb-[0.75em] overflow-hidden rounded-honeydeck font-mono text-[length:var(--honeydeck-font-size-code)]",
+				className,
+			]
+				.filter(Boolean)
+				.join(" ")}
+		>
+			<CodeBlockCopyButton source={source} />
+			{children}
 		</div>
 	);
 }

package/src/runtime/components/CodeBlockCopyButton.tsx

@@ -0,0 +1,64 @@
+import { CheckIcon, CopyIcon } from "lucide-react";
+import { useState } from "react";
+
+async function writeClipboardText(text: string): Promise<boolean> {
+	try {
+		if (navigator.clipboard) {
+			await navigator.clipboard.writeText(text);
+			return true;
+		}
+	} catch {
+		// Fall back to the textarea path below.
+	}
+
+	try {
+		const textarea = document.createElement("textarea");
+		textarea.value = text;
+		textarea.setAttribute("readonly", "");
+		textarea.style.position = "fixed";
+		textarea.style.inset = "0";
+		textarea.style.opacity = "0";
+		document.body.appendChild(textarea);
+		textarea.select();
+		const didCopy = document.execCommand("copy");
+		document.body.removeChild(textarea);
+		return didCopy;
+	} catch {
+		return false;
+	}
+}
+
+type CodeBlockCopyButtonProps = {
+	source?: string;
+};
+
+export function CodeBlockCopyButton({ source }: CodeBlockCopyButtonProps) {
+	const [copied, setCopied] = useState(false);
+
+	async function copySource() {
+		if (!source) return;
+
+		if (await writeClipboardText(source)) {
+			setCopied(true);
+			window.setTimeout(() => setCopied(false), 1600);
+		}
+	}
+
+	if (!source) return null;
+
+	return (
+		<button
+			className="honeydeck-code-copy-button"
+			type="button"
+			aria-label={copied ? "Code copied" : "Copy code"}
+			title={copied ? "Copied" : "Copy code"}
+			onClick={copySource}
+		>
+			{copied ? (
+				<CheckIcon aria-hidden="true" />
+			) : (
+				<CopyIcon aria-hidden="true" />
+			)}
+		</button>
+	);
+}

package/src/runtime/components/CodeBlockShared.ts

@@ -0,0 +1,17 @@
+/** A single step-through group: line numbers (1-based) or 'all'. */
+export type StepGroup = number[] | "all";
+
+export function parseJsonProp<T>(
+	value: string,
+	fallback: T,
+	propName?: string,
+): T {
+	try {
+		return JSON.parse(value) as T;
+	} catch (error) {
+		if (propName) {
+			console.warn(`Honeydeck Magic Code could not parse ${propName}.`, error);
+		}
+		return fallback;
+	}
+}

package/src/runtime/components/Fade.tsx

@@ -0,0 +1,51 @@
+import type { ReactNode } from "react";
+import { useTimelineVisibility } from "./timelineVisibility.ts";
+
+export type FadeProps = {
+	/** The step index at which this content fades out. */
+	at?: number;
+	/** Wrapper element. Injected by the compiler from MDX context. */
+	as?: "div" | "span";
+	/** Additional CSS class for custom transition overrides. */
+	className?: string;
+	/** Remove hidden content from the DOM/layout instead of reserving space. */
+	ephemeral?: boolean;
+	children?: ReactNode;
+};
+
+/**
+ * Timeline-driven fade component for content that starts visible and disappears
+ * once the slide reaches its assigned step.
+ */
+export function Fade({
+	as: Component = "div",
+	at = 1,
+	className = "",
+	ephemeral = false,
+	children,
+}: FadeProps) {
+	const { shouldRender, style } = useTimelineVisibility({
+		mode: "fade",
+		at,
+		ephemeral,
+	});
+
+	if (!shouldRender) return null;
+
+	return (
+		<Component
+			className={[
+				"honeydeck-fade mb-[0.75em] text-[length:var(--honeydeck-font-size-body)] leading-[1.6] [&>:last-child]:mb-0",
+				className,
+			]
+				.filter(Boolean)
+				.join(" ")}
+			style={{
+				display: Component === "span" ? "inline" : "block",
+				...style,
+			}}
+		>
+			{children}
+		</Component>
+	);
+}

package/src/runtime/components/FadeGroup.tsx

@@ -0,0 +1,175 @@
+import {
+	Children,
+	type CSSProperties,
+	cloneElement,
+	isValidElement,
+	type Key,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+import { useTimeline } from "../TimelineContext.tsx";
+import { Fade } from "./Fade.tsx";
+
+type ElementWithCommonProps = ReactElement<{
+	children?: ReactNode;
+	className?: string;
+	style?: CSSProperties;
+}>;
+
+export type FadeGroupProps = {
+	/** The step index for the first child. Subsequent children increment by 1. */
+	at?: number;
+	/** Internal compiler-provided absolute steps for each direct fade target. */
+	targetStepsJson?: string;
+	/** Remove hidden children from the DOM/layout instead of reserving space. */
+	ephemeral?: boolean;
+	children?: ReactNode;
+};
+
+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 fadeVisibility(
+	stepIndex: number,
+	at: number,
+	showFutureSteps: boolean,
+	futureStepOpacity: number,
+	ephemeral: boolean,
+): { shouldRender: boolean; style: CSSProperties } {
+	const visible = stepIndex < at;
+	const previewFuture = !visible && showFutureSteps;
+
+	return {
+		shouldRender: visible || previewFuture || !ephemeral,
+		style: {
+			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 [];
+	}
+}
+
+/** Fades each meaningful direct child out as a separate timeline step. */
+export function FadeGroup({
+	at = 1,
+	targetStepsJson,
+	ephemeral = false,
+	children,
+}: FadeGroupProps) {
+	const { stepIndex, showFutureSteps, futureStepOpacity } = useTimeline();
+	const fadeTargets = 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 (
+		<>
+			{fadeTargets.map((child, _index) => {
+				if (isListElement(child)) {
+					const listItems = toMeaningfulArray(child.props.children);
+					const listKey = childKey(child, `fade-list-${at}-${targetIndex}`);
+					const renderedListItems = listItems.map((listItem) => {
+						const itemAt = nextTargetAt();
+						const itemKey = childKey(listItem, `fade-item-${itemAt}`);
+
+						if (!isElementWithCommonProps(listItem)) {
+							return (
+								<Fade key={itemKey} at={itemAt} ephemeral={ephemeral}>
+									{listItem}
+								</Fade>
+							);
+						}
+
+						const { shouldRender, style } = fadeVisibility(
+							stepIndex,
+							itemAt,
+							showFutureSteps,
+							futureStepOpacity,
+							ephemeral,
+						);
+
+						if (!shouldRender) return null;
+
+						return cloneElement(listItem, {
+							key: itemKey,
+							style: {
+								...listItem.props.style,
+								...style,
+							},
+						});
+					});
+
+					if (ephemeral && renderedListItems.every((item) => item === null)) {
+						return null;
+					}
+
+					return cloneElement(child, {
+						key: listKey,
+						children: renderedListItems,
+					});
+				}
+
+				const childAt = nextTargetAt();
+
+				return (
+					<Fade
+						key={childKey(child, `fade-child-${childAt}`)}
+						at={childAt}
+						ephemeral={ephemeral}
+					>
+						{child}
+					</Fade>
+				);
+			})}
+		</>
+	);
+}

package/src/runtime/components/FadeWith.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from "react";
+import { useTimelineVisibility } from "./timelineVisibility.ts";
+
+export type FadeWithProps = {
+	/** Slide-local reveal target name or existing slide-local timeline step. */
+	target?: string | number;
+	/** Existing slide-local timeline step to fade with. */
+	at?: number;
+	/** Wrapper element. Injected by the compiler from MDX context. */
+	as?: "div" | "span";
+	/** Additional CSS class for custom transition overrides. */
+	className?: string;
+	/** Remove hidden content from the DOM/layout instead of reserving space. */
+	ephemeral?: boolean;
+	children?: ReactNode;
+};
+
+/** Fade content out at an explicit target step without creating a timeline step. */
+export function FadeWith({
+	as: Component = "div",
+	at,
+	target,
+	className = "",
+	ephemeral = false,
+	children,
+}: FadeWithProps) {
+	const fadeAt = typeof target === "number" ? target : (at ?? 1);
+	const { shouldRender, style } = useTimelineVisibility({
+		mode: "fade",
+		at: fadeAt,
+		target: fadeAt,
+		ephemeral,
+	});
+
+	if (!shouldRender) return null;
+
+	return (
+		<Component
+			className={[
+				"honeydeck-fade honeydeck-fade-with mb-[0.75em] text-[length:var(--honeydeck-font-size-body)] leading-[1.6] [&>:last-child]:mb-0",
+				className,
+			]
+				.filter(Boolean)
+				.join(" ")}
+			style={{
+				display: Component === "span" ? "inline" : "block",
+				...style,
+			}}
+			data-honeydeck-fade-with={typeof target === "string" ? target : undefined}
+		>
+			{children}
+		</Component>
+	);
+}