@pantheon-systems/p1-media 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactElement, ImgHTMLAttributes, ReactNode } from 'react';
+import { ComponentConfig } from '@puckeditor/core';
+
+/**
+ * A metadata field advertised by the Worker's `GET /media/schema` endpoint.
+ * The set is Pantheon-defined and global for v1; the plugin renders one input
+ * per entry and iterates these to render metadata generically (req. R14).
+ */
+interface MetadataFieldDef {
+    name: string;
+    label: string;
+    type: "string";
+    required?: boolean;
+}
+/**
+ * The value written by the `p1-media` field (rich mode). Carries the pinned
+ * asset identity plus a snapshot of the metadata defaults copied at edit time.
+ * `metaSchemaVersion` records the schema that produced the snapshot (req. R12).
+ * `alt` and any schema-driven fields (byline, caption, …) live alongside as
+ * string metadata; `width`/`height` may be present as captured numeric
+ * dimensions (a CLS win when rendered).
+ */
+interface MediaValue {
+    assetId: string;
+    versionId: string;
+    url: string;
+    metaSchemaVersion?: number;
+    alt?: string;
+    [meta: string]: string | number | undefined;
+}
+/**
+ * string = basic mode (a bare CDN URL, kept first-class forever); object =
+ * rich mode. Every render helper accepts both.
+ */
+type MediaFieldValue = string | MediaValue;
+/** Props produced by getMediaProps, spreadable onto `<img>` or next/image. */
+interface MediaProps {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+}
+
+interface MediaConfig {
+    workerUrl: string;
+    siteId: string;
+    workstreamId?: string;
+    getAuthToken: () => Promise<string | null> | string | null;
+    /**
+     * Fallback metadata field schema for the rich `p1-media` field, used when
+     * `GET /media/schema` is absent/unreachable (lets the plugin ship before the
+     * Worker upgrade). Defaults to `[{ name: "alt", label: "Alt text", type: "string" }]`.
+     */
+    metadataFields?: MetadataFieldDef[];
+}
+
+type GetAuthToken = () => Promise<string | null> | string | null;
+
+interface MediaPluginOptions {
+    /** The base URL of the Cloudflare Worker media API. Defaults to the production host. */
+    workerUrl?: string;
+    /**
+     * Site identifier used to scope media to a specific site. Defaults to the
+     * ambient puck-css site context (`P1PuckProvider`) when omitted — pass this
+     * explicitly only when rendering outside that provider, or to override it.
+     */
+    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
+     * documents otherwise.
+     */
+    workstreamId?: string;
+    /**
+     * Function that returns the current auth token, or null if unauthenticated.
+     * May be async. Defaults to the ambient puck-css auth context's `getToken`
+     * (`P1AuthProvider`) when omitted — pass this explicitly only when rendering
+     * outside that provider, or to override it.
+     */
+    getAuthToken?: GetAuthToken;
+    /** Field name patterns that trigger the media picker (defaults to common image URL patterns) */
+    fieldNamePatterns?: RegExp[];
+    /**
+     * Fallback metadata field schema for the rich `p1-media` field, used when
+     * `GET /media/schema` is unavailable. Defaults to
+     * `[{ name: "alt", label: "Alt text", type: "string" }]`.
+     */
+    metadataFields?: MetadataFieldDef[];
+}
+/**
+ * Creates a Puck plugin that adds a media library backed by Cloudflare R2 + D1.
+ * 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()`.
+ *   - Rich: a registered `p1-media` field type stores a MediaValue object (version
+ *     URL + metadata such as alt). Render with `getMediaProps()` / `MediaImage` /
+ *     `MediaFigure`. The editor's crop intent is carried as `?fit=…&gravity=…`.
+ *
+ * @example
+ * ```tsx
+ * // Inside a P1 site (rendered within P1PuckProvider + P1AuthProvider):
+ * // siteId and getAuthToken are read from context automatically.
+ * const mediaPlugin = createMediaPlugin({});
+ *
+ * // Outside a P1 site, or to override the ambient context, pass explicitly:
+ * const mediaPlugin = createMediaPlugin({
+ *   siteId: "my-site",
+ *   getAuthToken: () => localStorage.getItem("token"),
+ * });
+ *
+ * <Puck plugins={[mediaPlugin]} config={config} data={data} />
+ * ```
+ */
+declare function createMediaPlugin(options: MediaPluginOptions): {
+    name: string;
+    overrides: {
+        fieldTypes: {
+            text: (props: any) => react_jsx_runtime.JSX.Element;
+            "p1-media": (props: any) => react_jsx_runtime.JSX.Element;
+        };
+    };
+    fieldTransforms: {
+        "p1-media": ({ value }: {
+            value: MediaFieldValue;
+        }) => MediaValue | {
+            url: string;
+            alt: string;
+        };
+    };
+};
+
+/**
+ * Default field name patterns that trigger the media library picker.
+ * Targets image/logo/icon source fields while excluding navigation URLs
+ * (buttonUrl, linkUrl, ctaUrl, etc.) and alt text fields.
+ */
+declare const DEFAULT_MEDIA_PATTERNS: RegExp[];
+
+interface ImageTransformParams {
+    width?: number;
+    height?: number;
+    /** `auto` negotiates avif → webp → jpeg from the request's Accept header. */
+    format?: "auto" | "webp" | "jpeg" | "png" | "gif" | "avif";
+    quality?: number;
+}
+/**
+ * Merges Cloudflare Images 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).
+ *
+ * @example
+ * buildImageUrl(data.heroImage, { width: 1200, height: 630, format: "webp" })
+ */
+declare function buildImageUrl(url: string, params: ImageTransformParams): string;
+
+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.
+     *
+     * 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
+     * **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.
+     */
+    mediaBaseUrl?: string;
+    /** Transform params merged onto the validated URL (width, height, format, quality). */
+    transform?: ImageTransformParams;
+}
+/**
+ * Normalizes a `string | MediaValue | null` into `{ src, alt, width?, height? }`.
+ * A string (basic mode) yields `alt: ""`. `src` is validated against the CDN
+ * origin (see GetMediaPropsOptions) and empty on rejection.
+ */
+declare function getMediaProps(value: MediaFieldValue | null | undefined, options?: GetMediaPropsOptions): MediaProps;
+/**
+ * Common-case `<img>` wrapper. Renders nothing when the src is rejected/empty
+ * (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 }: {
+    image: MediaFieldValue | null | undefined;
+    mediaBaseUrl?: string;
+    transform?: ImageTransformParams;
+} & Omit<ImgHTMLAttributes<HTMLImageElement>, "src">): ReactElement | null;
+/**
+ * `<figure>` that renders the image plus the schema-advertised text fields as
+ * 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, }: {
+    image: MediaFieldValue | null | undefined;
+    schema?: MetadataFieldDef[];
+    mediaBaseUrl?: string;
+    transform?: ImageTransformParams;
+    className?: string;
+    captionClassName?: string;
+}): ReactElement | null;
+
+interface MediaFigureBlockProps {
+    photo: MediaFieldValue | null;
+}
+interface MediaFigureBlockOptions {
+    /**
+     * The CDN image origin used to validate value URLs — NOT the Worker API
+     * URL. See GetMediaPropsOptions. Defaults to the production origin
+     * ("https://media.p1.pantheon.io"); override for sandbox/staging/local dev.
+     */
+    mediaBaseUrl?: string;
+    /**
+     * Render-time transform. Include BOTH width and height — the editor's crop
+     * intent only changes the output when there is a target aspect ratio.
+     * Defaults to `{ width: 1200, height: 630, format: "auto" }`.
+     */
+    transform?: ImageTransformParams;
+    /** Component label in the Puck sidebar. Defaults to "Media Figure". */
+    label?: string;
+    /** Label of the media field. Defaults to "Photo". */
+    fieldLabel?: string;
+    /** Metadata schema passed to MediaFigure — pins figcaption field order/labels. */
+    schema?: MetadataFieldDef[];
+    className?: string;
+    captionClassName?: string;
+    /** Rendered when no photo is chosen (or its URL fails origin validation). */
+    placeholder?: ReactNode;
+}
+/**
+ * Builds a registerable Puck component around the rich `p1-media` field and
+ * `MediaFigure`. Spares consumers the custom-field-type cast and the
+ * width+height transform pitfall:
+ *
+ * ```tsx
+ * const config = {
+ *   components: {
+ *     MediaFigureBlock: createMediaFigureBlock({ mediaBaseUrl: MEDIA_BASE }),
+ *   },
+ * };
+ * ```
+ */
+declare function createMediaFigureBlock(options: MediaFigureBlockOptions): ComponentConfig<MediaFigureBlockProps>;
+
+/** Narrows a MediaFieldValue to the rich object form. */
+declare function isMediaValue(value: MediaFieldValue | null | undefined): value is MediaValue;
+/**
+ * Builds the value the `p1-media` field writes on asset selection.
+ *
+ * R10 invariant: never synthesize a MediaValue unless BOTH `assetId` and
+ * `versionId` are present — otherwise fall back to a bare URL string (basic
+ * mode). A value with undefined identity is unfindable by "update usages" and
+ * can render `src=undefined`, so this fallback is load-bearing, not cosmetic.
+ * It also means picking from a pre-upgrade Worker (bare-array `GET /media`, no
+ * assetId) yields a string, so the plugin degrades cleanly before the cutover.
+ */
+declare function makeMediaValue(input: {
+    assetId?: string | null;
+    versionId?: string | null;
+    url: string;
+    metaSchemaVersion?: number;
+    metadata?: Record<string, string | number | undefined>;
+}): MediaFieldValue;
+
+export { DEFAULT_MEDIA_PATTERNS, type GetMediaPropsOptions, type ImageTransformParams, type MediaConfig, type MediaFieldValue, MediaFigure, type MediaFigureBlockOptions, type MediaFigureBlockProps, MediaImage, type MediaPluginOptions, type MediaProps, type MediaValue, type MetadataFieldDef, buildImageUrl, createMediaFigureBlock, createMediaPlugin, getMediaProps, isMediaValue, makeMediaValue };