@honeydeck/honeydeck 0.1.0

package/src/runtime/components/SPEC.md

@@ -0,0 +1,263 @@
+# Honeydeck Core Components Specification
+
+> Observable behavior for public built-in React components.
+
+## Core Components
+
+All core components are explicit imports from the `'@honeydeck/honeydeck'` package. They are also exported from `@honeydeck/honeydeck/components`:
+
+```mdx
+import { Reveal, RevealGroup, TimelineSteps, ListStyle, Keyboard, BrowserFrame, Notes } from '@honeydeck/honeydeck'
+```
+
+Injected fenced code blocks render through `HoneydeckCodeBlock` from the direct `@honeydeck/honeydeck/components/code-block` subpath. The component is not part of the public barrel, but transformed slide code blocks must show syntax-highlighted code and reveal an icon-only copy button on hover or keyboard focus. Copying writes the original fenced source text.
+
+### Color Mode Controls
+
+`@honeydeck/honeydeck/components` exports the configured color mode type and color mode cycle button for public imports used by Honeydeck chrome surfaces and the marketing site.
+
+```tsx
+import { ColorModeCycleButton, type ColorMode } from '@honeydeck/honeydeck/components'
+```
+
+Behavior:
+
+- `ColorMode` is `"system" | "light" | "dark"`.
+- `getNextColorMode(mode)` cycles `system` → `light` → `dark` → `system`.
+- `<ColorModeCycleButton>` renders the matching Lucide icon for the configured mode: monitor for `system`, sun for `light`, moon for `dark`.
+- Clicking the button calls `onSetColorMode` with the next configured mode.
+- The button accepts `className`, `iconSize`, `title`, and `ariaLabel` so slide chrome, reference pages, and other Honeydeck surfaces can share behavior while styling the control locally.
+
+### Button Controls
+
+`@honeydeck/honeydeck/components` exports generic Honeydeck-token-based button primitives and class recipes for runtime chrome, runtime reference pages, and marketing controls.
+
+```tsx
+import { Button, buttonPrimaryClass, iconButtonClass } from '@honeydeck/honeydeck/components'
+```
+
+Behavior:
+
+- `<Button>` renders a native `button` with `type="button"` by default.
+- `variant` selects one of `primary`, `secondary`, `icon`, `small`, or `quiet`.
+- `buttonClass(variant, className)` returns the matching token-based Tailwind class string and appends `className` when provided.
+- Exported class recipes use only shipped Honeydeck base-theme tokens for foreground, surface, border, primary, and transition behavior (`--honeydeck-primary`, `--honeydeck-primary-foreground`, `--honeydeck-surface`, `--honeydeck-surface-foreground`, `--honeydeck-border`, `--honeydeck-foreground`, `--honeydeck-background`) so public imports do not depend on marketing-only aliases at publish time.
+
+### Runtime chrome buttons
+
+Icon-only runtime chrome buttons, including the floating navigation bar actions, expose an explicit accessible name with `aria-label` and keep matching hover titles for the same action text.
+
+### `<Reveal>`
+
+Reveals content at the next timeline step.
+
+```mdx
+<Reveal>This appears at step 1</Reveal>
+<Reveal>This appears at step 2</Reveal>
+```
+
+Behavior:
+
+- Hidden content **reserves layout space** (`visibility: hidden` + `opacity: 0`, not `display: none`)
+- Runtime wrapper matches MDX context: flow/block reveals render a block-level `div`, text/inline reveals render an inline `span`
+- Nested reveals are supported; inline nested reveals inside paragraphs must not create invalid `div`-inside-`p` HTML
+- Default effect: fade in
+- Reveals are **cumulative** (once visible, stays visible)
+- Supports `className` for custom transitions
+- Supports `at?: number`; Honeydeck injects this during compilation and manual use works as an escape hatch
+- Supports `as?: "div" | "span"`; Honeydeck injects this during compilation and manual use works as an escape hatch
+- No `effect` prop
+
+### `<RevealGroup>`
+
+Convenience: reveals each meaningful direct child one by one. Whitespace-only text children are ignored. As a special case, when a direct child is a Markdown/HTML/JSX list, each item in that list is revealed one after another while preserving the list container. Empty groups currently consume one timeline step.
+
+```mdx
+<RevealGroup>
+  - First point
+  - Second point
+  - Third point
+</RevealGroup>
+```
+
+Each list item becomes its own timeline step.
+
+Nested timeline entries inside a group target are flattened after that target
+and before the following group target:
+
+```mdx
+<RevealGroup>
+  <div>
+    Parent item
+    <Reveal>Nested detail</Reveal>
+  </div>
+  <div>Sibling item</div>
+</RevealGroup>
+```
+
+Timeline:
+
+1. Parent item appears
+2. Nested detail appears
+3. Sibling item appears
+
+### `<ListStyle>`
+
+Styles Markdown/HTML/JSX lists inside a wrapper. By default, it removes bullets from every list inside it. With the `bullets` prop, it renders custom bullet markers and supports one marker per nesting level. Deeper levels reuse the last configured marker.
+
+```mdx
+import { ListStyle } from '@honeydeck/honeydeck'
+import { CheckIcon, CircleIcon } from 'lucide-react'
+
+<ListStyle>
+  - No marker
+  - Still aligned
+</ListStyle>
+
+<ListStyle bullets={[<CheckIcon />, <CircleIcon />]}>
+  - Level one uses a check icon
+    - Level two uses a circle icon
+</ListStyle>
+
+<ListStyle bullets={["→", "–", "·"]}>
+  - Level one
+    - Level two
+      - Level three
+</ListStyle>
+```
+
+Behavior:
+
+- Native list markers are removed for all nested lists in the wrapper.
+- `bullets` accepts a single React node/string marker or an array of markers by nesting level.
+- `bullets={false}`, `bullets="none"`, `bullets={null}`, or omitting `bullets` renders markerless lists.
+- Custom marker injection applies to authored list elements passed as children; native markers remain hidden for any deeper rendered lists because styling is scoped to the wrapper.
+
+### `<Keyboard>`
+
+Displays one keyboard key or a keyboard shortcut using semantic `<kbd>` markup.
+
+```mdx
+import { Keyboard } from '@honeydeck/honeydeck'
+
+Press <Keyboard>Esc</Keyboard> to close overview.
+
+Open command palette with <Keyboard keys={["Ctrl", "Shift", "P"]} />.
+
+Advance with <Keyboard keys="Space" />.
+```
+
+Props:
+
+- `keys?: ReactNode | ReactNode[]` — key label or ordered shortcut key labels.
+- `children?: ReactNode` — single key label when `keys` is omitted.
+- `separator?: ReactNode` — separator rendered between array entries; defaults to `+`.
+- `className?: string` — applied to the outer wrapper.
+
+Behavior:
+
+- A single `children` value or single `keys` value renders one `<kbd>`.
+- An array `keys` value renders one `<kbd>` per item, in order, separated by `separator`.
+- The component is inline by default so it works inside prose.
+- It uses Honeydeck default styling and can be customized with `className`.
+- It does not participate in the Honeydeck timeline.
+
+### `<BrowserFrame>`
+
+Displays an iframe inside a macOS-style browser window frame.
+
+```mdx
+import { BrowserFrame } from '@honeydeck/honeydeck'
+
+<BrowserFrame
+  src="https://example.com"
+  addressBar="example.com"
+  fallbackImage="/example-fallback-light.png"
+  fallbackDarkImage="/example-fallback-dark.png"
+/>
+```
+
+Props:
+
+- `src: string` — iframe URL.
+- `addressBar?: ReactNode` — optional content shown in the address-bar field. When omitted, no address-bar field is rendered.
+- `fallbackImage?: string` — light/default screenshot shown when the iframe cannot be loaded or fallback mode is toggled on.
+- `fallbackDarkImage?: string` — dark-mode screenshot shown in dark color mode; falls back to `fallbackImage` when omitted.
+- `fallbackAlt?: string` — accessible alt text for fallback images; defaults to `Fallback preview`.
+- `defaultFallback?: boolean` — initially render the fallback image instead of the iframe, useful for demos and final-state screenshots.
+- `aspectRatio?: CSSProperties["aspectRatio"]` — aspect ratio for the full browser window; defaults to `16 / 9`.
+- `className?: string` — applied to the outer wrapper.
+- `iframeClassName?: string` — applied to the iframe.
+- Standard iframe attributes such as `allow`, `sandbox`, `loading`, and `referrerPolicy` are forwarded.
+
+Behavior:
+
+- Renders a single `<iframe>` with a surrounding browser chrome.
+- The frame stretches to the largest size that fits its available parent space while preserving the configured aspect ratio, using CSS sizing (Tailwind utilities and container query units) rather than JavaScript measurement.
+- The chrome uses macOS traffic-light controls and an optional address-bar field.
+- When a fallback image is configured, iframe load errors switch the frame to fallback mode.
+- The fallback uses `fallbackDarkImage` in dark mode and `fallbackImage` otherwise.
+- While fallback mode is active, the top browser chrome shows a badge aligned with the address-bar field so presenters can see that the iframe is not live.
+- When a fallback image is configured, a fourth round control sits next to the macOS traffic-light controls. It is visible only when the control itself is hovered or keyboard-focused, and it toggles fallback mode on and off.
+- Styling uses Honeydeck theme tokens for surface, foreground, border, radius, font, and shadow colors.
+- The component does not participate in the Honeydeck timeline.
+
+### `<TimelineSteps>`
+
+Reserves a static block of timeline steps for an imported custom component.
+The custom component reads its local state with `useTimelineSteps()`.
+
+```mdx
+import { Reveal, TimelineSteps } from '@honeydeck/honeydeck'
+import { AccordionDemo } from './AccordionDemo'
+
+<Reveal>Intro appears first</Reveal>
+
+<TimelineSteps steps={3}>
+  <AccordionDemo />
+</TimelineSteps>
+
+<Reveal>Outro appears after the accordion</Reveal>
+```
+
+Inside `AccordionDemo`:
+
+```tsx
+import { useTimelineSteps } from '@honeydeck/honeydeck'
+
+export function AccordionDemo() {
+  const { phase, stepIndex, stepCount, isPdfFinalRender } = useTimelineSteps()
+  // phase: "before" | "active" | "after"
+  // stepIndex: 0 before start, 1..stepCount while active, stepCount after end
+  // isPdfFinalRender: true only for one-page final-state PDF export
+}
+```
+
+Behavior:
+
+- `steps` must be a literal positive integer in slide MDX, for example
+  `steps={3}`. Dynamic values are not supported because the timeline is counted
+  at build time.
+- `<TimelineSteps>` must appear at the usage site in slide MDX. Imported TSX
+  components cannot register steps by rendering `<TimelineSteps>` internally,
+  because their internals are not visible to the MDX compiler.
+- Nested Honeydeck timeline producers inside `<TimelineSteps>` are not supported.
+  Use the wrapper to reserve the block, then use `useTimelineSteps()` inside
+  the custom component.
+- Hook state includes `{ phase, stepIndex, stepCount, startAt, endAt, isPdfFinalRender }`.
+- In `isPdfFinalRender`, custom step components may render a PDF-specific final
+  composition, such as opening all accordion sections. Step-by-step PDF export
+  (`pdfSteps: all`) uses the normal timeline states and does not set this flag.
+
+### `<Notes>`
+
+Presenter notes. Hidden from audience view and normal PDF. Notes are collected in presenter mode through runtime context and are not emitted into the audience DOM. Markdown authored inside `<Notes>` renders as formatted speaker notes in presenter mode, including headings, paragraphs, lists, links, inline code, code blocks, and block quotes.
+
+```mdx
+<Notes>
+  # Demo cue
+
+  - Remember to demo the sparkle button here.
+  - Mention PDF export.
+</Notes>
+```

