@hexdn/react 0.1.0

package/dist/player/use-player-analytics.d.ts

@@ -0,0 +1,13 @@
+import { type MonitorPlaybackOptions, type PlaybackMonitor, type PlaybackObservation } from "@hexdn/analytics";
+import { type RefObject } from "react";
+export type PlayerAnalyticsOptions = Omit<MonitorPlaybackOptions, "nativeErrorsFatal"> & {
+    readonly onError?: ((error: unknown) => void) | undefined;
+    readonly onObservation?: ((observation: PlaybackObservation) => void) | undefined;
+};
+export declare function usePlayerAnalytics(input: {
+    readonly analytics?: PlayerAnalyticsOptions | undefined;
+    readonly autoPlay: boolean;
+    readonly monitorRef: RefObject<PlaybackMonitor | null>;
+    readonly sourceError?: string | null | undefined;
+    readonly videoRef: RefObject<HTMLVideoElement | null>;
+}): void;

package/dist/player/use-player-analytics.js

@@ -0,0 +1,79 @@
+"use client";
+import { monitorPlayback, } from "@hexdn/analytics";
+import { useLayoutEffect, useRef } from "react";
+export function usePlayerAnalytics(input) {
+    const latest = useRef(input.analytics);
+    useLayoutEffect(() => {
+        latest.current = input.analytics;
+    });
+    const { monitorRef, videoRef } = input;
+    const enabled = Boolean(input.analytics);
+    const id = input.analytics?.video.id;
+    const assetId = input.analytics?.video.assetId;
+    const outputId = input.analytics?.video.outputId;
+    const pendingAttempt = input.analytics?.pendingAttempt;
+    const attachment = useRef(null);
+    // Callback identity and credential changes do not detach the existing view.
+    useLayoutEffect(() => {
+        const media = videoRef.current;
+        const analytics = latest.current;
+        if (!enabled || !media || !analytics)
+            return;
+        let current = attachment.current;
+        if (!current ||
+            current.media !== media ||
+            current.pendingAttempt !== pendingAttempt) {
+            current?.monitor.destroy();
+            try {
+                const monitor = monitorPlayback(media, {
+                    video: analytics.video,
+                    transport: (report, context) => (latest.current ?? analytics).transport(report, context),
+                    nativeErrorsFatal: false,
+                    ...(analytics.pendingAttempt
+                        ? { pendingAttempt: analytics.pendingAttempt }
+                        : {}),
+                    ...(analytics.reportIntervalMs === undefined
+                        ? {}
+                        : { reportIntervalMs: analytics.reportIntervalMs }),
+                });
+                monitor.subscribe((observation) => latest.current?.onObservation?.(observation));
+                current = { media, monitor, pendingAttempt, disposal: null };
+                attachment.current = current;
+            }
+            catch (error) {
+                analytics.onError?.(error);
+                return;
+            }
+        }
+        current.disposal = null;
+        monitorRef.current = current.monitor;
+        return () => {
+            const token = {};
+            current.disposal = token;
+            // React's development effect replay reuses this exact element. Give its
+            // replacement setup one microtask to retain the same viewing attempt.
+            queueMicrotask(() => {
+                if (current.disposal !== token)
+                    return;
+                if (monitorRef.current === current.monitor)
+                    monitorRef.current = null;
+                if (attachment.current === current)
+                    attachment.current = null;
+                current.monitor.destroy({ flush: latest.current !== undefined });
+            });
+        };
+    }, [enabled, pendingAttempt, monitorRef, videoRef]);
+    useLayoutEffect(() => {
+        const analytics = latest.current;
+        if (!analytics)
+            return;
+        monitorRef.current?.setVideo(analytics.video);
+    }, [enabled, pendingAttempt, id, assetId, outputId, monitorRef]);
+    useLayoutEffect(() => {
+        if (input.sourceError && input.autoPlay) {
+            monitorRef.current?.recordError("source_acquisition_failed", {
+                fatal: true,
+            });
+        }
+    }, [input.sourceError, input.autoPlay, monitorRef]);
+}

package/dist/player/use-slider-pointer.d.ts

