@enigmax/primitives 0.25.0 → 0.26.0

package/src/react/video/menu.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { useEffect, type ReactNode } from "react";
+import type { ContextMenuPoint } from "@/core/context-menu";
+import { ContextMenu, useContextMenuContext, type ContextMenuItem, type ContextMenuNode } from "@/react/context-menu";
+
+/**
+ * The menu a right-click on the player opens, the way YouTube's does.
+ *
+ * It IS the context menu component. Writing a second popup here would mean a second keyboard
+ * model, a second set of roles, a second thing to fix - and the `fe-context-menu-hand-rolled`
+ * guardrail exists to say so. The rows come from the player, because only the player knows
+ * what is playing.
+ *
+ * Its own chunk, mounted the first time a pointer reaches the player rather than on render: a
+ * page of embedded videos nobody right-clicks downloads none of it, and a pointer arrives long
+ * before the second button does. A press that beats the chunk falls through to the browser's
+ * own menu, which is a better answer than swallowing it.
+ *
+ * There is no trigger part. The player opens the menu itself, at the point of the press, so
+ * what this renders into the tree is nothing at all - the panel is portalled.
+ */
+
+export type OpenVideoMenu = (point: ContextMenuPoint) => boolean;
+
+export interface VideoMenuProps {
+    rows: readonly ContextMenuNode[];
+    title?: string;
+    onSelect: (item: ContextMenuItem) => void;
+    /**
+     * Called with the opener once the menu is live, and with null when it goes away.
+     *
+     * The player opens the menu itself, at the point of the press, so this is how the two
+     * halves meet - and it is also what tells the player that its menu is READY. Until it
+     * arrives a right-click is left to the browser rather than swallowed.
+     */
+    onReady: (open: OpenVideoMenu | null) => void;
+}
+
+export function VideoMenu({ rows, title, onSelect, onReady }: VideoMenuProps): ReactNode {
+    return (
+        <ContextMenu.Root
+            items={rows}
+            title={title}
+            // Nothing in a player is writable and nothing in it is selected: Copy, Cut and
+            // Paste built from the press would be three rows that never do anything.
+            clipboard={false}
+            onSelect={onSelect}
+        >
+            <Publish onReady={onReady} />
+            <ContextMenu.Content />
+        </ContextMenu.Root>
+    );
+}
+
+/** Hands the opener up to the player, which is the only part that knows where the press was. */
+function Publish({ onReady }: { onReady: (open: OpenVideoMenu | null) => void; }): ReactNode {
+    const menu = useContextMenuContext("Video.Menu");
+
+    useEffect(() => {
+        onReady(menu.open);
+        return () => onReady(null);
+    }, [menu.open, onReady]);
+
+    return null;
+}

