@honeydeck/honeydeck 0.1.0

package/src/runtime/views/docs/ThemeTab.tsx

@@ -0,0 +1,110 @@
+import type { TokenManifestEntry } from "virtual:honeydeck/token-manifest";
+import * as tokenManifest from "virtual:honeydeck/token-manifest";
+import { useEffect, useState } from "react";
+import { Intro } from "./Intro.tsx";
+
+const { tokens } = tokenManifest;
+
+function colorLike(token: TokenManifestEntry): boolean {
+	const value = token.defaultValue.toLowerCase();
+	return (
+		value.startsWith("#") ||
+		value.startsWith("rgb(") ||
+		value.startsWith("hsl(") ||
+		value.startsWith("oklch(")
+	);
+}
+
+function TokenValue({ value }: { value: string }) {
+	return (
+		<code
+			className="block max-w-full overflow-hidden text-ellipsis whitespace-nowrap rounded-xs bg-surface px-2 py-1 font-mono text-xs text-surface-foreground"
+			title={value}
+		>
+			{value}
+		</code>
+	);
+}
+
+function ComputedTokenValue({ name }: { name: string }) {
+	const [value, setValue] = useState("");
+
+	useEffect(() => {
+		function read() {
+			setValue(
+				getComputedStyle(document.documentElement)
+					.getPropertyValue(name)
+					.trim(),
+			);
+		}
+
+		read();
+		const observer = new MutationObserver(read);
+		observer.observe(document.documentElement, {
+			attributes: true,
+			attributeFilter: ["data-honeydeck-color-mode"],
+		});
+		return () => observer.disconnect();
+	}, [name]);
+
+	return <TokenValue value={value || "—"} />;
+}
+
+export function ThemeTab() {
+	return (
+		<>
+			<Intro title="Theme tokens">
+				All{" "}
+				<code className="rounded-xs bg-surface px-1 py-0.5 font-mono">
+					--honeydeck-*
+				</code>{" "}
+				tokens. Descriptions come from CSS comments; computed values come from{" "}
+				<code className="rounded-xs bg-surface px-1 py-0.5 font-mono">
+					getComputedStyle
+				</code>
+				.
+			</Intro>
+
+			<div className="overflow-x-auto rounded-md border border-border">
+				<table className="w-full min-w-240 table-fixed border-collapse text-left text-md">
+					<thead className="border-b border-border bg-surface text-xs uppercase tracking-wider text-surface-foreground/60">
+						<tr>
+							<th className="w-[28%] px-4 py-3 font-medium">Token</th>
+							<th className="w-[32%] px-4 py-3 font-medium">Description</th>
+							<th className="w-[20%] px-4 py-3 font-medium">Default</th>
+							<th className="w-[20%] px-4 py-3 font-medium">Computed</th>
+						</tr>
+					</thead>
+					<tbody className="divide-y divide-border">
+						{tokens.map((token) => (
+							<tr key={token.name}>
+								<td className="px-4 py-3 align-top">
+									<div className="flex items-center gap-2">
+										{colorLike(token) && (
+											<span
+												className="size-5 shrink-0 rounded-xs border border-border"
+												style={{ backgroundColor: `var(${token.name})` }}
+											/>
+										)}
+										<code className="font-mono text-sm font-medium text-foreground">
+											{token.name}
+										</code>
+									</div>
+								</td>
+								<td className="px-4 py-3 align-top leading-6 text-foreground/70">
+									{token.description || "—"}
+								</td>
+								<td className="px-4 py-3 align-top">
+									<TokenValue value={token.defaultValue} />
+								</td>
+								<td className="px-4 py-3 align-top">
+									<ComputedTokenValue name={token.name} />
+								</td>
+							</tr>
+						))}
+					</tbody>
+				</table>
+			</div>
+		</>
+	);
+}

package/src/runtime/views/index.ts

@@ -0,0 +1,7 @@
+/**
+ * View exports for Honeydeck.
+ */
+
+export { DocsView } from "./DocsView.tsx";
+export { OverviewView } from "./OverviewView.tsx";
+export { PresenterView } from "./PresenterView.tsx";

