{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "preview-stage", "title": "Preview stage", "description": "A measured preview frame: a width switch with a ruler and shutters, scale to fit, light and dark, reload and open in a new tab, plus loading and error states with try again.", "dependencies": [ "lucide-react" ], "registryDependencies": [ "utils" ], "files": [ { "path": "registry/manniche/preview-stage/preview-stage.tsx", "content": "// Preview stage: shows a demo at a chosen width, like a measuring instrument. A ruler with two caliper jaws and a\n// readout says how wide the frame is, and two shutters close in from the sides when the frame is narrower than the\n// window. When the frame is wider than the window (1440 in a 700 px column), the content is scaled down to fit with\n// a transform, so you still see the whole layout; the note under the window says by how much.\n//\n// Content is either a page in an iframe (`src`; the theme goes into its URL through `themeParam`, by default as\n// `mode=light|dark`) or your own `children`. Plain children get the `dark` class in dark, so token-based content\n// follows; to show light content on a dark page, pass a function, which gets the width and theme to apply yourself.\n// Above the window: the width switch, a light/dark switch for the content, reload, and (for `src`) open in a new tab.\n//\n// States: loading shows a thin bar, but only after 300 ms, so a quick load never flashes; ready fades the content\n// in; error says so and offers Try again. An iframe on this origin is checked when it loads (the browser's error\n// page or an HTTP error status counts as failed), and any iframe that has not loaded `timeout` ms after it came into\n// view is an error. Pass `status` to drive the states yourself, and `onReload` to hear Reload and Try again.\n//\n// Keyboard: the width switch is a radio group (arrow keys). While focus is inside the stage, W steps the width\n// (Shift+W back) and T flips the theme; `shortcuts={false}` turns both off, hides their hints and drops\n// `aria-keyshortcuts` (WCAG 2.1.4). Width and theme changes, and a failed load, are announced politely. Try again\n// hands focus to Reload, since the button it was on goes away.\n//\n// Motion: jaws and shutters travel 300 ms, the width indicator 280 ms, the switch knob 260 ms, the readout digits\n// roll; all transform, all ease-out-quint. A change made from the keyboard jumps straight there, and so does\n// everything under reduced motion (the loader then shows a still bar).\nimport { ArrowUpRight, RotateCw } from 'lucide-react'\nimport {\n useEffect,\n useId,\n useLayoutEffect,\n useRef,\n useState,\n useSyncExternalStore,\n type KeyboardEvent,\n type MouseEvent,\n type ReactNode,\n} from 'react'\nimport { useReducedMotion } from '@/registry/manniche/hooks/use-reduced-motion'\nimport { cn } from '@/lib/utils'\n\nexport type StageTheme = 'light' | 'dark'\nexport type StageStatus = 'loading' | 'ready' | 'error'\n\nexport type PreviewStageLabels = {\n /** The label of the width switch. */\n width: string\n /** The unit after each width, read out with it (\"320 px\"). */\n px: string\n dark: string\n light: string\n /** What the switch turns on; read after \"Dark Light:\". */\n themeSwitch: string\n reload: string\n /** The open-in-a-new-tab link (only with `src`). */\n open: string\n loading: string\n error: string\n retry: string\n /** The note under the window. `percent` is below 100 when the frame is scaled to fit. */\n frame: (width: number, percent: number) => string\n /** Announced when the width changes. */\n announceWidth: (width: number) => string\n /** Announced when the theme changes. */\n announceTheme: (theme: StageTheme) => string\n}\n\nconst LABELS: PreviewStageLabels = {\n width: 'Width',\n px: 'px',\n dark: 'Dark',\n light: 'Light',\n themeSwitch: 'light theme in the frame',\n reload: 'Reload the preview',\n open: 'Open the preview in a new tab',\n loading: 'Loading the preview',\n error: 'The preview could not load.',\n retry: 'Try again',\n frame: (width, percent) => (percent < 100 ? `Frame ${width} px ยท shown at ${percent} %` : `Frame ${width} px`),\n announceWidth: (width) => `Frame ${width} px wide`,\n announceTheme: (theme) => (theme === 'light' ? 'Light theme in the frame' : 'Dark theme in the frame'),\n}\n\n// The default `themeParam`: puts the theme into the URL as `mode=light|dark` and keeps the rest (relative stays relative).\nfunction modeParam(src: string, theme: StageTheme) {\n const hashAt = src.indexOf('#')\n const hash = hashAt < 0 ? '' : src.slice(hashAt)\n const rest = hashAt < 0 ? src : src.slice(0, hashAt)\n const q = rest.indexOf('?')\n const params = new URLSearchParams(q < 0 ? '' : rest.slice(q + 1))\n params.set('mode', theme)\n return `${q < 0 ? rest : rest.slice(0, q)}?${params}${hash}`\n}\n\nexport type PreviewStageProps = {\n /** Names the stage and the iframe (\"data-tile demo\"). */\n title: string\n /** A page to show in an iframe. */\n src?: string\n /** Or your own content. As a function it gets the width and theme; plain nodes get the `dark` class in dark. */\n children?: ReactNode | ((view: { width: number; theme: StageTheme }) => ReactNode)\n /** Builds the iframe URL for a theme. By default it sets `mode=light|dark` in the query and keeps the rest. */\n themeParam?: (src: string, theme: StageTheme) => string\n /** The widths to switch between, in CSS px. */\n widths?: number[]\n /** The width, if you control it. */\n width?: number\n /** The first width when you do not. Defaults to the widest. */\n defaultWidth?: number\n onWidthChange?: (width: number) => void\n /** The content's theme, if you control it. */\n theme?: StageTheme\n defaultTheme?: StageTheme\n onThemeChange?: (theme: StageTheme) => void\n /** Drive the states yourself. Without it, an iframe is loading until it loads, and `children` are ready. */\n status?: StageStatus\n /** Called on Reload and Try again (the stage reloads its own iframe or remounts `children` either way). */\n onReload?: () => void\n /** Milliseconds an iframe may take, counted once it is in view, before the stage shows the error. */\n timeout?: number\n /** A line beside the frame note, e.g. where the demo comes from. */\n caption?: ReactNode\n /** The window's height. Defaults to clamp(300px, 48vh, 540px). */\n height?: number | string\n /** W and T while focus is in the stage. Off: no keys, no hints, no aria-keyshortcuts. */\n shortcuts?: boolean\n /** Every visible and announced string, for other languages. */\n labels?: Partial\n className?: string\n}\n\nconst KEYCAP =\n 'shadow-[inset_0_-2px_0_color-mix(in_oklab,var(--foreground)_7%,transparent),0_0_0_1px_color-mix(in_oklab,var(--foreground)_10%,transparent),0_1px_2px_rgb(0_0_0/0.06)] dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.09),inset_0_-2px_0_rgb(0_0_0/0.42),0_0_0_1px_rgb(255_255_255/0.1)]'\nconst PIT =\n 'bg-foreground/[0.045] shadow-[inset_0_1px_2px_rgb(0_0_0/0.06),inset_0_0_0_1px_color-mix(in_oklab,var(--foreground)_7%,transparent)] dark:bg-black/35 dark:shadow-[inset_0_1px_2px_rgb(0_0_0/0.55),inset_0_0_0_1px_rgb(255_255_255/0.05)]'\nconst HINT =\n 'inline-grid h-5 min-w-5 flex-none place-items-center rounded-[5px] bg-muted px-[5px] font-mono text-[11px] leading-none text-muted-foreground shadow-[inset_0_1px_0_color-mix(in_oklab,var(--foreground)_8%,transparent),inset_0_-1.5px_0_rgb(0_0_0/0.18),0_0_0_1px_color-mix(in_oklab,var(--foreground)_8%,transparent)] @max-[35rem]:hidden [@media(hover:none)]:hidden'\nconst ROUND =\n 'inline-grid size-11 flex-none place-items-center rounded-full bg-muted text-muted-foreground transition-transform duration-100 ease-out-quint hover:text-foreground active:translate-y-px motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring'\nconst DOTS = 'bg-[radial-gradient(color-mix(in_oklab,var(--foreground)_9%,transparent)_1px,transparent_1.3px)] bg-[size:16px_16px]'\n\nfunction isTyping(target: EventTarget | null) {\n if (!(target instanceof HTMLElement)) return false\n return target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName)\n}\n\n// An iframe fires `load` even when its page failed. For a page on this origin the stage can look: no document (the\n// browser's own error page) or an HTTP error status means it failed. A page on another origin cannot be read, so\n// only the timeout can catch it.\n// False on the server and while hydrating, true after. The iframe waits for it: one that loads before React has\n// hydrated would fire its load event with no listener and sit at loading until the timeout.\nconst noSubscribe = () => () => {}\nconst useHydrated = () => useSyncExternalStore(noSubscribe, () => true, () => false)\n\nfunction frameFailed(frame: HTMLIFrameElement) {\n try {\n if (new URL(frame.src, location.href).origin !== location.origin) return false\n const doc = frame.contentDocument\n if (!doc || doc.URL === 'about:blank') return true\n const nav = frame.contentWindow?.performance.getEntriesByType('navigation')[0] as (PerformanceEntry & { responseStatus?: number }) | undefined\n return (nav?.responseStatus ?? 0) >= 400\n } catch {\n return false\n }\n}\n\n/** The readout's digits roll to the new width (transform only). */\nfunction Odometer({ value, still }: { value: number; still: boolean }) {\n const digits = String(value).split('')\n return (\n \n {digits.map((d, i) => (\n \n \n {Array.from({ length: 10 }, (_, n) => (\n \n {n}\n \n ))}\n \n \n ))}\n \n )\n}\n\n/** A framed, measured preview with a width switch, light/dark, reload and open in a new tab. */\nexport function PreviewStage({\n title,\n src,\n children,\n themeParam: buildSrc = modeParam,\n widths = [320, 768, 1440],\n width: widthProp,\n defaultWidth,\n onWidthChange,\n theme: themeProp,\n defaultTheme = 'dark',\n onThemeChange,\n status,\n onReload,\n timeout = 20000,\n caption,\n height,\n shortcuts = true,\n labels: labelsProp,\n className,\n}: PreviewStageProps) {\n const labels = { ...LABELS, ...labelsProp }\n const reduced = useReducedMotion()\n const widthLabelId = useId()\n const box = useRef(null)\n const group = useRef(null)\n const reloadButton = useRef(null)\n const hydrated = useHydrated()\n\n const [ownWidth, setOwnWidth] = useState(defaultWidth ?? widths[widths.length - 1])\n const [ownTheme, setOwnTheme] = useState(defaultTheme)\n const width = widthProp ?? ownWidth\n const theme = themeProp ?? ownTheme\n const [size, setSize] = useState({ w: 0, h: 0 })\n const [instant, setInstant] = useState(false)\n const [reloads, setReloads] = useState(0)\n const [seen, setSeen] = useState(false)\n const [said, setSaid] = useState('')\n\n // The iframe's own state belongs to one URL and one reload; a new one starts out loading.\n const frameSrc = src ? buildSrc(src, theme) : undefined\n const loadKey = `${frameSrc ?? ''}#${reloads}`\n const [loaded, setLoaded] = useState<{ key: string; state: 'ready' | 'error' } | null>(null)\n const own: StageStatus = !src ? 'ready' : loaded?.key === loadKey ? loaded.state : 'loading'\n const state = status ?? own\n\n // Same text twice in a row still gets read: the no-break space makes it a change.\n const say = (text: string) => setSaid((prev) => (prev === text ? `${text}\\u00a0` : text))\n\n const still = instant || reduced\n const index = Math.max(0, widths.indexOf(width))\n const scale = size.w ? Math.min(1, size.w / width) : 1\n const open = size.w ? Math.min(1, (width * scale) / size.w) : 1\n const percent = Math.round(scale * 100)\n\n useLayoutEffect(() => {\n const el = box.current\n if (!el) return\n const measure = () => setSize((prev) => (prev.w === el.clientWidth && prev.h === el.clientHeight ? prev : { w: el.clientWidth, h: el.clientHeight }))\n measure()\n const ro = new ResizeObserver(measure)\n ro.observe(el)\n return () => ro.disconnect()\n }, [])\n\n // The timeout counts from when the window is first in view, since a lazy iframe off screen never loads.\n useEffect(() => {\n const el = box.current\n if (!el || seen || typeof IntersectionObserver === 'undefined') return\n const io = new IntersectionObserver((entries) => {\n if (entries.some((e) => e.isIntersecting)) setSeen(true)\n })\n io.observe(el)\n return () => io.disconnect()\n }, [seen])\n\n useEffect(() => {\n if (!src || own !== 'loading' || status || !(seen || typeof IntersectionObserver === 'undefined')) return\n const t = window.setTimeout(() => setLoaded({ key: loadKey, state: 'error' }), timeout)\n return () => window.clearTimeout(t)\n }, [src, own, seen, status, loadKey, timeout])\n\n const setWidth = (next: number, fromKey: boolean) => {\n setInstant(fromKey)\n if (next === width) return\n if (widthProp === undefined) setOwnWidth(next)\n onWidthChange?.(next)\n say(labels.announceWidth(next))\n }\n const stepWidth = (dir: number, fromKey: boolean, focus = false) => {\n const next = (index + dir + widths.length) % widths.length\n setWidth(widths[next], fromKey)\n if (focus) group.current?.querySelectorAll('[role=radio]')[next]?.focus()\n }\n const flipTheme = (fromKey: boolean) => {\n const next: StageTheme = theme === 'light' ? 'dark' : 'light'\n setInstant(fromKey)\n if (themeProp === undefined) setOwnTheme(next)\n onThemeChange?.(next)\n say(labels.announceTheme(next))\n }\n const reload = () => {\n setReloads((n) => n + 1)\n say(labels.loading)\n onReload?.()\n }\n const retry = () => {\n reload()\n reloadButton.current?.focus({ preventScroll: true })\n }\n\n const onKeyDown = (e: KeyboardEvent) => {\n if (!shortcuts || e.defaultPrevented || e.repeat || e.metaKey || e.ctrlKey || e.altKey || isTyping(e.target)) return\n const k = e.key.toLowerCase()\n if (k === 'w') {\n e.preventDefault()\n stepWidth(e.shiftKey ? -1 : 1, true)\n } else if (k === 't' && !e.shiftKey) {\n e.preventDefault()\n flipTheme(true)\n }\n }\n\n const onRadioKey = (e: KeyboardEvent) => {\n const step = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[e.key]\n if (step) {\n e.preventDefault()\n stepWidth(step, true, true)\n } else if (e.key === 'Home' || e.key === 'End') {\n e.preventDefault()\n const to = e.key === 'Home' ? 0 : widths.length - 1\n setWidth(widths[to], true)\n group.current?.querySelectorAll('[role=radio]')[to]?.focus()\n }\n }\n\n const content = typeof children === 'function' ? children({ width, theme }) : children\n const light = theme === 'light'\n\n return (\n
\n \n\n
\n
\n \n {labels.width}\n \n \n \n \n \n {widths.map((w, i) => (\n setWidth(w, e.detail === 0)}\n className={cn(\n 'relative flex min-h-11 items-center justify-center rounded-[10px] px-2.5 font-mono text-[13px] leading-none font-medium tabular-nums select-none',\n 'transition-transform duration-100 ease-out-quint active:translate-y-px motion-reduce:transition-none',\n 'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring',\n i === index ? 'text-foreground' : 'text-muted-foreground hover:text-foreground',\n )}\n >\n {w}\n {labels.px}\n \n ))}\n
\n {shortcuts && (\n \n W\n \n )}\n
\n\n
\n
\n flipTheme(e.detail === 0)}\n className=\"group/tog inline-flex min-h-11 items-center gap-2.5 rounded-full px-1 text-[13px] leading-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring\"\n >\n {labels.dark}\n \n \n \n {labels.light}\n \n {shortcuts && (\n \n T\n \n )}\n
\n
\n \n {frameSrc && (\n \n \n \n )}\n
\n
\n
\n\n
\n
\n \n {[-1, 1].map((side) => (\n \n \n
\n ))}\n
\n \n {labels.px}\n
\n
\n\n \n \n {frameSrc ? (\n hydrated && (\n setLoaded({ key: loadKey, state: frameFailed(e.currentTarget) ? 'error' : 'ready' })}\n onError={() => setLoaded({ key: loadKey, state: 'error' })}\n className={cn(\n 'block size-full border-0 transition-opacity duration-200 ease-out-quint motion-reduce:transition-none',\n state === 'ready' ? 'opacity-100' : 'pointer-events-none opacity-0',\n )}\n />\n )\n ) : (\n \n {content}\n \n )}\n \n\n {state === 'loading' && (\n \n \n \n \n {labels.loading}\n \n )}\n\n {state === 'error' && (\n
\n

{labels.error}

\n \n \n {labels.retry}\n \n
\n )}\n\n {[-1, 1].map((side) => (\n \n ))}\n \n\n

