@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/media/video-player.d.ts

@@ -0,0 +1,135 @@
+import * as React from "react";
+import { type ImageAspect } from "../components/image.js";
+import type { MediaAsset } from "./types.js";
+declare const videoLabels: {
+    player: string;
+    play: string;
+    pause: string;
+    replay: string;
+    playVideo: string;
+    seek: string;
+    time: string;
+    mute: string;
+    unmute: string;
+    volume: string;
+    captionsOn: string;
+    captionsOff: string;
+    speed: string;
+    speedValue: string;
+    normal: string;
+    pip: string;
+    fullscreen: string;
+    exitFullscreen: string;
+    error: string;
+    hlsUnsupported: string;
+    pauseBackground: string;
+    playBackground: string;
+};
+export type VideoPlayerLabels = typeof videoLabels;
+export type VideoSource = string | MediaAsset | {
+    url: string;
+    type: "mp4" | "webm" | "hls";
+}[];
+export interface VideoTrack {
+    src: string;
+    /** BCP 47, e.g. "en", "tr". */
+    lang: string;
+    label: string;
+    kind?: "subtitles" | "captions";
+    default?: boolean;
+}
+/** Minimal shape of the `hls.js` default export (optional peer, loaded on demand). */
+export interface HlsConstructor {
+    new (config?: Record<string, unknown>): {
+        loadSource(url: string): void;
+        attachMedia(el: HTMLMediaElement): void;
+        destroy(): void;
+        on?(event: string, cb: (...args: unknown[]) => void): void;
+    };
+    isSupported(): boolean;
+}
+/** `1:02:05` / `3:07`. */
+export declare function formatMediaTime(seconds: number, locale?: string): string;
+export declare const videoPlayerVariants: (props?: ({
+    rounded?: "ui" | "ui-lg" | "none" | null | undefined;
+    chrome?: "overlay" | "bar" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface VideoPlayerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onTimeUpdate" | "onEnded"> {
+    src: VideoSource;
+    poster?: string | MediaAsset;
+    /** Box ratio. Default: the asset's ratio, else 16/9. */
+    aspect?: ImageAspect;
+    tracks?: VideoTrack[];
+    autoPlay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+    playsInline?: boolean;
+    /** `custom` (default) kit controls · `native` browser controls · `none`. */
+    controls?: "custom" | "native" | "none";
+    /** `overlay` floats over the picture and hides while playing; `bar` stays visible. */
+    chrome?: "overlay" | "bar";
+    rounded?: "none" | "ui" | "ui-lg";
+    /** Accessible name, e.g. the video title. */
+    title?: string;
+    preload?: "none" | "metadata" | "auto";
+    /** Lazy loader for HLS streams in browsers without native HLS: `hls={() => import("hls.js")}`. */
+    hls?: () => Promise<{
+        default: HlsConstructor;
+    }>;
+    onEnded?: () => void;
+    onTimeUpdate?: (time: number) => void;
+    /** The `<video>` element. */
+    videoRef?: React.Ref<HTMLVideoElement>;
+    /** CORS mode, needed when caption tracks come from another origin. */
+    crossOrigin?: "anonymous" | "use-credentials";
+    labels?: Partial<VideoPlayerLabels>;
+}
+/**
+ * Consistent controls for self-hosted video: play, seek, time, volume, captions, speed,
+ * picture-in-picture and full screen. Keyboard: Space/K play, ←/→ 5 s, ↑/↓ volume, F full screen,
+ * M mute, C captions. HLS loads `hls.js` only when needed. The chrome is always dark, because
+ * video content is.
+ *
+ * ```tsx
+ * <VideoPlayer src="/media/onboarding.mp4" poster="/media/onboarding.jpg" title="Onboarding: your first week"
+ *   tracks={[{ src: "/media/onboarding.en.vtt", lang: "en", label: "English", default: true }]} />
+ * ```
+ */
+export declare const VideoPlayer: React.ForwardRefExoticComponent<VideoPlayerProps & React.RefAttributes<HTMLDivElement>>;
+export interface VideoEmbedProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    provider: "youtube" | "vimeo";
+    /** Video id (`dQw4w9WgXcQ`, `76979871`). */
+    id: string;
+    /** Required: names the play button and the iframe. */
+    title: string;
+    /** Facade image. YouTube default: the video's own thumbnail. Vimeo needs one. */
+    poster?: string;
+    aspect?: ImageAspect;
+    /** Start at second. */
+    start?: number;
+    rounded?: "none" | "ui" | "ui-lg";
+    labels?: Partial<VideoPlayerLabels>;
+}
+/**
+ * A privacy-friendly embed: a poster and a play button until clicked, then a
+ * `youtube-nocookie.com` (or `player.vimeo.com` with `dnt=1`) iframe. No third-party request,
+ * cookie or script before the visitor chooses to play.
+ */
+export declare const VideoEmbed: React.ForwardRefExoticComponent<VideoEmbedProps & React.RefAttributes<HTMLDivElement>>;
+export interface BackgroundVideoProps extends React.HTMLAttributes<HTMLDivElement> {
+    src: string | {
+        url: string;
+        type: "mp4" | "webm";
+    }[];
+    /** Shown before playback and, under reduced motion, instead of the video. */
+    poster: string;
+    /** Content on top (hero copy). */
+    children?: React.ReactNode;
+    labels?: Partial<VideoPlayerLabels>;
+}
+/**
+ * Muted, looping, decorative video (hero backgrounds). `aria-hidden`, with a visible pause
+ * button (WCAG 2.2.2). Reduced motion shows the poster only.
+ */
+export declare const BackgroundVideo: React.ForwardRefExoticComponent<BackgroundVideoProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/media/video-player.js

@@ -0,0 +1,319 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { Captions, CaptionsOff, Maximize, Minimize, Pause, PictureInPicture2, Play, RotateCcw, Volume1, Volume2, VolumeX, TriangleAlert } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { useReducedMotion } from "../lib/use-reduced-motion.js";
+import { aspectRatioOf } from "../components/image.js";
+import { Slider } from "../components/slider.js";
+import { Spinner } from "../components/spinner.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuTrigger } from "../components/dropdown-menu.js";
+import { PortalContainer } from "../lib/theme-scope.js";
+import { isMediaAsset } from "./media-provider.js";
+const videoLabels = {
+    player: "Video player",
+    play: "Play",
+    pause: "Pause",
+    replay: "Replay",
+    playVideo: "Play video: {title}",
+    seek: "Seek",
+    time: "{current} of {duration}",
+    mute: "Mute",
+    unmute: "Unmute",
+    volume: "Volume",
+    captionsOn: "Turn on captions",
+    captionsOff: "Turn off captions",
+    speed: "Playback speed",
+    speedValue: "{rate}×",
+    normal: "Normal",
+    pip: "Picture in picture",
+    fullscreen: "Full screen",
+    exitFullscreen: "Exit full screen",
+    error: "This video can't be played.",
+    hlsUnsupported: "This stream needs HLS support. Pass the `hls` loader.",
+    pauseBackground: "Pause background video",
+    playBackground: "Play background video",
+};
+/** `1:02:05` / `3:07`. */
+export function formatMediaTime(seconds, locale = "en-US") {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        seconds = 0;
+    const s = Math.floor(seconds % 60);
+    const m = Math.floor((seconds / 60) % 60);
+    const h = Math.floor(seconds / 3600);
+    const two = new Intl.NumberFormat(locale, { minimumIntegerDigits: 2, useGrouping: false });
+    const one = new Intl.NumberFormat(locale, { useGrouping: false });
+    return h > 0 ? `${one.format(h)}:${two.format(m)}:${two.format(s)}` : `${one.format(m)}:${two.format(s)}`;
+}
+const SPEEDS = [0.5, 0.75, 1, 1.25, 1.5, 2];
+export const videoPlayerVariants = cva("vui-video group/video relative isolate overflow-hidden bg-scene", {
+    variants: {
+        rounded: { none: "", ui: "rounded-ui", "ui-lg": "rounded-ui-lg" },
+        chrome: { overlay: "", bar: "" },
+    },
+    defaultVariants: { rounded: "ui", chrome: "overlay" },
+});
+function sourcesOf(src) {
+    if (Array.isArray(src))
+        return src;
+    const url = isMediaAsset(src) ? src.url : src;
+    const type = /\.m3u8(\?|$)/i.test(url) || (isMediaAsset(src) && /mpegurl/i.test(src.mime)) ? "hls" : /\.webm(\?|$)/i.test(url) ? "webm" : "mp4";
+    return [{ url, type }];
+}
+const MIME = { mp4: "video/mp4", webm: "video/webm", hls: "application/vnd.apple.mpegurl" };
+/**
+ * Consistent controls for self-hosted video: play, seek, time, volume, captions, speed,
+ * picture-in-picture and full screen. Keyboard: Space/K play, ←/→ 5 s, ↑/↓ volume, F full screen,
+ * M mute, C captions. HLS loads `hls.js` only when needed. The chrome is always dark, because
+ * video content is.
+ *
+ * ```tsx
+ * <VideoPlayer src="/media/onboarding.mp4" poster="/media/onboarding.jpg" title="Onboarding: your first week"
+ *   tracks={[{ src: "/media/onboarding.en.vtt", lang: "en", label: "English", default: true }]} />
+ * ```
+ */
+export const VideoPlayer = React.forwardRef(function VideoPlayer({ src, poster: posterProp, aspect, tracks, autoPlay, muted: mutedProp = false, loop, playsInline = true, controls = "custom", chrome = "overlay", rounded, title, preload = "metadata", hls, onEnded, onTimeUpdate, videoRef, crossOrigin, labels, className, style, onKeyDown, ...props }, ref) {
+    const t = useLabels("videoPlayer", videoLabels, labels);
+    const { locale } = useLocale();
+    const reduced = useReducedMotion();
+    const video = React.useRef(null);
+    const root = React.useRef(null);
+    const asset = isMediaAsset(src) ? src : undefined;
+    const poster = isMediaAsset(posterProp) ? posterProp.url : posterProp ?? asset?.variants?.poster?.url;
+    const ratio = aspectRatioOf(aspect ?? "auto", asset?.width, asset?.height) ?? 16 / 9;
+    const sources = React.useMemo(() => sourcesOf(src), [src]);
+    const isHls = sources.some((s) => s.type === "hls");
+    const [playing, setPlaying] = React.useState(false);
+    const [started, setStarted] = React.useState(false);
+    const [ended, setEnded] = React.useState(false);
+    const [buffering, setBuffering] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const [time, setTime] = React.useState(0);
+    const [duration, setDuration] = React.useState(asset?.duration ?? 0);
+    const [volume, setVolume] = React.useState(1);
+    const [muted, setMuted] = React.useState(mutedProp);
+    const [rate, setRate] = React.useState(1);
+    const [captions, setCaptions] = React.useState(Boolean(tracks?.some((tr) => tr.default)));
+    const [fullscreen, setFullscreen] = React.useState(false);
+    const [idle, setIdle] = React.useState(false);
+    const idleTimer = React.useRef(undefined);
+    React.useImperativeHandle(videoRef, () => video.current, []);
+    React.useImperativeHandle(ref, () => root.current, []);
+    const [rootEl, setRootEl] = React.useState(null);
+    const rootRef = React.useCallback((node) => {
+        root.current = node;
+        setRootEl(node);
+    }, []);
+    // HLS: native (Safari) or the lazy hls.js loader.
+    React.useEffect(() => {
+        const el = video.current;
+        if (!el || !isHls)
+            return;
+        const hlsUrl = sources.find((s) => s.type === "hls").url;
+        if (el.canPlayType(MIME.hls)) {
+            el.src = hlsUrl;
+            return;
+        }
+        if (!hls) {
+            setError(t("hlsUnsupported"));
+            return;
+        }
+        let instance;
+        let cancelled = false;
+        hls().then(({ default: Hls }) => {
+            if (cancelled || !video.current)
+                return;
+            if (!Hls.isSupported())
+                return setError(t("error"));
+            const h = new Hls();
+            h.loadSource(hlsUrl);
+            h.attachMedia(video.current);
+            instance = h;
+        }, () => setError(t("error")));
+        return () => {
+            cancelled = true;
+            instance?.destroy();
+        };
+    }, [isHls, sources, hls, t]);
+    React.useEffect(() => {
+        const el = video.current;
+        if (!el || !tracks?.length)
+            return;
+        for (let i = 0; i < el.textTracks.length; i++) {
+            const tr = el.textTracks[i];
+            const def = tracks.findIndex((x) => x.default);
+            tr.mode = captions && i === (def === -1 ? 0 : def) ? "showing" : "hidden";
+        }
+    }, [captions, tracks]);
+    // Metadata can arrive before hydration attaches the listeners: read it once on mount.
+    React.useEffect(() => {
+        const el = video.current;
+        if (!el)
+            return;
+        if (el.readyState >= 1 && Number.isFinite(el.duration))
+            setDuration(el.duration);
+        setMuted(el.muted);
+        if (!el.paused) {
+            setPlaying(true);
+            setStarted(true);
+        }
+    }, []);
+    React.useEffect(() => {
+        const onFs = () => setFullscreen(document.fullscreenElement === root.current);
+        document.addEventListener("fullscreenchange", onFs);
+        return () => document.removeEventListener("fullscreenchange", onFs);
+    }, []);
+    const poke = React.useCallback(() => {
+        setIdle(false);
+        clearTimeout(idleTimer.current);
+        idleTimer.current = setTimeout(() => setIdle(true), 2600);
+    }, []);
+    React.useEffect(() => () => clearTimeout(idleTimer.current), []);
+    const togglePlay = React.useCallback(() => {
+        const el = video.current;
+        if (!el)
+            return;
+        if (el.paused || el.ended)
+            void el.play()?.catch?.(() => { });
+        else
+            el.pause();
+    }, []);
+    const seekBy = (d) => {
+        const el = video.current;
+        if (el)
+            el.currentTime = Math.min(Math.max(0, el.currentTime + d), el.duration || Infinity);
+    };
+    const setVol = (v) => {
+        const el = video.current;
+        if (!el)
+            return;
+        el.volume = Math.min(1, Math.max(0, v));
+        el.muted = el.volume === 0;
+    };
+    const toggleMute = () => {
+        const el = video.current;
+        if (el)
+            el.muted = !el.muted;
+    };
+    const toggleFullscreen = () => {
+        const el = root.current;
+        if (!el)
+            return;
+        if (document.fullscreenElement)
+            void document.exitFullscreen?.();
+        else if (el.requestFullscreen)
+            void el.requestFullscreen();
+        else
+            video.current?.webkitEnterFullscreen?.();
+    };
+    // Feature detection after mount, so server and client render the same controls.
+    const [pipSupported, setPipSupported] = React.useState(false);
+    React.useEffect(() => setPipSupported(Boolean(document.pictureInPictureEnabled)), []);
+    const togglePip = () => {
+        const el = video.current;
+        if (!el)
+            return;
+        const d = document;
+        if (d.pictureInPictureElement)
+            void d.exitPictureInPicture?.();
+        else
+            void el.requestPictureInPicture?.();
+    };
+    const handleKeyDown = (e) => {
+        onKeyDown?.(e);
+        if (e.defaultPrevented || controls !== "custom" || e.metaKey || e.ctrlKey || e.altKey)
+            return;
+        const target = e.target;
+        const onSlider = target.getAttribute("role") === "slider";
+        const onButton = target.tagName === "BUTTON";
+        const k = e.key.toLowerCase();
+        if ((k === " " && !onButton) || k === "k")
+            togglePlay();
+        else if (k === "arrowleft" && !onSlider)
+            seekBy(-5);
+        else if (k === "arrowright" && !onSlider)
+            seekBy(5);
+        else if (k === "arrowup" && !onSlider)
+            setVol((video.current?.volume ?? 1) + 0.1);
+        else if (k === "arrowdown" && !onSlider)
+            setVol((video.current?.volume ?? 1) - 0.1);
+        else if (k === "f")
+            toggleFullscreen();
+        else if (k === "m")
+            toggleMute();
+        else if (k === "c" && tracks?.length)
+            setCaptions((c) => !c);
+        else
+            return;
+        e.preventDefault();
+        poke();
+    };
+    const nf = React.useMemo(() => new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }), [locale]);
+    const showChrome = controls === "custom" && (chrome === "bar" || !playing || !idle);
+    const VolumeIcon = muted || volume === 0 ? VolumeX : volume < 0.5 ? Volume1 : Volume2;
+    const btn = "vui-video-btn focus-ring inline-flex size-9 shrink-0 items-center justify-center rounded-ui-sm text-fg transition-colors hover:bg-hover [&_svg]:size-[18px]";
+    return (_jsxs("div", { ref: rootRef, role: "group", "aria-label": title ? `${t("player")}: ${title}` : t("player"), "data-slot": "video-player", "data-state": error ? "error" : ended ? "ended" : playing ? "playing" : started ? "paused" : "poster", "data-chrome": chrome, "data-idle": showChrome ? undefined : "", className: cn(videoPlayerVariants({ rounded, chrome }), "dark", className), style: { aspectRatio: fullscreen ? undefined : String(ratio), ...style }, onKeyDown: handleKeyDown, onPointerMove: poke, onFocusCapture: poke, ...props, children: [_jsxs("video", { ref: video, className: "absolute inset-0 size-full bg-transparent object-contain", poster: poster, autoPlay: autoPlay && !reduced, muted: muted, loop: loop, playsInline: playsInline, preload: preload, controls: controls === "native", crossOrigin: crossOrigin, onClick: controls === "custom" ? togglePlay : undefined, onPlay: () => {
+                    setPlaying(true);
+                    setStarted(true);
+                    setEnded(false);
+                    poke();
+                }, onPause: () => setPlaying(false), onEnded: () => {
+                    setPlaying(false);
+                    setEnded(true);
+                    onEnded?.();
+                }, onWaiting: () => setBuffering(true), onPlaying: () => setBuffering(false), onCanPlay: () => setBuffering(false), onTimeUpdate: (e) => {
+                    setTime(e.currentTarget.currentTime);
+                    onTimeUpdate?.(e.currentTarget.currentTime);
+                }, onLoadedMetadata: (e) => setDuration(e.currentTarget.duration), onDurationChange: (e) => Number.isFinite(e.currentTarget.duration) && setDuration(e.currentTarget.duration), onVolumeChange: (e) => {
+                    setVolume(e.currentTarget.volume);
+                    setMuted(e.currentTarget.muted);
+                }, onRateChange: (e) => setRate(e.currentTarget.playbackRate), onError: () => setError(t("error")), "aria-label": title, children: [isHls ? null : sources.map((s) => _jsx("source", { src: s.url, type: MIME[s.type] }, s.url)), tracks?.map((tr) => _jsx("track", { src: tr.src, srcLang: tr.lang, label: tr.label, kind: tr.kind ?? "subtitles", default: tr.default }, tr.src))] }), error ? (_jsxs("div", { "data-slot": "video-error", role: "alert", className: "absolute inset-0 z-20 flex flex-col items-center justify-center gap-2 bg-scene/80 p-6 text-center text-sm text-fg-muted", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-6 text-warning" }), error] })) : null, controls === "custom" && !error && (!started || ended) ? (_jsx("button", { type: "button", "data-slot": "video-big-play", "aria-label": ended ? t("replay") : title ? t("playVideo", { title }) : t("play"), onClick: togglePlay, className: "vui-video-bigplay focus-ring absolute start-1/2 top-1/2 z-10 flex size-16 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full surface-popover text-fg rtl:translate-x-1/2 [&_svg]:size-6", children: ended ? _jsx(RotateCcw, { "aria-hidden": true }) : _jsx(Play, { "aria-hidden": true, className: "ms-0.5 fill-current" }) })) : null, buffering && playing ? (_jsx("div", { "aria-hidden": true, className: "pointer-events-none absolute inset-0 z-10 flex items-center justify-center", children: _jsx(Spinner, { size: "lg", className: "text-fg" }) })) : null, controls === "custom" ? (_jsxs("div", { "data-slot": "video-controls", "data-visible": showChrome ? "" : undefined, className: cn("vui-video-controls absolute inset-x-0 bottom-0 z-20 flex flex-col gap-1 px-2 pt-8 pb-1.5", !started && chrome === "overlay" && "invisible"), children: [_jsx(Slider, { "aria-label": t("seek"), size: "sm", min: 0, max: duration || 1, step: 0.1, value: [Math.min(time, duration || 0)], onValueChange: ([v]) => {
+                            if (video.current && v !== undefined)
+                                video.current.currentTime = v;
+                        }, formatValue: (v) => t("time", { current: formatMediaTime(v, locale), duration: formatMediaTime(duration, locale) }), showValue: "never", dir: "ltr", className: "vui-video-seek px-1.5" }), _jsxs("div", { className: "flex items-center gap-0.5", children: [_jsx("button", { type: "button", "data-slot": "video-play", className: btn, "aria-label": playing ? t("pause") : t("play"), onClick: togglePlay, children: playing ? _jsx(Pause, { "aria-hidden": true, className: "fill-current" }) : _jsx(Play, { "aria-hidden": true, className: "fill-current" }) }), _jsxs("div", { className: "group/vol flex items-center", children: [_jsx("button", { type: "button", "data-slot": "video-mute", className: btn, "aria-label": muted ? t("unmute") : t("mute"), onClick: toggleMute, children: _jsx(VolumeIcon, { "aria-hidden": true }) }), _jsx("div", { className: "w-0 overflow-hidden opacity-0 transition-[width,opacity] duration-200 group-focus-within/vol:w-20 group-focus-within/vol:opacity-100 group-hover/vol:w-20 group-hover/vol:opacity-100", children: _jsx(Slider, { "aria-label": t("volume"), size: "sm", min: 0, max: 1, step: 0.05, value: [muted ? 0 : volume], onValueChange: ([v]) => v !== undefined && setVol(v), formatOptions: { style: "percent" }, showValue: "never", className: "w-18 px-1.5" }) })] }), _jsxs("span", { "data-slot": "video-time", className: "tabular ms-1.5 text-[12.5px] text-fg-muted", children: [_jsx("span", { className: "text-fg", children: formatMediaTime(time, locale) }), _jsx("span", { "aria-hidden": true, className: "mx-1 text-fg-subtle", children: "/" }), formatMediaTime(duration, locale)] }), _jsxs("div", { className: "ms-auto flex items-center gap-0.5", children: [tracks?.length ? (_jsx("button", { type: "button", "data-slot": "video-captions", className: btn, "aria-pressed": captions, "aria-label": captions ? t("captionsOff") : t("captionsOn"), onClick: () => setCaptions((c) => !c), children: captions ? _jsx(Captions, { "aria-hidden": true }) : _jsx(CaptionsOff, { "aria-hidden": true }) })) : null, _jsx(PortalContainer, { container: rootEl, children: _jsxs(DropdownMenu, { modal: false, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx("button", { type: "button", "data-slot": "video-speed", className: cn(btn, "w-auto px-2 text-[12.5px] font-medium tabular"), "aria-label": `${t("speed")}: ${t("speedValue", { rate: nf.format(rate) })}`, children: t("speedValue", { rate: nf.format(rate) }) }) }), _jsxs(DropdownMenuContent, { align: "end", side: "top", children: [_jsx(DropdownMenuLabel, { children: t("speed") }), _jsx(DropdownMenuRadioGroup, { value: String(rate), onValueChange: (v) => {
+                                                                if (video.current)
+                                                                    video.current.playbackRate = Number(v);
+                                                            }, children: SPEEDS.map((s) => (_jsx(DropdownMenuRadioItem, { value: String(s), children: s === 1 ? t("normal") : t("speedValue", { rate: nf.format(s) }) }, s))) })] })] }) }), pipSupported ? (_jsx("button", { type: "button", "data-slot": "video-pip", className: btn, "aria-label": t("pip"), onClick: togglePip, children: _jsx(PictureInPicture2, { "aria-hidden": true }) })) : null, _jsx("button", { type: "button", "data-slot": "video-fullscreen", className: btn, "aria-label": fullscreen ? t("exitFullscreen") : t("fullscreen"), onClick: toggleFullscreen, children: fullscreen ? _jsx(Minimize, { "aria-hidden": true }) : _jsx(Maximize, { "aria-hidden": true }) })] })] })] })) : null] }));
+});
+/**
+ * A privacy-friendly embed: a poster and a play button until clicked, then a
+ * `youtube-nocookie.com` (or `player.vimeo.com` with `dnt=1`) iframe. No third-party request,
+ * cookie or script before the visitor chooses to play.
+ */
+export const VideoEmbed = React.forwardRef(function VideoEmbed({ provider, id, title, poster, aspect = "16/9", start, rounded = "ui", labels, className, style, ...props }, ref) {
+    const t = useLabels("videoPlayer", videoLabels, labels);
+    const [active, setActive] = React.useState(false);
+    const ratio = aspectRatioOf(aspect) ?? 16 / 9;
+    const image = poster ?? (provider === "youtube" ? `https://i.ytimg.com/vi/${encodeURIComponent(id)}/hqdefault.jpg` : undefined);
+    const url = provider === "youtube"
+        ? `https://www.youtube-nocookie.com/embed/${encodeURIComponent(id)}?autoplay=1&rel=0${start ? `&start=${start}` : ""}`
+        : `https://player.vimeo.com/video/${encodeURIComponent(id)}?autoplay=1&dnt=1${start ? `#t=${start}s` : ""}`;
+    return (_jsx("div", { ref: ref, "data-slot": "video-embed", "data-provider": provider, "data-state": active ? "active" : "facade", className: cn(videoPlayerVariants({ rounded }), "dark", className), style: { aspectRatio: String(ratio), ...style }, ...props, children: active ? (_jsx("iframe", { src: url, title: title, className: "absolute inset-0 size-full border-0", allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen", allowFullScreen: true, referrerPolicy: "strict-origin-when-cross-origin" })) : (_jsxs("button", { type: "button", onClick: () => setActive(true), "aria-label": t("playVideo", { title }), className: "vui-video-facade focus-ring group/facade absolute inset-0 size-full", children: [image ? _jsx("img", { src: image, alt: "", loading: "lazy", decoding: "async", className: "absolute inset-0 size-full object-cover transition-transform duration-500 group-hover/facade:scale-[1.02] motion-reduce:transition-none" }) : null, _jsx("span", { "aria-hidden": true, className: "vui-video-facade-shade absolute inset-0" }), _jsx("span", { "aria-hidden": true, className: "absolute start-4 end-4 top-4 line-clamp-2 text-start text-[15px] font-medium text-fg", children: title }), _jsx("span", { "aria-hidden": true, className: "absolute start-1/2 top-1/2 flex size-16 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full surface-popover text-fg transition-transform group-hover/facade:scale-105 rtl:translate-x-1/2 [&_svg]:size-6", children: _jsx(Play, { className: "ms-0.5 fill-current" }) })] })) }));
+});
+/**
+ * Muted, looping, decorative video (hero backgrounds). `aria-hidden`, with a visible pause
+ * button (WCAG 2.2.2). Reduced motion shows the poster only.
+ */
+export const BackgroundVideo = React.forwardRef(function BackgroundVideo({ src, poster, labels, className, children, ...props }, ref) {
+    const t = useLabels("videoPlayer", videoLabels, labels);
+    const reduced = useReducedMotion();
+    const video = React.useRef(null);
+    const [paused, setPaused] = React.useState(false);
+    const list = typeof src === "string" ? sourcesOf(src) : src;
+    return (_jsxs("div", { ref: ref, "data-slot": "background-video", className: cn("relative isolate overflow-hidden", className), ...props, children: [reduced ? (_jsx("img", { src: poster, alt: "", "aria-hidden": true, className: "absolute inset-0 -z-10 size-full object-cover" })) : (_jsx("video", { ref: video, "aria-hidden": true, tabIndex: -1, className: "absolute inset-0 -z-10 size-full object-cover", poster: poster, autoPlay: true, muted: true, loop: true, playsInline: true, preload: "auto", children: list.map((s) => _jsx("source", { src: s.url, type: MIME[s.type] }, s.url)) })), children, reduced ? null : (_jsx("button", { type: "button", "data-slot": "background-video-toggle", "aria-label": paused ? t("playBackground") : t("pauseBackground"), onClick: () => {
+                    const el = video.current;
+                    if (!el)
+                        return;
+                    if (el.paused) {
+                        void el.play()?.catch?.(() => { });
+                        setPaused(false);
+                    }
+                    else {
+                        el.pause();
+                        setPaused(true);
+                    }
+                }, className: "focus-ring surface-popover absolute end-4 bottom-4 z-10 inline-flex size-9 items-center justify-center rounded-full text-fg [&_svg]:size-4", children: paused ? _jsx(Play, { "aria-hidden": true, className: "fill-current" }) : _jsx(Pause, { "aria-hidden": true, className: "fill-current" }) }))] }));
+});

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>;