@ttt-productions/upload-ui 0.2.0

package/dist/react/upload-activity-tray.js

@@ -0,0 +1,87 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Global upload activity tray.
+ *
+ * Renders a fixed bottom-left floating action button when there is any
+ * active or non-cleared terminal upload. Opens a popover listing each
+ * item with backend status. Terminal items (completed / failed / rejected)
+ * get a Clear (×) button that calls the consumer-supplied clear mutation.
+ *
+ * Framework-agnostic via render props:
+ *  - `renderViewAllLink` lets the consumer plug in their app's Link
+ *    component (Next.js Link, React Router Link, anchor, etc.) routed at
+ *    their canonical "view all uploads" destination.
+ *  - `renderFooter` lets the consumer fully replace the footer slot.
+ *  - Both omitted — footer is not rendered.
+ */
+import { useMemo } from 'react';
+import { Cloud, Loader2, CheckCircle2, AlertCircle, XCircle, X } from 'lucide-react';
+import { Button, Popover, PopoverTrigger, PopoverContent, ScrollArea, Separator, } from '@ttt-productions/ui-core/react';
+import { cn } from '@ttt-productions/ui-core';
+import { isTerminalUpload, useUploadActivityState, } from './in-flight-uploads-provider.js';
+function getRowMeta(item) {
+    switch (item.status) {
+        case 'pending':
+            return {
+                label: 'Waiting to process…',
+                icon: _jsx(Loader2, { className: "icon-sm animate-spin" }),
+                iconClassName: 'text-muted-foreground',
+            };
+        case 'processing':
+            return {
+                label: 'Processing…',
+                icon: _jsx(Loader2, { className: "icon-sm animate-spin" }),
+                iconClassName: 'text-primary',
+            };
+        case 'completed':
+            return {
+                label: 'Completed',
+                icon: _jsx(CheckCircle2, { className: "icon-sm" }),
+                iconClassName: 'text-green-600 dark:text-green-500',
+            };
+        case 'failed':
+            return {
+                label: 'Failed',
+                detail: item.errorMessage,
+                icon: _jsx(AlertCircle, { className: "icon-sm" }),
+                iconClassName: 'text-destructive',
+            };
+        case 'rejected':
+            return {
+                label: 'Rejected',
+                detail: item.errorMessage,
+                icon: _jsx(XCircle, { className: "icon-sm" }),
+                iconClassName: 'text-destructive',
+            };
+    }
+}
+function UploadActivityTrayRow({ item, onClear, isClearPending, }) {
+    const meta = getRowMeta(item);
+    return (_jsxs("div", { className: "flex items-start gap-3 p-3", children: [_jsx("div", { className: cn('mt-0.5 shrink-0', meta.iconClassName), children: meta.icon }), _jsxs("div", { className: "flex-1 min-w-0", children: [_jsx("p", { className: "text-sm font-medium truncate", children: meta.label }), _jsx("p", { className: "text-xs text-muted-foreground truncate", children: item.surface }), meta.detail && (_jsx("p", { className: "text-xs text-muted-foreground mt-1 line-clamp-2", children: meta.detail }))] }), onClear && (_jsx(Button, { size: "icon", variant: "ghost", className: "h-7 w-7 shrink-0", onClick: onClear, disabled: isClearPending, "aria-label": `Clear ${meta.label.toLowerCase()} upload`, children: _jsx(X, { className: "icon-sm" }) }))] }));
+}
+export function UploadActivityTray(props) {
+    const { clearMutation, viewAllHref, renderViewAllLink, renderFooter, viewAllLabel = 'View all uploads →', } = props;
+    const items = useUploadActivityState();
+    const activeCount = useMemo(() => items.filter((item) => item.status === 'pending' || item.status === 'processing').length, [items]);
+    if (items.length === 0) {
+        return null;
+    }
+    const footerContent = (() => {
+        if (renderFooter)
+            return renderFooter();
+        if (viewAllHref && renderViewAllLink) {
+            return (_jsx("div", { className: "p-3", children: renderViewAllLink({
+                    href: viewAllHref,
+                    children: (_jsx("span", { className: "text-sm text-primary hover:underline", children: viewAllLabel })),
+                }) }));
+        }
+        return null;
+    })();
+    return (_jsx("div", { className: "fixed bottom-6 left-6 z-50", children: _jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { size: "icon", variant: "inverted", className: "relative h-14 w-14 rounded-full shadow-lg", "aria-label": activeCount > 0
+                            ? `Upload activity: ${activeCount} in progress`
+                            : `Upload activity: ${items.length} item${items.length === 1 ? '' : 's'}`, children: [activeCount > 0 ? (_jsx(Loader2, { className: "icon-md animate-spin" })) : (_jsx(Cloud, { className: "icon-md" })), _jsx("span", { className: "absolute -top-1 -right-1 min-w-[1.25rem] h-5 px-1 rounded-full bg-destructive text-destructive-foreground text-xs font-medium flex items-center justify-center", "aria-hidden": "true", children: items.length })] }) }), _jsxs(PopoverContent, { align: "start", side: "top", className: "app-popover p-0 w-80", children: [_jsxs("div", { className: "flex items-center justify-between p-3", children: [_jsx("h2", { className: "text-sm font-semibold", children: "Upload Activity" }), _jsx("span", { className: "text-xs text-muted-foreground", children: activeCount > 0
+                                        ? `${activeCount} in progress`
+                                        : `${items.length} item${items.length === 1 ? '' : 's'}` })] }), _jsx(Separator, {}), _jsx(ScrollArea, { className: "max-h-80", children: _jsx("ul", { className: "divide-y", children: items.map((item) => (_jsx("li", { children: _jsx(UploadActivityTrayRow, { item: item, onClear: isTerminalUpload(item) ? () => clearMutation.mutate(item.id) : undefined, isClearPending: clearMutation.isPending && clearMutation.variables === item.id }) }, item.id))) }) }), footerContent !== null && (_jsxs(_Fragment, { children: [_jsx(Separator, {}), footerContent] }))] })] }) }));
+}
+//# sourceMappingURL=upload-activity-tray.js.map