package/src/runtime/components/SlideNumberBadge.tsx

@@ -0,0 +1,11 @@
+export function SlideNumberBadge({ slide }: { slide: number }) {
+	return (
+		<div
+			role="status"
+			aria-label={`Slide ${slide}`}
+			className="absolute right-4 bottom-4 z-50 pointer-events-none text-3xl md:text-4xl tabular-nums text-foreground/75"
+		>
+			{slide}
+		</div>
+	);
+}

package/src/runtime/components/TimelineSteps.tsx

@@ -0,0 +1,115 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { useTimeline } from "../TimelineContext.tsx";
+
+export type TimelineStepsPhase = "before" | "active" | "after";
+
+export type TimelineStepsState = {
+	/** Local step index within this block. 0 before start, 1..stepCount while active. */
+	stepIndex: number;
+	/** Number of steps reserved by this block. */
+	stepCount: number;
+	/** Where the slide timeline is relative to this block. */
+	phase: TimelineStepsPhase;
+	/** First absolute slide step reserved by this block. */
+	startAt: number;
+	/** Last absolute slide step reserved by this block. */
+	endAt: number;
+	/**
+	 * True while `honeydeck pdf` is capturing one final-state page per slide.
+	 * Use this for components that should render an all-open/all-visible PDF state.
+	 */
+	isPdfFinalRender: boolean;
+};
+
+export type TimelineStepsProps = {
+	/**
+	 * Number of slide timeline steps reserved for the children.
+	 * Must be a literal positive integer in MDX.
+	 */
+	steps: number;
+	/**
+	 * First absolute slide step. Injected by the Honeydeck compiler.
+	 * Defaults to 1 only for direct runtime/test usage.
+	 */
+	at?: number;
+	children?: ReactNode;
+};
+
+const TimelineStepsContext = createContext<TimelineStepsState | null>(null);
+
+function assertPositiveInteger(value: number, propName: string): void {
+	if (!Number.isInteger(value) || value < 1) {
+		throw new Error(
+			`Honeydeck <TimelineSteps> requires ${propName} to be a positive integer.`,
+		);
+	}
+}
+
+/**
+ * Reserves a static block of slide timeline steps for a custom component.
+ *
+ * Wrap custom interactive content in `TimelineSteps`, then call
+ * `useTimelineSteps()` inside that content to read the local step index,
+ * total step count, phase, and PDF-final-render state.
+ *
+ * ```mdx
+ * import { TimelineSteps, useTimelineSteps } from '@honeydeck/honeydeck'
+ *
+ * function AccordionDemo() {
+ *   const { phase, stepIndex, stepCount, isPdfFinalRender } = useTimelineSteps()
+ *   return <div>{phase}: {stepIndex} / {stepCount}</div>
+ * }
+ *
+ * <TimelineSteps steps={3}>
+ *   <AccordionDemo />
+ * </TimelineSteps>
+ * ```
+ *
+ * Keep `steps` as a literal positive integer in slide MDX so Honeydeck can
+ * calculate the slide step count at build time. The compiler injects `at`;
+ * set it manually only in runtime tests or highly controlled custom usage.
+ */
+export function TimelineSteps({ steps, at = 1, children }: TimelineStepsProps) {
+	assertPositiveInteger(steps, "steps");
+	assertPositiveInteger(at, "at");
+
+	const { stepIndex: slideStepIndex, isPdfFinalRender } = useTimeline();
+	const startAt = at;
+	const endAt = at + steps - 1;
+
+	let phase: TimelineStepsPhase = "active";
+	let localStepIndex = slideStepIndex - startAt + 1;
+
+	if (slideStepIndex < startAt) {
+		phase = "before";
+		localStepIndex = 0;
+	} else if (slideStepIndex > endAt) {
+		phase = "after";
+		localStepIndex = steps;
+	}
+
+	const value: TimelineStepsState = {
+		stepIndex: localStepIndex,
+		stepCount: steps,
+		phase,
+		startAt,
+		endAt,
+		isPdfFinalRender,
+	};
+
+	return (
+		<TimelineStepsContext.Provider value={value}>
+			{children}
+		</TimelineStepsContext.Provider>
+	);
+}
+
+export function useTimelineSteps(): TimelineStepsState {
+	const value = useContext(TimelineStepsContext);
+	if (!value) {
+		throw new Error(
+			"Honeydeck useTimelineSteps() must be used inside <TimelineSteps>.",
+		);
+	}
+	return value;
+}

