@firecms/media_manager 3.1.0-canary.02232f4

package/dist/locales/pt.d.ts

@@ -0,0 +1,45 @@
+export declare const mediaManagerTranslationsPt: {
+    media_library: string;
+    media_library_description: string;
+    media_search_assets: string;
+    media_grid_view: string;
+    media_list_view: string;
+    media_refresh: string;
+    media_upload: string;
+    media_error_loading: string;
+    media_try_again: string;
+    media_no_assets: string;
+    media_upload_first_file: string;
+    media_asset_updated: string;
+    media_error_updating: string;
+    media_asset_deleted: string;
+    media_error_deleting: string;
+    media_error_getting_url: string;
+    media_preview_not_available: string;
+    media_dimensions: string;
+    media_size: string;
+    media_type: string;
+    media_created: string;
+    media_file_name: string;
+    media_title: string;
+    media_alt_text: string;
+    media_recommended_seo: string;
+    media_caption: string;
+    media_tags: string;
+    media_add_tag: string;
+    media_add: string;
+    media_save_changes: string;
+    media_delete_asset: string;
+    media_delete_confirmation: string;
+    media_file_too_large: string;
+    media_file_type_not_allowed: string;
+    media_upload_failed: string;
+    media_upload_files: string;
+    media_drop_files: string;
+    media_max_file_size: string;
+    media_selected_files_count: string;
+    media_remove: string;
+    media_uploading: string;
+    media_manage_description: string;
+    media_assets_count: string;
+};

package/dist/types/config.d.ts

@@ -0,0 +1,87 @@
+import { DataSourceDelegate, StorageSource } from "@firecms/core";
+/**
+ * Configuration for a thumbnail size.
+ * Thumbnails are generated client-side before upload.
+ */
+export interface ThumbnailSize {
+    /**
+     * Unique name for this size (e.g., "small", "medium", "large").
+     * Used as a key in the thumbnails record.
+     */
+    name: string;
+    /**
+     * Maximum width in pixels.
+     * The image will be scaled to fit within this width while maintaining aspect ratio.
+     */
+    width: number;
+    /**
+     * Maximum height in pixels.
+     * The image will be scaled to fit within this height while maintaining aspect ratio.
+     */
+    height: number;
+    /**
+     * JPEG quality for the thumbnail (0-1).
+     * @default 0.8
+     */
+    quality?: number;
+}
+/**
+ * Configuration options for the Media Manager plugin.
+ */
+export interface MediaManagerConfig {
+    /**
+     * Storage source for file operations (upload, download, delete).
+     * Typically useFirebaseStorageSource() or similar.
+     */
+    storageSource: StorageSource;
+    /**
+     * Data source delegate for metadata persistence.
+     * Typically useFirestoreDelegate() or similar.
+     */
+    dataSourceDelegate: DataSourceDelegate;
+    /**
+     * Path in storage where media files will be uploaded.
+     * @default "media"
+     */
+    storagePath?: string;
+    /**
+     * Collection path in the database for storing asset metadata.
+     * @default "media_assets"
+     */
+    collectionPath?: string;
+    /**
+     * Optional bucket name for storage operations.
+     * If not specified, uses the default bucket.
+     */
+    bucket?: string;
+    /**
+     * Maximum file size allowed for uploads (in bytes).
+     * @default 52428800 (50MB)
+     */
+    maxFileSize?: number;
+    /**
+     * Allowed MIME types for uploads.
+     * If not specified, all file types are allowed.
+     */
+    acceptedMimeTypes?: string[];
+    /**
+     * Thumbnail sizes to generate on upload.
+     * Thumbnails are generated client-side using canvas before upload.
+     * If not specified, no thumbnails are generated.
+     *
+     * @example
+     * ```typescript
+     * thumbnailSizes: [
+     *     { name: "small", width: 150, height: 150 },
+     *     { name: "medium", width: 400, height: 400 }
+     * ]
+     * ```
+     */
+    thumbnailSizes?: ThumbnailSize[];
+    /**
+     * Subfolder path for storing thumbnails.
+     * Thumbnails are stored under `{storagePath}/{thumbnailPath}/{sizeName}/`.
+     * @default "thumbs"
+     */
+    thumbnailPath?: string;
+}

package/dist/types/controller.d.ts

