@honeydeck/honeydeck 0.1.0

package/src/layouts/clean/Image/Image.tsx

@@ -0,0 +1,103 @@
+/**
+ * Clean Image layout — image stage with minimal framing.
+ */
+
+import type { ReactNode } from "react";
+import type { LayoutDemo, LayoutProps } from "../../../runtime/types.ts";
+import {
+	ColorModeImage,
+	type DarkModeImageFrontmatter,
+} from "../../ColorModeImage.tsx";
+import { imagePlaceholder, imagePlaceholderDark } from "../../placeholders.ts";
+import CleanDefaultLayout from "../Default.tsx";
+
+type ImageFrontmatter = DarkModeImageFrontmatter & {
+	/** Accessible text for the image. */
+	alt?: string;
+};
+
+function ImageFrame({ children }: { children: ReactNode }) {
+	return (
+		<div className="max-h-full overflow-hidden rounded-honeydeck border border-border bg-surface">
+			{children}
+		</div>
+	);
+}
+
+function PlaceholderBox() {
+	return (
+		<div className="flex max-h-full min-h-0 flex-col items-center gap-8">
+			<ImageFrame>
+				<ColorModeImage
+					src={imagePlaceholder}
+					darkSrc={imagePlaceholderDark}
+					alt=""
+					className="max-h-full max-w-full object-contain"
+					aria-hidden="true"
+				/>
+			</ImageFrame>
+			<p className="text-center text-[length:var(--honeydeck-font-size-small)] leading-snug text-surface-foreground opacity-60">
+				Add{" "}
+				<code className="rounded-honeydeck bg-background px-4 py-1 font-mono">
+					image: /path/to/image.png
+				</code>{" "}
+				to frontmatter
+			</p>
+		</div>
+	);
+}
+
+export default function CleanImageLayout({
+	title,
+	children,
+	frontmatter,
+	rawChildren,
+}: LayoutProps<ImageFrontmatter>) {
+	const { image, darkImage, alt = "" } = frontmatter;
+	const hasImage = Boolean(image || darkImage);
+	const hasCaption = Boolean(children);
+
+	return (
+		<CleanDefaultLayout
+			title={title}
+			frontmatter={frontmatter}
+			rawChildren={rawChildren}
+		>
+			<figure className="m-0 flex h-full flex-col gap-8 p-0">
+				<div className="flex min-h-0 flex-1 flex-col items-center justify-center">
+					{hasImage ? (
+						<ImageFrame>
+							<ColorModeImage
+								src={image || imagePlaceholder}
+								darkSrc={darkImage}
+								alt={alt}
+								className="max-h-full max-w-full object-contain"
+							/>
+						</ImageFrame>
+					) : (
+						<PlaceholderBox />
+					)}
+				</div>
+
+				{hasCaption && (
+					<figcaption className="flex-shrink-0 pt-5 text-[length:var(--honeydeck-font-size-small)] leading-snug text-surface-foreground">
+						{children}
+					</figcaption>
+				)}
+			</figure>
+		</CleanDefaultLayout>
+	);
+}
+
+export const demo: LayoutDemo<ImageFrontmatter> = {
+	mdx: `---
+layout: Image
+image: ""
+darkImage: ""
+alt: Architecture diagram
+---
+
+# System Architecture
+
+Our distributed system in production.`,
+};

package/src/layouts/clean/ImageLeft.tsx

@@ -0,0 +1,27 @@
+import type { LayoutDemo, LayoutProps } from "../../runtime/types.ts";
+import type { DarkModeImageFrontmatter } from "../ColorModeImage.tsx";
+import { CleanImageSideLayout } from "./ImageSide.tsx";
+
+type ImageLeftFrontmatter = DarkModeImageFrontmatter & {
+	/** Accessible text for the image. */
+	alt?: string;
+};
+
+export default function CleanImageLeftLayout(
+	props: LayoutProps<ImageLeftFrontmatter>,
+) {
+	return <CleanImageSideLayout {...props} side="left" />;
+}
+
+export const demo: LayoutDemo<ImageLeftFrontmatter> = {
+	mdx: `---
+layout: ImageLeft
+image: ""
+darkImage: ""
+alt: Product detail
+---
+
+# Product Detail
+
+Use the body area for supporting context, bullets, or a short narrative beside the image.`,
+};

package/src/layouts/clean/ImageRight.tsx