@@ -0,0 +1,20 @@
+import { type PointerEvent } from "react";
+export declare function useSliderPointer<TElement extends HTMLElement>({ disabled, readValue, onPreviewChange, onCommit, }: {
+    readonly disabled: boolean;
+    readonly readValue: (point: {
+        readonly clientX: number;
+        readonly clientY: number;
+    }, dragging: boolean) => number | null;
+    readonly onPreviewChange: (value: number | null) => void;
+    readonly onCommit: (value: number) => void;
+}): {
+    cancel: () => void;
+    pointerHandlers: {
+        onPointerDown(event: PointerEvent<TElement>): void;
+        onPointerMove(event: PointerEvent<TElement>): void;
+        onPointerUp(event: PointerEvent<TElement>): void;
+        onPointerLeave(): void;
+        onPointerCancel: (event: PointerEvent<TElement>) => void;
+        onLostPointerCapture: (event: PointerEvent<TElement>) => void;
+    };
+};

package/dist/player/use-slider-pointer.js

@@ -0,0 +1,85 @@
+"use client";
+import { useCallback, useLayoutEffect, useRef } from "react";
+export function useSliderPointer({ disabled, readValue, onPreviewChange, onCommit, }) {
+    const activePointer = useRef(null);
+    const releasePointer = useCallback(() => {
+        const active = activePointer.current;
+        activePointer.current = null;
+        if (active?.element.hasPointerCapture(active.id)) {
+            active.element.releasePointerCapture(active.id);
+        }
+        return active;
+    }, []);
+    function cancel() {
+        releasePointer();
+        onPreviewChange(null);
+    }
+    useLayoutEffect(() => {
+        if (disabled)
+            releasePointer()?.clearPreview();
+        return () => {
+            // Activity can hide a retained page during a gesture. Cancel ownership
+            // without coupling cleanup to callbacks that change on every preview.
+            releasePointer()?.clearPreview();
+        };
+    }, [disabled, releasePointer]);
+    function cancelPointer(event) {
+        if (activePointer.current?.id === event.pointerId)
+            cancel();
+    }
+    return {
+        cancel,
+        pointerHandlers: {
+            onPointerDown(event) {
+                if (disabled ||
+                    !event.isPrimary ||
+                    event.button !== 0 ||
+                    activePointer.current) {
+                    return;
+                }
+                const value = readValue(event, false);
+                if (value === null)
+                    return;
+                event.preventDefault();
+                event.currentTarget.setPointerCapture(event.pointerId);
+                activePointer.current = {
+                    id: event.pointerId,
+                    element: event.currentTarget,
+                    clearPreview: () => onPreviewChange(null),
+                };
+                event.currentTarget.focus({ preventScroll: true });
+                onPreviewChange(value);
+            },
+            onPointerMove(event) {
+                if (disabled)
+                    return;
+                const active = activePointer.current;
+                if (active) {
+                    if (active.id === event.pointerId) {
+                        onPreviewChange(readValue(event, true));
+                    }
+                }
+                else if (event.isPrimary &&
+                    event.pointerType !== "touch" &&
+                    event.buttons === 0) {
+                    onPreviewChange(readValue(event, false));
+                }
+            },
+            onPointerUp(event) {
+                if (activePointer.current?.id !== event.pointerId)
+                    return;
+                const value = disabled ? null : readValue(event, true);
+                releasePointer();
+                onPreviewChange(event.pointerType === "touch" ? null : value);
+                if (value !== null)
+                    onCommit(value);
+            },
+            onPointerLeave() {
+                if (!activePointer.current)
+                    onPreviewChange(null);
+            },
+            onPointerCancel: cancelPointer,
+            onLostPointerCapture: cancelPointer,
+        },
+    };
+}

package/dist/player/utils.d.ts

@@ -0,0 +1 @@
+export declare function cn(...values: (string | false | null | undefined)[]): string;

package/dist/player/utils.js

@@ -0,0 +1,3 @@
+export function cn(...values) {
+    return values.filter(Boolean).join(" ");
+}

package/dist/upload/index.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode, type CSSProperties } from "react";
+import type { UploadResult } from "@hexdn/upload";
+import { type UploaderController, type UseUploaderOptions } from "./use-uploader.js";
+export { useUploader } from "./use-uploader.js";
+export type { UploaderController, UploaderProgress, UploaderState, UploaderTransfer, UploaderTransferContext, UseUploaderOptions, } from "./use-uploader.js";
+export interface UploaderLabels {
+    readonly title: string;
+    readonly choose: string;
+    readonly drop: string;
+    readonly pause: string;
+    readonly pausing: string;
+    readonly resume: string;
+    readonly retry: string;
+    readonly complete: string;
+    readonly preparing: string;
+    readonly uploading: string;
+    readonly completing: string;
+    readonly paused: string;
+    readonly error: string;
+}
+interface UploaderPresentation<Result> {
+    readonly accept?: string | undefined;
+    readonly disabled?: boolean | undefined;
+    readonly dropEnabled?: boolean | undefined;
+    readonly className?: string | undefined;
+    readonly style?: CSSProperties | undefined;
+    readonly inputClassName?: string | undefined;
+    readonly labels?: Partial<UploaderLabels> | undefined;
+    /** Replace the presentation while keeping the same input and transfer controller. */
+    readonly children?: ReactNode | ((controller: UploaderController<Result>) => ReactNode);
+}
+export type UploaderProps<Result = UploadResult> = UploaderPresentation<Result> & ({
+    readonly controller: UploaderController<Result>;
+} | (UseUploaderOptions<Result> & {
+    readonly controller?: never;
+}));
+export declare function Uploader<Result = UploadResult>(props: UploaderProps<Result>): import("react").JSX.Element;

