@honeydeck/honeydeck 0.1.0

package/src/layouts/SPEC.md

@@ -0,0 +1,393 @@
+# Honeydeck Layouts and Kits Specification
+
+> Observable behavior for kits, layout maps, built-in layouts, layout props, and layout demos.
+
+## Kits — Theme, Layouts, Components
+
+A **kit** is an npm package (or local folder) that bundles three concerns. Honeydeck does not require a special registry mechanism; themes are CSS imports, layouts are default-exported layout maps, and components are normal React/MDX imports:
+
+| Concern | What it is | How it's used |
+|---------|-----------|---------------|
+| Theme | CSS file (tokens, colors, typography) | explicit CSS import from MDX or another CSS file |
+| Layouts | Layout component map | `layouts:` in frontmatter |
+| Components | Reusable React components | `import` in MDX |
+
+### Kit Package Structure
+
+```txt
+@company/honeydeck-kit-brand/
+  package.json
+  theme.css              ← CSS tokens/variables
+  layouts/
+    index.ts             ← exports LayoutMap
+    Blank.tsx
+    Default.tsx
+    Cover.tsx
+    Section.tsx
+    TwoCol.tsx
+    Image.tsx
+    ImageLeft.tsx
+    ImageRight.tsx
+  components/
+    Callout.tsx
+    Badge.tsx
+```
+
+### Using a Kit
+
+```mdx
+---
+title: My Talk
+layouts: "@company/honeydeck-kit-brand/layouts"
+---
+
+import '@company/honeydeck-kit-brand/theme.css'
+import './my-overrides.css'
+
+import { Callout } from '@company/honeydeck-kit-brand/components'
+
+# First slide
+
+<Callout>Important!</Callout>
+```
+
+### Mix and Match
+
+Theme CSS from one kit, layouts from another, components from a third:
+
+```mdx
+---
+layouts: "@company/honeydeck-kit-brand/layouts"
+---
+
+import '@other/honeydeck-kit-minimal/theme.css'
+import { Badge } from '@third/honeydeck-kit-fancy/components'
+```
+
+### Local Kits
+
+Create a kit in your project folder:
+
+```txt
+awesome-talk/
+  theme.css
+  layouts/
+    index.ts
+    MyCustom.tsx
+```
+
+Reference locally (relative to the deck entry file):
+
+```yaml
+---
+layouts: "./layouts"
+---
+```
+
+```mdx
+import './theme.css'
+```
+
+### Kit CSS Inheritance
+
+Use standard CSS `@import` for extending another kit's theme:
+
+```css
+/* theme.css — extends company kit */
+@import '@company/honeydeck-kit-brand/theme.css';
+
+:root {
+  --honeydeck-primary: oklch(55% 0.25 145);
+}
+```
+
+### Layout Inheritance
+
+Use JS spread to compose layouts from multiple sources:
+
+```ts
+// layouts/index.ts
+import companyLayouts from '@company/honeydeck-kit-brand/layouts'
+import fancyLayouts from '@fancy/honeydeck-kit/layouts'
+import { MyCustomCover } from './Cover'
+
+export default {
+  ...companyLayouts,
+  Section: fancyLayouts.Section,
+  Cover: MyCustomCover,
+} satisfies LayoutMap
+```
+
+### Zero Config
+
+A plain `deck.mdx` file with no frontmatter still works with built-in layouts:
+
+```mdx
+# Hello world
+
+This renders with the built-in default layout.
+```
+
+Styling is provided only by explicit CSS imports. Honeydeck does not auto-inject Tailwind, `@honeydeck/honeydeck/theme.css`, or kit theme CSS. The starter project imports `./styles.css` from `deck.mdx`; `styles.css` imports Tailwind and `@honeydeck/honeydeck/theme.css`. Without that import, slides still render with built-in layouts, but mostly with browser/default styling. User imports override via cascade.
+
+### Bundled Theme Layers
+
+Honeydeck ships optional theme layers that are imported after the base theme. Theme layers are token overrides and are not standalone replacements for the base theme:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+@import "@honeydeck/honeydeck/themes/clean.css";
+```
+
+Honeydeck includes:
+
+| Theme import | Purpose |
+|--------------|---------|
+| `@honeydeck/honeydeck/theme.css` | Preferred base theme import; clean black/white/grey defaults |
+| `@honeydeck/honeydeck/themes/base.css` | Package export alias for the base theme |
+| `@honeydeck/honeydeck/themes/clean.css` | Optional clean visual style layer |
+| `@honeydeck/honeydeck/themes/bee.css` | Bee theme layer for the original playful palette |
+
+Use `@honeydeck/honeydeck/layouts` for clean default layouts. Use `@honeydeck/honeydeck/layouts/bee` together with `@honeydeck/honeydeck/themes/bee.css` for the Bee visual style.
+
+### Progressive Customization
+
+```txt
+Level 0: plain `deck.mdx`    → built-in layouts, browser/default styling
+Level 1: import CSS             → Tailwind, base styling, and token overrides
+Level 2: set layouts:           → custom layout map
+Level 3: local kit folder       → full control
+Level 4: publish npm kit        → share across projects
+```
+
+---
+
+---
+
+## Layouts
+
+### Default Layouts
+
+Honeydeck provides eight clean default layouts. Honeydeck also ships `@honeydeck/honeydeck/layouts/clean` as a named clean kit import path and `@honeydeck/honeydeck/layouts/bee` for the playful Bee layouts:
+
+| Layout | Purpose |
+|--------|---------|
+| `Blank` | Empty slide just rendering children |
+| `Default` | Title top-left, body flows below in a padded content frame |
+| `Section` | Display-sized centered heading for section breaks |
+| `Cover` | Opening/closing slide (title, body, author/date) |
+| `TwoCol` | Default title area plus two equal body columns |
+| `Image` | Default title area plus image stage and optional caption |
+| `ImageLeft` | Left image pane, title and body content on the right |
+| `ImageRight` | Right image pane, title and body content on the left |
+
+### Layout Selection
+
+Via frontmatter (PascalCase by convention — Honeydeck treats the value as a string key in the layout map):
+
+```mdx
+---
+layout: Cover
+author: Hendrik
+---
+
+# Welcome to Honeydeck
+
+A modern slide framework.
+```
+
+If no `layout:` is specified, the deck's `defaultLayout` is used (`"Default"` unless overridden). In dev, unknown layouts warn in the browser console and fall back to the configured default, then `Default`, then the first available layout. In production/PDF, unknown layouts throw.
+
+### Layout Props
+
+Layouts receive parsed content:
+
+```ts
+type LayoutProps<F extends Record<string, unknown> = Record<string, unknown>> = {
+  title: ReactNode | null      // currently plain text from the first h1, or null
+  children: ReactNode          // remaining content (first h1 removed; later h1s remain)
+  rawChildren: ReactNode       // currently same compiled content as children
+  frontmatter: F               // slide frontmatter fields
+}
+```
+
+The first `h1` is extracted as plain text and provided as `title`. This enables layouts to position titles independently from body content. Titles stay in the same position at all times — revealed body content must not shift the title.
+
+Built-in layouts share a `SlideFrame` wrapper that provides full-canvas sizing, `--honeydeck-slide-padding`, `bg-background`, `text-foreground`, `font-body`, and overflow clipping. `Blank` renders an empty `SlideFrame` without title and display children. `Default` owns the common headline/body structure. `TwoCol` and `Image` compose with `Default`; `ImageLeft` and `ImageRight` use a shared side-image helper with matching title styling.
+
+### Layout-Specific Typed Frontmatter
+
+Layouts type their accepted frontmatter via the generic parameter:
+
+```tsx
+type CoverFrontmatter = {
+  author?: string
+  date?: string
+}
+
+export default function CoverLayout({ title, children, frontmatter }: LayoutProps<CoverFrontmatter>) {
+  const { author, date } = frontmatter
+  return (/* ... */)
+}
+```
+
+This enables editor tooling to extract props and provide autocomplete.
+
+### Layout Demos
+
+Layouts optionally export a `demo` for the docs reference page:
+
+```tsx
+export const demo: LayoutDemo<CoverFrontmatter> = {
+  mdx: `---
+layout: Cover
+author: Hendrik
+---
+
+# Welcome to My Talk
+
+Building the future of presentations.`,
+}
+```
+
+`mdx` is required on `LayoutDemo` and is the single source for both the live visual preview and the copyable snippet shown in the layouts docs tab. Honeydeck compiles this MDX with the same slide MDX compiler family, extracts frontmatter/title/steps from it, and renders the resulting slide through the active layout map. Honeydeck statically crawls analyzable active layout maps at build time and discovers colocated `demo` exports from layout modules. Dynamic maps, computed entries, non-static imports, and demos whose `mdx` value is not a static string may be skipped with warnings. If no static MDX demo is discovered, the layout still appears in the reference pages with a "No demo MDX provided" hint.
+
+### TwoCol Slot Components
+
+The `TwoCol` layout composes with `Default` for the shared title area, then renders its body as a Tailwind-styled two-column grid (`grid h-full grid-cols-2 gap-12`). It exports `<Left>` and `<Right>` slot components. These are thin wrappers that render `<div data-honeydeck-slot="left|right">` with Tailwind column utilities (`col-start-1` / `col-start-2`) and `overflow-hidden`.
+
+This works because MDX components return fragments: the slot divs become direct DOM children of the grid container without any intermediate wrapper. No JavaScript slot-detection logic is needed.
+
+```mdx
+---
+layout: TwoCol
+---
+
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+
+<Left>
+## Pros
+- Fast
+- Simple
+</Left>
+
+<Right>
+## Cons
+- Limited
+</Right>
+```
+
+Implementation uses Tailwind utility classes:
+
+```tsx
+<div className="grid h-full grid-cols-2 gap-12">
+  {children}
+</div>
+
+export function Left({ children }) {
+  return <div data-honeydeck-slot="left" className="col-start-1 overflow-hidden">{children}</div>
+}
+
+export function Right({ children }) {
+  return <div data-honeydeck-slot="right" className="col-start-2 overflow-hidden">{children}</div>
+}
+```
+
+### Image Layout
+
+The `Image` layout composes with `Default` for the shared title area, then renders a large centered image stage in the remaining space.
+
+Frontmatter:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `image` | `string` | none | Image URL/path (`/foo.png` for `public/foo.png`, relative import output, or external URL) |
+| `darkImage` | `string` | falls back to `image` | Optional image URL/path used when Honeydeck's effective color mode is dark |
+| `alt` | `string` | `""` | Alt text forwarded to the `<img>` |
+
+Behavior:
+
+- The image is wrapped in a surface-colored frame with shadow and border ring.
+- The frame clings to the intrinsic image size (`object-contain`) instead of filling the full stage.
+- If `darkImage` is provided, Honeydeck renders both variants and uses Tailwind utility classes keyed by Honeydeck's effective color mode to display the dark variant in dark mode, including pinned dark mode, system dark mode, and PDF `--mode dark`.
+- MDX body content after the title becomes a `<figcaption>` below the image with an accent left border.
+- If `image` is omitted, Honeydeck shows a bundled placeholder image plus a hint to add `image: /path/to/image.png`; the placeholder also uses its bundled dark variant in dark mode.
+
+```yaml
+---
+layout: Image
+image: /diagrams/architecture.png
+darkImage: /diagrams/architecture-dark.png
+alt: High-level architecture diagram
+---
+
+# System Architecture
+
+Our distributed system in production.
+```
+
+### Side Image Layouts
+
+`ImageLeft` and `ImageRight` place an image beside the slide content. They use the same `image`, `darkImage`, and `alt` frontmatter as `Image`.
+
+Frontmatter:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `image` | `string` | none | Image URL/path (`/foo.png` for `public/foo.png`, relative import output, or external URL) |
+| `darkImage` | `string` | falls back to `image` | Optional image URL/path used when Honeydeck's effective color mode is dark |
+| `alt` | `string` | `""` | Alt text forwarded to the `<img>` |
+
+Behavior:
+- `ImageLeft` renders the image on the left and title/body content on the right.
+- `ImageRight` renders title/body content on the left and the image on the right.
+- The image pane fills half of the slide and uses `object-cover`.
+- If `darkImage` is provided, Honeydeck renders both variants and uses Tailwind utility classes keyed by Honeydeck's effective color mode to display the dark variant in dark mode, including pinned dark mode, system dark mode, and PDF `--mode dark`.
+- If `image` is omitted, Honeydeck shows a bundled vertical placeholder image; the placeholder also uses its bundled dark variant in dark mode.
+
+```yaml
+---
+layout: ImageLeft
+image: /photos/product.jpg
+darkImage: /photos/product-dark.jpg
+alt: Product detail
+---
+
+# Product Detail
+
+Supporting copy beside the image.
+```
+
+### Custom Layouts (Project-Local)
+
+Project-local custom layouts are usually exposed through a layout map and selected with `layouts: "./layouts"` plus per-slide `layout:`. You can also use ad-hoc React components via explicit import and wrapping:
+
+```mdx
+---
+
+import { CustomLayout } from './components/CustomLayout'
+
+<CustomLayout>
+# Special Slide
+
+With custom styling.
+</CustomLayout>
+
+---
+```
+
+### Layout Resolution
+
+```txt
+layouts: not specified     → built-in default layout map
+layouts: "@pkg/layouts"    → layout map from npm package
+layouts: "./layouts"       → local layout map default export, relative to entry MDX
+```
+
+Within a layout map, per-slide:
+
+```txt
+layout: "Cover"    → layoutMap["Cover"]
+layout: not set    → layoutMap[defaultLayout]
+```

package/src/layouts/SlideFrame.tsx

@@ -0,0 +1,48 @@
+/**
+ * SlideFrame — shared wrapper for all slide layouts.
+ *
+ * Provides the common structure every layout needs:
+ * - Full-size container (fills the deck canvas)
+ * - Content padding from `--honeydeck-slide-padding` CSS variable
+ * - Flex column layout
+ * - Overflow clipping
+ *
+ * Layouts compose on top of this by passing `className` for their specific
+ * styling (background, text color, alignment, etc.).
+ *
+ * @example
+ * ```tsx
+ * <SlideFrame className="bg-primary text-primary-foreground items-center justify-center text-center">
+ *   <h1>Section Title</h1>
+ * </SlideFrame>
+ * ```
+ */
+
+import type { ReactNode } from "react";
+import { cn } from "./utils.ts";
+
+export type SlideFrameProps = {
+	children: ReactNode;
+	/** Additional Tailwind classes for layout-specific styling (bg, alignment, etc.) */
+	className?: string;
+	/** Set to false for layouts that manage their own padding (e.g. Image with edge-to-edge elements). */
+	padded?: boolean;
+};
+
+export function SlideFrame({
+	children,
+	className = "",
+	padded = true,
+}: SlideFrameProps) {
+	return (
+		<div
+			className={cn(
+				"relative size-full flex flex-col overflow-hidden bg-background text-foreground font-body",
+				padded && "p-[var(--honeydeck-slide-padding)]",
+				className,
+			)}
+		>
+			{children}
+		</div>
+	);
+}

package/src/layouts/bee/Blank.tsx

@@ -0,0 +1,12 @@
+import type { LayoutDemo, LayoutProps } from "../../runtime/types.ts";
+import { SlideFrame } from "../SlideFrame.tsx";
+
+export default function BlankLayout(props: LayoutProps) {
+	return <SlideFrame>{props.children}</SlideFrame>;
+}
+
+export const demo: LayoutDemo = {
+	mdx: `---
+layout: Blank
+---`,
+};

package/src/layouts/bee/Cover.tsx

@@ -0,0 +1,70 @@
+/**
+ * Cover layout — centered title, body copy, and author.
+ *
+ * Designed for opening and closing slides. Title is large and centered;
+ * body content and optional `author` frontmatter appear below.
+ */
+
+import type { LayoutDemo, LayoutProps } from "../../runtime/types.ts";
+import { SlideFrame } from "../SlideFrame.tsx";
+import { hasTitle } from "../utils.ts";
+
+type CoverFrontmatter = {
+	/** Speaker or organization shown below the cover body. */
+	author?: string;
+	/** Date or event label shown below the cover body. */
+	date?: string;
+};
+
+export default function CoverLayout({
+	title,
+	children,
+	frontmatter,
+}: LayoutProps<CoverFrontmatter>) {
+	const { author, date } = frontmatter;
+
+	return (
+		<SlideFrame className="items-center justify-center text-center">
+			{/* Large centered title */}
+			{hasTitle(title) && (
+				<h1 className="font-heading font-bold text-[length:var(--honeydeck-font-size-h1)] leading-tight text-primary mb-14">
+					{title}
+				</h1>
+			)}
+
+			{/* Slide body (MDX content after title) */}
+			{children && (
+				<div className="text-[length:var(--honeydeck-font-size-body)] text-surface-foreground font-light mb-18 max-w-4xl">
+					{children}
+				</div>
+			)}
+
+			{/* Author / date metadata */}
+			{(author || date) && (
+				<div className="flex items-center gap-14 text-[length:var(--honeydeck-font-size-small)] text-surface-foreground mt-9">
+					{author && <span>{author}</span>}
+					{author && date && <span className="text-border">·</span>}
+					{date && <span>{date}</span>}
+				</div>
+			)}
+
+			{/* Decorative accent bar */}
+			<div
+				className="absolute bottom-0 left-0 right-0 h-5 bg-accent"
+				aria-hidden="true"
+			/>
+		</SlideFrame>
+	);
+}
+
+export const demo: LayoutDemo<CoverFrontmatter> = {
+	mdx: `---
+layout: Cover
+author: The honeydeck team
+date: 2026
+---
+
+# Welcome to My Talk
+
+A modern slide framework.`,
+};

package/src/layouts/bee/Default.tsx

@@ -0,0 +1,42 @@
+/**
+ * Default layout — title top-left, body flows below.
+ *
+ * The most versatile layout for content slides. Title is pinned to the
+ * upper-left area and body content fills the remaining space.
+ */
+
+import type { LayoutDemo, LayoutProps } from "../../runtime/types.ts";
+import { SlideFrame } from "../SlideFrame.tsx";
+import { hasTitle } from "../utils.ts";
+
+export default function DefaultLayout({ title, children }: LayoutProps) {
+	return (
+		<SlideFrame>
+			{/* Title — always visible, layout-stable */}
+			{hasTitle(title) && (
+				<header className="mb-8 flex-shrink-0">
+					<h1 className="font-heading font-bold text-[length:var(--honeydeck-font-size-h2)] leading-tight text-primary">
+						{title}
+					</h1>
+					<div
+						className="mt-4 h-2 w-28 rounded-full bg-accent"
+						aria-hidden="true"
+					/>
+				</header>
+			)}
+
+			{/* Body content */}
+			<div className="flex-1 min-h-0 overflow-hidden">{children}</div>
+		</SlideFrame>
+	);
+}
+
+export const demo: LayoutDemo = {
+	mdx: `---
+layout: Default
+---
+
+# Default Layout
+
+Body content flows naturally below the title.`,
+};