@@ -0,0 +1,27 @@
+import type { LayoutDemo, LayoutProps } from "../../runtime/types.ts";
+import type { DarkModeImageFrontmatter } from "../ColorModeImage.tsx";
+import { CleanImageSideLayout } from "./ImageSide.tsx";
+
+type ImageRightFrontmatter = DarkModeImageFrontmatter & {
+	/** Accessible text for the image. */
+	alt?: string;
+};
+
+export default function CleanImageRightLayout(
+	props: LayoutProps<ImageRightFrontmatter>,
+) {
+	return <CleanImageSideLayout {...props} side="right" />;
+}
+
+export const demo: LayoutDemo<ImageRightFrontmatter> = {
+	mdx: `---
+layout: ImageRight
+image: ""
+darkImage: ""
+alt: Launch moment
+---
+
+# Launch Moment
+
+Pair a flush image with focused supporting content.`,
+};

package/src/layouts/clean/ImageSide.tsx

@@ -0,0 +1,113 @@
+import type { ReactNode } from "react";
+import type { LayoutProps } from "../../runtime/types.ts";
+import {
+	ColorModeImage,
+	type DarkModeImageFrontmatter,
+} from "../ColorModeImage.tsx";
+import {
+	verticalImagePlaceholder,
+	verticalImagePlaceholderDark,
+} from "../placeholders.ts";
+import { SlideFrame } from "../SlideFrame.tsx";
+import { hasTitle } from "../utils.ts";
+
+type CleanImageSideFrontmatter = DarkModeImageFrontmatter & {
+	alt?: string;
+};
+
+type ImageSide = "left" | "right";
+
+type CleanImageSideLayoutProps = LayoutProps<CleanImageSideFrontmatter> & {
+	side: ImageSide;
+};
+
+function CleanSideImage({
+	image,
+	darkImage,
+	alt,
+}: {
+	image?: string;
+	darkImage?: string;
+	alt: string;
+}) {
+	const hasImage = Boolean(image || darkImage);
+
+	return (
+		<div className="h-full min-h-0 overflow-hidden">
+			<ColorModeImage
+				src={image || verticalImagePlaceholder}
+				darkSrc={
+					darkImage || (hasImage ? undefined : verticalImagePlaceholderDark)
+				}
+				alt={hasImage ? alt : ""}
+				className="size-full object-cover"
+				aria-hidden={hasImage ? undefined : "true"}
+			/>
+		</div>
+	);
+}
+
+function CleanSideContent({
+	title,
+	children,
+	side,
+}: {
+	title: ReactNode | null;
+	children: ReactNode;
+	side: ImageSide;
+}) {
+	return (
+		<div
+			className={`flex min-h-0 flex-col overflow-hidden ${
+				side === "left"
+					? "py-[var(--honeydeck-slide-padding)] pr-[var(--honeydeck-slide-padding)]"
+					: "py-[var(--honeydeck-slide-padding)] pl-[var(--honeydeck-slide-padding)]"
+			}`}
+		>
+			{hasTitle(title) && (
+				<header className="mb-8 flex-shrink-0">
+					<h1 className="font-heading text-[length:var(--honeydeck-font-size-h2)] font-semibold leading-tight text-foreground">
+						{title}
+					</h1>
+				</header>
+			)}
+
+			<div className="min-h-0 flex-1 overflow-hidden">{children}</div>
+		</div>
+	);
+}
+
+export function CleanImageSideLayout({
+	title,
+	children,
+	frontmatter,
+	side,
+}: CleanImageSideLayoutProps) {
+	const { image, darkImage, alt = "" } = frontmatter;
+	const imagePane = (
+		<CleanSideImage image={image} darkImage={darkImage} alt={alt} />
+	);
+	const contentPane = (
+		<CleanSideContent title={title} side={side}>
+			{children}
+		</CleanSideContent>
+	);
+
+	return (
+		<SlideFrame padded={false}>
+			<div className="grid size-full grid-cols-2 gap-10">
+				{side === "left" ? (
+					<>
+						{imagePane}
+						{contentPane}
+					</>
+				) : (
+					<>
+						{contentPane}
+						{imagePane}
+					</>
+				)}
+			</div>
+		</SlideFrame>
+	);
+}

package/src/layouts/clean/Section.tsx

