@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/motion/reveal.js

@@ -0,0 +1,133 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Slot } from "radix-ui";
+import { cn } from "../lib/cn.js";
+import { inViewport, ioSupported, motionAllowed, observe, transitionEnd } from "./core.js";
+const noopSubscribe = () => () => { };
+export const useIsoLayoutEffect = typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
+/**
+ * `true` when the component mounted on the client after hydration (a page switch, a tab, a
+ * replay); `false` when it was server-rendered and is being hydrated. Server-rendered content
+ * is already on screen, so it is never hidden again; fresh content may start hidden.
+ */
+export function useFreshMount() {
+    const hydrating = React.useSyncExternalStore(noopSubscribe, () => false, () => true);
+    const [fresh] = React.useState(!hydrating);
+    return fresh;
+}
+/**
+ * Scroll-reveal state machine on any element: `data-reveal-state` goes
+ * `pending → in → done`. CSS (motion.css) draws the states, so the hook only flips an attribute.
+ *
+ * - Server-rendered content that is already in view stays as it is (no flash, CLS 0).
+ * - Server-rendered content below the fold is hidden just before paint and revealed on scroll.
+ * - Freshly mounted content starts hidden and reveals when it enters the viewport.
+ * - Reduced motion, `data-motion="off"` or no IntersectionObserver → shown at once.
+ *
+ * Returns the props for the first render (spread them on the element).
+ */
+export function useReveal(ref, { once = true, rootMargin, threshold, stagger, disabled, onReveal } = {}) {
+    const fresh = useFreshMount();
+    const onRevealRef = React.useRef(onReveal);
+    onRevealRef.current = onReveal;
+    useIsoLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        let timer;
+        let frame = 0;
+        const set = (s) => el.setAttribute("data-reveal-state", s);
+        const show = () => {
+            if (el.getAttribute("data-reveal-state") !== "pending")
+                return;
+            set("in");
+            onRevealRef.current?.();
+            clearTimeout(timer);
+            // After the transition, drop the reveal styles so the element's own transitions
+            // (hover, focus) are its own again.
+            timer = setTimeout(() => el.getAttribute("data-reveal-state") === "in" && set("done"), transitionEnd(el, stagger) + 60);
+        };
+        if (disabled || !motionAllowed(el)) {
+            set("done");
+            return;
+        }
+        if (!ioSupported()) {
+            if (fresh)
+                frame = requestAnimationFrame(() => show());
+            else
+                set("done");
+            return () => cancelAnimationFrame(frame);
+        }
+        if (!fresh && inViewport(el)) {
+            set("done");
+            if (once)
+                return;
+        }
+        else
+            set("pending");
+        const stop = observe(el, (entry) => {
+            if (entry.isIntersecting) {
+                show();
+                if (once)
+                    stop();
+            }
+            else if (!once && entry.boundingClientRect.top > 0)
+                set("pending");
+        }, { rootMargin, threshold });
+        return () => {
+            stop();
+            clearTimeout(timer);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fresh, once, rootMargin, threshold, stagger, disabled]);
+    return { "data-reveal-state": fresh && !disabled ? "pending" : undefined };
+}
+function useComposedRef(...refs) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return React.useCallback((node) => {
+        for (const r of refs) {
+            if (typeof r === "function")
+                r(node);
+            else if (r)
+                r.current = node;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, refs);
+}
+const timing = (delay, duration, extra) => ({
+    ...(delay ? { "--vm-delay": `${delay}ms` } : null),
+    ...(duration ? { "--vm-duration": `${duration}ms` } : null),
+    ...extra,
+});
+/**
+ * Shows its content when it scrolls into view — opacity and transform only, so nothing moves
+ * (CLS 0). Server-rendered content is never hidden before hydration; reduced motion and
+ * `data-motion="off"` show it at once.
+ *
+ * ```tsx
+ * <Reveal effect="rise" delay={80}><Card>…</Card></Reveal>
+ * ```
+ */
+export const Reveal = React.forwardRef(function Reveal({ effect = "rise", delay, duration, once, rootMargin, threshold, disabled, onReveal, asChild, className, style, ...props }, ref) {
+    const inner = React.useRef(null);
+    const setRef = useComposedRef(ref, inner);
+    const initial = useReveal(inner, { once, rootMargin, threshold, disabled, onReveal });
+    const Comp = asChild ? Slot.Root : "div";
+    return _jsx(Comp, { ref: setRef, "data-reveal": effect, ...initial, className: cn("vm-reveal", className), style: { ...timing(delay, duration), ...style }, ...props });
+});
+/**
+ * Reveals its direct children one after another (the 13th and later share the last slot, so a
+ * long list never keeps people waiting). Use `asChild` on a list to keep its semantics.
+ *
+ * ```tsx
+ * <Stagger asChild step={70}><ul className="grid grid-cols-3">{plans.map(…)}</ul></Stagger>
+ * ```
+ */
+export const Stagger = React.forwardRef(function Stagger({ effect = "rise", step, delay, duration, once, rootMargin, threshold, disabled, onReveal, asChild, className, style, ...props }, ref) {
+    const inner = React.useRef(null);
+    const setRef = useComposedRef(ref, inner);
+    const initial = useReveal(inner, { once, rootMargin, threshold, disabled, onReveal, stagger: true });
+    const Comp = asChild ? Slot.Root : "div";
+    return (_jsx(Comp, { ref: setRef, "data-reveal": effect, "data-reveal-stagger": "", ...initial, className: cn("vm-stagger", className), style: { ...timing(delay, duration, step ? { "--vm-step": `${step}ms` } : undefined), ...style }, ...props }));
+});

package/dist/motion/scroll-shrink.d.ts

@@ -0,0 +1,18 @@
+import * as React from "react";
+export interface UseScrollShrinkOptions {
+    /** Scroll distance in px after which the header counts as scrolled. Default 24. */
+    threshold?: number;
+}
+/**
+ * Sticky header shrink: sets `data-scrolled` on the element once the page has scrolled past
+ * `threshold` (passive listener, rAF-throttled, no re-render). Pair it with the `vm-shrink`
+ * class, which tightens the bar with transforms only, so the content below never moves (CLS 0).
+ * Returns whether it is scrolled, for anything else you want to switch.
+ *
+ * ```tsx
+ * const ref = React.useRef<HTMLElement>(null);
+ * useScrollShrink(ref);
+ * <header ref={ref} className="vm-shrink sticky top-0">…</header>
+ * ```
+ */
+export declare function useScrollShrink(ref: React.RefObject<HTMLElement | null>, { threshold }?: UseScrollShrinkOptions): boolean;

package/dist/motion/scroll-shrink.js

@@ -0,0 +1,47 @@
+"use client";
+import * as React from "react";
+/**
+ * Sticky header shrink: sets `data-scrolled` on the element once the page has scrolled past
+ * `threshold` (passive listener, rAF-throttled, no re-render). Pair it with the `vm-shrink`
+ * class, which tightens the bar with transforms only, so the content below never moves (CLS 0).
+ * Returns whether it is scrolled, for anything else you want to switch.
+ *
+ * ```tsx
+ * const ref = React.useRef<HTMLElement>(null);
+ * useScrollShrink(ref);
+ * <header ref={ref} className="vm-shrink sticky top-0">…</header>
+ * ```
+ */
+export function useScrollShrink(ref, { threshold = 24 } = {}) {
+    const [scrolled, setScrolled] = React.useState(false);
+    React.useEffect(() => {
+        let raf = 0;
+        let last = null;
+        const update = () => {
+            raf = 0;
+            const next = window.scrollY > threshold;
+            if (next === last)
+                return;
+            last = next;
+            const el = ref.current;
+            if (el) {
+                if (next)
+                    el.setAttribute("data-scrolled", "");
+                else
+                    el.removeAttribute("data-scrolled");
+            }
+            setScrolled(next);
+        };
+        const onScroll = () => {
+            if (!raf)
+                raf = requestAnimationFrame(update);
+        };
+        update();
+        window.addEventListener("scroll", onScroll, { passive: true });
+        return () => {
+            cancelAnimationFrame(raf);
+            window.removeEventListener("scroll", onScroll);
+        };
+    }, [ref, threshold]);
+    return scrolled;
+}

package/dist/motion/skeleton-swap.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+export interface SkeletonSwapProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** While true the skeleton shows; when it turns false the content cross-fades in over it. */
+    loading: boolean;
+    /** The placeholder. Give it the content's size so the box does not jump when it leaves. */
+    skeleton: React.ReactNode;
+}
+/**
+ * Skeleton → content without a flash: both share one grid cell, the content fades in while the
+ * skeleton fades out, then the skeleton unmounts. `aria-busy` while loading. Content that is
+ * there from the first render never animates; reduced motion swaps at once.
+ *
+ * ```tsx
+ * <SkeletonSwap loading={isLoading} skeleton={<InvoiceSkeleton />}><InvoiceTable rows={rows} /></SkeletonSwap>
+ * ```
+ */
+export declare const SkeletonSwap: React.ForwardRefExoticComponent<SkeletonSwapProps & React.RefAttributes<HTMLDivElement>>;