package/src/react/video/rail.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import * as player from "@/core/player";
+import { useCallback, useRef, useState, type KeyboardEvent, type PointerEvent, type ReactNode } from "react";
+
+/**
+ * One horizontal rail, used by both the scrubber and the volume.
+ *
+ * They are the same control: a fraction set by a press, dragged with the pointer captured so
+ * it keeps following outside the box, and driven by the arrows for a keyboard. Writing it
+ * twice would mean fixing the drag twice.
+ */
+
+export interface RailProps {
+    /** Where the filled part ends, 0 to 1. */
+    value: number;
+    /** A second, dimmer fill behind it - what is buffered. Omit for a plain rail. */
+    secondary?: number;
+    onChange: (fraction: number) => void;
+    /** Fired once the drag ends, for a caller that only wants the final value. */
+    onCommit?: (fraction: number) => void;
+    label: string;
+    /** What a screen reader reads instead of a bare percentage. */
+    valueText?: string;
+    step?: number;
+    className?: string;
+}
+
+export function Rail({ value, secondary, onChange, onCommit, label, valueText, step = 0.05 }: RailProps): ReactNode {
+    const ref = useRef<HTMLDivElement | null>(null);
+    const [dragging, setDragging] = useState(false);
+
+    const fractionAt = useCallback((clientX: number): number => {
+        const box = ref.current?.getBoundingClientRect();
+        return box ? player.fractionAt(box, clientX) : 0;
+    }, []);
+
+    const onPointerDown = useCallback((event: PointerEvent<HTMLDivElement>) => {
+        if (event.button !== 0 && event.pointerType === "mouse") return;
+        event.preventDefault();
+        event.currentTarget.focus();
+        setDragging(true);
+        try { event.currentTarget.setPointerCapture(event.pointerId); } catch { /* a pointer already gone */ }
+        onChange(fractionAt(event.clientX));
+    }, [fractionAt, onChange]);
+
+    const onPointerMove = useCallback((event: PointerEvent<HTMLDivElement>) => {
+        if (!dragging) return;
+        onChange(fractionAt(event.clientX));
+    }, [dragging, fractionAt, onChange]);
+
+    const end = useCallback((event: PointerEvent<HTMLDivElement>) => {
+        if (!dragging) return;
+        setDragging(false);
+        onCommit?.(fractionAt(event.clientX));
+    }, [dragging, fractionAt, onCommit]);
+
+    const onKeyDown = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
+        const moves: Record<string, number> = {
+            ArrowLeft: -step, ArrowDown: -step, ArrowRight: step, ArrowUp: step
+        };
+        const by = moves[event.key];
+        if (by === undefined && event.key !== "Home" && event.key !== "End") return;
+        event.preventDefault();
+        // Stopped here as well: the player's own shortcuts answer the same arrows, and a rail
+        // that lets them through would seek the video while somebody sets the volume.
+        event.stopPropagation();
+        const next = event.key === "Home" ? 0 : event.key === "End" ? 1 : Math.min(Math.max(value + (by ?? 0), 0), 1);
+        onChange(next);
+        onCommit?.(next);
+    }, [step, value, onChange, onCommit]);
+
+    const percent = Math.round(value * 100);
+
+    return (
+        <div
+            ref={ref}
+            data-enigma-video-rail=""
+            role="slider"
+            tabIndex={0}
+            aria-label={label}
+            aria-valuemin={0}
+            aria-valuemax={100}
+            aria-valuenow={percent}
+            aria-valuetext={valueText ?? `${percent}%`}
+            onPointerDown={onPointerDown}
+            onPointerMove={onPointerMove}
+            onPointerUp={end}
+            onPointerCancel={end}
+            onKeyDown={onKeyDown}
+        >
+            <div data-enigma-video-track="">
+                {secondary !== undefined && <span data-enigma-video-buffer="" style={{ width: `${Math.round(secondary * 100)}%` }} />}
+                <span data-enigma-video-played="" style={{ width: `${percent}%` }} />
+            </div>
+            <span data-enigma-video-knob="" style={{ left: `${percent}%` }} />
+        </div>
+    );
+}

package/src/react/video/styles.ts