@@ -0,0 +1,35 @@
+/**
+ * Clean Section layout — simple centered section divider.
+ */
+
+import type { LayoutDemo, LayoutProps } from "../../runtime/types.ts";
+import { SlideFrame } from "../SlideFrame.tsx";
+import { hasTitle } from "../utils.ts";
+
+export default function CleanSectionLayout({ title, children }: LayoutProps) {
+	return (
+		<SlideFrame className="items-center justify-center text-center">
+			{hasTitle(title) && (
+				<h1 className="mb-7 max-w-5xl font-heading text-[length:var(--honeydeck-font-size-display)] font-semibold leading-none text-foreground">
+					{title}
+				</h1>
+			)}
+
+			{children && (
+				<div className="max-w-3xl text-[length:var(--honeydeck-font-size-body)] leading-snug text-surface-foreground">
+					{children}
+				</div>
+			)}
+		</SlideFrame>
+	);
+}
+
+export const demo: LayoutDemo = {
+	mdx: `---
+layout: Section
+---
+
+# Section Title
+
+An optional section subtitle or brief description.`,
+};

package/src/layouts/clean/TwoCol.tsx

@@ -0,0 +1,63 @@
+/**
+ * Clean TwoCol layout — two equal plain columns.
+ */
+
+import type { ReactNode } from "react";
+import type { LayoutDemo, LayoutProps } from "../../runtime/types.ts";
+import CleanDefaultLayout from "./Default.tsx";
+
+export function Left({ children }: { children?: ReactNode }) {
+	return (
+		<div data-honeydeck-slot="left" className="col-start-1 overflow-hidden">
+			{children}
+		</div>
+	);
+}
+
+export function Right({ children }: { children?: ReactNode }) {
+	return (
+		<div data-honeydeck-slot="right" className="col-start-2 overflow-hidden">
+			{children}
+		</div>
+	);
+}
+
+export default function CleanTwoColLayout({
+	title,
+	children,
+	frontmatter,
+	rawChildren,
+}: LayoutProps) {
+	return (
+		<CleanDefaultLayout
+			title={title}
+			frontmatter={frontmatter}
+			rawChildren={rawChildren}
+		>
+			<div className="grid h-full grid-cols-2 gap-10">{children}</div>
+		</CleanDefaultLayout>
+	);
+}
+
+export const demo: LayoutDemo = {
+	mdx: `---
+layout: TwoCol
+---
+
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+
+# Pros vs Cons
+
+<Left>
+## Pros
+
+- Fast
+- Simple
+</Left>
+
+<Right>
+## Cons
+
+- Limited
+</Right>`,
+};

package/src/layouts/clean/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Clean Honeydeck layout map.
+ *
+ * Same layout names and slot API as `@honeydeck/honeydeck/layouts`, with an explicit
+ * import path for decks that want to name the clean kit directly.
+ */
+
+import type { LayoutMap } from "../../runtime/types.ts";
+import BlankLayout from "./Blank.tsx";
+import CoverLayout from "./Cover.tsx";
+import DefaultLayout from "./Default.tsx";
+import ImageLayout from "./Image/Image.tsx";
+import ImageLeftLayout from "./ImageLeft.tsx";
+import ImageRightLayout from "./ImageRight.tsx";
+import SectionLayout from "./Section.tsx";
+import TwoColLayout from "./TwoCol.tsx";
+
+const cleanLayouts: LayoutMap = {
+	Default: DefaultLayout,
+	Blank: BlankLayout,
+	Cover: CoverLayout,
+	Section: SectionLayout,
+	TwoCol: TwoColLayout,
+	Image: ImageLayout,
+	ImageLeft: ImageLeftLayout,
+	ImageRight: ImageRightLayout,
+};
+
+export default cleanLayouts;
+
+export {
+	BlankLayout,
+	CoverLayout,
+	DefaultLayout,
+	ImageLayout,
+	ImageLeftLayout,
+	ImageRightLayout,
+	SectionLayout,
+	TwoColLayout,
+};

package/src/layouts/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Default Honeydeck layout map.
+ *
+ * Exported when no custom `layouts:` path is specified in deck frontmatter.
+ * Defaults are intentionally clean and minimal. Use
+ * `@honeydeck/honeydeck/layouts/bee` for the original playful Bee layouts.
+ *
+ * @example
+ * ```ts
+ * // layouts/index.ts — extend the default map
+ * import defaultLayouts from '@honeydeck/honeydeck/layouts'
+ * import { MyBrandCover } from './BrandCover'
+ *
+ * export default {
+ *   ...defaultLayouts,
+ *   Cover: MyBrandCover,
+ * } satisfies LayoutMap
+ * ```
+ */
+
+import type { LayoutMap } from "../runtime/types.ts";
+import { ColorModeImage } from "./ColorModeImage.tsx";
+import BlankLayout from "./clean/Blank.tsx";
+import CoverLayout from "./clean/Cover.tsx";
+import DefaultLayout from "./clean/Default.tsx";
+import ImageLayout from "./clean/Image/Image.tsx";
+import ImageLeftLayout from "./clean/ImageLeft.tsx";
+import ImageRightLayout from "./clean/ImageRight.tsx";
+import SectionLayout from "./clean/Section.tsx";
+import TwoColLayout from "./clean/TwoCol.tsx";
+
+const defaultLayouts: LayoutMap = {
+	Default: DefaultLayout,
+	Blank: BlankLayout,
+	Cover: CoverLayout,
+	Section: SectionLayout,
+	TwoCol: TwoColLayout,
+	Image: ImageLayout,
+	ImageLeft: ImageLeftLayout,
+	ImageRight: ImageRightLayout,
+};
+
+export default defaultLayouts;
+
+export type {
+	ColorModeImageProps,
+	DarkModeImageFrontmatter,
+} from "./ColorModeImage.tsx";
+// Re-export individual layouts for named imports
+export {
+	BlankLayout,
+	ColorModeImage,
+	CoverLayout,
+	DefaultLayout,
+	ImageLayout,
+	ImageLeftLayout,
+	ImageRightLayout,
+	SectionLayout,
+	TwoColLayout,
+};