package/dist/motion/skeleton-swap.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { motionAllowed } from "./core.js";
+import { useIsoLayoutEffect } from "./reveal.js";
+/**
+ * Skeleton → content without a flash: both share one grid cell, the content fades in while the
+ * skeleton fades out, then the skeleton unmounts. `aria-busy` while loading. Content that is
+ * there from the first render never animates; reduced motion swaps at once.
+ *
+ * ```tsx
+ * <SkeletonSwap loading={isLoading} skeleton={<InvoiceSkeleton />}><InvoiceTable rows={rows} /></SkeletonSwap>
+ * ```
+ */
+export const SkeletonSwap = React.forwardRef(function SkeletonSwap({ loading, skeleton, className, children, ...props }, ref) {
+    const inner = React.useRef(null);
+    const [prevLoading, setPrevLoading] = React.useState(loading);
+    const [leaving, setLeaving] = React.useState(false);
+    // Derived from the previous prop (React's "adjust state while rendering" pattern): the frame
+    // that flips loading → false already renders both layers, so nothing blinks.
+    if (prevLoading !== loading) {
+        setPrevLoading(loading);
+        setLeaving(!loading);
+    }
+    useIsoLayoutEffect(() => {
+        if (!leaving)
+            return;
+        if (!motionAllowed(inner.current)) {
+            setLeaving(false);
+            return;
+        }
+        const t = setTimeout(() => setLeaving(false), 700); // safety net if animationend never fires
+        return () => clearTimeout(t);
+    }, [leaving]);
+    return (_jsxs("div", { ref: (node) => {
+            inner.current = node;
+            if (typeof ref === "function")
+                ref(node);
+            else if (ref)
+                ref.current = node;
+        }, "aria-busy": loading || undefined, "data-loading": loading ? "" : undefined, className: cn("vm-swap", className), ...props, children: [loading ? null : (_jsx("div", { className: "vm-swap-content", "data-entering": leaving ? "" : undefined, children: children })), loading || leaving ? (_jsx("div", { className: "vm-swap-skeleton", "aria-hidden": !loading || undefined, "data-leaving": loading ? undefined : "", onAnimationEnd: (e) => e.target === e.currentTarget && setLeaving(false), children: skeleton })) : null] }));
+});