@@ -0,0 +1,161 @@
+/**
+ * The player's look, shaped after Plyr's: a bar over a gradient, a thin rail that grows under
+ * the pointer, a round play button in the middle while paused.
+ *
+ * It ships a theme for the reason the lightbox and the colour picker do: an unstyled player is
+ * not a plain player, it is a column of buttons under a video. `styles={false}` takes it away,
+ * and every colour and distance is a custom property, so a project usually only overrides the
+ * accent.
+ *
+ * `scripts/sync-recipes.mjs` generates `recipes/video/styles.css` from this module and CI
+ * fails when the two drift.
+ */
+
+export const VIDEO_STYLES = `
+:root {
+    --enigma-video-accent: #3b82f6;
+    --enigma-video-bg: #000000;
+    --enigma-video-text: #ffffff;
+    --enigma-video-muted: rgba(255, 255, 255, 0.72);
+    --enigma-video-rail: rgba(255, 255, 255, 0.28);
+    --enigma-video-buffer: rgba(255, 255, 255, 0.45);
+    --enigma-video-panel-bg: rgba(23, 23, 23, 0.96);
+    --enigma-video-radius: 0.5rem;
+    --enigma-video-control-size: 2rem;
+    /* The icons are sized HERE and not in em of the bar's text: 1.25em of a 13px label is a
+       16px icon, and the same markup in a project with larger type silently grew a different
+       player. */
+    --enigma-video-icon-size: 1.125rem;
+    --enigma-video-rail-height: 0.3125rem;
+    --enigma-video-rail-hover: 0.5rem;
+    --enigma-video-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
+}
+
+[data-enigma-video] {
+    position: relative; display: block; width: 100%; overflow: hidden;
+    background: var(--enigma-video-bg); border-radius: var(--enigma-video-radius);
+    color: var(--enigma-video-text);
+    font-size: 0.8125rem; line-height: 1;
+}
+[data-enigma-video] video { display: block; width: 100%; height: 100%; }
+/* Fullscreen needs no sizing of its own: the UA stylesheet pins the fullscreen element to the
+   screen with !important, which outranks anything a page or this sheet can say, and a video
+   element already fits itself with object-fit: contain. Only the corner is ours. */
+[data-enigma-video][data-fullscreen] { border-radius: 0; }
+[data-enigma-video][data-hidden] { cursor: none; }
+
+/* The big one, while nothing is playing. Plyr's shape: a filled circle over the poster,
+   large enough to be the obvious target on a phone. */
+[data-enigma-video-big] {
+    position: absolute; inset: 0; margin: auto;
+    display: grid; place-items: center;
+    width: 3.75rem; height: 3.75rem; padding: 0;
+    color: var(--enigma-video-text); background: var(--enigma-video-accent);
+    border: 0; border-radius: 999px; box-shadow: var(--enigma-video-shadow);
+    cursor: pointer;
+}
+[data-enigma-video-big]:focus-visible { outline: 2px solid var(--enigma-video-text); outline-offset: 3px; }
+
+[data-enigma-video-overlay] { position: absolute; inset: 0; display: grid; place-items: center; pointer-events: none; }
+[data-enigma-video-overlay] > * { pointer-events: auto; }
+
+[data-enigma-video-spinner] {
+    width: 2rem; height: 2rem;
+    border: 2px solid rgba(255, 255, 255, 0.25); border-top-color: var(--enigma-video-text);
+    border-radius: 999px; animation: enigma-video-spin 700ms linear infinite;
+}
+@keyframes enigma-video-spin { to { rotate: 360deg; } }
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-video-spinner] { animation-duration: 2s; }
+}
+
+[data-enigma-video-controls] {
+    position: absolute; inset-inline: 0; bottom: 0;
+    display: flex; align-items: center; gap: 0.375rem;
+    padding: 2.5rem 0.625rem 0.625rem;
+    background: linear-gradient(to top, rgba(0, 0, 0, 0.75), transparent);
+    transition: opacity 180ms ease, translate 180ms ease;
+}
+[data-enigma-video][data-hidden] [data-enigma-video-controls] { opacity: 0; translate: 0 0.5rem; pointer-events: none; }
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-video-controls] { transition: none; }
+}
+
+[data-enigma-video-button] {
+    display: grid; place-items: center; flex: none;
+    width: var(--enigma-video-control-size); height: var(--enigma-video-control-size);
+    padding: 0; color: var(--enigma-video-text); background: none; border: 0; border-radius: 0.375rem;
+    cursor: pointer;
+}
+[data-enigma-video-button] svg { width: var(--enigma-video-icon-size); height: var(--enigma-video-icon-size); flex: none; }
+[data-enigma-video-big] svg { width: 1.5rem; height: 1.5rem; }
+[data-enigma-video-button]:hover { background: rgba(255, 255, 255, 0.16); }
+[data-enigma-video-button]:focus-visible { outline: 2px solid var(--enigma-video-text); outline-offset: 1px; }
+[data-enigma-video-button][aria-pressed="true"] { color: var(--enigma-video-accent); }
+
+[data-enigma-video-time] { flex: none; color: var(--enigma-video-muted); font-variant-numeric: tabular-nums; }
+
+/* The rail. Its hit area is the row, not the 5px line: a scrubber you have to hit exactly is
+   one people miss and then seek by accident. */
+[data-enigma-video-rail] {
+    position: relative; flex: 1; min-width: 3rem; height: 1rem;
+    display: flex; align-items: center;
+    cursor: pointer; touch-action: none;
+}
+[data-enigma-video-track] {
+    position: relative; width: 100%; height: var(--enigma-video-rail-height);
+    background: var(--enigma-video-rail); border-radius: 999px; overflow: hidden;
+    transition: height 120ms ease;
+}
+[data-enigma-video-rail]:hover [data-enigma-video-track],
+[data-enigma-video-rail]:focus-visible [data-enigma-video-track] { height: var(--enigma-video-rail-hover); }
+[data-enigma-video-rail]:focus-visible { outline: 2px solid var(--enigma-video-text); outline-offset: 2px; border-radius: 999px; }
+[data-enigma-video-buffer] { position: absolute; inset-block: 0; left: 0; background: var(--enigma-video-buffer); }
+[data-enigma-video-played] { position: absolute; inset-block: 0; left: 0; background: var(--enigma-video-accent); }
+[data-enigma-video-knob] {
+    position: absolute; top: 50%; translate: -50% -50%;
+    width: 0.75rem; height: 0.75rem; border-radius: 999px;
+    background: var(--enigma-video-text); box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.35);
+    pointer-events: none;
+}
+
+/* The volume rail folds away until the control is reached, which is what keeps a narrow
+   player from spending a third of its bar on something rarely touched. */
+[data-enigma-video-volume] { display: flex; align-items: center; flex: none; }
+[data-enigma-video-volume] [data-enigma-video-rail] {
+    width: 0; min-width: 0; opacity: 0; transition: width 140ms ease, opacity 140ms ease;
+}
+[data-enigma-video-volume]:hover [data-enigma-video-rail],
+[data-enigma-video-volume]:focus-within [data-enigma-video-rail] { width: 4.5rem; min-width: 4.5rem; opacity: 1; }
+
+[data-enigma-video-menu] { position: relative; flex: none; }
+/* The panel opens upward, and the player CLIPS - it has to, or a rounded corner is not
+   rounded. So its height is bounded by the room above the button that opened it (measured, and
+   set inline) and what does not fit scrolls. Without this a speed list plus a language list is
+   a panel with its top cut off on any player under about 300px. */
+[data-enigma-video-panel] {
+    position: absolute; right: 0; bottom: calc(100% + 0.5rem); z-index: 2;
+    box-sizing: border-box; min-width: 8.5rem; max-width: calc(100vw - 2rem); padding: 0.25rem;
+    max-height: 14rem; overflow-y: auto; overscroll-behavior: contain; scrollbar-width: thin;
+    background: var(--enigma-video-panel-bg); border-radius: 0.5rem; box-shadow: var(--enigma-video-shadow);
+}
+[data-enigma-video-option] {
+    display: flex; align-items: center; justify-content: space-between; gap: 0.75rem;
+    width: 100%; padding: 0.4375rem 0.5rem;
+    color: var(--enigma-video-text); background: none; border: 0; border-radius: 0.375rem;
+    font: inherit; text-align: left; cursor: pointer;
+}
+[data-enigma-video-option]:hover { background: rgba(255, 255, 255, 0.12); }
+[data-enigma-video-option][aria-checked="true"] { color: var(--enigma-video-accent); }
+[data-enigma-video-option]:focus-visible { outline: 2px solid var(--enigma-video-text); outline-offset: -2px; }
+/* Sticky because the panel scrolls: the language you are choosing between should still say
+   which list it belongs to when the speeds have scrolled past it. */
+[data-enigma-video-heading] {
+    position: sticky; top: 0; z-index: 1; margin: 0;
+    padding: 0.375rem 0.5rem; color: var(--enigma-video-muted);
+    background: var(--enigma-video-panel-bg);
+    font-size: 0.6875rem; text-transform: uppercase; letter-spacing: 0.06em;
+}
+[data-enigma-video-option] svg { width: 0.875rem; height: 0.875rem; flex: none; }
+[data-enigma-video-option] span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+`;