\n {labels.frame(width, percent)}\n {caption && {caption}}\n

\n \n\n

\n {state === 'error' ? labels.error : said}\n

\n \n )\n}\n", "type": "registry:component" }, { "path": "registry/manniche/hooks/use-reduced-motion.ts", "content": "import { useSyncExternalStore } from 'react'\n\nconst QUERY = '(prefers-reduced-motion: reduce)'\n\nfunction subscribe(onChange: () => void) {\n const mq = window.matchMedia(QUERY)\n mq.addEventListener('change', onChange)\n return () => mq.removeEventListener('change', onChange)\n}\n\n/** True when the visitor has asked the system for less motion. */\nexport function useReducedMotion() {\n return useSyncExternalStore(\n subscribe,\n () => window.matchMedia(QUERY).matches,\n () => false,\n )\n}\n", "type": "registry:hook" } ], "meta": { "tier": "free", "added": "2026-10-07", "usedIn": [], "props": [ { "name": "title", "type": "string", "default": null, "required": true, "description": "Names the stage and the iframe (\"data-tile demo\")." }, { "name": "src", "type": "string", "default": null, "required": false, "description": "A page to show in an iframe." }, { "name": "children", "type": "ReactNode | ((view: { width: number; theme: StageTheme }) => ReactNode)", "default": null, "required": false, "description": "Or your own content. As a function it gets the width and theme; plain nodes get the `dark` class in dark." }, { "name": "themeParam", "type": "(src: string, theme: StageTheme) => string", "default": "modeParam", "required": false, "description": "Builds the iframe URL for a theme. By default it sets `mode=light|dark` in the query and keeps the rest." }, { "name": "widths", "type": "number[]", "default": "[320, 768, 1440]", "required": false, "description": "The widths to switch between, in CSS px." }, { "name": "width", "type": "number", "default": null, "required": false, "description": "The width, if you control it." }, { "name": "defaultWidth", "type": "number", "default": null, "required": false, "description": "The first width when you do not. Defaults to the widest." }, { "name": "onWidthChange", "type": "(width: number) => void", "default": null, "required": false, "description": null }, { "name": "theme", "type": "StageTheme", "default": null, "required": false, "description": "The content's theme, if you control it." }, { "name": "defaultTheme", "type": "StageTheme", "default": "'dark'", "required": false, "description": null }, { "name": "onThemeChange", "type": "(theme: StageTheme) => void", "default": null, "required": false, "description": null }, { "name": "status", "type": "StageStatus", "default": null, "required": false, "description": "Drive the states yourself. Without it, an iframe is loading until it loads, and `children` are ready." }, { "name": "onReload", "type": "() => void", "default": null, "required": false, "description": "Called on Reload and Try again (the stage reloads its own iframe or remounts `children` either way)." }, { "name": "timeout", "type": "number", "default": "20000", "required": false, "description": "Milliseconds an iframe may take, counted once it is in view, before the stage shows the error." }, { "name": "caption", "type": "ReactNode", "default": null, "required": false, "description": "A line beside the frame note, e.g. where the demo comes from." }, { "name": "height", "type": "number | string", "default": null, "required": false, "description": "The window's height. Defaults to clamp(300px, 48vh, 540px)." }, { "name": "shortcuts", "type": "boolean", "default": "true", "required": false, "description": "W and T while focus is in the stage. Off: no keys, no hints, no aria-keyshortcuts." }, { "name": "labels", "type": "Partial", "default": null, "required": false, "description": "Every visible and announced string, for other languages." }, { "name": "className", "type": "string", "default": null, "required": false, "description": null } ], "a11y": [ { "topic": "keyboard", "text": "The width switch is a radio group with one Tab stop: arrow keys, Home and End move it. The theme control is a switch. W and T change width and theme only while focus is inside the stage, and shortcuts={false} turns them off. Try again moves focus to Reload.", "keys": [ "ArrowLeft", "ArrowRight", "Home", "End", "W", "T" ] }, { "topic": "screen-reader", "text": "The stage is a group named by title. A polite status announces width, theme, loading and error. Icon buttons have names; the ruler and shutters are aria-hidden." }, { "topic": "motion", "text": "The shutters and scale use transform; under reduced motion they jump to the end state. The loader shows only after 300 ms." } ] }, "categories": [ "surfaces" ], "type": "registry:component" }