@mohasinac/appkit 2.3.0 → 2.3.2

package/dist/features/media/upload/ImageUpload.js

@@ -0,0 +1,132 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ImageUpload — canonical image upload component for @mohasinac/feat-media.
+ *
+ * Stage locally → caller-provided onUpload() → /api/media/upload.
+ * Optional focal-point crop (enableCrop, default true).
+ * Optional camera capture (captureSource="both").
+ */
+import { useState, useRef } from "react";
+import { useTranslations } from "next-intl";
+import { useCamera } from "../../../react";
+import { Alert, Button, Div, Label, Progress, Row, Span, Spinner, Text, } from "../../../ui";
+import { MediaImage } from "../MediaImage";
+import { ImageCropModal } from "../modals/ImageCropModal";
+import CameraCapture from "./CameraCapture";
+function formatFileSize(bytes) {
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)}MB`;
+}
+export function ImageUpload({ currentImage, onUpload, onChange, accept = "image/jpeg,image/png,image/gif,image/webp", maxSizeMB = 10, label = "Upload Image", helperText, captureSource = "both", enableCrop = true, onCropDataChange, }) {
+    const [uploading, setUploading] = useState(false);
+    const [preview, setPreview] = useState(currentImage || "");
+    const [error, setError] = useState("");
+    const [progress, setProgress] = useState(0);
+    const [showCropModal, setShowCropModal] = useState(false);
+    const [cropPreviewUrl, setCropPreviewUrl] = useState(null);
+    const [pendingFile, setPendingFile] = useState(null);
+    const [captureMode, setCaptureMode] = useState("file");
+    const fileInputRef = useRef(null);
+    const mobileCaptureRef = useRef(null);
+    const t = useTranslations("camera");
+    const tUpload = useTranslations("upload");
+    const tMediaEditor = useTranslations("mediaEditor");
+    const { isSupported: isCameraSupported } = useCamera();
+    const showCamera = captureSource === "camera-only" ||
+        (captureSource === "both" && captureMode === "camera");
+    const showFileInput = captureSource === "file-only" ||
+        (captureSource === "both" && captureMode === "file");
+    const performUpload = async (file, cropData) => {
+        try {
+            setUploading(true);
+            setProgress(30);
+            const url = await onUpload(file);
+            setProgress(100);
+            setPreview(url);
+            onChange?.(url);
+            if (cropData)
+                onCropDataChange?.(cropData);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Upload failed";
+            setError(message);
+            setPreview(currentImage || "");
+        }
+        finally {
+            setUploading(false);
+            setProgress(0);
+        }
+    };
+    const prepareFile = (file) => {
+        if (!enableCrop) {
+            void performUpload(file);
+            return;
+        }
+        const reader = new FileReader();
+        reader.onload = (event) => {
+            if (event.target?.result) {
+                setCropPreviewUrl(event.target.result);
+                setPendingFile(file);
+                setShowCropModal(true);
+            }
+        };
+        reader.readAsDataURL(file);
+    };
+    const handleCropSave = (cropData) => {
+        setShowCropModal(false);
+        if (pendingFile)
+            void performUpload(pendingFile, cropData);
+        setCropPreviewUrl(null);
+        setPendingFile(null);
+    };
+    const handleCropClose = () => {
+        setShowCropModal(false);
+        setCropPreviewUrl(null);
+        if (pendingFile) {
+            void performUpload(pendingFile);
+            setPendingFile(null);
+        }
+    };
+    const handleCameraCapture = (blob) => {
+        const file = new File([blob], "camera-capture.webp", {
+            type: "image/webp",
+        });
+        setError("");
+        setProgress(0);
+        prepareFile(file);
+    };
+    const handleFileChange = (e) => {
+        const file = e.target.files?.[0];
+        if (!file)
+            return;
+        setError("");
+        setProgress(0);
+        const fileSizeMB = file.size / 1024 / 1024;
+        if (fileSizeMB > maxSizeMB) {
+            setError(`File size must be less than ${maxSizeMB}MB (current: ${formatFileSize(file.size)})`);
+            return;
+        }
+        const acceptedTypes = accept.split(",").map((t) => t.trim());
+        if (!acceptedTypes.includes(file.type)) {
+            setError(`Invalid file type. Accepted: ${accept}`);
+            return;
+        }
+        prepareFile(file);
+    };
+    const handleRemove = () => {
+        setPreview("");
+        setError("");
+        if (fileInputRef.current)
+            fileInputRef.current.value = "";
+        onChange?.("");
+    };
+    return (_jsxs(Div, { className: "space-y-3", children: [label && (_jsx(Label, { className: "block text-sm font-medium text-zinc-600 dark:text-zinc-400", children: label })), _jsx(Div, { className: "relative", children: preview ? (_jsxs(Div, { className: "space-y-2", children: [_jsxs(Div, { className: "relative aspect-[16/9] overflow-hidden rounded-xl border-2 border-zinc-200 dark:border-zinc-700", children: [_jsx(MediaImage, { src: preview, alt: "Preview", size: "card" }), uploading && progress > 0 && (_jsx(Div, { className: "absolute inset-x-0 bottom-0", children: _jsx(Progress, { value: progress, size: "sm" }) }))] }), !uploading && (_jsxs(Row, { wrap: true, gap: "sm", children: [enableCrop && (_jsx(Button, { type: "button", onClick: () => {
+                                        setCropPreviewUrl(preview);
+                                        setShowCropModal(true);
+                                    }, variant: "secondary", size: "sm", children: tMediaEditor("editImage") })), _jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), variant: "outline", size: "sm", children: tUpload("change") }), _jsx(Button, { type: "button", onClick: handleRemove, variant: "danger", size: "sm", children: tUpload("remove") })] }))] })) : (_jsxs(_Fragment, { children: [captureSource === "both" && isCameraSupported && (_jsxs(Row, { justify: "center", className: "gap-2 mb-3", children: [_jsx(Button, { type: "button", variant: captureMode === "file" ? "primary" : "outline", size: "sm", onClick: () => setCaptureMode("file"), children: t("switchToUpload") }), _jsx(Button, { type: "button", variant: captureMode === "camera" ? "primary" : "outline", size: "sm", onClick: () => setCaptureMode("camera"), children: t("switchToCamera") })] })), showCamera && isCameraSupported && (_jsx(CameraCapture, { mode: "photo", facingMode: "environment", onCapture: handleCameraCapture, onError: setError })), showCamera && !isCameraSupported && (_jsx(Button, { type: "button", onClick: () => mobileCaptureRef.current?.click(), disabled: uploading, variant: "ghost", className: "w-full aspect-[16/9] border-2 border-dashed border-zinc-200 dark:border-zinc-700 rounded-xl flex items-center justify-center flex-col text-zinc-500 dark:text-zinc-400", children: _jsx(Span, { className: "text-sm font-medium", children: t("switchToCamera") }) })), showFileInput && (_jsxs(Button, { type: "button", onClick: () => fileInputRef.current?.click(), disabled: uploading, variant: "ghost", className: "w-full aspect-[16/9] border-2 border-dashed border-zinc-200 dark:border-zinc-700 rounded-xl flex items-center justify-center flex-col text-zinc-500 dark:text-zinc-400", children: [_jsx("svg", { className: "w-12 h-12 mb-3", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 1.5, d: "M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" }) }), _jsx(Span, { className: "text-sm font-medium", children: uploading ? tUpload("uploading") : tUpload("clickToUpload") }), _jsxs(Span, { className: "text-xs mt-1", children: [accept
+                                            .split(",")
+                                            .map((t) => t.split("/")[1]?.toUpperCase() ?? t)
+                                            .join(", "), " ", "(max ", maxSizeMB, "MB)"] })] }))] })) }), _jsx("input", { ref: fileInputRef, type: "file", accept: accept, onChange: handleFileChange, className: "hidden", "aria-hidden": "true" }), showCamera && !isCameraSupported && (_jsx("input", { ref: mobileCaptureRef, type: "file", accept: "image/*", capture: "environment", onChange: handleFileChange, className: "hidden", "aria-hidden": "true" })), helperText && !error && (_jsx(Text, { variant: "secondary", size: "xs", children: helperText })), error && _jsx(Alert, { variant: "error", children: error }), uploading && (_jsxs(Row, { className: "gap-2", children: [_jsx(Spinner, { size: "sm" }), _jsx(Text, { size: "sm", variant: "secondary", children: tUpload("uploadingProgress", { progress }) })] })), cropPreviewUrl && (_jsx(ImageCropModal, { isOpen: showCropModal, imageUrl: cropPreviewUrl, onClose: handleCropClose, onSave: handleCropSave }))] }));
+}

package/dist/features/media/upload/MediaUploadField.d.ts

@@ -0,0 +1,31 @@
+import { type MediaField } from "../types/index";
+export interface MediaUploadFieldProps {
+    label: string;
+    value: string;
+    onChange: (url: string) => void;
+    onChangeField?: (media: MediaField | null) => void;
+    onUpload: (file: File) => Promise<string>;
+    accept?: string;
+    maxSizeMB?: number;
+    disabled?: boolean;
+    helperText?: string;
+    captureSource?: "file-only" | "camera-only" | "both";
+    captureMode?: "photo" | "video" | "both";
+    enableTrim?: boolean;
+    enableThumbnail?: boolean;
+    onThumbnailChange?: (url: string) => void;
+    /**
+     * Called with every URL that was staged (uploaded) but never persisted.
+     * The parent form should call `DELETE /api/media?url=…` for each entry.
+     */
+    onAbort?: (stagedUrls: string[]) => void;
+    /**
+     * Called whenever staged URLs change.
+     */
+    onStagedUrlsChange?: (stagedUrls: string[]) => void;
+    /**
+     * Set true after successful save to prevent auto-cleanup on unmount.
+     */
+    isPersisted?: boolean;
+}
+export declare function MediaUploadField({ label, value, onChange, onChangeField, onUpload, accept, maxSizeMB, disabled, helperText, captureSource, captureMode, enableTrim, enableThumbnail, onThumbnailChange, onAbort, onStagedUrlsChange, isPersisted, }: MediaUploadFieldProps): import("react/jsx-runtime").JSX.Element;

package/dist/features/media/upload/MediaUploadField.js

@@ -0,0 +1,204 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * MediaUploadField — single-file upload field for @mohasinac/feat-media.
+ *
+ * For video: optionally opens VideoTrimModal then VideoThumbnailSelector after upload.
+ * Stage locally → caller-provided onUpload() → /api/media/upload.
+ */
+import { useState, useRef, useEffect } from "react";
+import { useTranslations } from "next-intl";
+import { useCamera } from "../../../react";
+import { Alert, Button, Div, Label, Row, Spinner, Text } from "../../../ui";
+import { MediaImage } from "../MediaImage";
+import { MediaVideo } from "../MediaVideo";
+import { VideoTrimModal } from "../modals/VideoTrimModal";
+import { VideoThumbnailSelector } from "../modals/VideoThumbnailSelector";
+import CameraCapture from "./CameraCapture";
+import { inferMediaTypeFromMime } from "../types/index";
+function isVideo(url) {
+    return /\.(mp4|webm|ogg|mov|avi)(\?|$)/i.test(url);
+}
+function isImage(url) {
+    return /\.(jpe?g|png|gif|webp|svg)(\?|$)/i.test(url);
+}
+function filenameFromUrl(url) {
+    try {
+        const parts = new URL(url).pathname.split("/");
+        return decodeURIComponent(parts[parts.length - 1] || url);
+    }
+    catch {
+        return url;
+    }
+}
+export function MediaUploadField({ label, value, onChange, onChangeField, onUpload, accept = "*", maxSizeMB = 50, disabled = false, helperText, captureSource = "file-only", captureMode = "photo", enableTrim = true, enableThumbnail = true, onThumbnailChange, onAbort, onStagedUrlsChange, isPersisted = false, }) {
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [pendingVideoUrl, setPendingVideoUrl] = useState(null);
+    const [showTrimModal, setShowTrimModal] = useState(false);
+    const [showThumbnailModal, setShowThumbnailModal] = useState(false);
+    const [inputMode, setInputMode] = useState("file");
+    const fileInputRef = useRef(null);
+    const mobileCaptureRef = useRef(null);
+    const stagedUrlsRef = useRef([]);
+    const onAbortRef = useRef(onAbort);
+    const onStagedUrlsChangeRef = useRef(onStagedUrlsChange);
+    const isPersistedRef = useRef(isPersisted);
+    useEffect(() => {
+        onAbortRef.current = onAbort;
+    }, [onAbort]);
+    useEffect(() => {
+        onStagedUrlsChangeRef.current = onStagedUrlsChange;
+    }, [onStagedUrlsChange]);
+    useEffect(() => {
+        isPersistedRef.current = isPersisted;
+    }, [isPersisted]);
+    // On unmount, clean up only if the form wasn't persisted.
+    useEffect(() => {
+        return () => {
+            if (!isPersistedRef.current && stagedUrlsRef.current.length > 0) {
+                onAbortRef.current?.([...stagedUrlsRef.current]);
+            }
+        };
+    }, []);
+    const emitStaged = () => {
+        onStagedUrlsChangeRef.current?.([...stagedUrlsRef.current]);
+    };
+    const stageUrl = (url) => {
+        if (!stagedUrlsRef.current.includes(url)) {
+            stagedUrlsRef.current.push(url);
+            emitStaged();
+        }
+    };
+    const unstageUrl = (url) => {
+        const next = stagedUrlsRef.current.filter((u) => u !== url);
+        if (next.length !== stagedUrlsRef.current.length) {
+            stagedUrlsRef.current = next;
+            emitStaged();
+        }
+    };
+    const t = useTranslations("camera");
+    const tUpload = useTranslations("upload");
+    const tMediaEditor = useTranslations("mediaEditor");
+    const { isSupported: isCameraSupported } = useCamera();
+    const showCamera = captureSource === "camera-only" ||
+        (captureSource === "both" && inputMode === "camera");
+    const showFileInput = captureSource === "file-only" ||
+        (captureSource === "both" && inputMode === "file");
+    const captureModeAccept = captureMode === "video"
+        ? "video/*"
+        : captureMode === "both"
+            ? "image/*,video/*"
+            : "image/*";
+    const afterUpload = (url, fileType) => {
+        onChangeField?.({
+            url,
+            type: inferMediaTypeFromMime(fileType, url),
+        });
+        const isVideoFile = fileType.startsWith("video/");
+        if (isVideoFile && enableTrim) {
+            setPendingVideoUrl(url);
+            setShowTrimModal(true);
+            return;
+        }
+        if (isVideoFile && enableThumbnail) {
+            setPendingVideoUrl(url);
+            setShowThumbnailModal(true);
+            return;
+        }
+        onChange(url);
+    };
+    const handleTrimSave = (trimmedUrl) => {
+        setShowTrimModal(false);
+        if (enableThumbnail) {
+            setPendingVideoUrl(trimmedUrl);
+            setShowThumbnailModal(true);
+        }
+        else {
+            onChange(trimmedUrl);
+            setPendingVideoUrl(null);
+        }
+    };
+    const handleTrimClose = () => {
+        setShowTrimModal(false);
+        if (enableThumbnail && pendingVideoUrl) {
+            setShowThumbnailModal(true);
+        }
+        else {
+            if (pendingVideoUrl)
+                onChange(pendingVideoUrl);
+            setPendingVideoUrl(null);
+        }
+    };
+    const handleThumbnailSelect = (thumbUrl) => {
+        setShowThumbnailModal(false);
+        if (pendingVideoUrl)
+            onChange(pendingVideoUrl);
+        onThumbnailChange?.(thumbUrl);
+        setPendingVideoUrl(null);
+    };
+    const handleThumbnailClose = () => {
+        setShowThumbnailModal(false);
+        if (pendingVideoUrl)
+            onChange(pendingVideoUrl);
+        setPendingVideoUrl(null);
+    };
+    const handleFileChange = async (e) => {
+        const file = e.target.files?.[0];
+        if (!file)
+            return;
+        const fileSizeMB = file.size / 1024 / 1024;
+        if (fileSizeMB > maxSizeMB) {
+            setError(`File size must be less than ${maxSizeMB}MB`);
+            return;
+        }
+        setError(null);
+        setIsLoading(true);
+        try {
+            const url = await onUpload(file);
+            stageUrl(url);
+            afterUpload(url, file.type);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : "Upload failed");
+        }
+        finally {
+            setIsLoading(false);
+            if (fileInputRef.current)
+                fileInputRef.current.value = "";
+        }
+    };
+    const handleRemove = () => {
+        if (value && stagedUrlsRef.current.includes(value)) {
+            onAbortRef.current?.([value]);
+            unstageUrl(value);
+        }
+        onChange("");
+        onChangeField?.(null);
+        setError(null);
+    };
+    const handleCameraCapture = async (blob, type) => {
+        const ext = type === "video" ? "webm" : "webp";
+        const file = new File([blob], `camera-capture.${ext}`, { type: blob.type });
+        setError(null);
+        setIsLoading(true);
+        try {
+            const url = await onUpload(file);
+            stageUrl(url);
+            afterUpload(url, blob.type);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : "Upload failed");
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    return (_jsxs(Div, { className: "space-y-2", children: [_jsx(Label, { className: "block text-sm font-medium text-zinc-600 dark:text-zinc-400", children: label }), value && !isLoading && (_jsxs(Div, { className: "rounded-lg border border-zinc-200 dark:border-zinc-700 bg-zinc-50 dark:bg-zinc-900 p-3", children: [isVideo(value) ? (_jsx(Div, { className: "relative aspect-video overflow-hidden rounded-lg", children: _jsx(MediaVideo, { src: value, alt: label, controls: true, objectFit: "contain" }) })) : isImage(value) ? (_jsx(Div, { className: "relative aspect-video overflow-hidden rounded-lg", children: _jsx(MediaImage, { src: value, alt: label, size: "card", objectFit: "contain" }) })) : (_jsx("a", { href: value, target: "_blank", rel: "noopener noreferrer", className: "text-sm underline break-all text-blue-600 dark:text-blue-400", children: filenameFromUrl(value) })), !disabled && (_jsxs(Row, { wrap: true, gap: "sm", className: "mt-2", children: [isVideo(value) && (enableTrim || enableThumbnail) && (_jsx(Button, { type: "button", onClick: () => {
+                                    setPendingVideoUrl(value);
+                                    if (enableTrim)
+                                        setShowTrimModal(true);
+                                    else
+                                        setShowThumbnailModal(true);
+                                }, variant: "secondary", size: "sm", children: tMediaEditor("editVideo") })), _jsx(Button, { type: "button", onClick: handleRemove, variant: "danger", size: "sm", children: tUpload("remove") })] }))] })), !disabled && !isLoading && (_jsxs(_Fragment, { children: [captureSource === "both" && isCameraSupported && (_jsxs(Row, { className: "gap-2", children: [_jsx(Button, { type: "button", variant: inputMode === "file" ? "primary" : "outline", size: "sm", onClick: () => setInputMode("file"), children: t("switchToUpload") }), _jsx(Button, { type: "button", variant: inputMode === "camera" ? "primary" : "outline", size: "sm", onClick: () => setInputMode("camera"), children: t("switchToCamera") })] })), showCamera && isCameraSupported && (_jsx(CameraCapture, { mode: captureMode, facingMode: "environment", onCapture: handleCameraCapture, onError: (msg) => setError(msg) })), showCamera && !isCameraSupported && (_jsx(Button, { type: "button", onClick: () => mobileCaptureRef.current?.click(), variant: "ghost", className: "w-full py-3 border-2 border-dashed border-zinc-200 dark:border-zinc-700 rounded-xl text-sm text-zinc-500 dark:text-zinc-400", children: t("switchToCamera") })), showFileInput && (_jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), variant: "ghost", className: "w-full py-3 border-2 border-dashed border-zinc-200 dark:border-zinc-700 rounded-xl text-sm text-zinc-500 dark:text-zinc-400", children: value ? tUpload("replaceFile") : tUpload("chooseFile") }))] })), isLoading && (_jsxs(Row, { className: "gap-2", children: [_jsx(Spinner, { size: "sm" }), _jsx(Text, { size: "sm", variant: "secondary", children: tUpload("uploading") })] })), _jsx("input", { ref: fileInputRef, type: "file", accept: accept, onChange: handleFileChange, className: "hidden", "aria-hidden": "true" }), showCamera && !isCameraSupported && (_jsx("input", { ref: mobileCaptureRef, type: "file", accept: captureModeAccept, capture: "environment", onChange: handleFileChange, className: "hidden", "aria-hidden": "true" })), helperText && !error && (_jsx(Text, { variant: "secondary", size: "xs", children: helperText })), error && _jsx(Alert, { variant: "error", children: error }), pendingVideoUrl && (_jsx(VideoTrimModal, { isOpen: showTrimModal, videoUrl: pendingVideoUrl, onClose: handleTrimClose, onSave: handleTrimSave })), pendingVideoUrl && (_jsx(VideoThumbnailSelector, { isOpen: showThumbnailModal, videoUrl: pendingVideoUrl, onClose: handleThumbnailClose, onSelect: handleThumbnailSelect, onUpload: onUpload }))] }));
+}

package/dist/features/media/upload/MediaUploadList.d.ts

@@ -0,0 +1,26 @@
+import { type MediaField } from "../types/index";
+export interface MediaUploadListProps {
+    label: string;
+    value: MediaField[];
+    onChange: (media: MediaField[]) => void;
+    onUpload: (file: File) => Promise<string>;
+    accept?: string;
+    maxSizeMB?: number;
+    maxItems?: number;
+    disabled?: boolean;
+    helperText?: string;
+    /**
+     * Called with staged URLs that were uploaded but never persisted.
+     * Parent should call DELETE /api/media?url=... for each URL.
+     */
+    onAbort?: (stagedUrls: string[]) => void;
+    /**
+     * Live callback for parent forms to track staged URLs.
+     */
+    onStagedUrlsChange?: (stagedUrls: string[]) => void;
+    /**
+     * Set true after successful save to prevent auto-cleanup on unmount.
+     */
+    isPersisted?: boolean;
+}
+export declare function MediaUploadList({ label, value, onChange, onUpload, accept, maxSizeMB, maxItems, disabled, helperText, onAbort, onStagedUrlsChange, isPersisted, }: MediaUploadListProps): import("react/jsx-runtime").JSX.Element;

package/dist/features/media/upload/MediaUploadList.js

@@ -0,0 +1,104 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Alert, Button, Div, Label, Spinner, Text } from "../../../ui";
+import { MediaImage } from "../MediaImage";
+import { MediaVideo } from "../MediaVideo";
+import { inferMediaTypeFromMime } from "../types/index";
+function fileNameFromUrl(url) {
+    try {
+        const parts = new URL(url).pathname.split("/");
+        return decodeURIComponent(parts[parts.length - 1] || url);
+    }
+    catch {
+        return url;
+    }
+}
+export function MediaUploadList({ label, value, onChange, onUpload, accept = "image/*,video/*", maxSizeMB = 50, maxItems = 12, disabled = false, helperText, onAbort, onStagedUrlsChange, isPersisted = false, }) {
+    const inputRef = useRef(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const stagedUrlsRef = useRef([]);
+    const onAbortRef = useRef(onAbort);
+    const onStagedUrlsChangeRef = useRef(onStagedUrlsChange);
+    const isPersistedRef = useRef(isPersisted);
+    useEffect(() => {
+        onAbortRef.current = onAbort;
+    }, [onAbort]);
+    useEffect(() => {
+        onStagedUrlsChangeRef.current = onStagedUrlsChange;
+    }, [onStagedUrlsChange]);
+    useEffect(() => {
+        isPersistedRef.current = isPersisted;
+    }, [isPersisted]);
+    useEffect(() => {
+        return () => {
+            if (!isPersistedRef.current && stagedUrlsRef.current.length > 0) {
+                onAbortRef.current?.([...stagedUrlsRef.current]);
+            }
+        };
+    }, []);
+    const emitStaged = () => {
+        onStagedUrlsChangeRef.current?.([...stagedUrlsRef.current]);
+    };
+    const stageUrl = (url) => {
+        if (!stagedUrlsRef.current.includes(url)) {
+            stagedUrlsRef.current.push(url);
+            emitStaged();
+        }
+    };
+    const unstageUrl = (url) => {
+        const next = stagedUrlsRef.current.filter((u) => u !== url);
+        if (next.length !== stagedUrlsRef.current.length) {
+            stagedUrlsRef.current = next;
+            emitStaged();
+        }
+    };
+    const handleFileChange = async (e) => {
+        const files = Array.from(e.target.files ?? []);
+        if (files.length === 0)
+            return;
+        if (value.length + files.length > maxItems) {
+            setError(`You can upload up to ${maxItems} files.`);
+            e.currentTarget.value = "";
+            return;
+        }
+        setError(null);
+        setIsLoading(true);
+        try {
+            const uploaded = [];
+            for (const file of files) {
+                const sizeMb = file.size / 1024 / 1024;
+                if (sizeMb > maxSizeMB) {
+                    throw new Error(`${file.name} exceeds ${maxSizeMB}MB`);
+                }
+                const url = await onUpload(file);
+                stageUrl(url);
+                uploaded.push({
+                    url,
+                    type: inferMediaTypeFromMime(file.type, url),
+                });
+            }
+            onChange([...value, ...uploaded]);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : "Upload failed");
+        }
+        finally {
+            setIsLoading(false);
+            e.currentTarget.value = "";
+        }
+    };
+    const removeAt = (index) => {
+        const target = value[index];
+        if (!target)
+            return;
+        const next = value.filter((_, i) => i !== index);
+        onChange(next);
+        if (stagedUrlsRef.current.includes(target.url)) {
+            onAbortRef.current?.([target.url]);
+            unstageUrl(target.url);
+        }
+    };
+    return (_jsxs(Div, { className: "space-y-2", children: [_jsx(Label, { className: "block text-sm font-medium text-zinc-600 dark:text-zinc-400", children: label }), value.length > 0 && (_jsx(Div, { className: "grid grid-cols-1 sm:grid-cols-2 gap-3", children: value.map((item, index) => (_jsxs(Div, { className: "rounded-lg border border-zinc-200 dark:border-zinc-700 bg-zinc-50 dark:bg-zinc-900 p-3", children: [item.type === "video" ? (_jsx(Div, { className: "relative aspect-video overflow-hidden rounded-lg", children: _jsx(MediaVideo, { src: item.url, alt: item.alt || `Media ${index + 1}`, controls: true }) })) : item.type === "image" ? (_jsx(Div, { className: "relative aspect-video overflow-hidden rounded-lg", children: _jsx(MediaImage, { src: item.url, alt: item.alt || `Media ${index + 1}`, size: "card", objectFit: "contain" }) })) : (_jsx("a", { href: item.url, target: "_blank", rel: "noopener noreferrer", className: "text-sm underline break-all text-blue-600 dark:text-blue-400", children: fileNameFromUrl(item.url) })), !disabled && (_jsx(Div, { className: "mt-2", children: _jsx(Button, { type: "button", size: "sm", variant: "danger", onClick: () => removeAt(index), children: "Remove" }) }))] }, `${item.url}-${index}`))) })), !disabled && value.length < maxItems && (_jsx(Button, { type: "button", variant: "ghost", className: "w-full py-3 border-2 border-dashed border-zinc-200 dark:border-zinc-700 rounded-xl text-sm text-zinc-500 dark:text-zinc-400", onClick: () => inputRef.current?.click(), disabled: isLoading, children: isLoading ? "Uploading..." : "Add media" })), isLoading && (_jsxs(Div, { className: "flex items-center gap-2", children: [_jsx(Spinner, { size: "sm" }), _jsx(Text, { size: "sm", variant: "secondary", children: "Uploading" })] })), _jsx("input", { ref: inputRef, type: "file", multiple: true, accept: accept, onChange: handleFileChange, className: "hidden", "aria-hidden": "true" }), helperText && !error && (_jsx(Text, { variant: "secondary", size: "xs", children: helperText })), error && _jsx(Alert, { variant: "error", children: error })] }));
+}

package/dist/features/orders/actions/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./order-actions";
+export * from "./refund-actions";

package/dist/features/orders/actions/index.js

@@ -0,0 +1,2 @@
+export * from "./order-actions";
+export * from "./refund-actions";

package/dist/features/orders/actions/order-actions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Orders Domain Actions (appkit)
+ *
+ * Pure business functions — auth, rate-limiting, and Next.js specifics
+ * are handled by the calling server action in the consumer.
+ */
+import type { OrderDocument } from "../schemas";
+import type { TrackingInfo } from "../../../contracts/shipping";
+export declare function cancelOrderForUser(userId: string, orderId: string, reason: string): Promise<void>;
+export declare function listOrdersForUser(userId: string): Promise<OrderDocument[]>;
+export declare function getOrderByIdForUser(userId: string, orderId: string): Promise<OrderDocument>;
+/**
+ * Retrieve live tracking info for an order via the registered IShippingProvider.
+ * Returns null when no shipping provider is registered or no trackingNumber exists.
+ */
+export declare function getTrackingInfo(trackingId: string): Promise<TrackingInfo | null>;

package/dist/features/orders/actions/order-actions.js

@@ -0,0 +1,46 @@
+/**
+ * Orders Domain Actions (appkit)
+ *
+ * Pure business functions — auth, rate-limiting, and Next.js specifics
+ * are handled by the calling server action in the consumer.
+ */
+import { NotFoundError, AuthorizationError, ValidationError, } from "../../../errors";
+import { serverLogger } from "../../../monitoring";
+import { getProviders } from "../../../contracts";
+import { orderRepository } from "../repository/orders.repository";
+const CANCELLABLE_STATUSES = ["pending", "confirmed"];
+export async function cancelOrderForUser(userId, orderId, reason) {
+    const order = await orderRepository.findById(orderId);
+    if (!order)
+        throw new NotFoundError("Order not found");
+    if (order.userId !== userId)
+        throw new AuthorizationError("You are not authorised to cancel this order");
+    if (!CANCELLABLE_STATUSES.includes(order.status)) {
+        throw new ValidationError("Only pending or confirmed orders can be cancelled");
+    }
+    await orderRepository.cancelOrder(orderId, reason);
+    serverLogger.info("Order cancelled by user", { userId, orderId, reason });
+}
+export async function listOrdersForUser(userId) {
+    return orderRepository.findByUser(userId);
+}
+export async function getOrderByIdForUser(userId, orderId) {
+    const order = await orderRepository.findById(orderId);
+    if (!order)
+        throw new NotFoundError("Order not found");
+    if (order.userId !== userId)
+        throw new NotFoundError("Order not found");
+    return order;
+}
+/**
+ * Retrieve live tracking info for an order via the registered IShippingProvider.
+ * Returns null when no shipping provider is registered or no trackingNumber exists.
+ */
+export async function getTrackingInfo(trackingId) {
+    const { shipping } = getProviders();
+    if (!shipping) {
+        serverLogger.warn("getTrackingInfo called but no shipping provider registered");
+        return null;
+    }
+    return shipping.trackShipment(trackingId);
+}

package/dist/features/orders/actions/refund-actions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Refund Domain Actions (appkit)
+ *
+ * Pure business functions for admin-initiated partial refunds and
+ * user-facing refund previews.  Auth, rate-limiting, and Next.js specifics
+ * are handled by the consumer.
+ */
+export interface PartialRefundResult {
+    orderId: string;
+    grossRefund: number;
+    feeDeducted: number;
+    netRefund: number;
+    currency: string;
+}
+export declare function issuePartialRefund(adminUid: string, orderId: string, deductFees: boolean, refundNote?: string): Promise<PartialRefundResult>;
+export declare function previewCancellationRefund(userId: string, orderId: string): Promise<PartialRefundResult | null>;