package/src/layouts/placeholders.ts

@@ -0,0 +1,9 @@
+import imagePlaceholderUrl from "./bee/Image/placeholder.webp";
+import imagePlaceholderDarkUrl from "./bee/Image/placeholder-dark.webp";
+import verticalImagePlaceholderUrl from "./bee/Image/placeholder-vertical.webp";
+import verticalImagePlaceholderDarkUrl from "./bee/Image/placeholder-vertical-dark.webp";
+
+export const imagePlaceholder = imagePlaceholderUrl;
+export const imagePlaceholderDark = imagePlaceholderDarkUrl;
+export const verticalImagePlaceholder = verticalImagePlaceholderUrl;
+export const verticalImagePlaceholderDark = verticalImagePlaceholderDarkUrl;

package/src/layouts/utils.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared utility helpers for Honeydeck layout components.
+ */
+
+/** Joins class names, filtering falsy values. No external dependencies. */
+export function cn(...classes: (string | undefined | null | false)[]): string {
+	return classes.filter(Boolean).join(" ");
+}
+
+/** Returns true when `title` is a non-empty string. */
+export function hasTitle(title: unknown): title is string {
+	return title != null && title !== "";
+}

package/src/remark/SPEC.md

@@ -0,0 +1,49 @@
+# Honeydeck Remark Transform Specification
+
+> Observable behavior for code highlighting transforms.
+
+## Code Highlighting
+
+### Syntax Highlighting
+
+Honeydeck highlights fenced code blocks without author configuration. Unsupported or failed languages render as plain code using Honeydeck CSS tokens.
+
+### Step-Through Syntax
+
+````mdx
+```ts {2|4|all}
+const a = 1
+const b = 2
+console.log(a + b)
+```
+````
+
+Syntax:
+
+- `{2}` — highlight line 2 immediately; adds 0 timeline steps
+- `{2-3}` — highlight lines 2 through 3 immediately; adds 0 timeline steps
+- `{1,3}` — highlight lines 1 and 3 immediately; adds 0 timeline steps
+- `{2-3|5|all}` — start with lines 2-3 active, then step to line 5, then all
+- `|` separates code highlight groups; every group after the first adds one timeline step
+
+### Behavior
+
+- Stepped code blocks show the first metadata group immediately, including at slide step 0 when the block is visible
+- Each later code group adds one timeline step
+- `{1|3-4|6-7|all}` starts with line 1 active, then steps to lines 3-4, then lines 6-7, then all lines
+- Each active code group highlights only the specified lines (non-cumulative)
+- Non-highlighted lines are dimmed (`--honeydeck-code-line-dim-opacity`)
+- Dimming is applied by Honeydeck runtime markup/styles independently of Tailwind utility generation
+- Code steps participate in the same slide timeline as `Reveal` components
+- Unsupported/failed languages render as plain code using Honeydeck CSS tokens
+- Code blocks expose a hover/focus copy control that copies the original fenced code text, not the highlighted HTML
+
+### Visual Style
+
+- Highlighted lines: normal brightness
+- Non-highlighted lines: dimmed (reduced opacity)
+- No background stripe
+
+### Theme
+
+Code highlighting colors come from Honeydeck's built-in light/dark syntax themes, not from Honeydeck CSS tokens. Honeydeck does not expose syntax theme configuration. The `--honeydeck-code-line-dim-opacity` token controls dimming of non-highlighted lines.

package/src/remark/h1-extract.ts