package/src/runtime/views/overviewGrid.ts

@@ -0,0 +1,106 @@
+/**
+ * Helpers for overview-grid keyboard navigation.
+ *
+ * Arrow up/down must follow the grid the browser actually rendered. This keeps
+ * keyboard movement aligned with CSS after first layout and after resizes.
+ */
+
+export function countGridColumnsFromChildren(children: HTMLCollection): number {
+	const firstChild = children.item(0) as HTMLElement | null;
+	if (!firstChild) return 0;
+
+	const firstRowTop = firstChild.offsetTop;
+	let columns = 0;
+
+	for (const child of Array.from(children) as HTMLElement[]) {
+		if (Math.abs(child.offsetTop - firstRowTop) > 1) break;
+		columns += 1;
+	}
+
+	return columns;
+}
+
+export function countGridTemplateColumns(templateColumns: string): number {
+	const trimmed = templateColumns.trim();
+	if (!trimmed || trimmed === "none") return 0;
+
+	let depth = 0;
+	let count = 0;
+	let inTrack = false;
+
+	for (const char of trimmed) {
+		if (char === "(" || char === "[") depth += 1;
+		if (char === ")" || char === "]") depth = Math.max(0, depth - 1);
+
+		if (/\s/.test(char) && depth === 0) {
+			if (inTrack) count += 1;
+			inTrack = false;
+			continue;
+		}
+
+		inTrack = true;
+	}
+
+	if (inTrack) count += 1;
+
+	return count;
+}
+
+export function getOverviewGridColumnCount(grid: HTMLElement | null): number {
+	if (!grid) return 1;
+
+	const measuredColumns = countGridColumnsFromChildren(grid.children);
+	if (measuredColumns > 0) return measuredColumns;
+
+	const templateColumns = window.getComputedStyle(grid).gridTemplateColumns;
+	const computedColumns = countGridTemplateColumns(templateColumns);
+
+	return Math.max(1, computedColumns);
+}
+
+export type OverviewGridSelectionDirection =
+	| "ArrowRight"
+	| "ArrowLeft"
+	| "ArrowDown"
+	| "ArrowUp";
+
+export type OverviewGridSelectionMove = {
+	selected: number;
+	didMove: boolean;
+};
+
+export function getOverviewGridSelectionMove(
+	selected: number,
+	total: number,
+	columns: number,
+	direction: OverviewGridSelectionDirection,
+): OverviewGridSelectionMove {
+	if (total <= 0) return { selected: 0, didMove: false };
+
+	const columnCount = Math.max(1, columns);
+	const current = Math.min(Math.max(selected, 0), total - 1);
+
+	let next = current;
+
+	switch (direction) {
+		case "ArrowRight":
+			next = Math.min(current + 1, total - 1);
+			break;
+		case "ArrowLeft":
+			next = Math.max(current - 1, 0);
+			break;
+		case "ArrowDown": {
+			const lastRowStart = Math.floor((total - 1) / columnCount) * columnCount;
+			next =
+				current >= lastRowStart
+					? current
+					: Math.min(current + columnCount, total - 1);
+			break;
+		}
+		case "ArrowUp":
+			next = current < columnCount ? current : current - columnCount;
+			break;
+	}
+
+	return { selected: next, didMove: next !== current };
+}

package/src/runtime/views/presenterPreview.ts

@@ -0,0 +1,27 @@
+export type PresenterNextPreview = {
+	slideIndex: number;
+	stepIndex: number;
+} | null;
+
+export function getPresenterNextPreview({
+	currentIndex,
+	step,
+	stepCount,
+	totalSlides,
+}: {
+	currentIndex: number;
+	step: number;
+	stepCount: number;
+	totalSlides: number;
+}): PresenterNextPreview {
+	if (step < stepCount) {
+		return { slideIndex: currentIndex, stepIndex: step + 1 };
+	}
+
+	const nextSlideIndex = currentIndex + 1;
+	if (nextSlideIndex < totalSlides) {
+		return { slideIndex: nextSlideIndex, stepIndex: 0 };
+	}
+
+	return null;
+}

package/src/runtime/virtual-modules.d.ts