package/src/runtime/components/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Public runtime component exports for Honeydeck.
+ *
+ * These are the components that end users import in their MDX slides:
+ *
+ * ```mdx
+ * import { Reveal, RevealGroup, Notes } from '@honeydeck/honeydeck'
+ * ```
+ */
+
+export type { BrowserFrameProps } from "./BrowserFrame.tsx";
+export { BrowserFrame } from "./BrowserFrame.tsx";
+export type { ButtonProps, ButtonVariant } from "./Button.tsx";
+export {
+	Button,
+	buttonClass,
+	buttonPrimaryClass,
+	buttonSecondaryClass,
+	hoverBorderClass,
+	iconButtonClass,
+	quietLinkClass,
+	smallButtonClass,
+	surfaceControlClass,
+	transitionClass,
+} from "./Button.tsx";
+export type {
+	ColorMode,
+	ColorModeCycleButtonProps,
+} from "./ColorModeCycleButton.tsx";
+export {
+	COLOR_MODES,
+	ColorModeCycleButton,
+	getNextColorMode,
+} from "./ColorModeCycleButton.tsx";
+export type { KeyboardKey, KeyboardProps } from "./Keyboard.tsx";
+export { Keyboard } from "./Keyboard.tsx";
+export type { ListBullet, ListBullets, ListStyleProps } from "./ListStyle.tsx";
+export { ListStyle } from "./ListStyle.tsx";
+export type { NotesProps } from "./Notes.tsx";
+export { Notes } from "./Notes.tsx";
+export type { RevealProps } from "./Reveal.tsx";
+export { Reveal } from "./Reveal.tsx";
+export type { RevealGroupProps } from "./RevealGroup.tsx";
+export { RevealGroup } from "./RevealGroup.tsx";
+export type {
+	TimelineStepsPhase,
+	TimelineStepsProps,
+	TimelineStepsState,
+} from "./TimelineSteps.tsx";
+export { TimelineSteps, useTimelineSteps } from "./TimelineSteps.tsx";
+
+// HoneydeckCodeBlock is intentionally NOT exported from the public barrel.
+// It is an internal component injected by remarkShikiCodeBlocks via a
+// direct subpath import: '@honeydeck/honeydeck/components/code-block'.
+// Do not import it from '@honeydeck/honeydeck' or '@honeydeck/honeydeck/components' — use the subpath.