package/dist/react/upload-activity-tray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-activity-tray.js","sourceRoot":"","sources":["../../src/react/upload-activity-tray.tsx"],"names":[],"mappings":"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"}

package/dist/react/use-clear-upload-activity.d.ts

@@ -0,0 +1,8 @@
+export interface ClearUploadActivityOptions {
+    /** Network call performing the clear. Receives the pendingMediaId. */
+    clearFn: (pendingMediaId: string) => Promise<void>;
+    /** Optional error callback. Receives the error and the pendingMediaId that failed. */
+    onError?: (error: Error, pendingMediaId: string) => void;
+}
+export declare function useClearUploadActivity(options: ClearUploadActivityOptions): import("@tanstack/react-query").UseMutationResult<void, Error, string, unknown>;
+//# sourceMappingURL=use-clear-upload-activity.d.ts.map

package/dist/react/use-clear-upload-activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-clear-upload-activity.d.ts","sourceRoot":"","sources":["../../src/react/use-clear-upload-activity.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,0BAA0B;IACzC,sEAAsE;IACtE,OAAO,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,sFAAsF;IACtF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,0BAA0B,mFAQzE"}

package/dist/react/use-clear-upload-activity.js

@@ -0,0 +1,24 @@
+'use client';
+/**
+ * Generic mutation hook to clear a terminal pendingMedia item from the tray.
+ *
+ * Pure adapter: the consumer supplies `clearFn` (typically a wrapped Firebase
+ * callable in ttt-prod, or a fetch call elsewhere). The package owns the
+ * useMutation wiring and the optional `onError` toast hook; the consumer owns
+ * the network call.
+ *
+ * The provider's Firestore listener observes the `uploadTrayClearedAt` write
+ * and removes the item from the tray selector automatically — no optimistic
+ * update is needed in this hook.
+ */
+import { useMutation } from '@tanstack/react-query';
+export function useClearUploadActivity(options) {
+    const { clearFn, onError } = options;
+    return useMutation({
+        mutationFn: clearFn,
+        onError: (error, pendingMediaId) => {
+            onError?.(error, pendingMediaId);
+        },
+    });
+}
+//# sourceMappingURL=use-clear-upload-activity.js.map