package/dist/motion/text-reveal.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+import { type UseRevealOptions } from "./reveal.js";
+type TextTag = "h1" | "h2" | "h3" | "h4" | "p" | "span" | "div" | "blockquote";
+export interface TextRevealProps extends Omit<React.HTMLAttributes<HTMLElement>, "children">, Omit<UseRevealOptions, "stagger"> {
+    /** The text. In `by="line"` mode, `\n` separates lines. */
+    children: string;
+    /** Element to render. Default `"h2"`. */
+    as?: TextTag;
+    /** Split into words (default) or lines. */
+    by?: "word" | "line";
+    /**
+     * mask: each unit rises from behind its own baseline (default) · fade · blur.
+     */
+    effect?: "mask" | "fade" | "blur";
+    /** ms between two units. Default 45 (words) / 110 (lines). */
+    step?: number;
+    /** Delay before the first unit, in ms. */
+    delay?: number;
+}
+/**
+ * A heading that reveals word by word (or line by line) as it scrolls into view. Assistive
+ * tech gets one plain string: the split copy is `aria-hidden`, the real text is a visually
+ * hidden twin. Transform and opacity only; reduced motion shows it at once.
+ *
+ * ```tsx
+ * <TextReveal as="h2">Small rooms, slow mornings, nothing to scroll.</TextReveal>
+ * ```
+ */
+export declare const TextReveal: React.ForwardRefExoticComponent<TextRevealProps & React.RefAttributes<HTMLElement>>;
+export {};

