@createcms/core 0.1.1

package/dist/plugins/media-optimize/index.cjs

@@ -0,0 +1,315 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var react = require('react');
+
+function isImageFile(file) {
+    return file.type.startsWith('image/');
+}
+function loadImage(file) {
+    return new Promise((resolve, reject)=>{
+        const img = new Image();
+        const url = URL.createObjectURL(file);
+        img.onload = ()=>{
+            URL.revokeObjectURL(url);
+            resolve(img);
+        };
+        img.onerror = ()=>{
+            URL.revokeObjectURL(url);
+            reject(new Error(`Failed to load image: ${file.name}`));
+        };
+        img.src = url;
+    });
+}
+function calculateDimensions(width, height, maxSize) {
+    if (width <= maxSize && height <= maxSize) {
+        return {
+            width,
+            height
+        };
+    }
+    const ratio = width / height;
+    if (width > height) {
+        return {
+            width: maxSize,
+            height: Math.round(maxSize / ratio)
+        };
+    }
+    return {
+        width: Math.round(maxSize * ratio),
+        height: maxSize
+    };
+}
+function drawToCanvas(img, width, height) {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) throw new Error('Failed to get canvas 2d context');
+    ctx.imageSmoothingEnabled = true;
+    ctx.imageSmoothingQuality = 'high';
+    ctx.drawImage(img, 0, 0, width, height);
+    return canvas;
+}
+function canvasToBlobAsync(canvas, mimeType, quality) {
+    return new Promise((resolve, reject)=>{
+        canvas.toBlob((blob)=>blob ? resolve(blob) : reject(new Error(`canvas.toBlob failed for ${mimeType}`)), mimeType, quality);
+    });
+}
+let _nativeWebpSupported = null;
+async function supportsNativeWebp() {
+    if (_nativeWebpSupported !== null) return _nativeWebpSupported;
+    const c = document.createElement('canvas');
+    c.width = 1;
+    c.height = 1;
+    const blob = await new Promise((r)=>c.toBlob((b)=>r(b), 'image/webp', 0.5));
+    _nativeWebpSupported = blob?.type === 'image/webp';
+    return _nativeWebpSupported;
+}
+async function encodeWebp(canvas, quality) {
+    if (await supportsNativeWebp()) {
+        return canvasToBlobAsync(canvas, 'image/webp', quality);
+    }
+    try {
+        const { encode } = await import(/* webpackIgnore: true */ '@jsquash/webp');
+        const ctx = canvas.getContext('2d');
+        if (!ctx) throw new Error('Failed to get canvas 2d context');
+        const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+        const buffer = await encode(imageData, {
+            quality: quality * 100
+        });
+        return new Blob([
+            buffer
+        ], {
+            type: 'image/webp'
+        });
+    } catch  {
+        throw new Error('WebP encoding not supported natively and @jsquash/webp is not installed. ' + 'Install it as a dependency: npm install @jsquash/webp');
+    }
+}
+function inferMimeFromName(name) {
+    const ext = name.split('.').pop()?.toLowerCase();
+    const map = {
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        webp: 'image/webp',
+        svg: 'image/svg+xml',
+        bmp: 'image/bmp',
+        avif: 'image/avif'
+    };
+    return ext && map[ext] || 'image/jpeg';
+}
+function replaceExtension(filename, newExt) {
+    const dot = filename.lastIndexOf('.');
+    const base = dot > 0 ? filename.slice(0, dot) : filename;
+    return `${base}.${newExt}`;
+}
+/**
+ * Optimize an image file on the client before uploading.
+ *
+ * - **Resize**: Downscale if either dimension exceeds `config.resize.maxSize`
+ * - **Compress**: Reduce quality via `config.compress.quality` (1-100)
+ * - **Convert**: Convert to WebP when `config.convert.format` is set
+ * - **storeOriginal**: When `convert.storeOriginal` is true, also returns an
+ *   `originalVariant` -- same resize + compress but kept in the original format
+ *
+ * Non-image files are returned unchanged with `optimized: false`.
+ */ async function optimizeImage(file, config) {
+    if (!isImageFile(file)) {
+        return {
+            file,
+            optimized: false
+        };
+    }
+    const hasResize = !!config.resize?.maxSize;
+    const hasCompress = config.compress?.quality != null;
+    const hasConvert = config.convert?.format === 'webp';
+    if (!hasResize && !hasCompress && !hasConvert) {
+        return {
+            file,
+            optimized: false
+        };
+    }
+    const img = await loadImage(file);
+    const maxSize = config.resize?.maxSize ?? Math.max(img.naturalWidth, img.naturalHeight);
+    const quality = config.compress?.quality != null ? config.compress.quality / 100 : 0.8;
+    const { width, height } = calculateDimensions(img.naturalWidth, img.naturalHeight, maxSize);
+    const canvas = drawToCanvas(img, width, height);
+    let originalVariant;
+    const originalMime = file.type || inferMimeFromName(file.name);
+    if (hasConvert && config.convert.storeOriginal) {
+        const originalBlob = await canvasToBlobAsync(canvas, originalMime, quality);
+        originalVariant = new File([
+            originalBlob
+        ], file.name, {
+            type: originalMime,
+            lastModified: Date.now()
+        });
+    }
+    let primaryBlob;
+    let primaryName;
+    let primaryType;
+    if (hasConvert) {
+        primaryBlob = await encodeWebp(canvas, quality);
+        primaryName = replaceExtension(file.name, 'webp');
+        primaryType = 'image/webp';
+    } else {
+        primaryBlob = await canvasToBlobAsync(canvas, originalMime, quality);
+        primaryName = file.name;
+        primaryType = originalMime;
+    }
+    const primaryFile = new File([
+        primaryBlob
+    ], primaryName, {
+        type: primaryType,
+        lastModified: Date.now()
+    });
+    return {
+        file: primaryFile,
+        originalVariant,
+        optimized: true
+    };
+}
+
+const INITIAL_STATE = {
+    results: null,
+    isOptimizing: false,
+    error: null
+};
+/**
+ * React hook that optimizes image files on the client.
+ *
+ * Accepts a single `File` or `File[]` and an `OptimizationConfig`.
+ * Runs `optimizeImage` automatically whenever the input reference changes.
+ * Non-image files pass through with `optimized: false`.
+ *
+ * ```tsx
+ * const { results, isOptimizing, error } = cmsClient.optimize.useOptimize(file, {
+ *   compress: { quality: 80 },
+ *   resize: { maxSize: 1200 },
+ * });
+ * ```
+ */ function useOptimize(input, config) {
+    const [state, setState] = react.useState(INITIAL_STATE);
+    const abortRef = react.useRef(false);
+    const runIdRef = react.useRef(0);
+    const files = react.useMemo(()=>Array.isArray(input) ? input : [
+            input
+        ], // Stabilize: same File instances → same array
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        Array.isArray(input) ? input.length : input
+    ]);
+    const configKey = JSON.stringify(config);
+    const configRef = react.useRef(config);
+    configRef.current = config;
+    react.useEffect(()=>{
+        if (files.length === 0) {
+            setState((prev)=>prev.results?.length === 0 && !prev.isOptimizing ? prev : {
+                    results: [],
+                    isOptimizing: false,
+                    error: null
+                });
+            return;
+        }
+        abortRef.current = false;
+        const currentRun = ++runIdRef.current;
+        setState({
+            results: null,
+            isOptimizing: true,
+            error: null
+        });
+        Promise.all(files.map((file)=>optimizeImage(file, configRef.current))).then((results)=>{
+            if (abortRef.current || runIdRef.current !== currentRun) return;
+            setState({
+                results,
+                isOptimizing: false,
+                error: null
+            });
+        }).catch((err)=>{
+            if (abortRef.current || runIdRef.current !== currentRun) return;
+            setState({
+                results: null,
+                isOptimizing: false,
+                error: err instanceof Error ? err.message : 'Optimization failed'
+            });
+        });
+        return ()=>{
+            abortRef.current = true;
+        };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        files,
+        configKey
+    ]);
+    return state;
+}
+
+const PLUGIN_ID = 'media-optimize';
+const $ERROR_CODES = {
+    OPTIMIZATION_FAILED: {
+        status: 422,
+        message: 'Image optimization failed'
+    },
+    WEBP_NOT_SUPPORTED: {
+        status: 422,
+        message: 'WebP encoding is not supported in this browser and @jsquash/webp is not installed'
+    },
+    CANVAS_CONTEXT_FAILED: {
+        status: 500,
+        message: 'Failed to acquire canvas 2D context for image processing'
+    }
+};
+/**
+ * Client plugin that adds image optimization under its own namespace.
+ *
+ * Exposes `cmsClient.optimize.useOptimize(file, config)` for client-side
+ * image optimization. Optimized files can then be passed to
+ * `cmsClient.media.useUploadAssets().upload(files)`.
+ *
+ * ```ts
+ * import { mediaOptimizeClient } from '@createcms/core/plugins/media-optimize';
+ *
+ * const client = createCMSClient<typeof cms>({
+ *   baseURL: '/api/cms',
+ *   plugins: [
+ *     mediaOptimizeClient({
+ *       compress: { quality: 90 },
+ *       resize: { maxSize: 2000 },
+ *       convert: { format: 'webp', storeOriginal: true },
+ *     }),
+ *   ],
+ * });
+ *
+ * // In a component:
+ * const { results, isOptimizing } = client.optimize.useOptimize(file, config);
+ * ```
+ */ function mediaOptimizeClient(config) {
+    return {
+        id: PLUGIN_ID,
+        $ERROR_CODES,
+        async init (_$fetch, _$store) {
+            return {
+                context: {
+                    [`${PLUGIN_ID}:config`]: config
+                }
+            };
+        },
+        getActions: ()=>({
+                optimize: {
+                    useOptimize: (input, overrideConfig)=>useOptimize(input, overrideConfig ?? config)
+                }
+            }),
+        atomListeners: [
+            {
+                matcher: (path)=>path.startsWith('/media/createSignedUpload'),
+                signal: '$mediaSignal'
+            }
+        ]
+    };
+}
+
+exports.mediaOptimizeClient = mediaOptimizeClient;
+exports.optimizeImage = optimizeImage;
+exports.useOptimize = useOptimize;