@@ -0,0 +1,124 @@
+/**
+ * Remark plugin: extract the first h1 from each slide and parse YAML frontmatter.
+ *
+ * ### What it does
+ * 1. **Frontmatter extraction** — visits the `yaml` node created by
+ *    `remark-frontmatter`, parses the YAML string into a plain object, and
+ *    stores it as `vfile.data.frontmatter`. This makes per-slide frontmatter
+ *    (e.g. `layout: Cover`) available to the virtual-modules plugin without
+ *    an extra YAML parsing library.
+ *
+ * 2. **H1 extraction** — finds the first `heading[depth=1]` node in the AST,
+ *    reads its plain-text content via `mdast-util-to-string`, removes the node
+ *    from the tree, and stores the text as `vfile.data.title`. Layouts can
+ *    then render the title independently from the body, keeping its position
+ *    stable regardless of how many steps have been revealed.
+ *
+ * ### Plugin ordering
+ * This plugin must run AFTER `remark-frontmatter` (which creates the `yaml`
+ * node) and BEFORE any plugins that rely on a cleaned-up AST.
+ *
+ * Recommended order:
+ * ```ts
+ * remarkPlugins: [remarkFrontmatter, remarkH1Extract, remarkStepNumbering]
+ * ```
+ */
+
+import type { Heading, Parent, Root } from "mdast";
+import { toString as mdastToString } from "mdast-util-to-string";
+import type { Plugin } from "unified";
+import { visit } from "unist-util-visit";
+
+// ---------------------------------------------------------------------------
+// Simple YAML parser — handles flat key: value pairs.
+// Coerces booleans and numbers; everything else stays as a string.
+// ---------------------------------------------------------------------------
+
+function parseFlatYaml(yaml: string): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+
+	for (const line of yaml.split("\n")) {
+		const colonIdx = line.indexOf(":");
+		if (colonIdx === -1) continue;
+
+		const key = line.slice(0, colonIdx).trim();
+		const raw = line.slice(colonIdx + 1).trim();
+
+		if (!key) continue;
+
+		if (raw === "true") {
+			result[key] = true;
+		} else if (raw === "false") {
+			result[key] = false;
+		} else if (raw !== "" && !Number.isNaN(Number(raw))) {
+			result[key] = Number(raw);
+		} else if (
+			(raw.startsWith('"') && raw.endsWith('"')) ||
+			(raw.startsWith("'") && raw.endsWith("'"))
+		) {
+			result[key] = raw.slice(1, -1);
+		} else {
+			result[key] = raw;
+		}
+	}
+
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * Remark plugin that:
+ * 1. Parses `yaml` nodes (from remark-frontmatter) into `vfile.data.frontmatter`
+ * 2. Removes the first `h1` from the tree and stores its text in `vfile.data.title`
+ */
+export const remarkH1Extract: Plugin<[], Root> = () => (tree, vfile) => {
+	// ── Step 1: parse YAML frontmatter ──────────────────────────────────────
+	visit(tree, "yaml", (node) => {
+		const yamlNode = node as unknown as { value: string };
+		vfile.data.frontmatter = parseFlatYaml(yamlNode.value);
+	});
+
+	// ── Step 2: find and remove first h1 ────────────────────────────────────
+	// We collect the location during the visit and mutate after, to avoid
+	// iterator invalidation while unist-util-visit walks the tree.
+
+	type H1Location = {
+		index: number;
+		parent: Parent;
+		text: string;
+	};
+
+	let firstH1: H1Location | null = null;
+
+	visit(tree, "heading", (node, index, parent) => {
+		if (firstH1) return; // already found one — stop collecting
+		const heading = node as unknown as Heading;
+		if (
+			heading.depth === 1 &&
+			parent &&
+			index !== null &&
+			index !== undefined
+		) {
+			firstH1 = {
+				index: index as number,
+				parent: parent as unknown as Parent,
+				text: mdastToString(heading),
+			};
+		}
+	});
+
+	if (firstH1) {
+		// Remove the h1 node from its parent
+		(firstH1 as H1Location).parent.children.splice(
+			(firstH1 as H1Location).index,
+			1,
+		);
+		vfile.data.title = (firstH1 as H1Location).text;
+	} else {
+		// No h1 found — title is empty string
+		vfile.data.title = "";
+	}
+};

package/src/remark/index.ts

@@ -0,0 +1,4 @@
+export { remarkH1Extract } from "./h1-extract.ts";
+export type { StepGroup } from "./shiki-code-blocks.ts";
+export { remarkShikiCodeBlocks } from "./shiki-code-blocks.ts";
+export { remarkStepNumbering } from "./step-numbering.ts";