package/dist/motion/text-reveal.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useReveal } from "./reveal.js";
+/**
+ * A heading that reveals word by word (or line by line) as it scrolls into view. Assistive
+ * tech gets one plain string: the split copy is `aria-hidden`, the real text is a visually
+ * hidden twin. Transform and opacity only; reduced motion shows it at once.
+ *
+ * ```tsx
+ * <TextReveal as="h2">Small rooms, slow mornings, nothing to scroll.</TextReveal>
+ * ```
+ */
+export const TextReveal = React.forwardRef(function TextReveal({ children, as: Tag = "h2", by = "word", effect = "mask", step, delay, once, rootMargin, threshold, disabled, onReveal, className, style, ...props }, ref) {
+    const inner = React.useRef(null);
+    const initial = useReveal(inner, { once, rootMargin, threshold, disabled, onReveal });
+    const text = String(children);
+    const units = by === "line" ? text.split("\n") : text.split(/\s+/).filter(Boolean);
+    const gap = step ?? (by === "line" ? 110 : 45);
+    const Comp = Tag;
+    return (_jsxs(Comp, { ref: (node) => {
+            inner.current = node;
+            if (typeof ref === "function")
+                ref(node);
+            else if (ref)
+                ref.current = node;
+        }, "data-reveal": effect === "mask" ? "text" : effect, "data-text-reveal": by, ...initial, className: cn("vm-text-reveal", className), style: { "--vm-step": `${gap}ms`, ...(delay ? { "--vm-delay": `${delay}ms` } : null), ...style }, ...props, children: [_jsx("span", { className: "sr-only", children: by === "line" ? units.join(" ") : text }), _jsx("span", { "aria-hidden": "true", className: "vm-text-reveal-visual", children: units.map((u, i) => (_jsxs(React.Fragment, { children: [_jsx("span", { className: "vm-tr-mask", children: _jsx("span", { className: "vm-tr-unit", style: { "--vm-i": i }, children: u }) }), by === "word" && i < units.length - 1 ? " " : null] }, i))) })] }));
+});

package/dist/motion/ticker.d.ts

@@ -0,0 +1,35 @@
+import * as React from "react";
+export interface TickerProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Seconds for one full loop. Default 40. */
+    duration?: number;
+    /** Which way the strip travels (mirrored in RTL). Default `"start"`. */
+    direction?: "start" | "end";
+    /** Element for each copy of the items, e.g. `"ul"` when the children are `li`. Default `"div"`. */
+    as?: "div" | "ul" | "ol";
+    /** Space between items (any CSS length). Default `clamp(2.5rem, 6cqi, 4.5rem)`. */
+    gap?: string;
+    /** Fade the start and end edges. Default true. */
+    fade?: boolean;
+    /**
+     * A small pause control (a native checkbox — works without JavaScript). Moving content that
+     * lasts longer than five seconds needs one (WCAG 2.2.2). Default true.
+     */
+    controls?: boolean;
+    /** Accessible name of the pause control. Default `"Pause animation"`. */
+    pauseLabel?: string;
+    /** Names the list of items (it lands on the first copy, e.g. the `ul`). */
+    "aria-label"?: string;
+    /** Classes for each copy of the items. */
+    groupClassName?: string;
+}
+/**
+ * The motion kit's marquee: an endless strip of logos or words that follows the motion level. Pure CSS (server component): the items are rendered
+ * twice and the track slides by one copy. The copy is `aria-hidden` and `inert`, so assistive
+ * tech and the keyboard meet every item once. Pauses on hover and focus and with its pause
+ * control; under reduced motion or `data-motion="off"` it becomes a static, wrapped row.
+ *
+ * ```tsx
+ * <Ticker as="ul" duration={30}>{logos.map((l) => <li key={l.name}>…</li>)}</Ticker>
+ * ```
+ */
+export declare const Ticker: React.ForwardRefExoticComponent<TickerProps & React.RefAttributes<HTMLDivElement>>;