package/dist/upload/index.js

@@ -0,0 +1,60 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import {} from "react";
+import { useUploader, } from "./use-uploader.js";
+import styles from "./upload.module.css";
+export { useUploader } from "./use-uploader.js";
+const defaultLabels = {
+    title: "Upload video",
+    choose: "Choose video",
+    drop: "Drop a video here, or choose a file.",
+    pause: "Pause",
+    pausing: "Pausing…",
+    resume: "Resume",
+    retry: "Retry",
+    complete: "Upload complete",
+    preparing: "Preparing upload",
+    uploading: "Uploading",
+    completing: "Finishing upload",
+    paused: "Upload paused",
+    error: "Upload failed. Please try again.",
+};
+export function Uploader(props) {
+    if (props.controller)
+        return _jsx(UploaderView, { ...props, controller: props.controller });
+    return _jsx(ManagedUploader, { ...props });
+}
+function ManagedUploader(props) {
+    const controller = useUploader(props);
+    return _jsx(UploaderView, { ...props, controller: controller });
+}
+function UploaderView({ controller, children, accept = "video/*,.mkv", disabled = false, dropEnabled = true, className, inputClassName, labels: overrides, style, }) {
+    const labels = { ...defaultLabels, ...overrides };
+    const blocked = disabled || controller.isBusy;
+    const { state } = controller;
+    const status = state.status === "idle" ? labels.drop : labels[state.status];
+    const custom = children !== undefined;
+    return (_jsxs("section", { "aria-label": labels.title, "aria-busy": controller.isBusy, className: [custom ? "" : styles.root, className].filter(Boolean).join(" ") ||
+            undefined, style: style, "data-upload-state": state.status, onDragOver: (event) => {
+            if (dropEnabled &&
+                !blocked &&
+                event.dataTransfer.types.includes("Files"))
+                event.preventDefault();
+        }, onDrop: (event) => {
+            if (!dropEnabled)
+                return;
+            event.preventDefault();
+            if (blocked)
+                return;
+            const file = event.dataTransfer.files[0];
+            if (file)
+                void controller.start(file).catch(() => undefined);
+        }, children: [_jsx("input", { type: "file", accept: accept, disabled: blocked, ref: (element) => controller.bindInput(element), hidden: true, className: inputClassName, "aria-label": labels.choose, onChange: (event) => {
+                    const file = event.currentTarget.files?.[0];
+                    event.currentTarget.value = "";
+                    if (file && !blocked)
+                        void controller.start(file).catch(() => undefined);
+                } }), custom ? (typeof children === "function" ? (children(controller)) : (children)) : (_jsxs(_Fragment, { children: [_jsx("div", { className: styles.heading, children: labels.title }), state.file ? _jsx("p", { className: styles.file, children: state.file.name }) : null, _jsx("p", { role: state.status === "error" ? "alert" : "status", "aria-live": "polite", children: status }), state.progress ? (_jsx("progress", { className: styles.progress, "aria-label": labels.uploading, max: 100, value: state.progress.percent })) : null, _jsxs("div", { className: styles.actions, children: [_jsx("button", { type: "button", disabled: blocked, onClick: controller.openPicker, children: labels.choose }), controller.isBusy ? (_jsx("button", { type: "button", disabled: state.status === "pausing", onClick: controller.pause, children: state.status === "pausing" ? labels.pausing : labels.pause })) : null, state.status === "error" || state.status === "paused" ? (_jsx("button", { type: "button", disabled: disabled, onClick: () => {
+                                    void controller.retry().catch(() => undefined);
+                                }, children: state.status === "paused" ? labels.resume : labels.retry })) : null] })] }))] }));
+}

package/dist/upload/upload.module.css