@@ -0,0 +1,66 @@
+import { MediaAsset } from "./media_asset";
+/**
+ * Controller interface for managing media assets.
+ * Provides methods for CRUD operations and state management.
+ */
+export interface MediaManagerController {
+    /**
+     * Whether the controller is currently loading data
+     */
+    loading: boolean;
+    /**
+     * Error if any operation failed
+     */
+    error?: Error;
+    /**
+     * List of loaded media assets
+     */
+    assets: MediaAsset[];
+    /**
+     * Total count of assets (may differ from assets.length during pagination)
+     */
+    totalCount?: number;
+    /**
+     * Currently selected asset (for details view)
+     */
+    selectedAsset?: MediaAsset;
+    /**
+     * Select an asset for viewing/editing
+     */
+    selectAsset: (asset: MediaAsset | undefined) => void;
+    /**
+     * Upload a new file to the media library
+     * @param file The file to upload
+     * @param metadata Optional metadata to attach
+     * @returns The created MediaAsset
+     */
+    uploadFile: (file: File, metadata?: Partial<Pick<MediaAsset, "title" | "altText" | "caption" | "tags">>) => Promise<MediaAsset>;
+    /**
+     * Delete an asset from storage and database
+     * @param assetId The ID of the asset to delete
+     */
+    deleteAsset: (assetId: string) => Promise<void>;
+    /**
+     * Update asset metadata
+     * @param assetId The ID of the asset to update
+     * @param data The fields to update
+     */
+    updateAsset: (assetId: string, data: Partial<MediaAsset>) => Promise<void>;
+    /**
+     * Refresh the assets list from the database
+     */
+    refreshAssets: () => Promise<void>;
+    /**
+     * Search assets by text
+     * @param query Search query string
+     */
+    searchAssets: (query: string) => void;
+    /**
+     * Storage path configuration
+     */
+    storagePath: string;
+    /**
+     * Collection path configuration
+     */
+    collectionPath: string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./media_asset";
+export * from "./config";
+export * from "./controller";

package/dist/types/media_asset.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Represents a media asset stored in the media library.
+ * This interface defines the metadata stored in the database for each file.
+ */
+export interface MediaAsset {
+    /**
+     * Unique identifier for the asset (document ID in the database)
+     */
+    id: string;
+    /**
+     * Original file name
+     */
+    fileName: string;
+    /**
+     * Path in storage where the file is located
+     */
+    storagePath: string;
+    /**
+     * Cached download URL for quick access
+     */
+    downloadURL?: string;
+    /**
+     * MIME type of the file (e.g., "image/jpeg", "application/pdf")
+     */
+    mimeType: string;
+    /**
+     * File size in bytes
+     */
+    size: number;
+    /**
+     * Dimensions for image/video files
+     */
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * User-defined title for the asset
+     */
+    title?: string;
+    /**
+     * Alternative text for accessibility (SEO recommended)
+     */
+    altText?: string;
+    /**
+     * Optional caption/description
+     */
+    caption?: string;
+    /**
+     * User-defined tags for categorization
+     */
+    tags?: string[];
+    /**
+     * Timestamp when the asset was created
+     */
+    createdAt: Date;
+    /**
+     * Timestamp when the asset was last updated
+     */
+    updatedAt: Date;
+    /**
+     * Storage bucket name (for multi-bucket setups)
+     */
+    bucket?: string;
+    /**
+     * Thumbnail URLs keyed by size name (e.g., "small", "medium").
+     * These are generated during upload based on thumbnailSizes config.
+     */
+    thumbnails?: Record<string, string>;
+}

package/dist/useMediaManagerController.d.ts

@@ -0,0 +1,18 @@
+import { DataSourceDelegate, StorageSource } from "@firecms/core";
+import { MediaManagerController, ThumbnailSize } from "./types";
+export interface UseMediaManagerControllerProps {
+    storageSource: StorageSource;
+    dataSourceDelegate: DataSourceDelegate;
+    storagePath: string;
+    collectionPath: string;
+    bucket?: string;
+    /** Thumbnail sizes to generate on upload */
+    thumbnailSizes?: ThumbnailSize[];
+    /** Path prefix for thumbnails. Default: "thumbs" */
+    thumbnailPath?: string;
+}
+/**
+ * Hook that creates a MediaManagerController for managing media assets.
+ * Handles all CRUD operations for files and their metadata.
+ */
+export declare function useMediaManagerController({ storageSource, dataSourceDelegate, storagePath, collectionPath, bucket, thumbnailSizes, thumbnailPath }: UseMediaManagerControllerProps): MediaManagerController;

package/dist/useMediaManagerPlugin.d.ts

@@ -0,0 +1,23 @@
+import { FireCMSPlugin } from "@firecms/core";
+import { MediaManagerConfig } from "./types";
+export interface MediaManagerPluginProps extends MediaManagerConfig {
+}
+/**
+ * Hook to create the Media Manager plugin for FireCMS.
+ *
+ * The plugin automatically registers the Media Library view in the navigation.
+ *
+ * @example
+ * ```tsx
+ * const { plugin: mediaManagerPlugin } = useMediaManagerPlugin({
+ *     storageSource,
+ *     dataSourceDelegate: firestoreDelegate,
+ *     storagePath: "media",
+ *     collectionPath: "media_assets"
+ * });
+ *
+ * // Add plugin to your plugins array - view is auto-registered
+ * const plugins = [mediaManagerPlugin, ...otherPlugins];
+ * ```
+ */
+export declare function useMediaManagerPlugin(props: MediaManagerPluginProps): FireCMSPlugin;

package/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "@firecms/media_manager",
+    "type": "module",
+    "version": "3.1.0-canary.02232f4",
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "firebase",
+        "cms",
+        "media",
+        "media manager",
+        "asset manager",
+        "firecms",
+        "storage"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.es.js",
+            "require": "./dist/index.umd.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "main": "./dist/index.umd.js",
+    "module": "./dist/index.es.js",
+    "types": "./dist/index.d.ts",
+    "source": "src/index.ts",
+    "dependencies": {
+        "@firecms/core": "^3.1.0-canary.02232f4",
+        "@firecms/formex": "^3.1.0-canary.02232f4",
+        "@firecms/ui": "^3.1.0-canary.02232f4"
+    },
+    "peerDependencies": {
+        "react": ">=18.3.1 || >=19.0.0",
+        "react-dom": ">=18.3.1 || >=19.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20.19.17",
+        "@types/react": "^19.2.3",
+        "@types/react-dom": "^19.2.3",
+        "@vitejs/plugin-react": "^4.7.0",
+        "babel-plugin-react-compiler": "^19.0.0-beta-af1b7da-20250417",
+        "eslint-plugin-react-compiler": "^19.1.0-rc.2",
+        "typescript": "^5.9.3",
+        "vite": "^7.2.4"
+    },
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+        "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "gitHead": "6281205d9f39f85991e1d8533474bfb9a542ed03"
+}