@@ -0,0 +1,98 @@
+/**
+ * TypeScript ambient declarations for Honeydeck virtual modules.
+ *
+ * These modules don't exist on disk — they're synthesised at build/dev time
+ * by `src/vite-plugin/virtual-modules.ts`. Without these declarations,
+ * TypeScript would reject any `import` statement targeting them.
+ */
+
+/** Barrel re-export of all slides in the deck. */
+declare module "virtual:honeydeck/slides" {
+	/** Total number of slides in the deck. */
+	export const slideCount: number;
+
+	// Individual slide components are exported as Slide0, Slide1, Slide2, …
+	// Per-slide metadata is exported as stepCount0, slideTitle0, slideFrontmatter0, slideLayout0, …
+	// They cannot be statically typed here because the count is dynamic.
+	// Access them via a cast:
+	//   import * as slideModules from 'virtual:honeydeck/slides';
+	//   const C = (slideModules as Record<string, unknown>)[`Slide${i}`] as ComponentType;
+	//   const title = (slideModules as Record<string, unknown>)[`slideTitle${i}`] as string;
+}
+
+/**
+ * CSS token manifest — all --honeydeck-* tokens with descriptions and default values.
+ * Generated at build time from src/theme/base.css.
+ */
+declare module "virtual:honeydeck/token-manifest" {
+	export type TokenManifestEntry = {
+		name: string;
+		description: string;
+		defaultValue: string;
+	};
+	export const tokens: TokenManifestEntry[];
+	export default tokens;
+}
+
+/** Active layout map and docs reference demo metadata. */
+declare module "virtual:honeydeck/layouts" {
+	import type {
+		CompiledLayoutDemo,
+		LayoutMap,
+		LayoutPropDoc,
+	} from "./types.ts";
+
+	export const layoutMap: LayoutMap;
+	export const layoutNames: string[];
+	export const layoutDemos: Record<string, CompiledLayoutDemo>;
+	export const layoutPropDocs: Record<string, LayoutPropDoc[]>;
+	export const layoutDemoWarnings: string[];
+	export default layoutMap;
+}
+
+/** Built-in component reference documentation metadata. */
+declare module "virtual:honeydeck/components" {
+	import type { ComponentType } from "react";
+	import type { ComponentDoc } from "./types.ts";
+
+	export const componentMap: Record<
+		string,
+		ComponentType<Record<string, unknown>>
+	>;
+	export const componentNames: string[];
+	export const componentDocs: Record<string, ComponentDoc>;
+	export const componentDocWarnings: string[];
+	export default componentMap;
+}
+
+/** Parsed deck-level frontmatter (the YAML block at the top of deck.mdx). */
+declare module "virtual:honeydeck/config" {
+	const config: Record<string, unknown>;
+
+	export { config };
+	export default config;
+}
+
+/**
+ * Individual compiled slide modules.
+ * Each slide exports its component as default, plus metadata named exports.
+ */
+declare module "virtual:honeydeck/slide/*.mdx" {
+	import type { ComponentType } from "react";
+
+	/** Compiled slide React component */
+	const Component: ComponentType;
+	export default Component;
+
+	/** Number of timeline steps on this slide (from remarkStepNumbering) */
+	export const stepCount: number;
+
+	/** Plain-text content of the first h1 (from remarkH1Extract) */
+	export const slideTitle: string;
+
+	/** Parsed YAML frontmatter for this slide (from remarkH1Extract) */
+	export const slideFrontmatter: Record<string, unknown>;
+
+	/** Layout name from frontmatter.layout, or '' for default */
+	export const slideLayout: string;
+}

package/src/theme/SPEC.md

