@pro-laico/payload-images 0.0.0

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-2026 Pro Laico LLC <contact@prolaico.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @pro-laico/payload-images
+
+On-demand image optimization for [Payload CMS](https://payloadcms.com/) — an Images collection that stores only the original and generates, crops, and caches each rendered size on first request, with a responsive `<ResponsiveImage>` component and admin focal-point picker.
+
+```bash
+pnpm add @pro-laico/payload-images
+```
+
+**[Documentation →](https://payload-plugins.prolaico.com/docs/plugins/payload-images)**
+
+Ported from [`@pro-laico/images`](https://github.com/pro-laico/atomic-payload) (Atomic Payload, MIT).

package/dist/access.d.ts

@@ -0,0 +1,4 @@
+import type { Access } from 'payload';
+export declare const anyone: Access;
+export declare const authd: Access;
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC,eAAO,MAAM,MAAM,EAAE,MAAmB,CAAA;AACxC,eAAO,MAAM,KAAK,EAAE,MAAuC,CAAA"}

package/dist/access.js

@@ -0,0 +1,4 @@
+export const anyone = ()=>true;
+export const authd = ({ req })=>Boolean(req.user);
+
+//# sourceMappingURL=access.js.map

package/dist/access.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/access.ts"],"sourcesContent":["import type { Access } from 'payload'\n\nexport const anyone: Access = () => true\nexport const authd: Access = ({ req }) => Boolean(req.user)\n"],"names":["anyone","authd","req","Boolean","user"],"mappings":"AAEA,OAAO,MAAMA,SAAiB,IAAM,KAAI;AACxC,OAAO,MAAMC,QAAgB,CAAC,EAAEC,GAAG,EAAE,GAAKC,QAAQD,IAAIE,IAAI,EAAC"}

package/dist/collections/generatedImages.d.ts

@@ -0,0 +1,26 @@
+import type { CollectionConfig } from 'payload';
+export declare const GENERATED_IMAGES_SLUG = "generated-images";
+export interface CreateGeneratedImagesOptions {
+    /** Slug for this collection. Default `generated-images`. */
+    slug?: string;
+    /** Slug of the source image collection the variants point back to. Default `images`. */
+    sourceSlug?: string;
+}
+/**
+ * The hidden, durable cache of on-demand image variants. The transform endpoint
+ * writes one upload doc here per (source, settings, focal) combination; the source
+ * `images` collection surfaces them through a `join` field and purges them when the
+ * source changes or is deleted.
+ *
+ * It is an UPLOAD collection so variant bytes flow through whatever storage adapter
+ * is configured (local disk, S3, Vercel Blob, …) — keeping the feature
+ * platform-agnostic. With a cloud storage adapter, register it with a SERVER-upload
+ * storage instance, since the endpoint creates docs server-side via the Local API.
+ *
+ * Deliberately carries NO revalidation hooks: variants are derived and disposable,
+ * so busting cache tags on every cache-miss create would be pure churn.
+ */
+export declare const createGeneratedImagesCollection: (opts?: CreateGeneratedImagesOptions) => CollectionConfig;
+/** The default generated-images collection. */
+export declare const GeneratedImages: CollectionConfig;
+//# sourceMappingURL=generatedImages.d.ts.map

package/dist/collections/generatedImages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generatedImages.d.ts","sourceRoot":"","sources":["../../src/collections/generatedImages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAkB,MAAM,SAAS,CAAA;AAK/D,eAAO,MAAM,qBAAqB,qBAAqB,CAAA;AAEvD,MAAM,WAAW,4BAA4B;IAC3C,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,+BAA+B,GAAI,OAAM,4BAAiC,KAAG,gBA6BzF,CAAA;AAED,+CAA+C;AAC/C,eAAO,MAAM,eAAe,EAAE,gBAAoD,CAAA"}

package/dist/collections/generatedImages.js

@@ -0,0 +1,91 @@
+import { authd } from "../access.js";
+import { IMAGE_MIME_TYPES } from "../transform/params.js";
+export const GENERATED_IMAGES_SLUG = 'generated-images';
+/**
+ * The hidden, durable cache of on-demand image variants. The transform endpoint
+ * writes one upload doc here per (source, settings, focal) combination; the source
+ * `images` collection surfaces them through a `join` field and purges them when the
+ * source changes or is deleted.
+ *
+ * It is an UPLOAD collection so variant bytes flow through whatever storage adapter
+ * is configured (local disk, S3, Vercel Blob, …) — keeping the feature
+ * platform-agnostic. With a cloud storage adapter, register it with a SERVER-upload
+ * storage instance, since the endpoint creates docs server-side via the Local API.
+ *
+ * Deliberately carries NO revalidation hooks: variants are derived and disposable,
+ * so busting cache tags on every cache-miss create would be pure churn.
+ */ export const createGeneratedImagesCollection = (opts = {})=>{
+    const slug = opts.slug || GENERATED_IMAGES_SLUG;
+    const sourceSlug = opts.sourceSlug || 'images';
+    return {
+        slug,
+        access: {
+            create: authd,
+            delete: authd,
+            read: authd,
+            update: authd
+        },
+        admin: {
+            hidden: true,
+            group: 'Assets',
+            useAsTitle: 'cacheKey',
+            defaultColumns: [
+                'cacheKey',
+                'width',
+                'height',
+                'format'
+            ]
+        },
+        fields: [
+            {
+                name: 'source',
+                type: 'relationship',
+                relationTo: sourceSlug,
+                required: true,
+                index: true
+            },
+            {
+                name: 'cacheKey',
+                type: 'text',
+                required: true,
+                unique: true
+            },
+            {
+                type: 'row',
+                fields: [
+                    {
+                        name: 'fit',
+                        type: 'text'
+                    },
+                    {
+                        name: 'format',
+                        type: 'text'
+                    },
+                    {
+                        name: 'quality',
+                        type: 'number'
+                    }
+                ]
+            },
+            {
+                type: 'row',
+                fields: [
+                    {
+                        name: 'focalX',
+                        type: 'number'
+                    },
+                    {
+                        name: 'focalY',
+                        type: 'number'
+                    }
+                ]
+            }
+        ],
+        upload: {
+            mimeTypes: IMAGE_MIME_TYPES
+        }
+    };
+};
+/** The default generated-images collection. */ export const GeneratedImages = createGeneratedImagesCollection();
+
+//# sourceMappingURL=generatedImages.js.map

package/dist/collections/generatedImages.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/collections/generatedImages.ts"],"sourcesContent":["import type { CollectionConfig, CollectionSlug } from 'payload'\n\nimport { authd } from '../access'\nimport { IMAGE_MIME_TYPES } from '../transform/params'\n\nexport const GENERATED_IMAGES_SLUG = 'generated-images'\n\nexport interface CreateGeneratedImagesOptions {\n  /** Slug for this collection. Default `generated-images`. */\n  slug?: string\n  /** Slug of the source image collection the variants point back to. Default `images`. */\n  sourceSlug?: string\n}\n\n/**\n * The hidden, durable cache of on-demand image variants. The transform endpoint\n * writes one upload doc here per (source, settings, focal) combination; the source\n * `images` collection surfaces them through a `join` field and purges them when the\n * source changes or is deleted.\n *\n * It is an UPLOAD collection so variant bytes flow through whatever storage adapter\n * is configured (local disk, S3, Vercel Blob, …) — keeping the feature\n * platform-agnostic. With a cloud storage adapter, register it with a SERVER-upload\n * storage instance, since the endpoint creates docs server-side via the Local API.\n *\n * Deliberately carries NO revalidation hooks: variants are derived and disposable,\n * so busting cache tags on every cache-miss create would be pure churn.\n */\nexport const createGeneratedImagesCollection = (opts: CreateGeneratedImagesOptions = {}): CollectionConfig => {\n  const slug = opts.slug || GENERATED_IMAGES_SLUG\n  const sourceSlug = (opts.sourceSlug || 'images') as CollectionSlug\n\n  return {\n    slug,\n    access: { create: authd, delete: authd, read: authd, update: authd },\n    admin: { hidden: true, group: 'Assets', useAsTitle: 'cacheKey', defaultColumns: ['cacheKey', 'width', 'height', 'format'] },\n    fields: [\n      { name: 'source', type: 'relationship', relationTo: sourceSlug, required: true, index: true },\n      { name: 'cacheKey', type: 'text', required: true, unique: true },\n      {\n        type: 'row',\n        fields: [\n          { name: 'fit', type: 'text' },\n          { name: 'format', type: 'text' },\n          { name: 'quality', type: 'number' },\n        ],\n      },\n      {\n        type: 'row',\n        fields: [\n          { name: 'focalX', type: 'number' },\n          { name: 'focalY', type: 'number' },\n        ],\n      },\n    ],\n    upload: { mimeTypes: IMAGE_MIME_TYPES },\n  }\n}\n\n/** The default generated-images collection. */\nexport const GeneratedImages: CollectionConfig = createGeneratedImagesCollection()\n"],"names":["authd","IMAGE_MIME_TYPES","GENERATED_IMAGES_SLUG","createGeneratedImagesCollection","opts","slug","sourceSlug","access","create","delete","read","update","admin","hidden","group","useAsTitle","defaultColumns","fields","name","type","relationTo","required","index","unique","upload","mimeTypes","GeneratedImages"],"mappings":"AAEA,SAASA,KAAK,QAAQ,eAAW;AACjC,SAASC,gBAAgB,QAAQ,yBAAqB;AAEtD,OAAO,MAAMC,wBAAwB,mBAAkB;AASvD;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC,kCAAkC,CAACC,OAAqC,CAAC,CAAC;IACrF,MAAMC,OAAOD,KAAKC,IAAI,IAAIH;IAC1B,MAAMI,aAAcF,KAAKE,UAAU,IAAI;IAEvC,OAAO;QACLD;QACAE,QAAQ;YAAEC,QAAQR;YAAOS,QAAQT;YAAOU,MAAMV;YAAOW,QAAQX;QAAM;QACnEY,OAAO;YAAEC,QAAQ;YAAMC,OAAO;YAAUC,YAAY;YAAYC,gBAAgB;gBAAC;gBAAY;gBAAS;gBAAU;aAAS;QAAC;QAC1HC,QAAQ;YACN;gBAAEC,MAAM;gBAAUC,MAAM;gBAAgBC,YAAYd;gBAAYe,UAAU;gBAAMC,OAAO;YAAK;YAC5F;gBAAEJ,MAAM;gBAAYC,MAAM;gBAAQE,UAAU;gBAAME,QAAQ;YAAK;YAC/D;gBACEJ,MAAM;gBACNF,QAAQ;oBACN;wBAAEC,MAAM;wBAAOC,MAAM;oBAAO;oBAC5B;wBAAED,MAAM;wBAAUC,MAAM;oBAAO;oBAC/B;wBAAED,MAAM;wBAAWC,MAAM;oBAAS;iBACnC;YACH;YACA;gBACEA,MAAM;gBACNF,QAAQ;oBACN;wBAAEC,MAAM;wBAAUC,MAAM;oBAAS;oBACjC;wBAAED,MAAM;wBAAUC,MAAM;oBAAS;iBAClC;YACH;SACD;QACDK,QAAQ;YAAEC,WAAWxB;QAAiB;IACxC;AACF,EAAC;AAED,6CAA6C,GAC7C,OAAO,MAAMyB,kBAAoCvB,kCAAiC"}

package/dist/collections/images.d.ts

@@ -0,0 +1,60 @@
+import type { CollectionConfig } from 'payload';
+/** Admin component subpaths (referenced by the Payload import map). */
+export declare const FocalPreviewFieldPath = "@pro-laico/payload-images/admin/focalPreview";
+export declare const PurgeVariantsFieldPath = "@pro-laico/payload-images/admin/purgeVariants";
+export interface CreateImagesOptions {
+    /** Render the focal-point + ratio-preview field and the purge-variants button. Default true. */
+    focalUI?: boolean;
+    /** Aspect ratios shown in the focal preview tiles. */
+    previewRatios?: string[];
+    /** Slug of the generated-images collection the `variants` join targets. */
+    variantSlug?: string;
+    /** Purge route (under the API base) the purge button POSTs to. Default `/img/purge`. */
+    purgePath?: string;
+    /** Admin list/preview thumbnail width (px), served on-demand via the transform endpoint so the
+     *  admin never loads full-res originals. Default 160; pass `false` to use Payload's default. */
+    adminThumbnail?: number | false;
+    /** The app's API route base (`config.routes.api`), used to build the admin thumbnail URL. Default `/api`. */
+    apiRoute?: string;
+    /** Whether the transform + purge endpoints are registered (`transform !== false`). When false, the
+     *  purge button and the `variants` join — UI that targets those endpoints — are skipped. Default true. */
+    endpointsEnabled?: boolean;
+    /** Add virtual `src`/`srcset`/`placeholderURL`/`thumbnailURL` fields (computed on read), so
+     *  optimized URLs ride along in every REST/GraphQL/Local-API response. Default true. */
+    virtualFields?: boolean;
+    /** Mark the `alt` field `localized: true` (requires Payload localization). Default false. */
+    localizeAlt?: boolean;
+    /** Accepted upload mime types. Defaults to the raster formats the transform pipeline can
+     *  process ({@link IMAGE_MIME_TYPES}: avif/webp/jpeg/png). Override to widen or narrow what
+     *  the collection accepts — but the endpoint only meaningfully transforms raster images. */
+    mimeTypes?: string[];
+    /** Enable Payload's native folder organization on the collection (adds a folder relationship). Default false. */
+    folders?: boolean;
+    /** Cap the *stored* original's longest edge (px) via `upload.resizeOptions`, applied once on upload.
+     *  Off by default — the original is kept untouched. Set it only to bound storage. */
+    maxOriginalSize?: number;
+}
+/**
+ * The image-pipeline additions, as a partial config to deep-merge onto a collection: the admin
+ * image-management UI (gated by `focalUI`), the purge hooks, `upload.focalPoint`, the on-demand
+ * admin thumbnail, and the lean `defaultPopulate` / `forceSelect` that keep the virtual URLs
+ * riding through select/populated reads. The factory below folds these into the default `images`
+ * collection; the plugin folds them onto an existing collection when `extendCollection` is set
+ * (so a project's own `media` collection gains the pipeline without a second collection).
+ * Deliberately omits `alt`/`access`/`admin`/`slug` and the mime whitelist so it never clobbers a
+ * collection it's merged onto (the plugin also re-merges the target's own
+ * `defaultPopulate`/`forceSelect`/thumbnail on top).
+ */
+export declare const imageEnhancements: (opts?: CreateImagesOptions) => Partial<CollectionConfig>;
+/**
+ * The source image upload collection. Stores only the original (no pre-generated sizes by
+ * default); keeps Payload's built-in `focalPoint` (the focal component enhances it). The
+ * on-demand transform endpoint serves every rendered variant and records it in the
+ * generated-images collection, surfaced here via the `variants` join and purged by the
+ * change/delete hooks. The LQIP placeholder is generated on demand by `<ResponsiveImage>` (a tiny
+ * inline base64 via the shared variant cache) — there's no stored placeholder field.
+ */
+export declare const createImagesCollection: (opts?: CreateImagesOptions) => CollectionConfig;
+/** The default Images collection (on-demand transforms, no pre-generated sizes). */
+export declare const Images: CollectionConfig;
+//# sourceMappingURL=images.d.ts.map

package/dist/collections/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../src/collections/images.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAA4C,MAAM,SAAS,CAAA;AAQzF,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,iDAAiD,CAAA;AACnF,eAAO,MAAM,sBAAsB,kDAAkD,CAAA;AAErF,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;oGACgG;IAChG,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC/B,6GAA6G;IAC7G,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;8GAC0G;IAC1G,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;4FACwF;IACxF,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;gGAE4F;IAC5F,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,iHAAiH;IACjH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;yFACqF;IACrF,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAuDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAM,mBAAwB,KAAG,OAAO,CAAC,gBAAgB,CA2B1F,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAM,mBAAwB,KAAG,gBA0CvE,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,MAAM,EAAE,gBAA2C,CAAA"}

package/dist/collections/images.js

@@ -0,0 +1,223 @@
+import { anyone, authd } from "../access.js";
+import { VIRTUAL_URL_FIELDS, VIRTUAL_URL_INPUTS, virtualUrlFields } from "../fields/virtualUrls.js";
+import { purgeStaleVariantsAfterChange, purgeVariantsBeforeDelete } from "../hooks/purge.js";
+import { IMAGE_MIME_TYPES } from "../transform/params.js";
+import { GENERATED_IMAGES_SLUG } from "./generatedImages.js";
+/** Admin component subpaths (referenced by the Payload import map). */ export const FocalPreviewFieldPath = '@pro-laico/payload-images/admin/focalPreview';
+export const PurgeVariantsFieldPath = '@pro-laico/payload-images/admin/purgeVariants';
+/**
+ * A focal-cropped admin thumbnail served by the transform endpoint, so the Images list view
+ * loads tiny WebP thumbnails instead of full-resolution originals. Returns `undefined` when
+ * disabled (`adminThumbnail: false`, or the transform endpoint isn't registered). The API base
+ * comes from the app's `routes.api` (threaded through as `apiRoute`).
+ */ const resolveAdminThumbnail = (adminThumbnail, apiRoute = '/api')=>{
+    if (adminThumbnail === false) return undefined;
+    const w = typeof adminThumbnail === 'number' ? adminThumbnail : 160;
+    return ({ doc })=>doc?.id ? `${apiRoute}/img/${String(doc.id)}?w=${w}&h=${w}&fit=cover&fmt=auto` : null;
+};
+/**
+ * The admin "image management" fields, shown only when `focalUI` is on: the focal-point picker,
+ * the ratio preview, the purge-variants button, and the `variants` join listing the cached
+ * variants (it pairs with the purge button). With `focalUI: false` the collection is a clean
+ * upload — just `alt` + the file — and the import map isn't needed.
+ */ const adminUIFields = (focalUI, variantSlug, previewRatios, purgePath, endpoints = true)=>focalUI ? [
+        {
+            name: 'focalPreview',
+            type: 'ui',
+            admin: {
+                components: {
+                    Field: {
+                        path: FocalPreviewFieldPath,
+                        ...previewRatios ? {
+                            clientProps: {
+                                previewRatios
+                            }
+                        } : {}
+                    }
+                }
+            }
+        },
+        // The purge button POSTs to the purge endpoint and the join lists endpoint-generated
+        // variants — with the endpoints unregistered, both would be dead UI.
+        ...endpoints ? [
+            {
+                name: 'purgeVariants',
+                type: 'ui',
+                admin: {
+                    components: {
+                        Field: {
+                            path: PurgeVariantsFieldPath,
+                            ...purgePath ? {
+                                clientProps: {
+                                    purgePath
+                                }
+                            } : {}
+                        }
+                    }
+                }
+            },
+            {
+                name: 'variants',
+                type: 'join',
+                collection: variantSlug,
+                on: 'source',
+                admin: {
+                    defaultColumns: [
+                        'filename',
+                        'width',
+                        'height',
+                        'format'
+                    ],
+                    allowCreate: false
+                }
+            }
+        ] : []
+    ] : [];
+/**
+ * The image-pipeline additions, as a partial config to deep-merge onto a collection: the admin
+ * image-management UI (gated by `focalUI`), the purge hooks, `upload.focalPoint`, the on-demand
+ * admin thumbnail, and the lean `defaultPopulate` / `forceSelect` that keep the virtual URLs
+ * riding through select/populated reads. The factory below folds these into the default `images`
+ * collection; the plugin folds them onto an existing collection when `extendCollection` is set
+ * (so a project's own `media` collection gains the pipeline without a second collection).
+ * Deliberately omits `alt`/`access`/`admin`/`slug` and the mime whitelist so it never clobbers a
+ * collection it's merged onto (the plugin also re-merges the target's own
+ * `defaultPopulate`/`forceSelect`/thumbnail on top).
+ */ export const imageEnhancements = (opts = {})=>{
+    const { focalUI = true, virtualFields = true, previewRatios, purgePath, folders, endpointsEnabled = true } = opts;
+    const variantSlug = opts.variantSlug || GENERATED_IMAGES_SLUG;
+    const adminThumbnail = resolveAdminThumbnail(opts.adminThumbnail, opts.apiRoute);
+    // Lean relationship population: when an image is referenced (e.g. `page.heroImage`), populate the
+    // renderable fields + the virtual URLs, and skip the `variants` join (which would run an extra
+    // query per populated image). `forceSelect` keeps the virtual fields' inputs present under `select`.
+    const renderableFields = {
+        alt: true,
+        url: true,
+        filename: true,
+        width: true,
+        height: true,
+        focalX: true,
+        focalY: true
+    };
+    const defaultPopulate = virtualFields ? {
+        ...renderableFields,
+        ...Object.fromEntries(VIRTUAL_URL_FIELDS.map((f)=>[
+                f,
+                true
+            ]))
+    } : renderableFields;
+    const forceSelect = virtualFields ? Object.fromEntries(VIRTUAL_URL_INPUTS.map((f)=>[
+            f,
+            true
+        ])) : undefined;
+    return {
+        // Admin UI is gated by focalUI; the virtual URL fields are for API consumers, so they're
+        // added independently (hidden in the admin).
+        fields: [
+            ...adminUIFields(focalUI, variantSlug, previewRatios, purgePath, endpointsEnabled),
+            ...virtualFields ? virtualUrlFields() : []
+        ],
+        hooks: {
+            afterChange: [
+                purgeStaleVariantsAfterChange({
+                    variantSlug
+                })
+            ],
+            beforeDelete: [
+                purgeVariantsBeforeDelete({
+                    variantSlug
+                })
+            ]
+        },
+        defaultPopulate: defaultPopulate,
+        ...forceSelect ? {
+            forceSelect: forceSelect
+        } : {},
+        upload: {
+            focalPoint: true,
+            ...adminThumbnail ? {
+                adminThumbnail
+            } : {}
+        },
+        ...folders ? {
+            folders: true
+        } : {}
+    };
+};
+/**
+ * The source image upload collection. Stores only the original (no pre-generated sizes by
+ * default); keeps Payload's built-in `focalPoint` (the focal component enhances it). The
+ * on-demand transform endpoint serves every rendered variant and records it in the
+ * generated-images collection, surfaced here via the `variants` join and purged by the
+ * change/delete hooks. The LQIP placeholder is generated on demand by `<ResponsiveImage>` (a tiny
+ * inline base64 via the shared variant cache) — there's no stored placeholder field.
+ */ export const createImagesCollection = (opts = {})=>{
+    const { localizeAlt = false, folders, maxOriginalSize } = opts;
+    const enh = imageEnhancements(opts);
+    const adminThumbnail = enh.upload.adminThumbnail;
+    return {
+        slug: 'images',
+        access: {
+            create: authd,
+            delete: authd,
+            read: anyone,
+            update: authd
+        },
+        admin: {
+            group: 'Assets',
+            description: 'Upload images here. Display sizes are generated on demand and cached — store the original once, render any size.',
+            enableListViewSelectAPI: true,
+            useAsTitle: 'alt',
+            // `filename` first: the list view renders the (on-demand, adminThumbnail) preview on that cell.
+            defaultColumns: [
+                'filename',
+                'alt',
+                'updatedAt'
+            ],
+            listSearchableFields: [
+                'alt',
+                'filename'
+            ]
+        },
+        defaultPopulate: enh.defaultPopulate,
+        ...enh.forceSelect ? {
+            forceSelect: enh.forceSelect
+        } : {},
+        ...folders ? {
+            folders: true
+        } : {},
+        fields: [
+            {
+                name: 'alt',
+                type: 'text',
+                required: true,
+                localized: localizeAlt,
+                admin: {
+                    description: 'Describe the image for screen readers and SEO.'
+                }
+            },
+            ...enh.fields ?? []
+        ],
+        hooks: enh.hooks,
+        upload: {
+            focalPoint: true,
+            displayPreview: true,
+            mimeTypes: opts.mimeTypes ?? IMAGE_MIME_TYPES,
+            ...adminThumbnail ? {
+                adminThumbnail
+            } : {},
+            // Off by default — the stored original is kept untouched; only downsize when asked, to bound storage.
+            ...maxOriginalSize ? {
+                resizeOptions: {
+                    width: maxOriginalSize,
+                    height: maxOriginalSize,
+                    fit: 'inside',
+                    withoutEnlargement: true
+                }
+            } : {}
+        }
+    };
+};
+/** The default Images collection (on-demand transforms, no pre-generated sizes). */ export const Images = createImagesCollection();
+
+//# sourceMappingURL=images.js.map

package/dist/collections/images.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/collections/images.ts"],"sourcesContent":["import type { CollectionConfig, CollectionSlug, Field, GetAdminThumbnail } from 'payload'\n\nimport { anyone, authd } from '../access'\nimport { VIRTUAL_URL_FIELDS, VIRTUAL_URL_INPUTS, virtualUrlFields } from '../fields/virtualUrls'\nimport { purgeStaleVariantsAfterChange, purgeVariantsBeforeDelete } from '../hooks/purge'\nimport { IMAGE_MIME_TYPES } from '../transform/params'\nimport { GENERATED_IMAGES_SLUG } from './generatedImages'\n\n/** Admin component subpaths (referenced by the Payload import map). */\nexport const FocalPreviewFieldPath = '@pro-laico/payload-images/admin/focalPreview'\nexport const PurgeVariantsFieldPath = '@pro-laico/payload-images/admin/purgeVariants'\n\nexport interface CreateImagesOptions {\n  /** Render the focal-point + ratio-preview field and the purge-variants button. Default true. */\n  focalUI?: boolean\n  /** Aspect ratios shown in the focal preview tiles. */\n  previewRatios?: string[]\n  /** Slug of the generated-images collection the `variants` join targets. */\n  variantSlug?: string\n  /** Purge route (under the API base) the purge button POSTs to. Default `/img/purge`. */\n  purgePath?: string\n  /** Admin list/preview thumbnail width (px), served on-demand via the transform endpoint so the\n   *  admin never loads full-res originals. Default 160; pass `false` to use Payload's default. */\n  adminThumbnail?: number | false\n  /** The app's API route base (`config.routes.api`), used to build the admin thumbnail URL. Default `/api`. */\n  apiRoute?: string\n  /** Whether the transform + purge endpoints are registered (`transform !== false`). When false, the\n   *  purge button and the `variants` join — UI that targets those endpoints — are skipped. Default true. */\n  endpointsEnabled?: boolean\n  /** Add virtual `src`/`srcset`/`placeholderURL`/`thumbnailURL` fields (computed on read), so\n   *  optimized URLs ride along in every REST/GraphQL/Local-API response. Default true. */\n  virtualFields?: boolean\n  /** Mark the `alt` field `localized: true` (requires Payload localization). Default false. */\n  localizeAlt?: boolean\n  /** Accepted upload mime types. Defaults to the raster formats the transform pipeline can\n   *  process ({@link IMAGE_MIME_TYPES}: avif/webp/jpeg/png). Override to widen or narrow what\n   *  the collection accepts — but the endpoint only meaningfully transforms raster images. */\n  mimeTypes?: string[]\n  /** Enable Payload's native folder organization on the collection (adds a folder relationship). Default false. */\n  folders?: boolean\n  /** Cap the *stored* original's longest edge (px) via `upload.resizeOptions`, applied once on upload.\n   *  Off by default — the original is kept untouched. Set it only to bound storage. */\n  maxOriginalSize?: number\n}\n\n/**\n * A focal-cropped admin thumbnail served by the transform endpoint, so the Images list view\n * loads tiny WebP thumbnails instead of full-resolution originals. Returns `undefined` when\n * disabled (`adminThumbnail: false`, or the transform endpoint isn't registered). The API base\n * comes from the app's `routes.api` (threaded through as `apiRoute`).\n */\nconst resolveAdminThumbnail = (adminThumbnail: number | false | undefined, apiRoute = '/api'): GetAdminThumbnail | undefined => {\n  if (adminThumbnail === false) return undefined\n  const w = typeof adminThumbnail === 'number' ? adminThumbnail : 160\n  return ({ doc }) => (doc?.id ? `${apiRoute}/img/${String(doc.id)}?w=${w}&h=${w}&fit=cover&fmt=auto` : null)\n}\n\n/**\n * The admin \"image management\" fields, shown only when `focalUI` is on: the focal-point picker,\n * the ratio preview, the purge-variants button, and the `variants` join listing the cached\n * variants (it pairs with the purge button). With `focalUI: false` the collection is a clean\n * upload — just `alt` + the file — and the import map isn't needed.\n */\nconst adminUIFields = (\n  focalUI: boolean,\n  variantSlug: CollectionSlug,\n  previewRatios?: string[],\n  purgePath?: string,\n  endpoints = true,\n): Field[] =>\n  focalUI\n    ? [\n        {\n          name: 'focalPreview',\n          type: 'ui',\n          admin: { components: { Field: { path: FocalPreviewFieldPath, ...(previewRatios ? { clientProps: { previewRatios } } : {}) } } },\n        },\n        // The purge button POSTs to the purge endpoint and the join lists endpoint-generated\n        // variants — with the endpoints unregistered, both would be dead UI.\n        ...(endpoints\n          ? ([\n              {\n                name: 'purgeVariants',\n                type: 'ui',\n                admin: { components: { Field: { path: PurgeVariantsFieldPath, ...(purgePath ? { clientProps: { purgePath } } : {}) } } },\n              },\n              {\n                name: 'variants',\n                type: 'join',\n                collection: variantSlug,\n                on: 'source',\n                admin: { defaultColumns: ['filename', 'width', 'height', 'format'], allowCreate: false },\n              },\n            ] as Field[])\n          : []),\n      ]\n    : []\n\n/**\n * The image-pipeline additions, as a partial config to deep-merge onto a collection: the admin\n * image-management UI (gated by `focalUI`), the purge hooks, `upload.focalPoint`, the on-demand\n * admin thumbnail, and the lean `defaultPopulate` / `forceSelect` that keep the virtual URLs\n * riding through select/populated reads. The factory below folds these into the default `images`\n * collection; the plugin folds them onto an existing collection when `extendCollection` is set\n * (so a project's own `media` collection gains the pipeline without a second collection).\n * Deliberately omits `alt`/`access`/`admin`/`slug` and the mime whitelist so it never clobbers a\n * collection it's merged onto (the plugin also re-merges the target's own\n * `defaultPopulate`/`forceSelect`/thumbnail on top).\n */\nexport const imageEnhancements = (opts: CreateImagesOptions = {}): Partial<CollectionConfig> => {\n  const { focalUI = true, virtualFields = true, previewRatios, purgePath, folders, endpointsEnabled = true } = opts\n  const variantSlug = (opts.variantSlug || GENERATED_IMAGES_SLUG) as CollectionSlug\n  const adminThumbnail = resolveAdminThumbnail(opts.adminThumbnail, opts.apiRoute)\n\n  // Lean relationship population: when an image is referenced (e.g. `page.heroImage`), populate the\n  // renderable fields + the virtual URLs, and skip the `variants` join (which would run an extra\n  // query per populated image). `forceSelect` keeps the virtual fields' inputs present under `select`.\n  const renderableFields = { alt: true, url: true, filename: true, width: true, height: true, focalX: true, focalY: true }\n  const defaultPopulate = virtualFields\n    ? { ...renderableFields, ...Object.fromEntries(VIRTUAL_URL_FIELDS.map((f) => [f, true])) }\n    : renderableFields\n  const forceSelect = virtualFields ? Object.fromEntries(VIRTUAL_URL_INPUTS.map((f) => [f, true])) : undefined\n\n  return {\n    // Admin UI is gated by focalUI; the virtual URL fields are for API consumers, so they're\n    // added independently (hidden in the admin).\n    fields: [...adminUIFields(focalUI, variantSlug, previewRatios, purgePath, endpointsEnabled), ...(virtualFields ? virtualUrlFields() : [])],\n    hooks: {\n      afterChange: [purgeStaleVariantsAfterChange({ variantSlug })],\n      beforeDelete: [purgeVariantsBeforeDelete({ variantSlug })],\n    },\n    defaultPopulate: defaultPopulate as CollectionConfig['defaultPopulate'],\n    ...(forceSelect ? { forceSelect: forceSelect as CollectionConfig['forceSelect'] } : {}),\n    upload: { focalPoint: true, ...(adminThumbnail ? { adminThumbnail } : {}) },\n    ...(folders ? { folders: true } : {}),\n  }\n}\n\n/**\n * The source image upload collection. Stores only the original (no pre-generated sizes by\n * default); keeps Payload's built-in `focalPoint` (the focal component enhances it). The\n * on-demand transform endpoint serves every rendered variant and records it in the\n * generated-images collection, surfaced here via the `variants` join and purged by the\n * change/delete hooks. The LQIP placeholder is generated on demand by `<ResponsiveImage>` (a tiny\n * inline base64 via the shared variant cache) — there's no stored placeholder field.\n */\nexport const createImagesCollection = (opts: CreateImagesOptions = {}): CollectionConfig => {\n  const { localizeAlt = false, folders, maxOriginalSize } = opts\n  const enh = imageEnhancements(opts)\n  const adminThumbnail = (enh.upload as { adminThumbnail?: GetAdminThumbnail }).adminThumbnail\n\n  return {\n    slug: 'images',\n    access: { create: authd, delete: authd, read: anyone, update: authd },\n    admin: {\n      group: 'Assets',\n      description: 'Upload images here. Display sizes are generated on demand and cached — store the original once, render any size.',\n      enableListViewSelectAPI: true,\n      useAsTitle: 'alt',\n      // `filename` first: the list view renders the (on-demand, adminThumbnail) preview on that cell.\n      defaultColumns: ['filename', 'alt', 'updatedAt'],\n      listSearchableFields: ['alt', 'filename'],\n    },\n    defaultPopulate: enh.defaultPopulate,\n    ...(enh.forceSelect ? { forceSelect: enh.forceSelect } : {}),\n    ...(folders ? { folders: true } : {}),\n    fields: [\n      {\n        name: 'alt',\n        type: 'text',\n        required: true,\n        localized: localizeAlt,\n        admin: { description: 'Describe the image for screen readers and SEO.' },\n      },\n      ...(enh.fields ?? []),\n    ],\n    hooks: enh.hooks,\n    upload: {\n      focalPoint: true,\n      displayPreview: true, // show image thumbnails in upload/relationship fields that target this collection\n      mimeTypes: opts.mimeTypes ?? IMAGE_MIME_TYPES,\n      ...(adminThumbnail ? { adminThumbnail } : {}),\n      // Off by default — the stored original is kept untouched; only downsize when asked, to bound storage.\n      ...(maxOriginalSize\n        ? { resizeOptions: { width: maxOriginalSize, height: maxOriginalSize, fit: 'inside', withoutEnlargement: true } }\n        : {}),\n    },\n  }\n}\n\n/** The default Images collection (on-demand transforms, no pre-generated sizes). */\nexport const Images: CollectionConfig = createImagesCollection()\n"],"names":["anyone","authd","VIRTUAL_URL_FIELDS","VIRTUAL_URL_INPUTS","virtualUrlFields","purgeStaleVariantsAfterChange","purgeVariantsBeforeDelete","IMAGE_MIME_TYPES","GENERATED_IMAGES_SLUG","FocalPreviewFieldPath","PurgeVariantsFieldPath","resolveAdminThumbnail","adminThumbnail","apiRoute","undefined","w","doc","id","String","adminUIFields","focalUI","variantSlug","previewRatios","purgePath","endpoints","name","type","admin","components","Field","path","clientProps","collection","on","defaultColumns","allowCreate","imageEnhancements","opts","virtualFields","folders","endpointsEnabled","renderableFields","alt","url","filename","width","height","focalX","focalY","defaultPopulate","Object","fromEntries","map","f","forceSelect","fields","hooks","afterChange","beforeDelete","upload","focalPoint","createImagesCollection","localizeAlt","maxOriginalSize","enh","slug","access","create","delete","read","update","group","description","enableListViewSelectAPI","useAsTitle","listSearchableFields","required","localized","displayPreview","mimeTypes","resizeOptions","fit","withoutEnlargement","Images"],"mappings":"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"}

package/dist/components/admin/focalPreview.d.ts

@@ -0,0 +1,8 @@
+import type React from 'react';
+interface FocalPreviewProps {
+    previewRatios?: string[];
+    readOnly?: boolean;
+}
+export declare const FocalPreview: React.FC<FocalPreviewProps>;
+export default FocalPreview;
+//# sourceMappingURL=focalPreview.d.ts.map

package/dist/components/admin/focalPreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focalPreview.d.ts","sourceRoot":"","sources":["../../../src/components/admin/focalPreview.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA0B9B,UAAU,iBAAiB;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAID,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA6IpD,CAAA;AAED,eAAe,YAAY,CAAA"}