package/src/runtime/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Main Honeydeck runtime entry point.
+ *
+ * This is what end-users import in their MDX slides:
+ * ```mdx
+ * import { Reveal, RevealGroup, Notes } from '@honeydeck/honeydeck'
+ * ```
+ */
+
+export type { ColorModeImageProps } from "../layouts/ColorModeImage.tsx";
+export { ColorModeImage } from "../layouts/ColorModeImage.tsx";
+export type { BrowserFrameProps } from "./components/BrowserFrame.tsx";
+export { BrowserFrame } from "./components/BrowserFrame.tsx";
+export type { KeyboardKey, KeyboardProps } from "./components/Keyboard.tsx";
+export { Keyboard } from "./components/Keyboard.tsx";
+export type {
+	ListBullet,
+	ListBullets,
+	ListStyleProps,
+} from "./components/ListStyle.tsx";
+export { ListStyle } from "./components/ListStyle.tsx";
+export type { NotesProps } from "./components/Notes.tsx";
+export { Notes } from "./components/Notes.tsx";
+export type { RevealProps } from "./components/Reveal.tsx";
+export { Reveal } from "./components/Reveal.tsx";
+export type { RevealGroupProps } from "./components/RevealGroup.tsx";
+export { RevealGroup } from "./components/RevealGroup.tsx";
+export type {
+	TimelineStepsPhase,
+	TimelineStepsProps,
+	TimelineStepsState,
+} from "./components/TimelineSteps.tsx";
+export {
+	TimelineSteps,
+	useTimelineSteps,
+} from "./components/TimelineSteps.tsx";
+export type {
+	TimelineContextValue,
+	TimelineProviderProps,
+} from "./TimelineContext.tsx";
+// TimelineProvider and useTimeline are exported for kit/layout authors.
+export { TimelineProvider, useTimeline } from "./TimelineContext.tsx";

