@honeydeck/honeydeck 0.4.0 → 0.6.0

package/src/remark/step-numbering.ts

@@ -1,36 +1,45 @@
 /**
- * Remark plugin: assign `at` props to `<Reveal>` and `<RevealGroup>` elements
- * and count total timeline steps per slide.
+ * Remark plugin: assign `at` props to timeline-aware MDX elements and count
+ * total timeline steps per slide.
  *
  * ### What it does
  * Walks the MDAST (including MDX JSX nodes) in document order and:
- *  1. Assigns `at={n}` to each `<Reveal>` element (starting at 1) and
- *     injects `as="div"`/`as="span"` from the MDX flow/text context.
- *  2. Assigns `at={n}` to each `<RevealGroup>` element using the starting
- *     index of the group and adds internal per-target step numbers for group
- *     children/list items.
- *  3. Assigns `at={n}` to each `<TimelineSteps steps={n}>` element and
+ *  1. Assigns `at={n}` to each `<Reveal>`/`<Fade>` element (starting at 1)
+ *     and injects `as="div"`/`as="span"` from the MDX flow/text context.
+ *  2. Assigns `at={n}` to each `<RevealGroup>`/`<FadeGroup>` element using
+ *     the starting index of the group and adds internal per-target step numbers
+ *     for group children/list items. `listRevealMode="nested"` makes nested
+ *     RevealGroup list items step targets too.
+ *  3. Collects literal `<Reveal name="...">` targets and resolves
+ *     `<RevealWith target="...">`, numeric `target={n}`, and `at={n}`
+ *     sync props for `<RevealWith>`/`<FadeWith>` without adding steps.
+ *  4. Assigns `at={n}` to each `<TimelineSteps steps={n}>` element and
  *     advances the timeline by its literal static step count.
- *  4. Counts timeline steps from code fence `|`-separated groups after the
+ *  5. Counts timeline steps from code fence `|`-separated groups after the
  *     first baseline group (counted here so `stepCount` is already accurate).
- *  5. Writes the total step count to `vfile.data.stepCount`.
+ *  6. Writes the total step count to `vfile.data.stepCount`.
  *
  * ### `at` prop injection
  * Numeric JSX props require an ESTree expression node. We construct a minimal
  * `Program` → `ExpressionStatement` → `Literal` subtree so that `@mdx-js/mdx`
  * generates `at={<number>}` (not `at="<string>"`).
  *
- * ### Existing `at` props
- * If a `<Reveal>` or `<RevealGroup>` already has an explicit `at` prop, this
- * plugin leaves it untouched. Future V2 may expose `<Reveal at={2}>` as a
- * public API for out-of-order reveals. `<Reveal>` still receives a compiler
- * `as` prop when missing, so manually numbered inline reveals remain valid HTML.
+ * ### Internal `at` props
+ * Honeydeck injects `at` props during compilation to connect timeline-driven
+ * components to their assigned slide-local steps. `at` is internal compiler
+ * plumbing for `<Reveal>`, `<Fade>`, `<RevealGroup>`, and `<FadeGroup>`, and a
+ * validated sync target for `<RevealWith>`/`<FadeWith>`. Timeline-aware
+ * elements still receive compiler `as` props when missing, so inline usages
+ * remain valid HTML.
  *
  * ### Recursion
- * Nested step producers are flattened into the same slide-local timeline.
- * Parent reveal targets consume their step first, then nested reveals, groups,
- * and code walkthrough steps after the first baseline highlight consume later
- * steps before the next sibling target.
+ * Nested step producers are flattened into the same slide-local timeline for
+ * reveal targets. Parent reveal targets consume their step first, then nested
+ * reveal/fade elements, reveal groups, and code walkthrough steps after the
+ * first baseline highlight consume later steps before the next sibling target.
+ * With components cannot contain nested timeline producers because they do not
+ * create timeline steps. Fade targets cannot contain nested timeline producers
+ * because a faded parent would hide later nested steps.
  */
 
 import type { Program } from "estree";
@@ -42,6 +51,12 @@ import type {
 	MdxJsxTextElement,
 } from "mdast-util-mdx-jsx";
 import type { Plugin } from "unified";
