@pantheon-systems/p1-media 0.4.3 → 0.4.5

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactElement, ImgHTMLAttributes, ReactNode } from 'react';
+import { ImgHTMLAttributes, ReactElement, ReactNode } from 'react';
 import { ComponentConfig } from '@puckeditor/core';
 
 /**
@@ -58,7 +58,7 @@ interface MediaConfig {
 type GetAuthToken = () => Promise<string | null> | string | null;
 
 interface MediaPluginOptions {
-    /** The base URL of the Cloudflare Worker media API. Defaults to the production host. */
+    /** The base URL of the media API. Defaults to the production host. */
     workerUrl?: string;
     /**
      * Site identifier used to scope media to a specific site. Defaults to the
@@ -68,7 +68,7 @@ interface MediaPluginOptions {
     siteId?: string;
     /**
      * Workstream (branch) identifier. Currently accepted for forward-compat but not
-     * read by the Worker for any scoping decision — omit unless a future release
+     * read by the backend for any scoping decision — omit unless a future release
      * documents otherwise.
      */
     workstreamId?: string;
@@ -89,7 +89,7 @@ interface MediaPluginOptions {
     metadataFields?: MetadataFieldDef[];
 }
 /**
- * Creates a Puck plugin that adds a media library backed by Cloudflare R2 + D1.
+ * Creates a Puck plugin that adds a media library backed by Cloudflare R2.
  * It supports two field modes:
  *   - Basic: text fields matching image/media name patterns are replaced with the
  *     picker and store a clean CDN URL string. Render with `buildImageUrl()`.
@@ -145,7 +145,7 @@ interface ImageTransformParams {
     quality?: number;
 }
 /**
- * Merges Cloudflare Images transform params onto a CDN image URL.
+ * Merges image transform params onto a CDN image URL.
  * Preserves any existing params in the URL — e.g. the editor's crop intent
  * (`fit=cover&gravity=auto` for smart crop, `trim.*` for a manual crop).
  *
@@ -158,20 +158,17 @@ interface GetMediaPropsOptions {
     /**
      * The CDN image origin that serves media, e.g.
      * "https://staging.media.p1.pantheon.io". This is the public image host —
-     * NOT the Worker API URL (`…workers.dev`), whose origin would reject every
-     * real image URL.
+     * NOT the content API URL, whose origin would reject every real image URL.
      *
-     * Security (required): a value's `url` is untrusted document content — anyone
-     * who can edit a document, or call the CCR `/edits` API, controls it. Without
-     * an origin check a crafted `https://evil.example/beacon.png` turns every
-     * published render into a visitor-IP exfil beacon (and an SSRF under
-     * server-fetching `next/image`). getMediaProps therefore rejects any url that
-     * is not `https` on this exact origin. If `mediaBaseUrl` is omitted it
+     * Security (required): a value's `url` is untrusted document content —
+     * anyone who can edit a document controls it. getMediaProps rejects any url
+     * that is not `https` on this exact origin, so an edited document can't
+     * point a render at an arbitrary origin. If `mediaBaseUrl` is omitted it
      * **fails closed** (empty src) rather than degrading to an insecure pass-through.
      *
      * Local dev exception: when the configured base is itself `http` on a
-     * loopback host (`localhost`, `127.0.0.1`, `[::1]` — a local `wrangler dev`
-     * worker), same-origin `http` urls are allowed so rich values render locally.
+     * loopback host (`localhost`, `127.0.0.1`, `[::1]`), same-origin `http`
+     * urls are allowed so rich values render locally.
      */
     mediaBaseUrl?: string;
     /** Transform params merged onto the validated URL (width, height, format, quality). */