package/src/runtime/inputOwnership.ts

@@ -0,0 +1,68 @@
+const INTERACTIVE_SELECTOR = [
+	"button",
+	"a[href]",
+	"input",
+	"textarea",
+	"select",
+	"summary",
+	"[contenteditable='true']",
+	"[role='button']",
+	"[role='link']",
+].join(",");
+
+const SCROLL_OVERFLOW_VALUES = new Set(["auto", "scroll"]);
+
+function isElement(value: EventTarget | null): value is Element {
+	return typeof Element !== "undefined" && value instanceof Element;
+}
+
+function isHTMLElement(value: Element): value is HTMLElement {
+	return typeof HTMLElement !== "undefined" && value instanceof HTMLElement;
+}
+
+function allowsScroll(value: string): boolean {
+	return SCROLL_OVERFLOW_VALUES.has(value);
+}
+
+export function isInteractiveTarget(target: EventTarget | null): boolean {
+	if (!isElement(target)) return false;
+	return target.closest(INTERACTIVE_SELECTOR) !== null;
+}
+
+export function findScrollableAncestor(
+	target: EventTarget | null,
+	boundary?: Element | null,
+): HTMLElement | null {
+	if (!isElement(target)) return null;
+
+	let current: Element | null = target;
+	while (current && current !== boundary) {
+		if (isHTMLElement(current)) {
+			if (current.hasAttribute("data-honeydeck-scrollable")) return current;
+
+			const style = window.getComputedStyle(current);
+			const canScrollY =
+				allowsScroll(style.overflowY) &&
+				current.scrollHeight > current.clientHeight;
+			const canScrollX =
+				allowsScroll(style.overflowX) &&
+				current.scrollWidth > current.clientWidth;
+
+			if (canScrollY || canScrollX) return current;
+		}
+
+		current = current.parentElement;
+	}
+
+	return null;
+}
+
+export function shouldDeckOwnTouchGesture(
+	target: EventTarget | null,
+	boundary?: Element | null,
+): boolean {
+	if (!isElement(target)) return false;
+	if (target.closest("[data-honeydeck-no-swipe]")) return false;
+	if (isInteractiveTarget(target)) return false;
+	return findScrollableAncestor(target, boundary) === null;
+}