package/src/MediaManagerProvider.tsx

@@ -0,0 +1,34 @@
+import React, { createContext, PropsWithChildren, useContext } from "react";
+import { MediaManagerController } from "./types";
+
+const MediaManagerContext = createContext<MediaManagerController | undefined>(undefined);
+
+/**
+ * Hook to access the MediaManagerController from context.
+ * Must be used within a MediaManagerProvider.
+ */
+export function useMediaManager(): MediaManagerController {
+    const context = useContext(MediaManagerContext);
+    if (!context) {
+        throw new Error("useMediaManager must be used within a MediaManagerProvider");
+    }
+    return context;
+}
+
+export interface MediaManagerProviderProps {
+    controller: MediaManagerController;
+}
+
+/**
+ * Provider component that makes the MediaManagerController available to all children.
+ */
+export function MediaManagerProvider({
+    controller,
+    children
+}: PropsWithChildren<MediaManagerProviderProps>) {
+    return (
+        <MediaManagerContext.Provider value={controller}>
+            {children}
+        </MediaManagerContext.Provider>
+    );
+}

package/src/components/MediaAssetCard.tsx

@@ -0,0 +1,134 @@
+import React from "react";
+import {
+    Card,
+    Typography,
+    cls,
+    ImageIcon,
+    DescriptionIcon,
+    VideoLibraryIcon,
+    AudiotrackIcon,
+    CheckIcon,
+    defaultBorderMixin
+} from "@firecms/ui";
+import { MediaAsset } from "../types";
+
+export interface MediaAssetCardProps {
+    asset: MediaAsset;
+    viewMode: "grid" | "list";
+    onClick: () => void;
+    selected?: boolean;
+    /** Preferred thumbnail size to display (e.g., "small", "medium") */
+    thumbnailSize?: string;
+}
+
+/**
+ * Card component for displaying a media asset in the grid or list.
+ */
+export function MediaAssetCard({
+    asset,
+    viewMode,
+    onClick,
+    selected,
+    thumbnailSize = "small"
+}: MediaAssetCardProps) {
+    const isImage = asset.mimeType.startsWith("image/");
+    const isVideo = asset.mimeType.startsWith("video/");
+    const isAudio = asset.mimeType.startsWith("audio/");
+
+    const FileIcon = isImage ? ImageIcon
+        : isVideo ? VideoLibraryIcon
+            : isAudio ? AudiotrackIcon
+                : DescriptionIcon;
+
+    const formatSize = (bytes: number): string => {
+        if (bytes < 1024) return `${bytes} B`;
+        if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    };
+
+    // Use thumbnail if available, fallback to downloadURL
+    const imageUrl = asset.thumbnails?.[thumbnailSize] ?? asset.downloadURL;
+
+    const thumbnail = isImage && imageUrl ? (
+        <img
+            src={imageUrl}
+            alt={asset.altText || asset.fileName}
+            className="w-full h-full object-cover transition-transform duration-200 group-hover:scale-105"
+            loading="lazy"
+        />
+    ) : (
+        <div className="w-full h-full flex items-center justify-center bg-surface-100 dark:bg-surface-800">
+            <FileIcon size="large" className="text-surface-400 dark:text-surface-500" />
+        </div>
+    );
+
+    if (viewMode === "list") {
+        return (
+            <div
+                className={cls(
+                    "p-3 cursor-pointer flex items-center gap-3 rounded-lg",
+                    "hover:bg-surface-100 dark:hover:bg-surface-800",
+                    "transition-colors duration-150",
+                    `border ${defaultBorderMixin}`,
+                    selected && "ring-2 ring-primary bg-primary/5"
+                )}
+                onClick={onClick}
+            >
+                <div className="w-12 h-12 rounded-md overflow-hidden flex-shrink-0 bg-surface-100 dark:bg-surface-800">
+                    {thumbnail}
+                </div>
+                <div className="flex-1 min-w-0">
+                    <Typography variant="body2" className="font-medium truncate text-surface-900 dark:text-white">
+                        {asset.title || asset.fileName}
+                    </Typography>
+                    <Typography variant="caption" color="secondary">
+                        {formatSize(asset.size)} • {asset.mimeType.split("/")[1]?.toUpperCase()}
+                    </Typography>
+                </div>
+                {selected && (
+                    <div className="w-6 h-6 rounded-full bg-primary flex items-center justify-center flex-shrink-0">
+                        <CheckIcon size="smallest" className="text-white" />
+                    </div>
+                )}
+            </div>
+        );
+    }
+
+    return (
+        <Card
+            className={cls(
+                "cursor-pointer overflow-hidden group relative",
+                "transition-all duration-200",
+                "hover:shadow-lg hover:-translate-y-0.5",
+                selected && "ring-2 ring-primary"
+            )}
+            onClick={onClick}
+        >
+            <div className="aspect-square relative overflow-hidden bg-surface-100 dark:bg-surface-800">
+                {thumbnail}
+
+                {/* Hover overlay */}
+                <div className={cls(
+                    "absolute inset-0 bg-black/0 group-hover:bg-black/20",
+                    "transition-colors duration-200"
+                )} />
+
+                {/* Selection indicator */}
+                {selected && (
+                    <div className="absolute top-2 right-2 w-6 h-6 rounded-full bg-primary flex items-center justify-center shadow-md">
+                        <CheckIcon size="smallest" className="text-white" />
+                    </div>
+                )}
+            </div>
+
+            <div className="p-3">
+                <Typography variant="body2" className="font-medium truncate text-surface-900 dark:text-white">
+                    {asset.title || asset.fileName}
+                </Typography>
+                <Typography variant="caption" color="secondary" className="truncate block mt-0.5">
+                    {formatSize(asset.size)} • {asset.mimeType.split("/")[1]?.toUpperCase()}
+                </Typography>
+            </div>
+        </Card>
+    );
+}