package/dist/react/use-clear-upload-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-clear-upload-activity.js","sourceRoot":"","sources":["../../src/react/use-clear-upload-activity.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AASpD,MAAM,UAAU,sBAAsB,CAAC,OAAmC;IACxE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACrC,OAAO,WAAW,CAAsB;QACtC,UAAU,EAAE,OAAO;QACnB,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE;YACjC,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QACnC,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/react/use-guarded-navigation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a callable that wraps a navigation action. Calling the returned
+ * function with `performNavigation` either invokes it immediately (when no
+ * active uploads) or shows a confirmation prompt; if the user confirms,
+ * `performNavigation` is invoked.
+ */
+export declare function useGuardedNavigation(): (performNavigation: () => void) => void;
+//# sourceMappingURL=use-guarded-navigation.d.ts.map

package/dist/react/use-guarded-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-guarded-navigation.d.ts","sourceRoot":"","sources":["../../src/react/use-guarded-navigation.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,CAAC,iBAAiB,EAAE,MAAM,IAAI,KAAK,IAAI,CAU9E"}

package/dist/react/use-guarded-navigation.js

@@ -0,0 +1,34 @@
+'use client';
+/**
+ * Wraps a navigation action so it prompts the user when an upload is in
+ * progress. Returns a function that takes the consumer's actual navigation
+ * call and either runs it immediately (no active uploads) or shows a confirm()
+ * dialog first.
+ *
+ * Designed to be framework-agnostic — the consumer supplies the navigator
+ * (Next.js router.push, React Router navigate, plain location.assign, etc.).
+ *
+ * Typical use inside a button:
+ *
+ *     const guardedNav = useGuardedNavigation();
+ *     <Button onClick={() => guardedNav(() => router.push('/somewhere'))}>Go</Button>
+ *
+ * For links, use the `<GuardedLink>` render-prop wrapper.
+ */
+import { useCallback } from 'react';
+import { useLocalUploadGuard } from './local-upload-guard-provider.js';
+/**
+ * Returns a callable that wraps a navigation action. Calling the returned
+ * function with `performNavigation` either invokes it immediately (when no
+ * active uploads) or shows a confirmation prompt; if the user confirms,
+ * `performNavigation` is invoked.
+ */
+export function useGuardedNavigation() {
+    const { confirmNavigation } = useLocalUploadGuard();
+    return useCallback((performNavigation) => {
+        if (confirmNavigation()) {
+            performNavigation();
+        }
+    }, [confirmNavigation]);
+}
+//# sourceMappingURL=use-guarded-navigation.js.map

package/dist/react/use-guarded-navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-guarded-navigation.js","sourceRoot":"","sources":["../../src/react/use-guarded-navigation.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,EAAE,iBAAiB,EAAE,GAAG,mBAAmB,EAAE,CAAC;IACpD,OAAO,WAAW,CAChB,CAAC,iBAA6B,EAAE,EAAE;QAChC,IAAI,iBAAiB,EAAE,EAAE,CAAC;YACxB,iBAAiB,EAAE,CAAC;QACtB,CAAC;IACH,CAAC,EACD,CAAC,iBAAiB,CAAC,CACpB,CAAC;AACJ,CAAC"}

package/dist/react/use-guarded-upload.d.ts