package/dist/plugins/media-optimize/index.d.cts

@@ -0,0 +1,144 @@
+import { WritableAtom } from 'nanostores';
+
+type CompressOptions = {
+    /** JPEG/PNG quality (1-100). @default 80 */
+    quality?: number;
+};
+type ResizeOptions = {
+    /** Maximum width/height in pixels. @default 2000 */
+    maxSize?: number;
+};
+type ConvertOptions = {
+    /** Only WebP conversion is supported. */
+    format: 'webp';
+    /**
+     * When true, also store a copy in the original format (resized + compressed
+     * but not converted). Useful for email clients that don't support WebP.
+     * @default false
+     */
+    storeOriginal?: boolean;
+};
+type OptimizationConfig = {
+    /** Image compression options. Omit to disable. */
+    compress?: CompressOptions;
+    /** Resize options. Omit to disable. */
+    resize?: ResizeOptions;
+    /** Format conversion options. Omit to disable. */
+    convert?: ConvertOptions;
+};
+
+interface OptimizeResult {
+    file: File;
+    originalVariant?: File;
+    optimized: boolean;
+}
+/**
+ * Optimize an image file on the client before uploading.
+ *
+ * - **Resize**: Downscale if either dimension exceeds `config.resize.maxSize`
+ * - **Compress**: Reduce quality via `config.compress.quality` (1-100)
+ * - **Convert**: Convert to WebP when `config.convert.format` is set
+ * - **storeOriginal**: When `convert.storeOriginal` is true, also returns an
+ *   `originalVariant` -- same resize + compress but kept in the original format
+ *
+ * Non-image files are returned unchanged with `optimized: false`.
+ */
+declare function optimizeImage(file: File, config: OptimizationConfig): Promise<OptimizeResult>;
+
+type OptimizeState = {
+    results: OptimizeResult[] | null;
+    isOptimizing: boolean;
+    error: string | null;
+};
+/**
+ * React hook that optimizes image files on the client.
+ *
+ * Accepts a single `File` or `File[]` and an `OptimizationConfig`.
+ * Runs `optimizeImage` automatically whenever the input reference changes.
+ * Non-image files pass through with `optimized: false`.
+ *
+ * ```tsx
+ * const { results, isOptimizing, error } = cmsClient.optimize.useOptimize(file, {
+ *   compress: { quality: 80 },
+ *   resize: { maxSize: 1200 },
+ * });
+ * ```
+ */
+declare function useOptimize(input: File | File[], config: OptimizationConfig): OptimizeState;
+
+type CMSFetch = (path: string, options?: {
+    method?: string;
+    body?: unknown;
+    query?: unknown;
+    /**
+     * Forwarded to the underlying `fetch` (better-call → @better-fetch → native
+     * `fetch`). Set for fire-and-forget analytics beacons (the A/B event ingest)
+     * so the POST is NOT cancelled when the page unloads/navigates mid-request.
+     */
+    keepalive?: boolean;
+}) => Promise<unknown>;
+interface CMSClientStore {
+    notify: (signal: string) => void;
+    listen: (signal: string, listener: () => void) => void;
+    atoms: Record<string, WritableAtom<unknown>>;
+}
+
+/**
+ * Client plugin that adds image optimization under its own namespace.
+ *
+ * Exposes `cmsClient.optimize.useOptimize(file, config)` for client-side
+ * image optimization. Optimized files can then be passed to
+ * `cmsClient.media.useUploadAssets().upload(files)`.
+ *
+ * ```ts
+ * import { mediaOptimizeClient } from '@createcms/core/plugins/media-optimize';
+ *
+ * const client = createCMSClient<typeof cms>({
+ *   baseURL: '/api/cms',
+ *   plugins: [
+ *     mediaOptimizeClient({
+ *       compress: { quality: 90 },
+ *       resize: { maxSize: 2000 },
+ *       convert: { format: 'webp', storeOriginal: true },
+ *     }),
+ *   ],
+ * });
+ *
+ * // In a component:
+ * const { results, isOptimizing } = client.optimize.useOptimize(file, config);
+ * ```
+ */
+declare function mediaOptimizeClient(config: OptimizationConfig): {
+    id: "media-optimize";
+    $ERROR_CODES: {
+        readonly OPTIMIZATION_FAILED: {
+            readonly status: 422;
+            readonly message: "Image optimization failed";
+        };
+        readonly WEBP_NOT_SUPPORTED: {
+            readonly status: 422;
+            readonly message: "WebP encoding is not supported in this browser and @jsquash/webp is not installed";
+        };
+        readonly CANVAS_CONTEXT_FAILED: {
+            readonly status: 500;
+            readonly message: "Failed to acquire canvas 2D context for image processing";
+        };
+    };
+    init(_$fetch: CMSFetch, _$store: CMSClientStore): Promise<{
+        context: {
+            [x: string]: OptimizationConfig;
+        };
+    }>;
+    getActions: () => {
+        optimize: {
+            useOptimize: (input: File | File[], overrideConfig?: OptimizationConfig) => OptimizeState;
+        };
+    };
+    atomListeners: {
+        matcher: (path: string) => boolean;
+        signal: "$mediaSignal";
+    }[];
+};
+
+export { mediaOptimizeClient, optimizeImage, useOptimize };
+export type { OptimizeResult, OptimizeState };