package/src/runtime/keyboardTarget.ts

@@ -0,0 +1,7 @@
+export function isEditableKeyboardTarget(target: EventTarget | null): boolean {
+	if (typeof HTMLElement === "undefined") return false;
+	if (!(target instanceof HTMLElement)) return false;
+
+	const tag = target.tagName;
+	return tag === "INPUT" || tag === "TEXTAREA" || target.isContentEditable;
+}

package/src/runtime/lastSlideRoute.ts

@@ -0,0 +1,56 @@
+import type { Route } from "./router.ts";
+
+const STORAGE_KEY = "honeydeck:last-slide-route";
+const FALLBACK_SLIDE_ROUTE: Route = { view: "slide", slide: 1, step: 0 };
+
+function isStorageAvailable(): boolean {
+	return typeof sessionStorage !== "undefined";
+}
+
+function toStoredSlideRoute(route: Route): Route | null {
+	if (route.view !== "slide") return null;
+
+	const slide =
+		Number.isFinite(route.slide) && route.slide >= 1 ? route.slide : 1;
+	const step = Number.isFinite(route.step) && route.step >= 0 ? route.step : 0;
+
+	return { view: "slide", slide, step };
+}
+
+export function rememberSlideRoute(route: Route): void {
+	const slideRoute = toStoredSlideRoute(route);
+	if (!slideRoute || !isStorageAvailable()) return;
+
+	try {
+		sessionStorage.setItem(STORAGE_KEY, JSON.stringify(slideRoute));
+	} catch {
+		// Session storage can be unavailable in restrictive browser contexts.
+	}
+}
+
+export function getRememberedSlideRoute(): Route {
+	if (!isStorageAvailable()) return FALLBACK_SLIDE_ROUTE;
+
+	try {
+		const value = sessionStorage.getItem(STORAGE_KEY);
+		if (!value) return FALLBACK_SLIDE_ROUTE;
+
+		const parsed = JSON.parse(value) as Partial<Route>;
+		const slide =
+			typeof parsed.slide === "number" &&
+			Number.isFinite(parsed.slide) &&
+			parsed.slide >= 1
+				? parsed.slide
+				: 1;
+		const step =
+			typeof parsed.step === "number" &&
+			Number.isFinite(parsed.step) &&
+			parsed.step >= 0
+				? parsed.step
+				: 0;
+
+		return { view: "slide", slide, step };
+	} catch {
+		return FALLBACK_SLIDE_ROUTE;
+	}
+}