@@ -0,0 +1,37 @@
+import type { FirebaseStorage } from 'firebase/storage';
+import type { UploadState } from '@ttt-productions/media-schemas';
+export interface GuardedUploadArgs {
+    storage: FirebaseStorage;
+    path: string;
+    file: File;
+    metadata: {
+        contentType: string;
+    };
+    /** Stable identifier for the in-flight upload (used to register/unregister the local-upload guard). */
+    uploadId: string;
+    /** Optional progress callback. Fires with preparing → uploading (with percent) → finalizing → null on completion. */
+    onProgress?: (state: UploadState | null) => void;
+    /**
+     * Optional cancellation signal. When aborted, the in-flight Storage upload
+     * is canceled and `guardedUpload` rejects with the underlying AbortError.
+     * Callers should treat AbortError as a user-initiated cancel (not a real
+     * failure) — typically by checking `error.name === 'AbortError'` in the
+     * mutation's onError and swallowing toasts/error UI for that case.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Wraps `uploadFileResumable` with the canonical local-upload guard + phase reporting.
+ *
+ * Every upload-capable mutation hook MUST use this helper instead of calling
+ * `uploadFileResumable` directly. The helper owns:
+ * - phase reporting: preparing → uploading (with percent) → finalizing
+ * - beforeunload guard registration during the upload window only
+ * - error safety: the guard is unregistered in a `finally` block
+ *
+ * The helper does NOT call `onProgress?.(null)` — callers do that from the
+ * mutation's `onSuccess` and `onError` callbacks (because the upload window
+ * ends when the upload completes, but the mutation may have more work after).
+ */
+export declare function useGuardedUpload(): (args: GuardedUploadArgs) => Promise<void>;
+//# sourceMappingURL=use-guarded-upload.d.ts.map

package/dist/react/use-guarded-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-guarded-upload.d.ts","sourceRoot":"","sources":["../../src/react/use-guarded-upload.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAGlE,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,eAAe,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,uGAAuG;IACvG,QAAQ,EAAE,MAAM,CAAC;IACjB,qHAAqH;IACrH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACjD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,WAGI,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAAC,CAmBpE"}

package/dist/react/use-guarded-upload.js

@@ -0,0 +1,39 @@
+import { useCallback } from 'react';
+import { uploadFileResumable } from '@ttt-productions/upload-core/browser';
+import { useLocalUploadGuard } from './local-upload-guard-provider.js';
+/**
+ * Wraps `uploadFileResumable` with the canonical local-upload guard + phase reporting.
+ *
+ * Every upload-capable mutation hook MUST use this helper instead of calling
+ * `uploadFileResumable` directly. The helper owns:
+ * - phase reporting: preparing → uploading (with percent) → finalizing
+ * - beforeunload guard registration during the upload window only
+ * - error safety: the guard is unregistered in a `finally` block
+ *
+ * The helper does NOT call `onProgress?.(null)` — callers do that from the
+ * mutation's `onSuccess` and `onError` callbacks (because the upload window
+ * ends when the upload completes, but the mutation may have more work after).
+ */
+export function useGuardedUpload() {
+    const { registerUpload, unregisterUpload } = useLocalUploadGuard();
+    return useCallback(async (args) => {
+        const { uploadId, onProgress, storage, path, file, metadata, signal } = args;
+        onProgress?.({ phase: 'preparing', percent: null });
+        registerUpload(uploadId);
+        try {
+            await uploadFileResumable({
+                storage,
+                path,
+                file,
+                metadata,
+                signal,
+                onProgress: ({ percent }) => onProgress?.({ phase: 'uploading', percent }),
+            });
+        }
+        finally {
+            unregisterUpload(uploadId);
+        }
+        onProgress?.({ phase: 'finalizing', percent: null });
+    }, [registerUpload, unregisterUpload]);
+}
+//# sourceMappingURL=use-guarded-upload.js.map

package/dist/react/use-guarded-upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-guarded-upload.js","sourceRoot":"","sources":["../../src/react/use-guarded-upload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAG3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAqBvE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB;IAC5B,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAEnE,OAAO,WAAW,CAAC,KAAK,EAAE,IAAuB,EAAiB,EAAE;QAChE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAE7E,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,cAAc,CAAC,QAAQ,CAAC,CAAC;QACzB,IAAI,CAAC;YACD,MAAM,mBAAmB,CAAC;gBACtB,OAAO;gBACP,IAAI;gBACJ,IAAI;gBACJ,QAAQ;gBACR,MAAM;gBACN,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;aAC7E,CAAC,CAAC;QACP,CAAC;gBAAS,CAAC;YACP,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QACD,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC,EAAE,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/react/use-upload-processing.d.ts

@@ -0,0 +1,27 @@
+export interface UploadProcessingState {
+    status: 'idle' | 'pending' | 'processing' | 'success' | 'failed' | 'rejected-text' | 'rejected-media';
+    message: string;
+    errorMessage?: string;
+    isProcessing: boolean;
+    isComplete: boolean;
+    isFailed: boolean;
+    isRejected: boolean;
+}
+export interface UseUploadProcessingOptions {
+    /** Override the processing-phase message. */
+    processingMessage?: string;
+    /** Override the success-phase message. */
+    successMessage?: string;
+    /** Override the failed-phase message. */
+    failedMessage?: string;
+    /** Override the rejected-phase message. */
+    rejectedMessage?: string;
+}
+/**
+ * Returns local UI processing state for the given pendingMediaId. If the
+ * `onTerminal` callback is provided, it fires once when the doc reaches a
+ * terminal status (completed / failed / rejected). Use `onTerminal` for
+ * local UI cleanup — global toast/dialog routing belongs in the provider.
+ */
+export declare function useUploadProcessing<TFileOrigin extends string = string>(pendingMediaId: string | null | undefined, onTerminal?: (state: UploadProcessingState) => void, options?: UseUploadProcessingOptions): UploadProcessingState;
+//# sourceMappingURL=use-upload-processing.d.ts.map

package/dist/react/use-upload-processing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-upload-processing.d.ts","sourceRoot":"","sources":["../../src/react/use-upload-processing.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,GAAG,gBAAgB,CAAC;IACtG,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAOD,MAAM,WAAW,0BAA0B;IACzC,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAyED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,EACrE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,EACnD,OAAO,GAAE,0BAA+B,GACvC,qBAAqB,CAqBvB"}

package/dist/react/use-upload-processing.js

@@ -0,0 +1,112 @@
+'use client';
+/**
+ * Adapter that maps `useInFlightUpload` state to the legacy
+ * `{ isProcessing, message, isComplete, isRejected, isFailed }` shape used
+ * by per-component spinners and overlays.
+ *
+ * Routing of toasts and rejection dialogs lives in `InFlightUploadsProvider`
+ * via the consumer-supplied callbacks — `useUploadProcessing` only surfaces
+ * local UI state. The `onTerminal` callback fires once per terminal status
+ * (completed / failed / rejected) and is intended for local UI cleanup
+ * (clearing form state, closing modals, etc.).
+ */
+import { useEffect, useRef } from 'react';
+import { useInFlightUpload } from './in-flight-uploads-provider.js';
+const DEFAULT_PROCESSING_MESSAGE = 'Processing your content...';
+const DEFAULT_SUCCESS_MESSAGE = 'Complete!';
+const DEFAULT_FAILED_MESSAGE = 'Processing failed';
+const DEFAULT_REJECTED_MESSAGE = 'Content rejected';
+function buildState(upload, opts) {
+    const processingMessage = opts.processingMessage ?? DEFAULT_PROCESSING_MESSAGE;
+    const successMessage = opts.successMessage ?? DEFAULT_SUCCESS_MESSAGE;
+    const failedMessage = opts.failedMessage ?? DEFAULT_FAILED_MESSAGE;
+    const rejectedMessage = opts.rejectedMessage ?? DEFAULT_REJECTED_MESSAGE;
+    if (!upload) {
+        return {
+            status: 'idle',
+            message: '',
+            isProcessing: false,
+            isComplete: false,
+            isFailed: false,
+            isRejected: false,
+        };
+    }
+    if (upload.status === 'pending' || upload.status === 'processing') {
+        return {
+            status: upload.status,
+            message: processingMessage,
+            isProcessing: true,
+            isComplete: false,
+            isFailed: false,
+            isRejected: false,
+        };
+    }
+    if (upload.status === 'completed') {
+        return {
+            status: 'success',
+            message: successMessage,
+            isProcessing: false,
+            isComplete: true,
+            isFailed: false,
+            isRejected: false,
+        };
+    }
+    if (upload.status === 'failed') {
+        return {
+            status: 'failed',
+            message: failedMessage,
+            errorMessage: upload.errorMessage,
+            isProcessing: false,
+            isComplete: false,
+            isFailed: true,
+            isRejected: false,
+        };
+    }
+    if (upload.status === 'rejected') {
+        return {
+            status: upload.rejectionType === 'text' ? 'rejected-text' : 'rejected-media',
+            message: rejectedMessage,
+            errorMessage: upload.errorMessage,
+            isProcessing: false,
+            isComplete: false,
+            isFailed: false,
+            isRejected: true,
+        };
+    }
+    return {
+        status: 'processing',
+        message: processingMessage,
+        isProcessing: true,
+        isComplete: false,
+        isFailed: false,
+        isRejected: false,
+    };
+}
+/**
+ * Returns local UI processing state for the given pendingMediaId. If the
+ * `onTerminal` callback is provided, it fires once when the doc reaches a
+ * terminal status (completed / failed / rejected). Use `onTerminal` for
+ * local UI cleanup — global toast/dialog routing belongs in the provider.
+ */
+export function useUploadProcessing(pendingMediaId, onTerminal, options = {}) {
+    const upload = useInFlightUpload(pendingMediaId);
+    const state = buildState(upload, options);
+    const lastFiredRef = useRef(null);
+    useEffect(() => {
+        if (!onTerminal)
+            return;
+        if (!pendingMediaId) {
+            lastFiredRef.current = null;
+            return;
+        }
+        if (state.isComplete || state.isFailed || state.isRejected) {
+            const sig = `${pendingMediaId}:${state.status}`;
+            if (lastFiredRef.current !== sig) {
+                lastFiredRef.current = sig;
+                onTerminal(state);
+            }
+        }
+    }, [pendingMediaId, state.status, state.isComplete, state.isFailed, state.isRejected, state, onTerminal]);
+    return state;
+}
+//# sourceMappingURL=use-upload-processing.js.map

package/dist/react/use-upload-processing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-upload-processing.js","sourceRoot":"","sources":["../../src/react/use-upload-processing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@ttt-productions/upload-ui",
+    "version": "0.2.0",
+    "description": "Upload UI primitives: local upload guard provider, useGuardedUpload helper, DeferredUploadFormShell for forms that defer Firebase Storage upload until form submit.",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ttt-productions/ttt-packages.git",
+        "directory": "packages/upload-ui"
+    },
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "sideEffects": false,
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./react": {
+            "types": "./dist/react/index.d.ts",
+            "default": "./dist/react/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist *.tsbuildinfo",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "dependencies": {
+        "@ttt-productions/file-input": "*",
+        "@ttt-productions/media-schemas": "*",
+        "@ttt-productions/query-core": "*",
+        "@ttt-productions/ui-core": "*",
+        "@ttt-productions/upload-core": "*"
+    },
+    "peerDependencies": {
+        "@tanstack/react-query": ">=5.0.0",
+        "firebase": ">=10.0.0",
+        "lucide-react": ">=0.300.0",
+        "react": ">=18.0.0",
+        "react-dom": ">=18.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.8.3"
+    },
+    "author": "DJ (TTT Productions)",
+    "license": "MIT"
+}