@@ -0,0 +1,41 @@
+.root {
+  color: var(--hexdn-upload-color, #eee);
+  background: var(--hexdn-upload-background, #171717);
+  border: 1px solid var(--hexdn-upload-border, #525252);
+  border-radius: var(--hexdn-upload-radius, 0.75rem);
+  padding: 1.5rem;
+  font: inherit;
+}
+.heading {
+  font-weight: 600;
+}
+.file {
+  overflow-wrap: anywhere;
+}
+.progress {
+  width: 100%;
+  accent-color: var(--hexdn-upload-accent, #70cda5);
+}
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  margin-top: 1rem;
+}
+.actions button {
+  color: inherit;
+  background: transparent;
+  border: 1px solid currentColor;
+  border-radius: 0.375rem;
+  padding: 0.5rem 0.875rem;
+  font: inherit;
+  cursor: pointer;
+}
+.actions button:disabled {
+  cursor: default;
+  opacity: 0.55;
+}
+.actions button:focus-visible {
+  outline: 2px solid var(--hexdn-upload-accent, #70cda5);
+  outline-offset: 3px;
+}

package/dist/upload/use-uploader.d.ts

@@ -0,0 +1,42 @@
+import { type UploadCapability, type UploadResult } from "@hexdn/upload";
+export interface UploaderProgress {
+    readonly phase: "preparing" | "uploading" | "completing";
+    readonly percent: number;
+    readonly uploadedBytes?: number;
+    readonly totalBytes?: number;
+}
+export interface UploaderTransferContext {
+    readonly signal: AbortSignal;
+    /** Stable across retries of this file selection, including capability creation. */
+    readonly idempotencyKey: string;
+    readonly onProgress: (progress: UploaderProgress) => void;
+}
+export type UploaderTransfer<Result> = (file: File, context: UploaderTransferContext) => Promise<Result>;
+export interface UploaderState<Result> {
+    readonly status: "idle" | "preparing" | "uploading" | "completing" | "pausing" | "paused" | "complete" | "error";
+    readonly file: File | null;
+    readonly progress: UploaderProgress | null;
+    readonly result: Result | null;
+    readonly error: unknown;
+}
+export interface UseUploaderOptions<Result = UploadResult> {
+    readonly upload?: UploadCapability;
+    readonly getUpload?: (file: File, context: Pick<UploaderTransferContext, "signal" | "idempotencyKey">) => Promise<UploadCapability>;
+    /** An application-owned workflow may wrap the same transfer core. */
+    readonly transfer?: UploaderTransfer<Result>;
+    readonly onComplete?: (result: Result, file: File) => void;
+    /** Defaults to stopping local work. No remote cancellation is issued. */
+    readonly abortOnUnmount?: boolean;
+}
+export interface UploaderController<Result = UploadResult> {
+    readonly state: UploaderState<Result>;
+    readonly isBusy: boolean;
+    readonly bindInput: (element: HTMLInputElement | null) => void;
+    openPicker(): void;
+    start(file: File): Promise<Result | undefined>;
+    retry(): Promise<Result | undefined>;
+    /** Stops local work only. Remote cancellation belongs to an explicit tenant action. */
+    pause(): void;
+    reset(): void;
+}
+export declare function useUploader<Result = UploadResult>(options: UseUploaderOptions<Result>): UploaderController<Result>;

package/dist/upload/use-uploader.js

@@ -0,0 +1,179 @@
+"use client";
+import { isUploadCancellation, uploadSource, } from "@hexdn/upload";
+import { useCallback, useEffect, useRef, useState } from "react";
+const idle = {
+    status: "idle",
+    file: null,
+    progress: null,
+    result: null,
+    error: null,
+};
+export function useUploader(options) {
+    const latest = useRef(options);
+    latest.current = options;
+    const inputRef = useRef(null);
+    const mounted = useRef(true);
+    const lifecycle = useRef({ generation: 0 });
+    const active = useRef(null);
+    const selection = useRef(null);
+    const [state, setState] = useState(idle);
+    useEffect(() => {
+        mounted.current = true;
+        const owner = lifecycle.current;
+        const generation = ++owner.generation;
+        return () => {
+            mounted.current = false;
+            queueMicrotask(() => {
+                if (owner.generation === generation &&
+                    latest.current.abortOnUnmount !== false)
+                    active.current?.abort();
+            });
+        };
+    }, []);
+    const start = useCallback(async (file) => {
+        if (active.current)
+            return undefined;
+        const configuration = latest.current;
+        const controller = new AbortController();
+        const entry = selection.current?.file === file
+            ? selection.current
+            : { file, idempotencyKey: crypto.randomUUID() };
+        selection.current = entry;
+        active.current = controller;
+        if (mounted.current)
+            setState({
+                ...idle,
+                status: "preparing",
+                file,
+                progress: {
+                    phase: "preparing",
+                    percent: 0,
+                    uploadedBytes: 0,
+                    totalBytes: file.size,
+                },
+            });
+        const context = {
+            signal: controller.signal,
+            idempotencyKey: entry.idempotencyKey,
+            onProgress(progress) {
+                if (active.current !== controller ||
+                    controller.signal.aborted ||
+                    !mounted.current)
+                    return;
+                const percent = Number.isFinite(progress.percent)
+                    ? Math.max(0, Math.min(100, progress.percent))
+                    : 0;
+                setState((previous) => ({
+                    ...previous,
+                    status: progress.phase,
+                    progress: { ...progress, percent },
+                }));
+            },
+        };
+        try {
+            let result;
+            if (configuration.transfer) {
+                result = await configuration.transfer(file, context);
+            }
+            else {
+                if (file.size <= 0)
+                    throw new Error("The selected file is empty.");
+                if (!entry.upload) {
+                    const upload = configuration.upload ??
+                        (await configuration.getUpload?.(file, context));
+                    if (!upload)
+                        throw new Error("Provide an upload capability, getUpload, or transfer callback.");
+                    entry.upload = upload;
+                }
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                result = (await uploadSource({
+                    source: file,
+                    upload: entry.upload,
+                    signal: controller.signal,
+                    onProgress: (progress) => context.onProgress({
+                        phase: progress.phase,
+                        percent: progress.totalBytes > 0
+                            ? Math.round((progress.uploadedBytes / progress.totalBytes) * 100)
+                            : 0,
+                        uploadedBytes: progress.uploadedBytes,
+                        totalBytes: progress.totalBytes,
+                    }),
+                }));
+            }
+            // A confirmed completion wins a concurrent local pause request.
+            if (mounted.current)
+                setState({
+                    status: "complete",
+                    file,
+                    progress: {
+                        phase: "completing",
+                        percent: 100,
+                        uploadedBytes: file.size,
+                        totalBytes: file.size,
+                    },
+                    result,
+                    error: null,
+                });
+            try {
+                configuration.onComplete?.(result, file);
+            }
+            catch {
+                /* Observer failures cannot undo a completed transfer. */
+            }
+            return result;
+        }
+        catch (error) {
+            if (mounted.current)
+                setState((previous) => ({
+                    ...previous,
+                    status: controller.signal.aborted && isUploadCancellation(error)
+                        ? "paused"
+                        : "error",
+                    error: controller.signal.aborted && isUploadCancellation(error)
+                        ? null
+                        : error,
+                }));
+            throw error;
+        }
+        finally {
+            if (active.current === controller)
+                active.current = null;
+        }
+    }, []);
+    const pause = useCallback(() => {
+        if (!active.current || active.current.signal.aborted)
+            return;
+        if (mounted.current)
+            setState((previous) => ({ ...previous, status: "pausing" }));
+        active.current.abort();
+    }, []);
+    const reset = useCallback(() => {
+        if (active.current)
+            return;
+        selection.current = null;
+        if (inputRef.current)
+            inputRef.current.value = "";
+        if (mounted.current)
+            setState(idle);
+    }, []);
+    const setInputElement = useCallback((element) => {
+        inputRef.current = element;
+    }, []);
+    const openPicker = useCallback(() => {
+        inputRef.current?.click();
+    }, []);
+    const retry = useCallback(() => selection.current
+        ? start(selection.current.file)
+        : Promise.resolve(undefined), [start]);
+    return {
+        state,
+        isBusy: ["preparing", "uploading", "completing", "pausing"].includes(state.status),
+        bindInput: setInputElement,
+        openPicker,
+        start,
+        retry,
+        pause,
+        reset,
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hexdn/react",
+  "version": "0.1.0",
+  "description": "Customizable React playback and upload components for HexDN.",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./player": {
+      "types": "./dist/player/index.d.ts",
+      "import": "./dist/player/index.js"
+    },
+    "./upload": {
+      "types": "./dist/upload/index.d.ts",
+      "import": "./dist/upload/index.js"
+    }
+  },
+  "dependencies": {
+    "@hexdn/playback": "0.1.0",
+    "@hexdn/upload": "^0.1.0",
+    "@hexdn/analytics": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.2.5",
+    "jsdom": "^26.1.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive:true, force:true})\" && tsc --project tsconfig.build.json && node scripts/copy-styles.mjs",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}