package/dist/motion/ticker.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+/**
+ * The motion kit's marquee: an endless strip of logos or words that follows the motion level. Pure CSS (server component): the items are rendered
+ * twice and the track slides by one copy. The copy is `aria-hidden` and `inert`, so assistive
+ * tech and the keyboard meet every item once. Pauses on hover and focus and with its pause
+ * control; under reduced motion or `data-motion="off"` it becomes a static, wrapped row.
+ *
+ * ```tsx
+ * <Ticker as="ul" duration={30}>{logos.map((l) => <li key={l.name}>…</li>)}</Ticker>
+ * ```
+ */
+export const Ticker = React.forwardRef(function Ticker({ duration = 40, direction = "start", as: Group = "div", gap, fade = true, controls = true, pauseLabel = "Pause animation", groupClassName, className, style, children, "aria-label": ariaLabel, ...props }, ref) {
+    return (_jsxs("div", { ref: ref, "data-direction": direction, "data-fade": fade ? "" : undefined, className: cn("vm-marquee", className), style: { "--vm-marquee-duration": `${duration}s`, ...(gap ? { "--vm-marquee-gap": gap } : null), ...style }, ...props, children: [_jsx("div", { className: "vm-marquee-viewport", children: _jsxs("div", { className: "vm-marquee-track", children: [_jsx(Group, { className: cn("vm-marquee-group", groupClassName), "aria-label": ariaLabel, children: children }), _jsx(Group, { className: cn("vm-marquee-group", groupClassName), "aria-hidden": "true", inert: true, "data-marquee-copy": "", children: children })] }) }), controls ? (_jsxs("label", { className: "vm-marquee-toggle", children: [_jsx("input", { type: "checkbox", className: "vm-marquee-pause sr-only", "aria-label": pauseLabel }), _jsxs("svg", { "aria-hidden": "true", viewBox: "0 0 16 16", className: "vm-marquee-icon-pause", children: [_jsx("rect", { x: "4", y: "3", width: "2.5", height: "10", rx: "0.5" }), _jsx("rect", { x: "9.5", y: "3", width: "2.5", height: "10", rx: "0.5" })] }), _jsx("svg", { "aria-hidden": "true", viewBox: "0 0 16 16", className: "vm-marquee-icon-play", children: _jsx("path", { d: "M5 3.2v9.6a.5.5 0 0 0 .77.42l7.2-4.8a.5.5 0 0 0 0-.84l-7.2-4.8A.5.5 0 0 0 5 3.2Z" }) })] })) : null] }));
+});

package/dist/next/index.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+import { type VamosProviderProps } from "../lib/provider.js";
+/** The parts of Next.js the bindings need — pass the real imports. */
+export interface NextBindings {
+    /** `import Link from "next/link"` */
+    Link: React.ComponentType<any>;
+    /** `import Image from "next/image"` (optional; default `<img>`). */
+    Image?: React.ComponentType<any>;
+    /** `import { useRouter } from "next/navigation"` */
+    useRouter: () => {
+        push: (href: string, options?: {
+            scroll?: boolean;
+        }) => void;
+        replace: (href: string, options?: {
+            scroll?: boolean;
+        }) => void;
+    };
+    /** `import { usePathname } from "next/navigation"` */
+    usePathname: () => string | null;
+}
+export type NextVamosProviderProps = Omit<VamosProviderProps, "Link" | "Image" | "navigate">;
+/**
+ * Creates a `VamosProvider` wired to the Next.js App Router (Link, Image, `router.push/replace`,
+ * `usePathname`). Do it once in a client file and use the result in your root layout:
+ *
+ * ```tsx
+ * // app/providers.tsx
+ * "use client";
+ * import Link from "next/link";
+ * import Image from "next/image";
+ * import { usePathname, useRouter } from "next/navigation";
+ * import { createVamosNextProvider } from "@vamos-ui/react/next";
+ *
+ * export const Providers = createVamosNextProvider({ Link, Image, useRouter, usePathname });
+ *
+ * // app/layout.tsx (server)
+ * <Providers locale="tr-TR" messages={tr} timeZone="Europe/Istanbul" currency="TRY">{children}</Providers>
+ * ```
+ *
+ * Pass `currentPath` from the server layout too if you need the active nav item on first paint.
+ */
+export declare function createVamosNextProvider(next: NextBindings): ({ currentPath, children, ...props }: NextVamosProviderProps) => React.FunctionComponentElement<VamosProviderProps>;

package/dist/next/index.js