package/dist/plugins/media-optimize/index.d.ts

@@ -0,0 +1,144 @@
+import { WritableAtom } from 'nanostores';
+
+type CompressOptions = {
+    /** JPEG/PNG quality (1-100). @default 80 */
+    quality?: number;
+};
+type ResizeOptions = {
+    /** Maximum width/height in pixels. @default 2000 */
+    maxSize?: number;
+};
+type ConvertOptions = {
+    /** Only WebP conversion is supported. */
+    format: 'webp';
+    /**
+     * When true, also store a copy in the original format (resized + compressed
+     * but not converted). Useful for email clients that don't support WebP.
+     * @default false
+     */
+    storeOriginal?: boolean;
+};
+type OptimizationConfig = {
+    /** Image compression options. Omit to disable. */
+    compress?: CompressOptions;
+    /** Resize options. Omit to disable. */
+    resize?: ResizeOptions;
+    /** Format conversion options. Omit to disable. */
+    convert?: ConvertOptions;
+};
+
+interface OptimizeResult {
+    file: File;
+    originalVariant?: File;
+    optimized: boolean;
+}
+/**
+ * Optimize an image file on the client before uploading.
+ *
+ * - **Resize**: Downscale if either dimension exceeds `config.resize.maxSize`
+ * - **Compress**: Reduce quality via `config.compress.quality` (1-100)
+ * - **Convert**: Convert to WebP when `config.convert.format` is set
+ * - **storeOriginal**: When `convert.storeOriginal` is true, also returns an
+ *   `originalVariant` -- same resize + compress but kept in the original format
+ *
+ * Non-image files are returned unchanged with `optimized: false`.
+ */
+declare function optimizeImage(file: File, config: OptimizationConfig): Promise<OptimizeResult>;
+
+type OptimizeState = {
+    results: OptimizeResult[] | null;
+    isOptimizing: boolean;
+    error: string | null;
+};
+/**
+ * React hook that optimizes image files on the client.
+ *
+ * Accepts a single `File` or `File[]` and an `OptimizationConfig`.
+ * Runs `optimizeImage` automatically whenever the input reference changes.
+ * Non-image files pass through with `optimized: false`.
+ *
+ * ```tsx
+ * const { results, isOptimizing, error } = cmsClient.optimize.useOptimize(file, {
+ *   compress: { quality: 80 },
+ *   resize: { maxSize: 1200 },
+ * });
+ * ```
+ */
+declare function useOptimize(input: File | File[], config: OptimizationConfig): OptimizeState;
+
+type CMSFetch = (path: string, options?: {
+    method?: string;
+    body?: unknown;
+    query?: unknown;
+    /**
+     * Forwarded to the underlying `fetch` (better-call → @better-fetch → native
+     * `fetch`). Set for fire-and-forget analytics beacons (the A/B event ingest)
+     * so the POST is NOT cancelled when the page unloads/navigates mid-request.
+     */
+    keepalive?: boolean;
+}) => Promise<unknown>;
+interface CMSClientStore {
+    notify: (signal: string) => void;
+    listen: (signal: string, listener: () => void) => void;
+    atoms: Record<string, WritableAtom<unknown>>;
+}
+
+/**
+ * Client plugin that adds image optimization under its own namespace.
+ *
+ * Exposes `cmsClient.optimize.useOptimize(file, config)` for client-side
+ * image optimization. Optimized files can then be passed to
+ * `cmsClient.media.useUploadAssets().upload(files)`.
+ *
+ * ```ts
+ * import { mediaOptimizeClient } from '@createcms/core/plugins/media-optimize';
+ *
+ * const client = createCMSClient<typeof cms>({
+ *   baseURL: '/api/cms',
+ *   plugins: [
+ *     mediaOptimizeClient({
+ *       compress: { quality: 90 },
+ *       resize: { maxSize: 2000 },
+ *       convert: { format: 'webp', storeOriginal: true },
+ *     }),
+ *   ],
+ * });
+ *
+ * // In a component:
+ * const { results, isOptimizing } = client.optimize.useOptimize(file, config);
+ * ```
+ */
+declare function mediaOptimizeClient(config: OptimizationConfig): {
+    id: "media-optimize";
+    $ERROR_CODES: {
+        readonly OPTIMIZATION_FAILED: {
+            readonly status: 422;
+            readonly message: "Image optimization failed";
+        };
+        readonly WEBP_NOT_SUPPORTED: {
+            readonly status: 422;
+            readonly message: "WebP encoding is not supported in this browser and @jsquash/webp is not installed";
+        };
+        readonly CANVAS_CONTEXT_FAILED: {
+            readonly status: 500;
+            readonly message: "Failed to acquire canvas 2D context for image processing";
+        };
+    };
+    init(_$fetch: CMSFetch, _$store: CMSClientStore): Promise<{
+        context: {
+            [x: string]: OptimizationConfig;
+        };
+    }>;
+    getActions: () => {
+        optimize: {
+            useOptimize: (input: File | File[], overrideConfig?: OptimizationConfig) => OptimizeState;
+        };
+    };
+    atomListeners: {
+        matcher: (path: string) => boolean;
+        signal: "$mediaSignal";
+    }[];
+};
+
+export { mediaOptimizeClient, optimizeImage, useOptimize };
+export type { OptimizeResult, OptimizeState };