@@ -0,0 +1,179 @@
+# Honeydeck Theme Specification
+
+> Observable behavior for design tokens, theme CSS, Tailwind mapping, and color modes.
+
+## Design Token System
+
+Honeydeck defines a CSS custom property contract. In the base theme, colors derive from a primary color using `oklch` relative color syntax. Light and dark modes each have their own primary. Theme layers may override any token directly.
+
+### Color Tokens (per mode)
+
+```css
+/* Source color — brand identity for this mode */
+--honeydeck-primary
+
+/* Text color on primary backgrounds */
+--honeydeck-primary-foreground
+
+/* Main slide background (derived from primary) */
+--honeydeck-background
+
+/* Main text color (derived from primary) */
+--honeydeck-foreground
+
+/* Secondary surfaces — cards, code blocks, callouts */
+--honeydeck-surface
+
+/* Text color on surface backgrounds */
+--honeydeck-surface-foreground
+
+/* Border/divider color */
+--honeydeck-border
+
+/* Accent — computed as the complementary hue by default */
+--honeydeck-accent
+
+/* Text on accent backgrounds */
+--honeydeck-accent-foreground
+
+/* Link color */
+--honeydeck-link-color                /* default: inherit */
+
+/* Border radius for cards, code blocks, buttons */
+--honeydeck-border-radius
+```
+
+### Typography Tokens
+
+Typography tokens are **shared across color modes** (not redefined per light/dark).
+
+The base font size seeds `rem` for the entire slide canvas (`font-size` on `:root`). All other sizes are expressed in `rem` so they scale proportionally.
+
+```css
+/* Font families */
+--honeydeck-font-heading
+--honeydeck-font-body
+--honeydeck-font-mono
+
+/* Base font size — sets :root font-size, everything scales relative to this */
+--honeydeck-font-size-base            /* default: 36px */
+
+/* Scale factor for heading progression (e.g. 1.25 = major third) */
+--honeydeck-font-scale                /* default: 1.25 */
+
+/* Body / paragraph text */
+--honeydeck-font-size-body            /* 1rem (= base) */
+
+/* Computed heading sizes (1rem × scale^n), individually overridable */
+--honeydeck-font-size-display         /* 1rem × scale⁵ */
+--honeydeck-font-size-h1              /* 1rem × scale⁴ */
+--honeydeck-font-size-h2              /* 1rem × scale³ */
+--honeydeck-font-size-h3              /* 1rem × scale² */
+--honeydeck-font-size-h4              /* 1rem × scale¹ */
+--honeydeck-font-size-small           /* 1rem ÷ scale */
+
+/* Code blocks */
+--honeydeck-font-size-code            /* 0.83rem */
+```
+
+### Layout Token
+
+```css
+/* Internal padding between slide edge and layout content */
+--honeydeck-slide-padding             /* default: 2rem */
+```
+
+Built-in layouts apply this via the shared `SlideFrame` wrapper. This is content padding inside the slide canvas, not a viewport inset.
+
+### Code Token
+
+```css
+/* Opacity for non-highlighted lines during step-through (0–1) */
+--honeydeck-code-line-dim-opacity     /* default: 0.4 */
+```
+
+> **Note:** Code block syntax highlighting colors come from Honeydeck's built-in syntax themes, not from Honeydeck tokens. Honeydeck does not expose custom syntax theme configuration. Only the dim-opacity token is part of the Honeydeck token contract; plain fallback code blocks use Honeydeck CSS tokens.
+
+### Light/Dark Mode
+
+Each mode defines its own `--honeydeck-primary`. All other color tokens derive from it:
+
+```css
+[data-honeydeck-color-mode="light"] {
+  --honeydeck-primary: oklch(50% 0.2 250);
+  --honeydeck-primary-foreground: oklch(from var(--honeydeck-primary) 98% 0.01 h);
+  --honeydeck-background: oklch(from var(--honeydeck-primary) 98% 0.01 h);
+  --honeydeck-foreground: oklch(from var(--honeydeck-primary) 15% 0.02 h);
+  --honeydeck-surface: oklch(from var(--honeydeck-primary) 94% 0.02 h);
+  --honeydeck-surface-foreground: oklch(from var(--honeydeck-primary) 20% 0.02 h);
+  --honeydeck-border: oklch(from var(--honeydeck-primary) 85% 0.03 h);
+  --honeydeck-accent: oklch(from var(--honeydeck-primary) l c calc(h + 180));
+  --honeydeck-accent-foreground: oklch(from var(--honeydeck-accent) 15% 0.01 h);
+  --honeydeck-link-color: inherit;
+  --honeydeck-border-radius: 0.5rem;
+}
+
+[data-honeydeck-color-mode="dark"] {
+  --honeydeck-primary: oklch(70% 0.2 250);
+  --honeydeck-primary-foreground: oklch(from var(--honeydeck-primary) 10% 0.01 h);
+  --honeydeck-background: oklch(from var(--honeydeck-primary) 12% 0.02 h);
+  --honeydeck-foreground: oklch(from var(--honeydeck-primary) 95% 0.01 h);
+  --honeydeck-surface: oklch(from var(--honeydeck-primary) 20% 0.03 h);
+  --honeydeck-surface-foreground: oklch(from var(--honeydeck-primary) 90% 0.02 h);
+  --honeydeck-border: oklch(from var(--honeydeck-primary) 30% 0.03 h);
+  --honeydeck-accent: oklch(from var(--honeydeck-primary) l c calc(h + 180));
+  --honeydeck-accent-foreground: oklch(from var(--honeydeck-accent) 95% 0.01 h);
+  --honeydeck-link-color: inherit;
+  --honeydeck-border-radius: 0.5rem;
+}
+```
+
+Any derived token can be explicitly overridden.
+
+### Tailwind Mapping
+
+Honeydeck uses Tailwind v4 `@theme` in `base.css` to map tokens to utilities:
+
+```css
+@theme {
+  --color-primary: var(--honeydeck-primary);
+  --color-primary-foreground: var(--honeydeck-primary-foreground);
+  --color-background: var(--honeydeck-background);
+  --color-foreground: var(--honeydeck-foreground);
+  --color-surface: var(--honeydeck-surface);
+  --color-surface-foreground: var(--honeydeck-surface-foreground);
+  --color-border: var(--honeydeck-border);
+  --color-accent: var(--honeydeck-accent);
+  --color-accent-foreground: var(--honeydeck-accent-foreground);
+  --color-link: var(--honeydeck-link-color);
+
+  --radius-honeydeck: var(--honeydeck-border-radius);
+  --font-heading: var(--honeydeck-font-heading);
+  --font-body: var(--honeydeck-font-body);
+  --font-mono: var(--honeydeck-font-mono);
+}
+```
+
+`base.css` also defines runtime fallback colors (`bg-error-surface`, `bg-void`, etc.) plus pixel-based spacing/text-size scales so runtime UI is not affected by the slide root font size.
+
+Base theme CSS owns global and generated-content styling that cannot be attached at a React call site: slide Markdown typography, documentation Markdown typography, Shiki-generated code descendants, and generated plain-code fallback markup. Honeydeck-owned React component wrappers use Tailwind utilities for their own layout and visual styling while preserving stable `honeydeck-*` class hooks where runtime code, PDF export, tests, or generated descendant styling need to find them.
+
+The base CSS also applies `--honeydeck-link-color` to slide anchors and underlines links. `cursor: pointer` is reserved for real links only: anchors with `href` (`a[href]`) in slide/doc content and runtime route links. Buttons and other non-link controls must not set `cursor: pointer`; they keep the default cursor. Theme CSS is exported as `@honeydeck/honeydeck/theme.css`, `@honeydeck/honeydeck/themes/base.css`, `@honeydeck/honeydeck/themes/clean.css`, and `@honeydeck/honeydeck/themes/bee.css`.
+
+Usage in MDX:
+
+```mdx
+<div className="bg-surface text-surface-foreground border border-border rounded-honeydeck">
+  Card content
+</div>
+```
+
+### Color Mode Behavior
+
+- Browser defaults to system preference
+- User can toggle via navigation controls (system / light / dark)
+- `colorMode:` frontmatter can pin the deck to one mode
+- PDF ignores system preference; if no PDF override or pinned deck mode exists, it uses light
+- PDF color mode resolves as CLI `--mode` > `pdfColorMode` > pinned `colorMode` (`light`/`dark`) > `light`
+- Renderer applies: `data-honeydeck-color-mode="light"` or `data-honeydeck-color-mode="dark"`
+- Base theme CSS sets browser `color-scheme` to match the effective Honeydeck color mode so built-in browser defaults and embedded rendered assets stay visually consistent in static builds and PDF export