@@ -0,0 +1,36 @@
+"use client";
+// Public API of @vamos-ui/react/next — Next.js App Router bindings for VamosProvider.
+// The kit never imports `next/*` itself (it isn't a dependency); you hand the pieces in once.
+import * as React from "react";
+import { VamosProvider } from "../lib/provider.js";
+/**
+ * Creates a `VamosProvider` wired to the Next.js App Router (Link, Image, `router.push/replace`,
+ * `usePathname`). Do it once in a client file and use the result in your root layout:
+ *
+ * ```tsx
+ * // app/providers.tsx
+ * "use client";
+ * import Link from "next/link";
+ * import Image from "next/image";
+ * import { usePathname, useRouter } from "next/navigation";
+ * import { createVamosNextProvider } from "@vamos-ui/react/next";
+ *
+ * export const Providers = createVamosNextProvider({ Link, Image, useRouter, usePathname });
+ *
+ * // app/layout.tsx (server)
+ * <Providers locale="tr-TR" messages={tr} timeZone="Europe/Istanbul" currency="TRY">{children}</Providers>
+ * ```
+ *
+ * Pass `currentPath` from the server layout too if you need the active nav item on first paint.
+ */
+export function createVamosNextProvider(next) {
+    const Link = next.Link;
+    const Image = next.Image;
+    function NextVamosProvider({ currentPath, children, ...props }) {
+        const router = next.useRouter();
+        const pathname = next.usePathname();
+        const navigate = React.useCallback((href, options) => (options?.replace ? router.replace(href, { scroll: options.scroll }) : router.push(href, { scroll: options?.scroll })), [router]);
+        return React.createElement(VamosProvider, { ...props, Link, Image, navigate, currentPath: pathname ?? currentPath, children });
+    }
+    return NextVamosProvider;
+}

package/dist/render/block-renderer.d.ts

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { type BlockLabels } from "../blocks/labels.js";
+import { type PreparedDoc, type PrepareOptions, type Resolvers } from "./prepare.js";
+import type { BlockAdapters } from "../blocks/types.js";
+import type { BlockRegion } from "../blocks/schema/define-block.js";
+import type { VamosDoc } from "../blocks/schema/types.js";
+export interface RenderDocOptions extends PrepareOptions {
+    /** Framework bindings passed to every block (`{ Image: NextImage, Link: NextLink }`). */
+    components?: BlockAdapters;
+    /** Built-in strings (e.g. `blockLabelsTr`). */
+    labels?: Partial<BlockLabels>;
+    /** Show placeholders for unknown / invalid blocks. Default: `editMode` or not production. */
+    dev?: boolean;
+    /** Regions to render, in order. Default all four. */
+    regions?: readonly BlockRegion[];
+    /** Wrap the body in `<main id={mainId}>` (skip-link target). */
+    mainId?: string;
+    /** Emit one merged JSON-LD `@graph` script. Default true. */
+    jsonLd?: boolean;
+    /** Classes for the wrapper around consecutive text blocks. */
+    proseClassName?: string;
+}
+/** Edit/dev placeholder for a block that can't render normally. Server component. */
+export declare function BlockNotice({ tone, title, hint, type, blockId, }: {
+    tone?: "danger" | "warning";
+    title: string;
+    hint?: string;
+    type: string;
+    blockId?: string;
+}): React.JSX.Element;
+/** Renders an already prepared (and resolved) doc. */
+export declare function renderPrepared(prepared: PreparedDoc, opts: RenderDocOptions): React.ReactNode;
+/**
+ * Synchronous render of a VamosDoc (RSC-safe, also works in client trees and tests).
+ * `f.query` fields stay unresolved — use `<BlockRenderer resolvers>` for data-bound blocks.
+ *
+ * ```tsx
+ * renderDoc(page, { registry: siteBlocks, locale: "tr", components: { Image: NextImage, Link: NextLink } });
+ * ```
+ */
+export declare function renderDoc(doc: VamosDoc | unknown, opts: RenderDocOptions): React.ReactNode;
+export interface BlockRendererProps extends RenderDocOptions {
+    doc: VamosDoc | unknown;
+    /** Data for `f.query` fields, fetched in parallel on the server. */
+    resolvers?: Resolvers;
+}
+/**
+ * Async Server Component: filters hidden/scheduled blocks → migrates → validates (salvaging bad
+ * fields) → localizes → resolves queries in parallel → renders each block → merges JSON-LD.
+ *
+ * ```tsx
+ * <BlockRenderer doc={page} registry={siteBlocks} locale="tr" fallbackLocales={["en"]}
+ *   components={{ Image: NextImage, Link: NextLink }} resolvers={{ posts: (q) => db.posts.list(q) }} />
+ * ```
+ */
+export declare function BlockRenderer({ doc, resolvers, ...opts }: BlockRendererProps): Promise<React.ReactElement>;

package/dist/render/block-renderer.js