package/src/react/video/types.ts

@@ -0,0 +1,135 @@
+/**
+ * The prop shapes for `<Video>`.
+ *
+ * Shaped after Plyr, which is the player this one is measured against: the same control set,
+ * the same shortcuts, the same auto-hiding bar. What differs is that the controls are the
+ * component's own markup rather than a string of HTML it parses, so a project styles them
+ * with the attributes below instead of overriding a stylesheet it did not write.
+ */
+
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ContextMenuItem, ContextMenuNode } from "@/react/context-menu/context";
+
+export interface VideoSource {
+    src: string;
+    /** `video/mp4`, `video/webm`. The browser picks the first one it can play. */
+    type?: string;
+}
+
+export interface VideoTrack {
+    src: string;
+    /** BCP 47: `en`, `es-419`. */
+    srcLang: string;
+    label: string;
+    kind?: "subtitles" | "captions" | "descriptions" | "chapters" | "metadata";
+    default?: boolean;
+}
+
+/** Which controls the bar carries. Everything is on except `download`, as Plyr has it. */
+export interface VideoControls {
+    play?: boolean;
+    progress?: boolean;
+    currentTime?: boolean;
+    duration?: boolean;
+    volume?: boolean;
+    captions?: boolean;
+    settings?: boolean;
+    pip?: boolean;
+    /** Play on a TV. Feature-detected, and absent until the browser reports a screen to cast to. */
+    cast?: boolean;
+    fullscreen?: boolean;
+    /** Off by default: a video a page shows is not always one it means to hand over. */
+    download?: boolean;
+}
+
+export interface VideoLabels {
+    play?: string;
+    pause?: string;
+    mute?: string;
+    unmute?: string;
+    volume?: string;
+    seek?: string;
+    captions?: string;
+    /** The row that turns subtitles off. Default "Off". */
+    captionsOff?: string;
+    /** The heading over the language rows. Default "Subtitles". */
+    subtitles?: string;
+    settings?: string;
+    speed?: string;
+    normal?: string;
+    pip?: string;
+    cast?: string;
+    /** While it is playing on the other screen. Default "Stop casting". */
+    stopCast?: string;
+    /** The context menu's rows. */
+    loop?: string;
+    copyUrl?: string;
+    copyUrlAtTime?: string;
+    enterFullscreen?: string;
+    exitFullscreen?: string;
+    download?: string;
+    /** The player itself, as a screen reader announces the region. Default "Video player". */
+    player?: string;
+}
+
+// `contextMenu` is taken off the element's own props: it is a long-dead HTML attribute
+// naming a `<menu>` element, and this one is a menu the player draws.
+export interface VideoProps extends Omit<ComponentPropsWithoutRef<"video">, "controls" | "children" | "src" | "contextMenu"> {
+    /** One file, or the list the browser should choose from. */
+    src?: string | readonly VideoSource[];
+    poster?: string;
+    tracks?: readonly VideoTrack[];
+    /** The control bar. `false` leaves a bare `<video>` with nothing over it. */
+    controls?: boolean | VideoControls;
+    /** Rates the settings menu offers. Defaults to Plyr's 0.5 through 2. */
+    speeds?: readonly number[];
+    /** Space, arrows, M, F, C and the digits. On by default, and never while typing. */
+    keyboard?: boolean;
+    /** A press on the picture plays and pauses. On by default. */
+    clickToPlay?: boolean;
+    /** Hide the bar while playing, until the pointer moves. On by default. */
+    autoHide?: boolean;
+    /** How long the pointer has to be still before the bar goes, in ms. Default 2600. */
+    autoHideDelay?: number;
+    /**
+     * The menu a right-click opens, shaped the way YouTube's is. ON by default.
+     *
+     * `false` gives the browser's own menu back - which is what a page wants when the point of
+     * the video is that it can be saved from the native menu.
+     */
+    contextMenu?: boolean | VideoContextMenuOptions;
+    /** The player's stylesheet, injected once. There is no useful unstyled player. */
+    styles?: boolean;
+    labels?: VideoLabels;
+    /** The URL the download control saves. Defaults to what is playing. */
+    download?: string;
+    /** Rendered over the picture, under the controls - a title, a badge, your own overlay. */
+    children?: ReactNode;
+    /** Props for the element wrapping the video and its controls; this is what you size. */
+    wrapperProps?: ComponentPropsWithoutRef<"div">;
+}
+
+export interface VideoContextMenuOptions {
+    /** Rows of your own, after the built-in ones. */
+    items?: readonly ContextMenuNode[];
+    /** A row was invoked - yours, or one of the built-in ids. */
+    onSelect?: (item: ContextMenuItem) => void;
+    /** The two "copy the link" rows. On whenever the menu is, where there is a URL to copy. */
+    copyUrl?: boolean;
+    /** The heading over the rows, naming what the menu is acting on. */
+    title?: string;
+}
+
+export const CONTROL_DEFAULTS: Required<VideoControls> = {
+    play: true,
+    progress: true,
+    currentTime: true,
+    duration: true,
+    volume: true,
+    captions: true,
+    settings: true,
+    pip: true,
+    cast: true,
+    fullscreen: true,
+    download: false
+};