payload-plugin-aspect-preview 0.1.1 → 0.2.1

package/dist/components/AspectRatioPreviewGrid.js

@@ -46,9 +46,11 @@ function resolveCropPixels(crop, imgW, imgH) {
         h: crop.height
     };
 }
-// Editor stores focalX/focalY as percentages of the FULL image.
-// Convert to percentages within the crop region.
-function toCropRelativeFocal(focalX, focalY, crop, imgW, imgH) {
+// Editor passes focalX/focalY as percentages of the FULL image; convert to
+// percentages within the crop region. Pixel-based sibling of focal.ts'
+// `toCropRelativeFocal` — identical result, but expressed in pixels here
+// because this component already resolves the crop to pixels.
+function focalWithinCropPixels(focalX, focalY, crop, imgW, imgH) {
     const relX = (focalX / 100 * imgW - crop.x) / crop.w;
     const relY = (focalY / 100 * imgH - crop.y) / crop.h;
     return {
@@ -67,7 +69,7 @@ function computeCroppedBackgroundStyle(frameW, frameH, imgW, imgH, crop, focalX,
     // Scale the crop region to cover the frame (same math as object-fit:cover)
     const scale = Math.max(frameW / crop.w, frameH / crop.h);
     // Focal point inside the crop region, expressed as %
-    const relFocal = toCropRelativeFocal(focalX, focalY, crop, imgW, imgH);
+    const relFocal = focalWithinCropPixels(focalX, focalY, crop, imgW, imgH);
     // Where the crop region's top-left lands in the frame, per object-position math
     const cropDisplayW = crop.w * scale;
     const cropDisplayH = crop.h * scale;

package/dist/components/FocalPointEditor.js

@@ -1,10 +1,11 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useConfig, useDocumentInfo, useForm, useUploadEdits } from '@payloadcms/ui';
+import { useConfig, useDocumentInfo, useField, useForm, useUploadEdits } from '@payloadcms/ui';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import 'react-image-crop/dist/ReactCrop.css';
 import ReactCrop from 'react-image-crop';
 import { DEFAULT_ASPECT_RATIOS } from '../defaults';
+import { toCropRelativeFocal, toFullImageFocal } from '../focal';
 import { AspectRatioPreviewGrid } from './AspectRatioPreviewGrid';
 export const FocalPointEditor = ()=>{
     const { data } = useDocumentInfo();
@@ -20,16 +21,36 @@ export const FocalPointEditor = ()=>{
     }) : undefined;
     const aspectRatios = entityConfig?.custom?.aspectPreview?.aspectRatios ?? DEFAULT_ASPECT_RATIOS;
     const hasUserEditedRef = useRef(false);
+    // The freshly-picked File lives in the shared `file` form field (set by the
+    // upload component) before the document is saved. Reading it here lets us
+    // show the editor + preview immediately on selection, saving a save-round-trip.
+    const { value: pendingFile } = useField({
+        path: 'file'
+    });
+    const pendingUrl = React.useMemo(()=>pendingFile instanceof File && pendingFile.type.startsWith('image/') ? URL.createObjectURL(pendingFile) : undefined, [
+        pendingFile
+    ]);
+    // Revoke the object URL when it changes or the editor unmounts.
+    useEffect(()=>{
+        if (!pendingUrl) return;
+        return ()=>URL.revokeObjectURL(pendingUrl);
+    }, [
+        pendingUrl
+    ]);
     // Bust the browser cache when the document is re-saved so the regenerated
     // cropped image (same URL, new bytes) shows up in the preview grid.
     const rawUrl = data?.url;
     const updatedAtTag = data?.updatedAt ? String(data.updatedAt) : undefined;
     const imageUrl = React.useMemo(()=>{
+        // A pending selection wins over the saved doc — it's what the user is
+        // about to save. Blob URLs take no query string, so skip cache-busting.
+        if (pendingUrl) return pendingUrl;
         if (!rawUrl) return undefined;
         if (!updatedAtTag) return rawUrl;
         const sep = rawUrl.includes('?') ? '&' : '?';
         return `${rawUrl}${sep}v=${encodeURIComponent(updatedAtTag)}`;
     }, [
+        pendingUrl,
         rawUrl,
         updatedAtTag
     ]);
@@ -44,9 +65,18 @@ export const FocalPointEditor = ()=>{
         width: uploadEdits.crop.width,
         height: uploadEdits.crop.height
     } : undefined);
-    const [focalPoint, setFocalPoint] = useState({
-        x: uploadEdits?.focalPoint?.x || data?.focalX || 50,
-        y: uploadEdits?.focalPoint?.y || data?.focalY || 50
+    // Focal point is stored relative to the active crop region: a 0-100 position
+    // inside the crop, or inside the whole image when there is no crop. This is
+    // the same space Payload persists (it bakes the crop into the base image and
+    // reads focalX/focalY as percentages of the cropped result), so uploadEdits
+    // and data.focalX/Y are already in this space — no conversion on load.
+    // `typeof` (not `||`) so a valid edge focal of 0 doesn't fall through to 50.
+    const [focalPoint, setFocalPoint] = useState(()=>{
+        if (uploadEdits?.focalPoint) return uploadEdits.focalPoint;
+        return {
+            x: typeof data?.focalX === 'number' ? data.focalX : 50,
+            y: typeof data?.focalY === 'number' ? data.focalY : 50
+        };
     });
     const containerRef = useRef(null);
     const [isDragging, setIsDragging] = useState(false);
@@ -62,7 +92,9 @@ export const FocalPointEditor = ()=>{
     const docWidth = typeof data?.width === 'number' ? data.width : 0;
     const docHeight = typeof data?.height === 'number' ? data.height : 0;
     useEffect(()=>{
-        if (docWidth > 0 && docHeight > 0) {
+        // For a pending selection the doc dimensions are stale/absent — always
+        // decode the picked image so crop pixel math uses the real size.
+        if (!pendingUrl && docWidth > 0 && docHeight > 0) {
             queueMicrotask(()=>setNaturalSize({
                     width: docWidth,
                     height: docHeight
@@ -80,42 +112,60 @@ export const FocalPointEditor = ()=>{
         img.src = imageUrl;
     }, [
         imageUrl,
+        pendingUrl,
         docWidth,
         docHeight
     ]);
-    const [prevUpdatedAtTag, setPrevUpdatedAtTag] = useState(updatedAtTag);
-    // Re-sync local state from the saved document each time `updatedAt` changes.
+    // Re-sync local state from the saved document once per save. The guard is a
+    // ref (not state) so it flips synchronously — the effect cannot re-enter when
+    // the updateUploadEdits call below changes the upload-edits context. Driving
+    // the guard through state (and listing uploadEdits in the deps) is what
+    // previously re-entered on every context change and exceeded React's update
+    // depth on save.
+    const lastSyncedTagRef = useRef(updatedAtTag);
     useEffect(()=>{
-        if (updatedAtTag && updatedAtTag !== prevUpdatedAtTag) {
-            const nextFocal = {
-                x: typeof data?.focalX === 'number' ? data.focalX : 50,
-                y: typeof data?.focalY === 'number' ? data.focalY : 50
-            };
-            queueMicrotask(()=>{
-                setPrevUpdatedAtTag(updatedAtTag);
-                hasUserEditedRef.current = false;
-                setFocalPoint(nextFocal);
-                setCrop(undefined);
-            });
-            if (uploadEdits?.crop || uploadEdits?.focalPoint) {
-                updateUploadEdits({
-                    crop: undefined,
-                    focalPoint: nextFocal,
-                    heightInPixels: undefined,
-                    widthInPixels: undefined
-                });
-            }
-        }
+        if (!updatedAtTag || updatedAtTag === lastSyncedTagRef.current) return;
+        lastSyncedTagRef.current = updatedAtTag;
+        hasUserEditedRef.current = false;
+        const nextFocal = {
+            x: typeof data?.focalX === 'number' ? data.focalX : 50,
+            y: typeof data?.focalY === 'number' ? data.focalY : 50
+        };
+        setFocalPoint(nextFocal);
+        // The crop is now baked into the saved image, so there is no pending crop
+        // and the focal is relative to the whole (already-cropped) image again.
+        setCrop(undefined);
+        updateUploadEdits({
+            crop: undefined,
+            focalPoint: nextFocal,
+            heightInPixels: undefined,
+            widthInPixels: undefined
+        });
     }, [
         updatedAtTag,
-        prevUpdatedAtTag,
         data?.focalX,
         data?.focalY,
-        uploadEdits?.crop,
-        uploadEdits?.focalPoint,
         updateUploadEdits
     ]);
     const hasRealCrop = !!crop && crop.width > 0 && crop.height > 0 && (crop.width !== 100 || crop.height !== 100 || crop.x !== 0 || crop.y !== 0);
+    // The rectangle the focal point is measured against: the crop when one exists
+    // (in %), otherwise the whole image. Focal state is always a 0-100 position
+    // inside this rectangle; converting to/from full-image space happens only at
+    // the pointer and rendering boundaries.
+    const cropRect = React.useMemo(()=>hasRealCrop && crop && crop.unit === '%' ? {
+            x: crop.x,
+            y: crop.y,
+            width: crop.width,
+            height: crop.height
+        } : {
+            x: 0,
+            y: 0,
+            width: 100,
+            height: 100
+        }, [
+        hasRealCrop,
+        crop
+    ]);
     // Auto-save to uploadEdits whenever state changes
     useEffect(()=>{
         if (!hasUserEditedRef.current) return;
@@ -140,6 +190,8 @@ export const FocalPointEditor = ()=>{
                         width: crop.width,
                         height: crop.height
                     },
+                    // focalPoint is already relative to the crop region — exactly the
+                    // space Payload reads it in for the cropped image.
                     focalPoint,
                     heightInPixels,
                     widthInPixels
@@ -162,35 +214,28 @@ export const FocalPointEditor = ()=>{
         setModified,
         updateUploadEdits
     ]);
-    const clampFocalToCrop = useCallback((x, y)=>{
-        if (crop && crop.unit === '%' && hasRealCrop) {
-            x = Math.max(crop.x, Math.min(crop.x + crop.width, x));
-            y = Math.max(crop.y, Math.min(crop.y + crop.height, y));
-        }
-        return {
-            x,
-            y
-        };
-    }, [
-        crop,
-        hasRealCrop
-    ]);
-    // Focal point drag handlers
+    // Focal point drag handler. The pointer lands somewhere on the full image;
+    // convert that full-image % into the crop-relative space the focal lives in,
+    // then clamp to the crop (0-100 inside cropRect).
     const updateFocalFromEvent = useCallback((e)=>{
         const container = containerRef.current;
         if (!container) return;
         const rect = container.getBoundingClientRect();
         const clientX = 'touches' in e ? e.touches[0].clientX : e.clientX;
         const clientY = 'touches' in e ? e.touches[0].clientY : e.clientY;
-        let x = (clientX - rect.left) / rect.width * 100;
-        let y = (clientY - rect.top) / rect.height * 100;
-        x = Math.max(0, Math.min(100, x));
-        y = Math.max(0, Math.min(100, y));
-        const clamped = clampFocalToCrop(x, y);
+        const fullX = Math.max(0, Math.min(100, (clientX - rect.left) / rect.width * 100));
+        const fullY = Math.max(0, Math.min(100, (clientY - rect.top) / rect.height * 100));
+        const rel = toCropRelativeFocal({
+            x: fullX,
+            y: fullY
+        }, cropRect);
         hasUserEditedRef.current = true;
-        setFocalPoint(clamped);
+        setFocalPoint({
+            x: Math.max(0, Math.min(100, rel.x)),
+            y: Math.max(0, Math.min(100, rel.y))
+        });
     }, [
-        clampFocalToCrop
+        cropRect
     ]);
     const handleMouseDown = useCallback((e)=>{
         e.preventDefault();
@@ -285,6 +330,10 @@ export const FocalPointEditor = ()=>{
         height: crop.height
     } : undefined;
     const cropUnitLabel = crop?.unit === 'px' ? 'px' : '%';
+    // Full-image position of the focal point (crop-relative → whole image). Used
+    // to place the crosshair absolutely and to feed the preview grid, which
+    // re-derives the crop-relative position itself.
+    const focalFullImage = toFullImageFocal(focalPoint, cropRect);
     return /*#__PURE__*/ _jsx("div", {
         className: "focal-editor",
         children: /*#__PURE__*/ _jsxs("div", {
@@ -331,10 +380,10 @@ export const FocalPointEditor = ()=>{
                                                                             value: Math.round(focalPoint.x),
                                                                             onChange: (e)=>{
                                                                                 hasUserEditedRef.current = true;
-                                                                                setFocalPoint((prev)=>{
-                                                                                    const x = Math.max(0, Math.min(100, Number(e.target.value)));
-                                                                                    return clampFocalToCrop(x, prev.y);
-                                                                                });
+                                                                                setFocalPoint((prev)=>({
+                                                                                        ...prev,
+                                                                                        x: Math.max(0, Math.min(100, Number(e.target.value)))
+                                                                                    }));
                                                                             }
                                                                         }),
                                                                         /*#__PURE__*/ _jsx("span", {
@@ -357,10 +406,10 @@ export const FocalPointEditor = ()=>{
                                                                             value: Math.round(focalPoint.y),
                                                                             onChange: (e)=>{
                                                                                 hasUserEditedRef.current = true;
-                                                                                setFocalPoint((prev)=>{
-                                                                                    const y = Math.max(0, Math.min(100, Number(e.target.value)));
-                                                                                    return clampFocalToCrop(prev.x, y);
-                                                                                });
+                                                                                setFocalPoint((prev)=>({
+                                                                                        ...prev,
+                                                                                        y: Math.max(0, Math.min(100, Number(e.target.value)))
+                                                                                    }));
                                                                             }
                                                                         }),
                                                                         /*#__PURE__*/ _jsx("span", {
@@ -591,8 +640,8 @@ export const FocalPointEditor = ()=>{
                                             children: mode === 'focal' && /*#__PURE__*/ _jsxs("div", {
                                                 className: "focal-editor__crosshair",
                                                 style: {
-                                                    left: `${focalPoint.x}%`,
-                                                    top: `${focalPoint.y}%`
+                                                    left: `${focalFullImage.x}%`,
+                                                    top: `${focalFullImage.y}%`
                                                 },
                                                 children: [
                                                     /*#__PURE__*/ _jsx("div", {
@@ -614,8 +663,8 @@ export const FocalPointEditor = ()=>{
                     className: "focal-editor__right",
                     children: /*#__PURE__*/ _jsx(AspectRatioPreviewGrid, {
                         url: imageUrl,
-                        focalX: focalPoint.x,
-                        focalY: focalPoint.y,
+                        focalX: focalFullImage.x,
+                        focalY: focalFullImage.y,
                         aspectRatios: aspectRatios,
                         crop: cropConfig
                     })

package/dist/defaults.d.ts

@@ -1,2 +1,6 @@
 import type { AspectRatioConfig } from './types.js';
+/**
+ * The aspect ratios previewed when {@link AspectPreviewPluginOptions.aspectRatios}
+ * is omitted: square, 4:3, 3:2, 16:9, 9:16, and a 1200×630 social-share target.
+ */
 export declare const DEFAULT_ASPECT_RATIOS: AspectRatioConfig[];

package/dist/defaults.js

@@ -1,4 +1,7 @@
-export const DEFAULT_ASPECT_RATIOS = [
+/**
+ * The aspect ratios previewed when {@link AspectPreviewPluginOptions.aspectRatios}
+ * is omitted: square, 4:3, 3:2, 16:9, 9:16, and a 1200×630 social-share target.
+ */ export const DEFAULT_ASPECT_RATIOS = [
     {
         name: 'Square',
         ratio: '1:1',

package/dist/focal.d.ts

@@ -0,0 +1,17 @@
+import type { CropConfig, FocalPointState } from './types.js';
+/** The crop rectangle in percentage units — all this math needs. */
+type PercentCrop = Pick<CropConfig, 'x' | 'y' | 'width' | 'height'>;
+/**
+ * Payload stores the focal point relative to the CROP region: on save it bakes
+ * the crop into the base image, then interprets `focalX/focalY` as percentages
+ * of that cropped image. The editor, by contrast, works in full-image
+ * coordinates because the crosshair is drawn over the whole picture.
+ *
+ * These two pure inverses convert between the spaces. The math is percentage
+ * only — the image's pixel dimensions cancel out, so just the crop rectangle
+ * (in %) is required. Callers must guarantee a non-zero crop width/height.
+ */
+export declare function toCropRelativeFocal(focal: FocalPointState, crop: PercentCrop): FocalPointState;
+/** Inverse of {@link toCropRelativeFocal}: crop-relative % back to full-image %. */
+export declare function toFullImageFocal(focal: FocalPointState, crop: PercentCrop): FocalPointState;
+export {};

package/dist/focal.js

@@ -0,0 +1,21 @@
+/**
+ * Payload stores the focal point relative to the CROP region: on save it bakes
+ * the crop into the base image, then interprets `focalX/focalY` as percentages
+ * of that cropped image. The editor, by contrast, works in full-image
+ * coordinates because the crosshair is drawn over the whole picture.
+ *
+ * These two pure inverses convert between the spaces. The math is percentage
+ * only — the image's pixel dimensions cancel out, so just the crop rectangle
+ * (in %) is required. Callers must guarantee a non-zero crop width/height.
+ */ export function toCropRelativeFocal(focal, crop) {
+    return {
+        x: (focal.x - crop.x) / crop.width * 100,
+        y: (focal.y - crop.y) / crop.height * 100
+    };
+}
+/** Inverse of {@link toCropRelativeFocal}: crop-relative % back to full-image %. */ export function toFullImageFocal(focal, crop) {
+    return {
+        x: crop.x + focal.x / 100 * crop.width,
+        y: crop.y + focal.y / 100 * crop.height
+    };
+}

package/dist/plugin.d.ts

@@ -1,3 +1,28 @@
 import type { Plugin } from 'payload';
 import type { AspectPreviewPluginOptions } from './types.js';
+/**
+ * Adds an inline focal-point + crop editor with a live aspect-ratio preview
+ * grid to Payload upload collections.
+ *
+ * For every collection listed in {@link AspectPreviewPluginOptions.collections}
+ * it appends an `aspectPreview` UI field that renders the editor and (unless
+ * {@link AspectPreviewPluginOptions.disabled}) overrides the collection's upload
+ * component to replace Payload's default crop drawer.
+ *
+ * @param options - see {@link AspectPreviewPluginOptions}.
+ * @returns a Payload {@link Plugin}.
+ *
+ * @example
+ * ```ts
+ * // payload.config.ts
+ * import { aspectPreviewPlugin } from 'payload-plugin-aspect-preview'
+ *
+ * export default buildConfig({
+ *   plugins: [
+ *     // aspectRatios defaults to DEFAULT_ASPECT_RATIOS when omitted
+ *     aspectPreviewPlugin({ collections: ['media'] }),
+ *   ],
+ * })
+ * ```
+ */
 export declare const aspectPreviewPlugin: (options: AspectPreviewPluginOptions) => Plugin;

package/dist/plugin.js

@@ -1,7 +1,31 @@
 import { DEFAULT_ASPECT_RATIOS } from './defaults.js';
 const FIELD_COMPONENT = 'payload-plugin-aspect-preview/client#FocalPointEditor';
 const UPLOAD_COMPONENT = 'payload-plugin-aspect-preview/client#CustomUpload';
-export const aspectPreviewPlugin = (options)=>(config)=>{
+/**
+ * Adds an inline focal-point + crop editor with a live aspect-ratio preview
+ * grid to Payload upload collections.
+ *
+ * For every collection listed in {@link AspectPreviewPluginOptions.collections}
+ * it appends an `aspectPreview` UI field that renders the editor and (unless
+ * {@link AspectPreviewPluginOptions.disabled}) overrides the collection's upload
+ * component to replace Payload's default crop drawer.
+ *
+ * @param options - see {@link AspectPreviewPluginOptions}.
+ * @returns a Payload {@link Plugin}.
+ *
+ * @example
+ * ```ts
+ * // payload.config.ts
+ * import { aspectPreviewPlugin } from 'payload-plugin-aspect-preview'
+ *
+ * export default buildConfig({
+ *   plugins: [
+ *     // aspectRatios defaults to DEFAULT_ASPECT_RATIOS when omitted
+ *     aspectPreviewPlugin({ collections: ['media'] }),
+ *   ],
+ * })
+ * ```
+ */ export const aspectPreviewPlugin = (options)=>(config)=>{
         const aspectRatios = options.aspectRatios ?? DEFAULT_ASPECT_RATIOS;
         const enabled = new Set(options.collections);
         return {
@@ -16,6 +40,9 @@ export const aspectPreviewPlugin = (options)=>(config)=>{
                             name: 'aspectPreview',
                             type: 'ui',
                             admin: {
+                                // It's an edit-view editor, not data — keep it out of the
+                                // list view's columns.
+                                disableListColumn: true,
                                 components: {
                                     Field: FIELD_COMPONENT
                                 }

package/dist/types.d.ts

@@ -1,3 +1,8 @@
+/**
+ * A single aspect ratio shown in the editor's live preview grid. Pass an array
+ * of these as {@link AspectPreviewPluginOptions.aspectRatios} to tailor the
+ * ratios to your frontend; see {@link DEFAULT_ASPECT_RATIOS} for the shipped set.
+ */
 export interface AspectRatioConfig {
     /** Display label, e.g. "Social Share". */
     name: string;
@@ -14,6 +19,7 @@ export interface AspectRatioConfig {
     /** Optional free-form grouping label. */
     category?: string;
 }
+/** Options for {@link aspectPreviewPlugin}. */
 export interface AspectPreviewPluginOptions {
     /** Upload collections (by slug) to enhance with the inline editor. */
     collections: string[];
@@ -22,6 +28,7 @@ export interface AspectPreviewPluginOptions {
     /** Disable the plugin while keeping the schema field for DB consistency. */
     disabled?: boolean;
 }
+/** A crop rectangle. `x`/`y`/`width`/`height` are in `unit` (percent or pixels). */
 export interface CropConfig {
     unit: 'px' | '%';
     x: number;
@@ -29,10 +36,12 @@ export interface CropConfig {
     width: number;
     height: number;
 }
+/** Focal point as percentages (0-100) of its reference image. */
 export interface FocalPointState {
     x: number;
     y: number;
 }
+/** The editor's pending edits, mirrored into Payload's upload-edits context. */
 export interface UploadEditsState {
     crop?: CropConfig;
     focalPoint?: FocalPointState;

package/dist/types.js

@@ -1 +1,5 @@
-export { };
+/**
+ * A single aspect ratio shown in the editor's live preview grid. Pass an array
+ * of these as {@link AspectPreviewPluginOptions.aspectRatios} to tailor the
+ * ratios to your frontend; see {@link DEFAULT_ASPECT_RATIOS} for the shipped set.
+ */ /** The editor's pending edits, mirrored into Payload's upload-edits context. */ export { };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-plugin-aspect-preview",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Single-screen crop, focal point, and live multi-aspect-ratio preview editor for Payload upload collections.",
   "keywords": [
     "payload",