@@ -0,0 +1,137 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Container } from "../blocks/section.js";
+import { JsonLd, mergeJsonLd } from "../blocks/json-ld.js";
+import { renderInline } from "../blocks/rich-text.js";
+import { blockText } from "../blocks/labels.js";
+import { inlineToText } from "../blocks/schema/rich-doc.js";
+import { prepareDoc, resolveDoc } from "./prepare.js";
+const isProd = () => typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+/** Edit/dev placeholder for a block that can't render normally. Server component. */
+export function BlockNotice({ tone = "danger", title, hint, type, blockId, }) {
+    return (_jsx("div", { className: "vb-container py-4", "data-block-id": blockId, "data-block-type": type, "data-block-notice": tone, children: _jsxs("div", { role: "note", "data-tone": tone, className: "vb-notice flex flex-col gap-1 rounded-ui px-4 py-3.5 @2xl:flex-row @2xl:items-baseline @2xl:gap-4", children: [_jsx("span", { className: "shrink-0 font-mono text-eyebrow uppercase tracking-[0.08em] text-(--tone)", children: type }), _jsxs("span", { className: "text-small", children: [_jsx("strong", { className: "font-semibold text-fg", children: title }), hint ? _jsxs("span", { className: "text-fg-muted", children: [" \u2014 ", hint] }) : null] })] }) }));
+}
+function editAttrs(ctx, n) {
+    return ctx.opts.editMode ? { "data-block-id": n.node.id, "data-block-type": n.node.type, "data-hidden": n.node.hidden ? "" : undefined } : {};
+}
+/** Core text blocks (paragraph, heading, list, quote, code, divider) — render without a registry entry. */
+function renderCore(n, ctx, key) {
+    const { node } = n;
+    const p = (node.props ?? {});
+    const io = { components: ctx.opts.components, labels: ctx.opts.labels, locale: ctx.locale };
+    const attrs = editAttrs(ctx, n);
+    const children = (slot = "items") => (n.slots[slot] ?? []).map((c, i) => renderCore(c, ctx, `${key}-${i}`));
+    switch (node.type) {
+        case "paragraph":
+            return (_jsx("p", { ...attrs, children: renderInline(node.content, io) }, key));
+        case "heading": {
+            const level = Math.min(6, Math.max(1, p.level ?? 2));
+            const Tag = `h${level}`;
+            return (_jsx(Tag, { id: node.anchor, ...attrs, children: renderInline(node.content, io) }, key));
+        }
+        case "list": {
+            const Tag = p.ordered ? "ol" : "ul";
+            return (_jsx(Tag, { start: p.ordered && p.start && p.start !== 1 ? p.start : undefined, ...attrs, children: children() }, key));
+        }
+        case "list-item":
+            return (_jsxs("li", { ...attrs, children: [node.content?.length ? renderInline(node.content, io) : null, children()] }, key));
+        case "quote":
+            return (_jsxs("blockquote", { ...attrs, children: [node.content?.length ? _jsx("p", { children: renderInline(node.content, io) }) : null, children(), p.cite ? _jsx("footer", { children: p.cite }) : null] }, key));
+        case "code":
+            return (_jsx("pre", { "data-language": p.language, ...attrs, children: _jsx("code", { children: inlineToText(node.content) }) }, key));
+        case "divider":
+            return _jsx("hr", { ...attrs }, key);
+        default:
+            return null;
+    }
+}
+function renderNode(n, ctx, key) {
+    const { node, def } = n;
+    if (n.status === "core")
+        return renderCore(n, ctx, key);
+    if (n.status === "unknown") {
+        return ctx.dev ? _jsx(BlockNotice, { type: node.type, blockId: node.id, title: ctx.t("unknownBlock", { type: node.type }), hint: ctx.t("unknownBlockHint") }, key) : null;
+    }
+    if (n.status === "unrenderable" || !def?.component) {
+        return ctx.dev ? (_jsx(BlockNotice, { type: node.type, blockId: node.id, title: ctx.t("invalidBlock", { type: node.type }), hint: def?.component ? ctx.t("invalidBlockHint", { count: n.replaced.length || 1 }) : undefined }, key)) : null;
+    }
+    if (def.jsonLd) {
+        const ld = def.jsonLd(n.props, { locale: ctx.locale, node });
+        if (ld)
+            ctx.jsonLd.push(...(Array.isArray(ld) ? ld : [ld]));
+    }
+    const Component = def.component;
+    const slots = Object.fromEntries(Object.entries(n.slots).map(([k, list]) => [k, renderList(list, ctx, `${key}-${k}`)]));
+    const element = (_jsx(Component, { ...n.props, id: node.id, variant: node.variant ?? def.defaultVariant ?? def.variants?.[0], headingLevel: n.headingLevel, theme: node.theme, anchor: node.anchor, labels: ctx.opts.labels, locale: ctx.locale, components: ctx.opts.components, editMode: ctx.opts.editMode, slots: slots, block: { id: node.id, type: node.type, mode: ctx.opts.editMode ? "edit" : "view", v: node.v ?? def.version } }));
+    const notice = ctx.dev && (n.status === "invalid" || n.status === "newer") ? (_jsx(BlockNotice, { tone: "warning", type: node.type, title: n.status === "newer" ? ctx.t("newerBlock", { type: node.type, v: node.v ?? 1 }) : ctx.t("invalidBlock", { type: node.type }), hint: n.status === "invalid" ? ctx.t("invalidBlockHint", { count: n.replaced.length }) : undefined })) : null;
+    // display:contents keeps the block's own layout while builders map clicks with closest("[data-block-id]").
+    if (ctx.opts.editMode)
+        return (_jsxs("div", { style: { display: "contents" }, ...editAttrs(ctx, n), children: [notice, element] }, key));
+    return notice ? (_jsxs(React.Fragment, { children: [notice, element] }, key)) : (_jsx(React.Fragment, { children: element }, key));
+}
+/** Renders a list; consecutive core text blocks share one prose wrapper. */
+function renderList(list, ctx, keyPrefix) {
+    const out = [];
+    let run = [];
+    const flush = (i) => {
+        if (!run.length)
+            return;
+        const items = run;
+        run = [];
+        out.push(_jsx(Container, { size: "prose", className: cn("prose-ui vb-prose", ctx.opts.proseClassName), children: items.map((n, j) => renderCore(n, ctx, `${keyPrefix}-${i}-${j}`)) }, `${keyPrefix}-prose-${i}`));
+    };
+    list.forEach((n, i) => {
+        if (n.status === "core") {
+            run.push(n);
+            return;
+        }
+        flush(i);
+        out.push(renderNode(n, ctx, `${keyPrefix}-${i}`));
+    });
+    flush(list.length);
+    return out;
+}
+/** Renders an already prepared (and resolved) doc. */
+export function renderPrepared(prepared, opts) {
+    const ctx = {
+        opts,
+        dev: opts.dev ?? (!!opts.editMode || !isProd()),
+        t: blockText(opts.labels, prepared.locale),
+        jsonLd: [],
+        locale: prepared.locale,
+    };
+    const regions = opts.regions ?? ["header", "body", "footer", "overlay"];
+    const parts = regions.map((r) => {
+        const nodes = renderList(prepared[r], ctx, r);
+        if (r === "body" && opts.mainId)
+            return (_jsx("main", { id: opts.mainId, tabIndex: -1, className: "outline-none", children: nodes }, r));
+        return _jsx(React.Fragment, { children: nodes }, r);
+    });
+    const graph = opts.jsonLd === false ? null : mergeJsonLd(ctx.jsonLd);
+    return (_jsxs(_Fragment, { children: [parts, graph ? _jsx(JsonLd, { data: graph }) : null] }));
+}
+/**
+ * Synchronous render of a VamosDoc (RSC-safe, also works in client trees and tests).
+ * `f.query` fields stay unresolved — use `<BlockRenderer resolvers>` for data-bound blocks.
+ *
+ * ```tsx
+ * renderDoc(page, { registry: siteBlocks, locale: "tr", components: { Image: NextImage, Link: NextLink } });
+ * ```
+ */
+export function renderDoc(doc, opts) {
+    return renderPrepared(prepareDoc(doc, opts), opts);
+}
+/**
+ * Async Server Component: filters hidden/scheduled blocks → migrates → validates (salvaging bad
+ * fields) → localizes → resolves queries in parallel → renders each block → merges JSON-LD.
+ *
+ * ```tsx
+ * <BlockRenderer doc={page} registry={siteBlocks} locale="tr" fallbackLocales={["en"]}
+ *   components={{ Image: NextImage, Link: NextLink }} resolvers={{ posts: (q) => db.posts.list(q) }} />
+ * ```
+ */
+export async function BlockRenderer({ doc, resolvers, ...opts }) {
+    const prepared = await resolveDoc(prepareDoc(doc, opts), resolvers, opts.onIssue);
+    return _jsx(_Fragment, { children: renderPrepared(prepared, opts) });
+}