+import {
+	countCodeFenceGroups,
+	countCodeFenceSteps,
+	countMagicCodeStates,
+	isMagicCodeFence,
+} from "./code-utils.ts";
 
 // ---------------------------------------------------------------------------
 // Helper: build an `at={n}` attribute node
@@ -103,6 +118,28 @@ function hasAtProp(el: MdxJsxElement): boolean {
 	);
 }
 
+function hasAttribute(el: MdxJsxElement, name: string): boolean {
+	return el.attributes.some(
+		(a) => a.type === "mdxJsxAttribute" && a.name === name,
+	);
+}
+
+function isStepElementName(name: string | null | undefined): boolean {
+	return name === "Reveal" || name === "Fade";
+}
+
+function isWithElementName(name: string | null | undefined): boolean {
+	return name === "RevealWith" || name === "FadeWith";
+}
+
+function isGroupElementName(name: string | null | undefined): boolean {
+	return name === "RevealGroup" || name === "FadeGroup";
+}
+
+function isFadeElementName(name: string | null | undefined): boolean {
+	return name === "Fade";
+}
+
 function getAttribute(
 	el: MdxJsxElement,
 	name: string,
@@ -113,7 +150,27 @@ function getAttribute(
 	);
 }
 
-function injectRevealWrapperElement(el: MdxJsxElement): void {
+function removeAttribute(el: MdxJsxElement, name: string): void {
+	el.attributes = el.attributes.filter(
+		(a) => !(a.type === "mdxJsxAttribute" && a.name === name),
+	);
+}
+
+function setAtAttribute(el: MdxJsxElement, at: number): void {
+	removeAttribute(el, "at");
+	el.attributes.push(makeAtAttribute(at));
+}
+
+function setStringAttribute(
+	el: MdxJsxElement,
+	name: string,
+	value: string,
+): void {
+	removeAttribute(el, name);
+	el.attributes.push(makeStringAttribute(name, value));
+}
+
+function injectTimelineWrapperElement(el: MdxJsxElement): void {
 	if (getAttribute(el, "as")) return;
 
 	el.attributes.push(
@@ -125,28 +182,7 @@ function injectRevealWrapperElement(el: MdxJsxElement): void {
 // Helper: count reveal steps produced by a RevealGroup child
 // ---------------------------------------------------------------------------
 
-function countListItems(node: unknown): number | null {
-	const n = node as { type?: string; children?: unknown[] };
-
-	if (n.type === "list") {
-		return (n.children ?? []).filter((child) => {
-			const c = child as { type?: string };
-			return c.type === "listItem";
-		}).length;
-	}
-
-	if (isJsxElement(node) && (node.name === "ul" || node.name === "ol")) {
-		return node.children.filter((child) => {
-			const c = child as { type?: string; value?: string };
-			if (c.type === "text") {
-				return (c.value ?? "").trim().length > 0;
-			}
-			return true;
-		}).length;
-	}
-
-	return null;
-}
+type RevealGroupListRevealMode = "direct" | "nested";
 
 function getMeaningfulChildren(children: unknown[]): unknown[] {
 	return children.filter((child) => {
@@ -158,24 +194,54 @@ function getMeaningfulChildren(children: unknown[]): unknown[] {
 	});
 }
 
-function getRevealGroupTargets(el: MdxJsxElement): unknown[] {
+function isMarkdownList(node: unknown): boolean {
+	return (node as { type?: string }).type === "list";
+}
+
+function isMarkdownListItem(node: unknown): boolean {
+	return (node as { type?: string }).type === "listItem";
+}
+
+function isJsxListElement(node: unknown): node is MdxJsxElement {
+	return isJsxElement(node) && (node.name === "ul" || node.name === "ol");
+}
+
+function isJsxListItemElement(node: unknown): node is MdxJsxElement {
+	return isJsxElement(node) && node.name === "li";
+}
+
+function isHtmlJsxElement(node: unknown): node is MdxJsxElement {
+	return isJsxElement(node) && /^[a-z]/.test(node.name ?? "");
+}
+
+function isJsxFragmentElement(node: unknown): node is MdxJsxElement {
+	return isJsxElement(node) && !node.name;
+}
+
+function isListElement(node: unknown): boolean {
+	return isMarkdownList(node) || isJsxListElement(node);
+}
+
+function getListChildren(node: unknown): unknown[] {
+	const n = node as { type?: string; children?: unknown[] };
+
+	if (n.type === "list") {
+		return (n.children ?? []).filter(isMarkdownListItem);
+	}
+
+	if (isJsxListElement(node)) {
+		return getMeaningfulChildren(node.children);
+	}
+
+	return [];
+}
+
+function getDirectRevealGroupTargets(el: MdxJsxElement): unknown[] {
 	const targets: unknown[] = [];
 
 	for (const child of getMeaningfulChildren(el.children)) {
-		const listItemCount = countListItems(child);
-		const c = child as { type?: string; children?: unknown[] };
-
-		if (listItemCount !== null && Array.isArray(c.children)) {
-			if (c.type === "list") {
-				targets.push(
-					...c.children.filter((item) => {
-						const i = item as { type?: string };
-						return i.type === "listItem";
-					}),
-				);
-			} else {
-				targets.push(...getMeaningfulChildren(c.children));
-			}
+		if (isListElement(child)) {
+			targets.push(...getListChildren(child));
 			continue;
 		}
 
@@ -185,25 +251,6 @@ function getRevealGroupTargets(el: MdxJsxElement): unknown[] {
 	return targets;
 }
 
-// ---------------------------------------------------------------------------
-// Helper: count groups/steps encoded in a code fence meta string
-//
-// Pattern: `{2|4-5|all}` → 3 groups, 2 timeline steps.
-// The first group is the baseline active highlight. Each later group consumes
-// one timeline step.
-// ---------------------------------------------------------------------------
-
-function countCodeFenceGroups(meta: string | null | undefined): number {
-	if (!meta) return 0;
-	const match = meta.match(/\{([^}]+)\}/);
-	if (!match?.[1]) return 0;
-	return match[1].split("|").filter(Boolean).length;
-}
-
-function countCodeFenceSteps(meta: string | null | undefined): number {
-	return Math.max(0, countCodeFenceGroups(meta) - 1);
-}
-
 function expressionValue(attr: MdxJsxAttribute): unknown {
 	const value = attr.value;
 	if (
@@ -223,6 +270,29 @@ function expressionValue(attr: MdxJsxAttribute): unknown {
 	return expression.value;
 }
 
+function stringLiteralValue(attr: MdxJsxAttribute): string | null {
+	if (typeof attr.value === "string") return attr.value;
+
+	const value = expressionValue(attr);
+	return typeof value === "string" ? value : null;
+}
+
+function readNonEmptyStringLiteral(
+	attr: MdxJsxAttribute,
+	description: string,
+): string {
+	const value = stringLiteralValue(attr);
+	if (value === null) {
+		throw new Error(
+			`Honeydeck ${description} must be a literal string. Dynamic expressions are not supported because RevealWith targets are resolved at build time.`,
+		);
+	}
+	if (value.length === 0) {
+		throw new Error(`Honeydeck ${description} must not be empty.`);
+	}
+	return value;
+}
+
 function parsePositiveIntegerLiteral(attr: MdxJsxAttribute): number | null {
 	if (typeof attr.value === "string") {
 		if (!/^[1-9]\d*$/.test(attr.value)) return null;
@@ -241,6 +311,24 @@ function parsePositiveIntegerLiteral(attr: MdxJsxAttribute): number | null {
 	return null;
 }
 
+function readRevealGroupListRevealMode(
+	el: MdxJsxElement,
+): RevealGroupListRevealMode {
+	const attr = getAttribute(el, "listRevealMode");
+	if (!attr) return "direct";
+
+	const value =
+		typeof attr.value === "string" ? attr.value : expressionValue(attr);
+
+	if (value === "direct" || value === "nested") {
+		return value;
+	}
+
+	throw new Error(
+		'Honeydeck <RevealGroup> `listRevealMode` must be the literal string "direct" or "nested" because timeline steps are counted at build time.',
+	);
+}
+
 function readTimelineSteps(el: MdxJsxElement): number {
 	const attr = getAttribute(el, "steps");
 	if (!attr || attr.value === null) {
@@ -264,13 +352,18 @@ function findNestedStepProducer(node: unknown): string | null {
 
 	if (n.type === "code") {
 		const codeNode = node as Code;
+		if (isMagicCodeFence(codeNode)) {
+			return countMagicCodeStates(codeNode.value) > 1
+				? "Magic Code block"
+				: null;
+		}
 		return countCodeFenceSteps(codeNode.meta) > 0 ? "stepped code fence" : null;
 	}
 
 	if (isJsxElement(node)) {
 		if (
-			node.name === "Reveal" ||
-			node.name === "RevealGroup" ||
+			isStepElementName(node.name) ||
+			isGroupElementName(node.name) ||
 			node.name === "TimelineSteps"
 		) {
 			return `<${node.name}>`;
@@ -292,8 +385,8 @@ function findNestedStepProducer(node: unknown): string | null {
 // ---------------------------------------------------------------------------
 
 /**
- * Remark plugin that numbers `<Reveal>` and `<RevealGroup>` elements with
- * sequential `at` props and stores the total step count in `vfile.data`.
+ * Remark plugin that numbers timeline-aware MDX elements with sequential `at`
+ * props and stores the total step count in `vfile.data`.
  *
  * Usage (in Vite plugin config):
  * ```ts
@@ -302,6 +395,10 @@ function findNestedStepProducer(node: unknown): string | null {
  */
 export const remarkStepNumbering: Plugin<[], Root> = () => (tree, vfile) => {
 	let counter = 1; // next `at` value to assign; 1-based
+	let activeRevealGroupTargetSteps: number[] = [];
+	const namedReveals = new Map<string, number>();
+	const withStringTargets: Array<{ el: MdxJsxElement; target: string }> = [];
+	const withNumericTargets: Array<{ el: MdxJsxElement; at: number }> = [];
 
 	function visitChildren(node: unknown): void {
 		const n = node as { children?: unknown[] };
@@ -312,12 +409,92 @@ export const remarkStepNumbering: Plugin<[], Root> = () => (tree, vfile) => {
 		}
 	}
 
+	function pushRevealGroupTarget(
+		targetSteps: number[],
+		target: unknown,
+		visitContent: boolean,
+	): void {
+		targetSteps.push(counter);
+		counter++;
+		if (visitContent) visitNode(target);
+	}
+
+	function visitRevealGroupNestedListContent(node: unknown): void {
+		if (isListElement(node)) {
+			visitRevealGroupNestedList(node);
+			return;
+		}
+
+		if (isHtmlJsxElement(node) || isJsxFragmentElement(node)) {
+			for (const child of getMeaningfulChildren(node.children)) {
+				visitRevealGroupNestedListContent(child);
+			}
+			return;
+		}
+
+		visitNode(node);
+	}
+
+	function visitRevealGroupNestedListItemContent(item: unknown): void {
+		if (!isMarkdownListItem(item) && !isJsxListItemElement(item)) {
+			visitNode(item);
+			return;
+		}
+
+		const i = item as { children?: unknown[] };
+		for (const child of getMeaningfulChildren(i.children ?? [])) {
+			visitRevealGroupNestedListContent(child);
+		}
+	}
+
+	function visitRevealGroupNestedList(
+		list: unknown,
+		targetSteps: number[] = activeRevealGroupTargetSteps,
+	): void {
+		for (const item of getListChildren(list)) {
+			pushRevealGroupTarget(targetSteps, item, false);
+			visitRevealGroupNestedListItemContent(item);
+		}
+	}
+
+	function recordRevealName(el: MdxJsxElement, at: number): void {
+		const nameAttr = getAttribute(el, "name");
+		if (!nameAttr) return;
+
+		const name = readNonEmptyStringLiteral(nameAttr, "<Reveal> `name`");
+		if (namedReveals.has(name)) {
+			throw new Error(
+				`Honeydeck <Reveal> name "${name}" is duplicated on this slide. Reveal names must be unique per slide for <RevealWith target="..."> resolution.`,
+			);
+		}
+		namedReveals.set(name, at);
+	}
+
 	function visitNode(node: unknown): void {
 		const n = node as { type?: string };
 
 		// ── Code blocks with step-through meta ─────────────────────────────
 		if (n.type === "code") {
 			const codeNode = node as Code;
+
+			if (isMagicCodeFence(codeNode)) {
+				const stateCount = countMagicCodeStates(codeNode.value);
+				const steps = Math.max(0, stateCount - 1);
+				if (stateCount > 0) {
+					if (!(codeNode as unknown as Record<string, unknown>).data) {
+						(codeNode as unknown as Record<string, unknown>).data = {};
+					}
+					(
+						(codeNode as unknown as Record<string, unknown>).data as Record<
+							string,
+							unknown
+						>
+					).honeydeckStartAt = counter;
+				}
+				counter += steps;
+				return;
+			}
+
 			const groupCount = countCodeFenceGroups(codeNode.meta);
 			const steps = Math.max(0, groupCount - 1);
 			if (groupCount > 0) {
@@ -356,48 +533,156 @@ export const remarkStepNumbering: Plugin<[], Root> = () => (tree, vfile) => {
 					);
 				}
 
-				if (!hasAtProp(el)) {
-					el.attributes.push(makeAtAttribute(counter));
-				}
-
+				setAtAttribute(el, counter);
 				counter += steps;
+				visitChildren(el);
 				return;
 			}
 
-			if (el.name === "Reveal") {
-				injectRevealWrapperElement(el);
+			if (isStepElementName(el.name)) {
+				if (hasAtProp(el)) {
+					throw new Error(
+						`Honeydeck <${el.name}> \`at\` is internal compiler plumbing and cannot be authored. Use <RevealWith at={n}> or <FadeWith at={n}> to sync content with an existing step.`,
+					);
+				}
 
-				if (!hasAtProp(el)) {
-					el.attributes.push(makeAtAttribute(counter));
-					counter++;
+				if (isFadeElementName(el.name)) {
+					const nestedProducer = findNestedStepProducer({
+						type: "honeydeckFadeChildren",
+						children: el.children,
+					});
+
+					if (nestedProducer) {
+						throw new Error(
+							`Honeydeck <${el.name}> cannot contain nested timeline producers (${nestedProducer}). Put fade components inside a Reveal instead of putting reveal/timeline components inside a Fade.`,
+						);
+					}
+				}
+
+				const stepAt = counter;
+				injectTimelineWrapperElement(el);
+				setAtAttribute(el, stepAt);
+				if (el.name === "Reveal") {
+					recordRevealName(el, stepAt);
+				}
+				counter++;
+				if (!isFadeElementName(el.name)) {
 					visitChildren(el);
 				}
 				return;
 			}
 
-			if (el.name === "RevealGroup") {
+			if (isWithElementName(el.name)) {
+				injectTimelineWrapperElement(el);
+
+				const nestedProducer = findNestedStepProducer({
+					type: "honeydeckWithChildren",
+					children: el.children,
+				});
+
+				if (nestedProducer) {
+					throw new Error(
+						`Honeydeck <${el.name}> cannot contain nested timeline producers (${nestedProducer}). With components do not create timeline steps; target them at sibling timeline steps instead.`,
+					);
+				}
+
+				const hasTarget = hasAttribute(el, "target");
+				const hasAt = hasAtProp(el);
+				if (hasTarget === hasAt) {
+					throw new Error(
+						`Honeydeck <${el.name}> requires exactly one of \`target\` or \`at\`.`,
+					);
+				}
+
+				if (hasTarget) {
+					const targetAttr = getAttribute(el, "target");
+					if (!targetAttr) return;
+					const targetValue = expressionValue(targetAttr);
+					if (typeof targetValue === "number") {
+						const at = parsePositiveIntegerLiteral(targetAttr);
+						if (at === null) {
+							throw new Error(
+								`Honeydeck <${el.name}> \`target\` must be a literal positive integer or non-empty string.`,
+							);
+						}
+						withNumericTargets.push({ el, at });
+					} else {
+						const target = readNonEmptyStringLiteral(
+							targetAttr,
+							`<${el.name}> \`target\``,
+						);
+						withStringTargets.push({ el, target });
+					}
+				} else {
+					const atAttr = getAttribute(el, "at");
+					const at = atAttr ? parsePositiveIntegerLiteral(atAttr) : null;
+					if (at === null) {
+						throw new Error(
+							`Honeydeck <${el.name}> \`at\` must be a literal positive integer, for example at={2}. Dynamic expressions are not supported because With steps are resolved at build time.`,
+						);
+					}
+					setAtAttribute(el, at);
+					withNumericTargets.push({ el, at });
+				}
+
+				return;
+			}
+
+			if (isGroupElementName(el.name)) {
 				if (hasAtProp(el)) {
-					return;
+					throw new Error(
+						`Honeydeck <${el.name}> \`at\` is internal compiler plumbing and cannot be authored. Use <RevealWith at={n}> or <FadeWith at={n}> to sync content with an existing group step.`,
+					);
 				}
 
-				const targets = getRevealGroupTargets(el);
+				const listRevealMode =
+					el.name === "RevealGroup"
+						? readRevealGroupListRevealMode(el)
+						: "direct";
 				const targetSteps: number[] = [];
 
-				el.attributes.push(makeAtAttribute(counter));
-				if (targets.length === 0) {
-					counter++;
-					return;
+				setAtAttribute(el, counter);
+
+				if (listRevealMode === "nested") {
+					const previousTargetSteps = activeRevealGroupTargetSteps;
+					activeRevealGroupTargetSteps = targetSteps;
+
+					for (const child of getMeaningfulChildren(el.children)) {
+						if (isListElement(child)) {
+							visitRevealGroupNestedList(child);
+						} else {
+							pushRevealGroupTarget(targetSteps, child, true);
+						}
+					}
+
+					activeRevealGroupTargetSteps = previousTargetSteps;
+				} else {
+					const targets = getDirectRevealGroupTargets(el);
+
+					if (el.name === "FadeGroup") {
+						for (const target of targets) {
+							const nestedProducer = findNestedStepProducer(target);
+
+							if (nestedProducer) {
+								throw new Error(
+									`Honeydeck <FadeGroup> targets cannot contain nested timeline producers (${nestedProducer}). Put fade components inside a RevealGroup/Reveal target instead of nesting timeline components inside a FadeGroup target.`,
+								);
+							}
+						}
+					}
+
+					for (const target of targets) {
+						pushRevealGroupTarget(targetSteps, target, el.name !== "FadeGroup");
+					}
 				}
 
-				for (const target of targets) {
-					targetSteps.push(counter);
+				if (targetSteps.length === 0) {
+					removeAttribute(el, "targetStepsJson");
 					counter++;
-					visitNode(target);
+					return;
 				}
 
-				el.attributes.push(
-					makeStringAttribute("targetStepsJson", JSON.stringify(targetSteps)),
-				);
+				setStringAttribute(el, "targetStepsJson", JSON.stringify(targetSteps));
 				return;
 			}
 		}
@@ -407,6 +692,26 @@ export const remarkStepNumbering: Plugin<[], Root> = () => (tree, vfile) => {
 
 	visitChildren(tree);
 
+	const stepCount = counter - 1; // counter started at 1
+
+	for (const { el, target } of withStringTargets) {
+		const at = namedReveals.get(target);
+		if (at === undefined) {
+			throw new Error(
+				`Honeydeck <${el.name} target="${target}"> could not find a same-slide <Reveal name="${target}"> target.`,
+			);
+		}
+		setAtAttribute(el, at);
+	}
+
+	for (const { el, at } of withNumericTargets) {
+		if (at > stepCount) {
+			throw new Error(
+				`Honeydeck <${el.name} at={${at}}> targets step ${at}, but this slide only has ${stepCount} timeline step${stepCount === 1 ? "" : "s"}.`,
+			);
+		}
+	}
+
 	// Store total step count on the vfile for the virtual modules plugin to read.
-	vfile.data.stepCount = counter - 1; // counter started at 1
+	vfile.data.stepCount = stepCount;
 };