payload-plugin-aspect-preview 0.1.1 → 0.2.0

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,17 @@ 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
+    const [focalPoint, setFocalPoint] = useState(()=>{
+        // uploadEdits stores the focal crop-relative (see the save effect below);
+        // lift it back into the full-image space the editor works in. `??` — a
+        // focal of 0 (an edge) is valid and must not fall through to the centre.
+        if (uploadEdits?.focalPoint) {
+            return uploadEdits.crop && uploadEdits.crop.unit === '%' ? toFullImageFocal(uploadEdits.focalPoint, uploadEdits.crop) : 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 +91,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,6 +111,7 @@ export const FocalPointEditor = ()=>{
         img.src = imageUrl;
     }, [
         imageUrl,
+        pendingUrl,
         docWidth,
         docHeight
     ]);
@@ -132,6 +164,11 @@ export const FocalPointEditor = ()=>{
                 const topPx = Math.floor(crop.y / 100 * naturalSize.height);
                 const widthInPixels = Math.max(1, Math.min(Math.floor(crop.width / 100 * naturalSize.width), naturalSize.width - leftPx));
                 const heightInPixels = Math.max(1, Math.min(Math.floor(crop.height / 100 * naturalSize.height), naturalSize.height - topPx));
+                // Payload interprets the saved focal point relative to the CROPPED
+                // image (it swaps the base image for the cropped bytes before sizing),
+                // so re-express our full-image focal within the crop region. clampFocal-
+                // ToCrop already keeps the focal inside the crop, so this stays 0-100.
+                const cropRelativeFocal = toCropRelativeFocal(focalPoint, crop);
                 updateUploadEdits({
                     crop: {
                         unit: '%',
@@ -140,7 +177,7 @@ export const FocalPointEditor = ()=>{
                         width: crop.width,
                         height: crop.height
                     },
-                    focalPoint,
+                    focalPoint: cropRelativeFocal,
                     heightInPixels,
                     widthInPixels
                 });

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 {

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.0",
   "description": "Single-screen crop, focal point, and live multi-aspect-ratio preview editor for Payload upload collections.",
   "keywords": [
     "payload",