@caprionlinesrl/puck-plugin-media 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,479 @@
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Language configuration for multilingual fields
+ */
+interface Language {
+    code: string;
+    label: string;
+}
+/**
+ * Default languages when not specified
+ */
+declare const DEFAULT_LANGUAGES: Language[];
+/**
+ * Localized string value (e.g., { en: 'Hello', it: 'Ciao' })
+ */
+type LocalizedString = Record<string, string | undefined>;
+/**
+ * Image item - used both for API responses and stored values in Puck JSON
+ */
+interface ImageItem {
+    /** Unique identifier */
+    id: string;
+    /** Full URL to the image file */
+    url: string;
+    /** Original filename */
+    filename?: string;
+    /** Alt text (multilingual) */
+    alt?: LocalizedString;
+    /** Image width in pixels */
+    width?: number;
+    /** Image height in pixels */
+    height?: number;
+    /** File size in bytes */
+    size?: number;
+    /** Thumbnail URL for faster loading in picker (falls back to url if not provided) */
+    thumbnailUrl?: string;
+    /** Creation date (useful for cache invalidation) */
+    createdAt?: string;
+}
+/**
+ * Document item - used both for API responses and stored values in Puck JSON
+ */
+interface DocumentItem {
+    /** Unique identifier */
+    id: string;
+    /** Full URL to the document file */
+    url: string;
+    /** Original filename */
+    filename: string;
+    /** Display title (multilingual) */
+    title?: LocalizedString;
+    /** MIME type (e.g., 'application/pdf') */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** File extension (e.g., 'pdf', 'docx') */
+    extension: string;
+    /** Creation date (useful for cache invalidation) */
+    createdAt?: string;
+}
+/**
+ * Gallery item - used both for API responses and stored values in Puck JSON
+ */
+interface GalleryItem {
+    /** Unique identifier */
+    id: string;
+    /** Gallery name */
+    name: string;
+    /** Cover image for preview */
+    coverImage?: ImageItem;
+    /** Images in the gallery */
+    images: ImageItem[];
+    /** Number of images in the gallery (optional, can be calculated from images.length) */
+    imageCount?: number;
+    /** Creation date (useful for cache invalidation) */
+    createdAt?: string;
+}
+/**
+ * Parameters passed to fetchList functions
+ */
+interface FetchListParams {
+    /** Search query string */
+    query?: string;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    pageSize?: number;
+    /** Additional filters */
+    filters?: Record<string, unknown>;
+}
+/**
+ * Result from fetchList - paginated result
+ */
+interface FetchListResult<T> {
+    /** Array of items */
+    items: T[];
+    /** Total number of items (for pagination) */
+    total?: number;
+    /** Whether there are more items to load */
+    hasMore?: boolean;
+}
+/**
+ * Generic fetch list function type
+ */
+type FetchListFn<T> = (params: FetchListParams) => Promise<T[] | FetchListResult<T>>;
+/**
+ * Callbacks passed to upload functions
+ */
+interface UploadCallbacks {
+    /** Called with upload progress (0-100) */
+    onProgress: (percent: number) => void;
+}
+/**
+ * Upload function that handles single or multiple files
+ */
+type UploadFn<T> = (files: File | File[], callbacks: UploadCallbacks) => Promise<T | T[]>;
+/**
+ * Configuration for file uploads
+ */
+interface UploadConfig {
+    /**
+     * Accepted file types (MIME types or extensions)
+     * @default 'image/*' for images, '*' for documents
+     */
+    accept?: string;
+    /**
+     * Maximum file size in bytes
+     * @default 10485760 (10MB)
+     */
+    maxSize?: number;
+    /**
+     * Allow multiple file uploads
+     * @default true
+     */
+    multiple?: boolean;
+}
+/**
+ * Status of a file being uploaded
+ */
+type UploadStatus = 'pending' | 'uploading' | 'completed' | 'error';
+/**
+ * State of a file in the upload queue
+ */
+interface UploadingFile {
+    /** Unique ID for this upload */
+    id: string;
+    /** The file being uploaded */
+    file: File;
+    /** Upload progress (0-100) */
+    progress: number;
+    /** Current upload status */
+    status: UploadStatus;
+    /** Error message if status is 'error' */
+    error?: string;
+    /** Resulting item if status is 'completed' */
+    result?: ImageItem | DocumentItem;
+    /** Preview URL for the file (blob URL) */
+    previewUrl?: string;
+}
+/**
+ * Image-related callbacks
+ */
+interface ImageOptions {
+    /** Function to fetch image list from your API */
+    fetchList: FetchListFn<ImageItem>;
+    /** Function to upload images (optional) */
+    upload?: UploadFn<ImageItem>;
+    /** Function to update image metadata (alt text) */
+    update?: (id: string, data: {
+        alt?: LocalizedString;
+    }) => Promise<ImageItem>;
+    /** Function to delete an image (optional) */
+    delete?: (id: string) => Promise<void>;
+    /** Configuration for file uploads */
+    uploadConfig?: UploadConfig;
+}
+/**
+ * Gallery-related callbacks
+ */
+interface GalleryOptions {
+    /** Function to fetch gallery list from your API (required) */
+    fetchList: FetchListFn<GalleryItem>;
+    /** Function to fetch a single gallery by ID */
+    fetch: (id: string) => Promise<GalleryItem>;
+    /** Function to create a new gallery */
+    create: (name: string) => Promise<GalleryItem>;
+    /** Function to delete a gallery */
+    delete: (id: string) => Promise<void>;
+    /** Function to upload images to a gallery */
+    upload: (galleryId: string, files: File | File[], callbacks: UploadCallbacks) => Promise<ImageItem | ImageItem[]>;
+    /** Function to remove an image from a gallery */
+    removeImage: (galleryId: string, imageId: string) => Promise<void>;
+    /** Function to update image metadata within a gallery (optional - hides alt editing if not provided) */
+    updateImage?: (galleryId: string, imageId: string, data: {
+        alt?: LocalizedString;
+    }) => Promise<ImageItem>;
+}
+/**
+ * Document-related callbacks
+ */
+interface DocumentOptions {
+    /** Function to fetch document list from your API */
+    fetchList: FetchListFn<DocumentItem>;
+    /** Function to upload documents (optional - hides upload area if not provided) */
+    upload?: UploadFn<DocumentItem>;
+    /** Function to update document metadata (title) (optional - hides edit icon if not provided) */
+    update?: (id: string, data: {
+        title?: LocalizedString;
+    }) => Promise<DocumentItem>;
+    /** Function to delete a document (optional - hides manage button if not provided) */
+    delete?: (id: string) => Promise<void>;
+    /** Configuration for file uploads */
+    uploadConfig?: UploadConfig;
+}
+/**
+ * Plugin configuration options
+ */
+interface MediaPluginOptions {
+    /**
+     * Languages for multilingual fields (alt, title)
+     * @default [{ code: 'it', label: 'Italiano' }, { code: 'en', label: 'English' }]
+     */
+    languages?: Language[];
+    /**
+     * Image-related configuration (required)
+     */
+    image: ImageOptions;
+    /**
+     * Gallery-related configuration (optional)
+     */
+    gallery?: GalleryOptions;
+    /**
+     * Document-related configuration (optional)
+     */
+    document?: DocumentOptions;
+}
+/**
+ * Internal props passed to ImageField component
+ */
+interface ImageFieldProps {
+    name: string;
+    value: ImageItem | null;
+    onChange: (value: ImageItem | null) => void;
+    field: {
+        label?: string;
+        [key: string]: unknown;
+    };
+    languages: Language[];
+    imageOptions: ImageOptions;
+}
+/**
+ * Internal props passed to GalleryField component
+ */
+interface GalleryFieldProps {
+    name: string;
+    value: GalleryItem | null;
+    onChange: (value: GalleryItem | null) => void;
+    field: {
+        label?: string;
+        [key: string]: unknown;
+    };
+    languages: Language[];
+    galleryOptions: GalleryOptions;
+}
+/**
+ * Internal props passed to DocumentField component
+ */
+interface DocumentFieldProps {
+    name: string;
+    value: DocumentItem | null;
+    onChange: (value: DocumentItem | null) => void;
+    field: {
+        label?: string;
+        [key: string]: unknown;
+    };
+    languages: Language[];
+    documentOptions: DocumentOptions;
+}
+/**
+ * Props for ImagePickerModal component
+ */
+interface ImagePickerModalProps {
+    languages: Language[];
+    imageOptions: ImageOptions;
+    title?: string;
+    selectedImage?: ImageItem | null;
+    onSelect?: (item: ImageItem) => void;
+    onClose: () => void;
+    /** When false, hides the "Select Image" button. Useful for media library mode. Default: true */
+    selectable?: boolean;
+}
+/**
+ * Props for GalleryPickerModal component
+ */
+interface GalleryPickerModalProps {
+    languages: Language[];
+    galleryOptions: GalleryOptions;
+    title?: string;
+    selectedGallery?: GalleryItem | null;
+    onSelect?: (gallery: GalleryItem) => void;
+    onClose: () => void;
+    /** When false, hides the "Select Gallery" button. Useful for media library mode. Default: true */
+    selectable?: boolean;
+}
+/**
+ * Props for DocumentPickerModal component
+ */
+interface DocumentPickerModalProps {
+    languages: Language[];
+    documentOptions: DocumentOptions;
+    title?: string;
+    selectedDocument?: DocumentItem | null;
+    onSelect?: (item: DocumentItem) => void;
+    onClose: () => void;
+    /** When false, hides the "Select Document" button. Useful for media library mode. Default: true */
+    selectable?: boolean;
+}
+/**
+ * Props for ImageGrid component
+ */
+interface ImageGridProps {
+    items: ImageItem[];
+    onSelect: (item: ImageItem) => void;
+    selectedId?: string;
+    loading?: boolean;
+    /** Callback when user clicks edit icon */
+    onEditAlt?: (item: ImageItem) => void;
+    /** Whether manage mode is active (for bulk delete) */
+    manageMode?: boolean;
+    /** Set of selected item IDs for bulk operations */
+    selectedIds?: Set<string>;
+    /** Callback when user toggles selection in manage mode */
+    onToggleSelect?: (item: ImageItem) => void;
+}
+/**
+ * Puck Plugin type
+ */
+interface PuckPlugin {
+    name: string;
+    label?: string;
+    icon?: ReactNode;
+    render?: () => ReactNode;
+    overrides?: {
+        fieldTypes?: Record<string, (props: unknown) => ReactNode>;
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Create a Puck plugin for media library integration
+ *
+ * @example
+ * ```tsx
+ * import { createMediaPlugin } from '@onda-suite/puck-plugin-media';
+ *
+ * const mediaPlugin = createMediaPlugin({
+ *   // Optional: configure languages for alt/title fields
+ *   languages: [
+ *     { code: 'it', label: 'Italiano' },
+ *     { code: 'en', label: 'English' },
+ *   ],
+ *
+ *   // Image configuration (required)
+ *   image: {
+ *     fetchList: async ({ query, page, pageSize }) => {
+ *       const res = await fetch(`/api/images?q=${query}&page=${page}`);
+ *       return res.json();
+ *     },
+ *     upload: async (file, { onProgress }) => {
+ *       // Upload with progress tracking...
+ *       return uploadedImageItem;
+ *     },
+ *     update: async (id, { alt }) => {
+ *       // Update alt text
+ *       return updatedImageItem;
+ *     },
+ *     delete: async (id) => {
+ *       // Delete image (enables "Select Items" mode)
+ *     },
+ *     uploadConfig: {
+ *       accept: 'image/*',
+ *       maxSize: 10 * 1024 * 1024, // 10MB
+ *       multiple: true,
+ *     },
+ *   },
+ *
+ *   // Gallery configuration (optional)
+ *   gallery: {
+ *     fetchList: async ({ query, page }) => { ... },
+ *     fetch: async (id) => { ... },
+ *     create: async (name) => { ... },
+ *     delete: async (id) => { ... },
+ *     upload: async (galleryId, file, { onProgress }) => { ... },
+ *     removeImage: async (galleryId, imageId) => { ... },
+ *     updateImage: async (galleryId, imageId, { alt }) => { ... },
+ *   },
+ *
+ *   // Document configuration (optional)
+ *   document: {
+ *     fetchList: async ({ query, page }) => { ... },
+ *     upload: async (file, { onProgress }) => { ... },
+ *     update: async (id, { title }) => { ... },
+ *     delete: async (id) => {
+ *       // Delete document (enables "Select Items" mode)
+ *     },
+ *     uploadConfig: {
+ *       accept: '.pdf,.doc,.docx,.xls,.xlsx',
+ *       maxSize: 20 * 1024 * 1024, // 20MB
+ *       multiple: true,
+ *     },
+ *   },
+ * });
+ *
+ * <Puck config={config} plugins={[mediaPlugin]} />
+ * ```
+ */
+declare function createMediaPlugin(options: MediaPluginOptions): PuckPlugin;
+
+declare function ImageField({ value, onChange, field, languages, imageOptions, }: ImageFieldProps): react_jsx_runtime.JSX.Element;
+
+declare function ImagePickerModal({ languages, imageOptions, title, selectedImage, onSelect, onClose, selectable, }: ImagePickerModalProps): react_jsx_runtime.JSX.Element;
+
+declare function ImageGrid({ items, onSelect, selectedId, onEditAlt, manageMode, selectedIds, onToggleSelect, }: ImageGridProps): react_jsx_runtime.JSX.Element;
+
+declare function GalleryField({ value, onChange, field, languages, galleryOptions, }: GalleryFieldProps): react_jsx_runtime.JSX.Element;
+
+declare function GalleryPickerModal({ languages, galleryOptions, title, selectedGallery: _initialSelectedGallery, onSelect, onClose, selectable, }: GalleryPickerModalProps): react_jsx_runtime.JSX.Element;
+
+declare function DocumentField({ value, onChange, field, languages, documentOptions, }: DocumentFieldProps): react_jsx_runtime.JSX.Element;
+
+declare function DocumentPickerModal({ languages, documentOptions, title, selectedDocument, onSelect, onClose, selectable, }: DocumentPickerModalProps): react_jsx_runtime.JSX.Element;
+
+interface MediaPanelProps {
+    languages: Language[];
+    imageOptions: ImageOptions;
+    galleryOptions?: GalleryOptions;
+    documentOptions?: DocumentOptions;
+}
+declare function MediaPanel({ languages, imageOptions, galleryOptions, documentOptions, }: MediaPanelProps): react_jsx_runtime.JSX.Element;
+
+interface UploadDropzoneProps {
+    onFilesSelected: (files: FileList) => void;
+    config: Required<UploadConfig>;
+    disabled?: boolean;
+}
+declare function UploadDropzone({ onFilesSelected, config, disabled, }: UploadDropzoneProps): react_jsx_runtime.JSX.Element;
+
+interface UploadQueueProps {
+    files: UploadingFile[];
+    onCancel: (id: string) => void;
+    onClearCompleted: () => void;
+}
+declare function UploadQueue({ files, onCancel, onClearCompleted }: UploadQueueProps): react_jsx_runtime.JSX.Element | null;
+
+declare const formatFileSize: (bytes: number) => string;
+interface UseUploadOptions<T extends ImageItem | DocumentItem> {
+    upload: UploadFn<T>;
+    config?: UploadConfig;
+    onUploadComplete?: (item: T) => void;
+}
+interface UseUploadReturn {
+    /** Files currently being uploaded */
+    uploading: UploadingFile[];
+    /** Whether any upload is in progress */
+    isUploading: boolean;
+    /** Add files to upload queue */
+    addFiles: (files: FileList | File[]) => void;
+    /** Cancel a specific upload */
+    cancelUpload: (id: string) => void;
+    /** Clear completed/errored uploads */
+    clearCompleted: () => void;
+    /** The merged config being used */
+    uploadConfig: Required<UploadConfig>;
+}
+declare function useUpload<T extends ImageItem | DocumentItem>({ upload, config, onUploadComplete, }: UseUploadOptions<T>): UseUploadReturn;
+
+export { DEFAULT_LANGUAGES, DocumentField, type DocumentItem, type DocumentOptions, DocumentPickerModal, type FetchListFn, type FetchListParams, type FetchListResult, GalleryField, type GalleryItem, type GalleryOptions, GalleryPickerModal, ImageField, ImageGrid, type ImageItem, type ImageOptions, ImagePickerModal, type Language, type LocalizedString, MediaPanel, type MediaPluginOptions, type UploadCallbacks, type UploadConfig, UploadDropzone, type UploadFn, UploadQueue, type UploadStatus, type UploadingFile, createMediaPlugin, formatFileSize, useUpload };