@@ -188,7 +185,7 @@ declare function getMediaProps(value: MediaFieldValue | null | undefined, option
  * (a broken foreign-origin image is never emitted). `alt` may be overridden;
  * otherwise it comes from the value.
  */
-declare function MediaImage({ image, mediaBaseUrl, transform, alt, ...rest }: {
+declare function MediaImage({ image, mediaBaseUrl, transform, alt, loading, decoding, ...rest }: {
     image: MediaFieldValue | null | undefined;
     mediaBaseUrl?: string;
     transform?: ImageTransformParams;
@@ -198,17 +195,21 @@ declare function MediaImage({ image, mediaBaseUrl, transform, alt, ...rest }: {
  * ESCAPED text (React default escaping — never dangerouslySetInnerHTML, req.
  * R6). Renders nothing when the src is rejected/empty.
  */
-declare function MediaFigure({ image, schema, mediaBaseUrl, transform, className, captionClassName, }: {
+declare function MediaFigure({ image, schema, mediaBaseUrl, transform, className, captionClassName, loading, decoding, }: {
     image: MediaFieldValue | null | undefined;
     schema?: MetadataFieldDef[];
     mediaBaseUrl?: string;
     transform?: ImageTransformParams;
     className?: string;
     captionClassName?: string;
+    /** Defaults to "lazy"; pass "eager" for an above-the-fold figure. */
+    loading?: ImgHTMLAttributes<HTMLImageElement>["loading"];
+    decoding?: ImgHTMLAttributes<HTMLImageElement>["decoding"];
 }): ReactElement | null;
 
 interface MediaFigureBlockProps {
     photo: MediaFieldValue | null;
+    loading?: "lazy" | "eager";
 }
 interface MediaFigureBlockOptions {
     /**
@@ -233,6 +234,12 @@ interface MediaFigureBlockOptions {
     captionClassName?: string;
     /** Rendered when no photo is chosen (or its URL fails origin validation). */
     placeholder?: ReactNode;
+    /**
+     * Default for the block's "Loading" field. "lazy" (the default) keeps
+     * off-screen images off the wire on image-heavy pages; use "eager" when the
+     * block is reliably above the fold.
+     */
+    defaultLoading?: "lazy" | "eager";
 }
 /**
  * Builds a registerable Puck component around the rich `p1-media` field and

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactElement, ImgHTMLAttributes, ReactNode } from 'react';
+import { ImgHTMLAttributes, ReactElement, ReactNode } from 'react';
 import { ComponentConfig } from '@puckeditor/core';
 
 /**
@@ -58,7 +58,7 @@ interface MediaConfig {
 type GetAuthToken = () => Promise<string | null> | string | null;
 
 interface MediaPluginOptions {
-    /** The base URL of the Cloudflare Worker media API. Defaults to the production host. */
+    /** The base URL of the media API. Defaults to the production host. */
     workerUrl?: string;
     /**
      * Site identifier used to scope media to a specific site. Defaults to the
@@ -68,7 +68,7 @@ interface MediaPluginOptions {
     siteId?: string;
     /**
      * Workstream (branch) identifier. Currently accepted for forward-compat but not
-     * read by the Worker for any scoping decision — omit unless a future release
+     * read by the backend for any scoping decision — omit unless a future release
      * documents otherwise.
      */
     workstreamId?: string;
@@ -89,7 +89,7 @@ interface MediaPluginOptions {
     metadataFields?: MetadataFieldDef[];
 }
 /**
- * Creates a Puck plugin that adds a media library backed by Cloudflare R2 + D1.
+ * Creates a Puck plugin that adds a media library backed by Cloudflare R2.
  * It supports two field modes:
  *   - Basic: text fields matching image/media name patterns are replaced with the
  *     picker and store a clean CDN URL string. Render with `buildImageUrl()`.
@@ -145,7 +145,7 @@ interface ImageTransformParams {
     quality?: number;
 }
 /**
- * Merges Cloudflare Images transform params onto a CDN image URL.
+ * Merges image transform params onto a CDN image URL.
  * Preserves any existing params in the URL — e.g. the editor's crop intent
  * (`fit=cover&gravity=auto` for smart crop, `trim.*` for a manual crop).
  *
@@ -158,20 +158,17 @@ interface GetMediaPropsOptions {
     /**
      * The CDN image origin that serves media, e.g.
      * "https://staging.media.p1.pantheon.io". This is the public image host —
-     * NOT the Worker API URL (`…workers.dev`), whose origin would reject every
-     * real image URL.
+     * NOT the content API URL, whose origin would reject every real image URL.
      *
-     * Security (required): a value's `url` is untrusted document content — anyone
-     * who can edit a document, or call the CCR `/edits` API, controls it. Without
-     * an origin check a crafted `https://evil.example/beacon.png` turns every
-     * published render into a visitor-IP exfil beacon (and an SSRF under
-     * server-fetching `next/image`). getMediaProps therefore rejects any url that
-     * is not `https` on this exact origin. If `mediaBaseUrl` is omitted it
+     * Security (required): a value's `url` is untrusted document content —
+     * anyone who can edit a document controls it. getMediaProps rejects any url
+     * that is not `https` on this exact origin, so an edited document can't
+     * point a render at an arbitrary origin. If `mediaBaseUrl` is omitted it
      * **fails closed** (empty src) rather than degrading to an insecure pass-through.
      *
      * Local dev exception: when the configured base is itself `http` on a
-     * loopback host (`localhost`, `127.0.0.1`, `[::1]` — a local `wrangler dev`
-     * worker), same-origin `http` urls are allowed so rich values render locally.
+     * loopback host (`localhost`, `127.0.0.1`, `[::1]`), same-origin `http`
+     * urls are allowed so rich values render locally.
      */
     mediaBaseUrl?: string;
     /** Transform params merged onto the validated URL (width, height, format, quality). */
@@ -188,7 +185,7 @@ declare function getMediaProps(value: MediaFieldValue | null | undefined, option
  * (a broken foreign-origin image is never emitted). `alt` may be overridden;
  * otherwise it comes from the value.
  */
-declare function MediaImage({ image, mediaBaseUrl, transform, alt, ...rest }: {
+declare function MediaImage({ image, mediaBaseUrl, transform, alt, loading, decoding, ...rest }: {
     image: MediaFieldValue | null | undefined;
     mediaBaseUrl?: string;
     transform?: ImageTransformParams;
@@ -198,17 +195,21 @@ declare function MediaImage({ image, mediaBaseUrl, transform, alt, ...rest }: {
  * ESCAPED text (React default escaping — never dangerouslySetInnerHTML, req.
  * R6). Renders nothing when the src is rejected/empty.
  */
-declare function MediaFigure({ image, schema, mediaBaseUrl, transform, className, captionClassName, }: {
+declare function MediaFigure({ image, schema, mediaBaseUrl, transform, className, captionClassName, loading, decoding, }: {
     image: MediaFieldValue | null | undefined;
     schema?: MetadataFieldDef[];
     mediaBaseUrl?: string;
     transform?: ImageTransformParams;
     className?: string;
     captionClassName?: string;
+    /** Defaults to "lazy"; pass "eager" for an above-the-fold figure. */
+    loading?: ImgHTMLAttributes<HTMLImageElement>["loading"];
+    decoding?: ImgHTMLAttributes<HTMLImageElement>["decoding"];
 }): ReactElement | null;
 
 interface MediaFigureBlockProps {
     photo: MediaFieldValue | null;
+    loading?: "lazy" | "eager";
 }
 interface MediaFigureBlockOptions {
     /**
@@ -233,6 +234,12 @@ interface MediaFigureBlockOptions {
     captionClassName?: string;
     /** Rendered when no photo is chosen (or its URL fails origin validation). */
     placeholder?: ReactNode;
+    /**
+     * Default for the block's "Loading" field. "lazy" (the default) keeps
+     * off-screen images off the wire on image-heavy pages; use "eager" when the
+     * block is reliably above the fold.
+     */
+    defaultLoading?: "lazy" | "eager";
 }
 /**
  * Builds a registerable Puck component around the rich `p1-media` field and

package/dist/index.js

@@ -2815,6 +2815,8 @@ function MediaImage({
   mediaBaseUrl,
   transform,
   alt,
+  loading = "lazy",
+  decoding = "async",
   ...rest
 }) {
   const props = getMediaProps(image, { mediaBaseUrl, transform });
@@ -2824,6 +2826,8 @@ function MediaImage({
     {
       src: props.src,
       alt: alt ?? props.alt,
+      loading,
+      decoding,
       ...props.width !== void 0 ? { width: props.width } : {},
       ...props.height !== void 0 ? { height: props.height } : {},
       ...rest
@@ -2856,7 +2860,9 @@ function MediaFigure({
   mediaBaseUrl,
   transform,
   className,
-  captionClassName
+  captionClassName,
+  loading = "lazy",
+  decoding = "async"
 }) {
   const props = getMediaProps(image, { mediaBaseUrl, transform });
   if (!props.src) return null;
@@ -2867,6 +2873,8 @@ function MediaFigure({
       {
         src: props.src,
         alt: props.alt,
+        loading,
+        decoding,
         ...props.width !== void 0 ? { width: props.width } : {},
         ...props.height !== void 0 ? { height: props.height } : {}
       }
@@ -2898,19 +2906,29 @@ function createMediaFigureBlock(options) {
     schema,
     className,
     captionClassName,
-    placeholder = "Choose a photo from the media library"
+    placeholder = "Choose a photo from the media library",
+    defaultLoading = "lazy"
   } = options;
   return {
     label,
     fields: {
       // `p1-media` is registered by createMediaPlugin via overrides.fieldTypes,
       // so it is not part of Puck's built-in Field union.
-      photo: { type: "p1-media", label: fieldLabel }
+      photo: { type: "p1-media", label: fieldLabel },
+      loading: {
+        type: "radio",
+        label: "Loading",
+        options: [
+          { label: "Lazy", value: "lazy" },
+          { label: "Eager", value: "eager" }
+        ]
+      }
     },
     defaultProps: {
-      photo: null
+      photo: null,
+      loading: defaultLoading
     },
-    render: ({ photo }) => {
+    render: ({ photo, loading }) => {
       const { src } = getMediaProps(photo ?? null, { mediaBaseUrl });
       if (!src) {
         return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { style: placeholderStyle, children: placeholder });
@@ -2923,7 +2941,8 @@ function createMediaFigureBlock(options) {
           transform,
           schema,
           className,
-          captionClassName
+          captionClassName,
+          loading: loading === "eager" ? "eager" : "lazy"
         }
       );
     }