@phis/ui 0.2.0 → 0.3.0

package/gateway/form-registry.d.ts

@@ -4,11 +4,6 @@ import { type PhiFormDefinitionLike, type PhiResolvedFormDefinition } from "../c
 import type { PhiFormDescriptor } from "../types/form-descriptor";
 import type { PhiRuntimeModuleId } from "../types/cms-module-descriptors";
 import type { PhiFormId } from "../types/form-id";
-export declare const PHI_FORM_DEFINITION_STATUS: {
-    readonly workingDraft: 0;
-    readonly published: 1;
-    readonly archived: 2;
-};
 export type PhiFormRegistryRecord = {
     id: number;
     ownerModuleId: PhiRuntimeModuleId;
@@ -41,7 +36,7 @@ export type GetResolvedFormDefinitionOptions = FormRegistryRequestOptions & {
 export type ListResolvedFormDefinitionsOptions = FormRegistryRequestOptions & {
     presetDefinitions: readonly PhiRuntimeModuleFormDefinition[];
 };
-export declare const fetchFormRegistry: ({ apiBaseUrl, internalToken, siteKey, }: FormRegistryRequestOptions) => Promise<PhiFormRegistryRecord[]>;
+export declare const fetchFormRegistry: (options: FormRegistryRequestOptions) => Promise<PhiFormRegistryRecord[]>;
 export declare function listResolvedFormDefinitions({ apiBaseUrl, internalToken, siteKey, presetDefinitions, }: ListResolvedFormDefinitionsOptions): Promise<PhiResolvedFormDefinition<PhiFormDefinitionLike>[]>;
 export declare function getResolvedFormDefinition({ apiBaseUrl, internalToken, siteKey, formId, presetDefinitions, }: GetResolvedFormDefinitionOptions): Promise<PhiResolvedFormDefinition<PhiFormDefinitionLike> | null>;
 export {};

package/gateway/form-registry.js

@@ -1,12 +1,11 @@
-import { cache } from "react";
+import { definePhiRequestMemo } from "../server-helpers/request-memo";
 import "server-only";
-import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
 import { resolvePhiFormDefinition, } from "../components/forms/form-resolution";
 import { parsePhiFormDescriptor } from "../components/forms/form-descriptor-contract";
 import { isPhiFormId, normalizePhiFormId } from "../types/form-id";
 import { isPhiRecord } from "../helpers/is-record";
-import { throwPhiCmsGatewayError } from "./errors";
-export const PHI_FORM_DEFINITION_STATUS = {
+import { fetchPhiSiteApi } from "./site-api-request";
+const PHI_FORM_DEFINITION_STATUS = {
     workingDraft: 0,
     published: 1,
     archived: 2,
@@ -99,30 +98,15 @@ function buildResolvedDefinition(formId, records, presetDefinitions) {
         overrideDefinition,
     });
 }
-export const fetchFormRegistry = cache(async function fetchFormRegistry({ apiBaseUrl, internalToken, siteKey, }) {
-    if (!apiBaseUrl.trim()) {
-        throw new Error("Missing apiBaseUrl for fetchFormRegistry.");
-    }
-    if (!internalToken.trim()) {
-        throw new Error("Missing internalToken for fetchFormRegistry.");
-    }
-    if (!siteKey.trim()) {
-        throw new Error("Missing siteKey for fetchFormRegistry.");
-    }
-    const response = await fetch(buildApiUrl(apiBaseUrl, "/api/v1/forms/registry"), {
-        headers: buildApiHeaders({
-            token: internalToken,
-            siteKey,
-            includeToken: true,
-            includeSiteKey: true,
-            gateway: true,
-        }),
-        cache: "no-store",
-    });
-    if (!response.ok) {
-        throwPhiCmsGatewayError(`Failed to fetch form registry (${response.status}).`, response.status);
-    }
-    return normalizeRegistryResponse(await response.json().catch(() => null));
+export const fetchFormRegistry = definePhiRequestMemo(async function fetchFormRegistry({ apiBaseUrl, internalToken, siteKey, }) {
+    return normalizeRegistryResponse(await fetchPhiSiteApi({
+        context: "fetchFormRegistry",
+        apiBaseUrl,
+        internalToken,
+        siteKey,
+        path: "/api/v1/forms/registry",
+        failure: "Failed to fetch form registry",
+    }));
 });
 export async function listResolvedFormDefinitions({ apiBaseUrl, internalToken, siteKey, presetDefinitions, }) {
     const registry = await fetchFormRegistry({ apiBaseUrl, internalToken, siteKey });

package/gateway/form-submit.d.ts

@@ -1,32 +1,17 @@
 import "server-only";
 import type { PhiFormDefinitionLike } from "../components/forms/form-resolution";
 import type { PhiFormHandlerCredentialPolicy, PhiFormHandlerProviderDescriptor } from "../types/form-descriptor";
-export type PhiFormSubmitCategory = "auth" | "account" | "forms" | "site";
-export type PhiFormSubmitTransport = "relay" | "api" | "serverAction";
-export type PhiFormSubmitMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-export type PhiFormSubmitDescriptor = {
-    formId: string;
-    submitHandlerKey: string;
-    category: PhiFormSubmitCategory;
-    transport: PhiFormSubmitTransport;
-    method: PhiFormSubmitMethod;
-    endpointKey: string | null;
-    actionKey: string | null;
-    upstreamPath: string | null;
-    csrfPath: string | null;
-    requiresCsrf: boolean;
-    credentialPolicy: PhiFormHandlerCredentialPolicy;
-};
+import type { PhiFormSubmitRoute } from "../types/form-submit-route";
 export type PhiFormPreviewDescriptor = {
     formId: string;
 };
-export type PhiFormSubmitTarget = PhiFormSubmitDescriptor & {
+export type PhiFormSubmitTarget = PhiFormSubmitRoute & {
     upstreamPath: string | null;
     csrfPath: string | null;
     requiresCsrf: boolean;
     routeTarget: string;
 };
-type PhiFormSubmitDescriptorInput = {
+type PhiFormSubmitRouteInput = {
     formId: string;
     submitHandlerKey: string;
     category?: string | null;
@@ -43,9 +28,9 @@ type PhiFormDefinitionLikeWithPreview = Pick<PhiFormDefinitionLike, "formId" | "
     config?: Record<string, unknown>;
     defaultConfig?: Record<string, unknown>;
 };
-export declare function buildPhiFormSubmitDescriptor(input: PhiFormSubmitDescriptorInput): PhiFormSubmitDescriptor;
-export declare function resolvePhiFormSubmitTarget(descriptor: PhiFormSubmitDescriptor): PhiFormSubmitTarget;
-export declare function buildPhiFormSubmitDescriptorFromHandlerProvider(formId: string, provider: PhiFormHandlerProviderDescriptor): PhiFormSubmitDescriptor;
+export declare function buildPhiFormSubmitRoute(input: PhiFormSubmitRouteInput): PhiFormSubmitRoute;
+export declare function resolvePhiFormSubmitTarget(descriptor: PhiFormSubmitRoute): PhiFormSubmitTarget;
+export declare function buildPhiFormSubmitRouteFromHandlerProvider(formId: string, provider: PhiFormHandlerProviderDescriptor): PhiFormSubmitRoute;
 export declare function buildPhiFormPreviewDescriptor(input: Pick<PhiFormPreviewDescriptor, "formId">): PhiFormPreviewDescriptor;
 export declare function buildPhiFormPreviewDescriptorFromDefinition(definition: PhiFormDefinitionLikeWithPreview): PhiFormPreviewDescriptor | null;
 export {};

package/gateway/form-submit.js

@@ -1,10 +1,5 @@
+import { normalizePhiFormKey } from "../helpers/form-id";
 import "server-only";
-function normalizeFormId(value) {
-    return value.trim().toLowerCase();
-}
-function normalizeSubmitHandlerKey(value) {
-    return value.trim().toLowerCase();
-}
 function normalizeCategory(value) {
     if (value == null) {
         return null;
@@ -42,7 +37,7 @@ function resolveSubmitCategory(submitHandlerKey, explicitCategory) {
     if (category) {
         return category;
     }
-    const normalizedKey = normalizeSubmitHandlerKey(submitHandlerKey);
+    const normalizedKey = normalizePhiFormKey(submitHandlerKey);
     if (normalizedKey.startsWith("auth.")) {
         return "auth";
     }
@@ -106,9 +101,9 @@ function readPreviewHandlerKey(explicitPreviewHandlerKey, config) {
     }
     return readConfigString(config, "previewHandlerKey");
 }
-export function buildPhiFormSubmitDescriptor(input) {
-    const formId = normalizeFormId(input.formId);
-    const submitHandlerKey = normalizeSubmitHandlerKey(input.submitHandlerKey);
+export function buildPhiFormSubmitRoute(input) {
+    const formId = normalizePhiFormKey(input.formId);
+    const submitHandlerKey = normalizePhiFormKey(input.submitHandlerKey);
     const category = resolveSubmitCategory(submitHandlerKey, input.category);
     const endpointKey = resolveEndpointKey(input);
     const upstreamPath = typeof input.upstreamPath === "string" && input.upstreamPath.trim()
@@ -143,8 +138,8 @@ export function resolvePhiFormSubmitTarget(descriptor) {
         routeTarget: `${descriptor.category}:${upstreamPath}`,
     };
 }
-export function buildPhiFormSubmitDescriptorFromHandlerProvider(formId, provider) {
-    return buildPhiFormSubmitDescriptor({
+export function buildPhiFormSubmitRouteFromHandlerProvider(formId, provider) {
+    return buildPhiFormSubmitRoute({
         formId,
         submitHandlerKey: provider.handlerKey,
         category: provider.category,
@@ -158,7 +153,7 @@ export function buildPhiFormSubmitDescriptorFromHandlerProvider(formId, provider
     });
 }
 export function buildPhiFormPreviewDescriptor(input) {
-    return { formId: normalizeFormId(input.formId) };
+    return { formId: normalizePhiFormKey(input.formId) };
 }
 export function buildPhiFormPreviewDescriptorFromDefinition(definition) {
     const previewHandlerKey = readPreviewHandlerKey(definition.previewHandlerKey, undefined);

package/gateway/internal-references.d.ts

@@ -11,12 +11,15 @@ export type PhiResolvedInternalReferences = {
     pages: readonly PhiResolvedPageReference[];
     assets: ReadonlyMap<number, PhiPublicMediaAssetReference>;
 };
+/** One Asset of the public reference projection, as the server writes it; a shape it does not match throws. */
+export declare function readPhiPublicMediaAssetReference(entry: unknown): PhiPublicMediaAssetReference;
 /**
- * Resolves both internal reference kinds in one request.
+ * Resolves both internal reference kinds, together with whatever else asks in the same turn.
  *
- * Pages and Assets share one contract in `REFERENCES.md`, so they share one round trip: a page with a
- * dozen images no longer issues a dozen Asset lookups. The endpoint only ever returns publicly
- * deliverable Site Space Assets, so callers must not re-filter — an absent id is simply not renderable.
+ * Pages and Assets share one contract in `REFERENCES.md`, so they share one round trip -- and so do
+ * the callers of one render (see `pendingBatches`); each still receives only what it asked for. The
+ * endpoint only ever returns publicly deliverable Site Space Assets, so callers must not re-filter -- an
+ * absent id is simply not renderable.
  */
 export declare function resolveSiteInternalReferences(input: {
     apiBaseUrl: string;

package/gateway/internal-references.js

@@ -1,9 +1,11 @@
+import { isPhiRecord } from "../helpers/is-record";
 import "server-only";
 import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
 import { readPhiPageReference } from "../types/references";
 import { throwPhiCmsGatewayError } from "./errors";
+import { peekPhiSiteReadCache, writePhiSiteReadCache } from "./site-read-cache";
 function readResolvedPage(entry) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    if (!isPhiRecord(entry)) {
         throw new Error("Invalid internal Page reference projection.");
     }
     const value = entry;
@@ -18,8 +20,9 @@ function readResolvedPage(entry) {
         targetKind: value.targetKind === "module" ? "module" : "site",
     };
 }
-function readResolvedAsset(entry) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+/** One Asset of the public reference projection, as the server writes it; a shape it does not match throws. */
+export function readPhiPublicMediaAssetReference(entry) {
+    if (!isPhiRecord(entry)) {
         throw new Error("Invalid internal Asset reference projection.");
     }
     const value = entry;
@@ -30,19 +33,22 @@ function readResolvedAsset(entry) {
     }
     return value;
 }
-/**
- * Resolves both internal reference kinds in one request.
+/** What the server takes per list in one request (`MAX_REFERENCES_PER_REQUEST`). */
+const PHI_REFERENCES_PER_REQUEST = 256;
+/*
+ * The batches waiting for the end of the current turn, by server, Site and Area.
  *
- * Pages and Assets share one contract in `REFERENCES.md`, so they share one round trip: a page with a
- * dozen images no longer issues a dozen Asset lookups. The endpoint only ever returns publicly
- * deliverable Site Space Assets, so callers must not re-filter — an absent id is simply not renderable.
+ * A render resolves references from many places at once -- every Image, Card and Video poster, the
+ * Markdown and HTML Widgets, the background, the fonts -- and each asked on its own: one request to the
+ * server per Widget. Calls that arrive in the same turn now share one request. The answer depends on
+ * the Site and the Area alone, never on who is looking (the endpoint takes the internal token and no
+ * session), so two requests that happen to resolve at the same moment may share a batch as well.
  */
-export async function resolveSiteInternalReferences(input) {
-    const references = [...new Set(input.references ?? [])];
-    const assetIds = [...new Set((input.assetIds ?? []).filter((id) => Number.isSafeInteger(id) && id > 0))];
-    if (references.length === 0 && assetIds.length === 0) {
-        return { pages: [], assets: new Map() };
-    }
+const pendingBatches = new Map();
+function batchKey(input) {
+    return JSON.stringify([input.apiBaseUrl, input.internalToken, input.siteKey, input.area ?? ""]);
+}
+async function requestSiteInternalReferences(input, references, assetIds) {
     const response = await fetch(buildApiUrl(input.apiBaseUrl, "/api/v1/site/references"), {
         method: "POST",
         headers: buildApiHeaders({
@@ -63,9 +69,145 @@ export async function resolveSiteInternalReferences(input) {
     if (!Array.isArray(payload?.resolved) || !Array.isArray(payload?.assets)) {
         throw new Error("Missing internal reference projection.");
     }
-    const assets = payload.assets.map(readResolvedAsset);
+    const assets = payload.assets.map(readPhiPublicMediaAssetReference);
     return {
         pages: payload.resolved.map(readResolvedPage),
         assets: new Map(assets.map((asset) => [asset.id, asset])),
     };
 }
+function openBatch(key, input) {
+    const batch = {
+        ...input,
+        references: new Set(),
+        assetIds: new Set(),
+    };
+    batch.result = new Promise((resolve, reject) => {
+        // The end of this turn: whatever else asks before then rides along.
+        setImmediate(() => {
+            if (pendingBatches.get(key) === batch)
+                pendingBatches.delete(key);
+            requestSiteInternalReferences(batch, [...batch.references], [...batch.assetIds]).then(resolve, reject);
+        });
+    });
+    pendingBatches.set(key, batch);
+    return batch;
+}
+/**
+ * Resolves both internal reference kinds, together with whatever else asks in the same turn.
+ *
+ * Pages and Assets share one contract in `REFERENCES.md`, so they share one round trip -- and so do
+ * the callers of one render (see `pendingBatches`); each still receives only what it asked for. The
+ * endpoint only ever returns publicly deliverable Site Space Assets, so callers must not re-filter -- an
+ * absent id is simply not renderable.
+ */
+export async function resolveSiteInternalReferences(input) {
+    const references = [...new Set(input.references ?? [])];
+    const assetIds = [...new Set((input.assetIds ?? []).filter((id) => Number.isSafeInteger(id) && id > 0))];
+    if (references.length === 0 && assetIds.length === 0) {
+        return { pages: [], assets: new Map() };
+    }
+    const request = {
+        apiBaseUrl: input.apiBaseUrl,
+        internalToken: input.internalToken,
+        siteKey: input.siteKey,
+        ...(input.area ? { area: input.area } : {}),
+    };
+    if (!keepsReferences()) {
+        return requestThroughBatch(request, references, assetIds);
+    }
+    /*
+     * Kept per reference rather than per answer: which references share a request depends on what else
+     * happened to resolve in the same turn, so an answer as a whole would almost never be asked for again.
+     * An Asset that did not come back is kept as absent too -- it is not renderable, and asking again on
+     * every view would cost exactly what this saves.
+     */
+    const pages = new Map();
+    const assets = new Map();
+    const missingReferences = [];
+    const missingAssetIds = [];
+    await Promise.all([
+        ...references.map(async (reference) => {
+            const cached = peekPhiSiteReadCache(pageCacheKey(request, reference));
+            if (cached)
+                pages.set(reference, await cached);
+            else
+                missingReferences.push(reference);
+        }),
+        ...assetIds.map(async (id) => {
+            const cached = peekPhiSiteReadCache(assetCacheKey(request, id));
+            if (!cached) {
+                missingAssetIds.push(id);
+                return;
+            }
+            const asset = await cached;
+            if (asset)
+                assets.set(id, asset);
+        }),
+    ]);
+    if (missingReferences.length > 0 || missingAssetIds.length > 0) {
+        const fetched = await requestThroughBatch(request, missingReferences, missingAssetIds);
+        for (const entry of fetched.pages) {
+            pages.set(entry.reference, entry);
+            writePhiSiteReadCache(pageCacheKey(request, entry.reference), entry);
+        }
+        for (const id of missingAssetIds) {
+            const asset = fetched.assets.get(id) ?? null;
+            if (asset)
+                assets.set(id, asset);
+            writePhiSiteReadCache(assetCacheKey(request, id), asset);
+        }
+    }
+    return {
+        pages: references.flatMap((reference) => {
+            const entry = pages.get(reference);
+            return entry ? [entry] : [];
+        }),
+        assets: new Map(assetIds.flatMap((id) => {
+            const asset = assets.get(id);
+            return asset ? [[id, asset]] : [];
+        })),
+    };
+}
+/*
+ * Outside development only, as every read this cache holds (gateway/CACHES.md): `next dev` is where a
+ * change has to show on the next reload, and nothing there is under load.
+ */
+function keepsReferences() {
+    return process.env.NODE_ENV !== "development";
+}
+// A Page reference resolves within its Area; an Asset is Site scoped and carries none.
+function pageCacheKey(request, reference) {
+    return `references:${request.siteKey.trim().toLowerCase()}:page:${request.area ?? ""}:${reference}`;
+}
+function assetCacheKey(request, id) {
+    return `references:${request.siteKey.trim().toLowerCase()}:asset:${id}`;
+}
+/** Joins the batch of the current turn and returns what this caller asked for. */
+async function requestThroughBatch(request, references, assetIds) {
+    if (references.length === 0 && assetIds.length === 0) {
+        return { pages: [], assets: new Map() };
+    }
+    const key = batchKey(request);
+    let batch = pendingBatches.get(key) ?? openBatch(key, request);
+    const fits = (candidate) => new Set([...candidate.references, ...references]).size <= PHI_REFERENCES_PER_REQUEST &&
+        new Set([...candidate.assetIds, ...assetIds]).size <= PHI_REFERENCES_PER_REQUEST;
+    if (!fits(batch)) {
+        // A full batch leaves on its own; this caller starts the next one.
+        pendingBatches.delete(key);
+        batch = openBatch(key, request);
+    }
+    for (const reference of references)
+        batch.references.add(reference);
+    for (const assetId of assetIds)
+        batch.assetIds.add(assetId);
+    // Each caller gets what it asked for and nothing a neighbour in the batch did.
+    const projection = await batch.result;
+    const askedReferences = new Set(references);
+    return {
+        pages: projection.pages.filter((entry) => askedReferences.has(entry.reference)),
+        assets: new Map(assetIds.flatMap((id) => {
+            const asset = projection.assets.get(id);
+            return asset ? [[id, asset]] : [];
+        })),
+    };
+}

package/gateway/media-folder-images.d.ts

@@ -0,0 +1,19 @@
+import "server-only";
+import type { PhiPublicMediaAssetReference } from "../types/media";
+export type PhiMediaFolderImagesSort = "name_asc" | "created_at_desc";
+/**
+ * The public pictures of a Media Folder (`/api/v1/site/media/folder-images`), in the projection the
+ * reference resolver answers for named Assets, so whoever draws one draws the other.
+ *
+ * Read with the internal token: a public render has no Media session, and the library's own listing
+ * wants one. The server decides what is public; a Folder outside the Site Space answers empty.
+ */
+export declare function listPhiPublicMediaFolderImages(input: {
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+    folderId: number;
+    subfolders: boolean;
+    sort: PhiMediaFolderImagesSort;
+    limit: number;
+}): Promise<PhiPublicMediaAssetReference[]>;

package/gateway/media-folder-images.js

@@ -0,0 +1,37 @@
+import "server-only";
+import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
+import { throwPhiCmsGatewayError } from "./errors";
+import { readPhiPublicMediaAssetReference } from "./internal-references";
+/**
+ * The public pictures of a Media Folder (`/api/v1/site/media/folder-images`), in the projection the
+ * reference resolver answers for named Assets, so whoever draws one draws the other.
+ *
+ * Read with the internal token: a public render has no Media session, and the library's own listing
+ * wants one. The server decides what is public; a Folder outside the Site Space answers empty.
+ */
+export async function listPhiPublicMediaFolderImages(input) {
+    const query = new URLSearchParams({
+        folderId: String(input.folderId),
+        subfolders: input.subfolders ? "1" : "0",
+        sort: input.sort,
+        limit: String(input.limit),
+    });
+    const response = await fetch(buildApiUrl(input.apiBaseUrl, `/api/v1/site/media/folder-images?${query}`), {
+        headers: buildApiHeaders({
+            token: input.internalToken,
+            siteKey: input.siteKey,
+            includeToken: true,
+            includeSiteKey: true,
+            gateway: true,
+        }),
+        cache: "no-store",
+    });
+    if (!response.ok) {
+        throwPhiCmsGatewayError(`Failed to read the media folder's pictures (${response.status}).`, response.status);
+    }
+    const payload = (await response.json().catch(() => null));
+    if (!Array.isArray(payload?.assets)) {
+        throw new Error("Missing media folder picture projection.");
+    }
+    return payload.assets.map(readPhiPublicMediaAssetReference);
+}

package/gateway/module-diagnostics-route.js

@@ -1,25 +1,20 @@
+import { jsonResponse } from "./route-handler-helpers";
 import "server-only";
 import { getPhiCapabilitySnapshot } from "./server-capabilities";
 import { loadPhiSiteAreaBridges } from "./site-area-bridges";
 import { resolvePhiRuntimeModuleServerBinding } from "../plugins/runtime-modules/server-capabilities";
 import { PHIS_TOKEN_HEADER } from "../constants/http-headers";
-function json(body, status = 200) {
-    return new Response(JSON.stringify(body), {
-        status,
-        headers: { "content-type": "application/json" },
-    });
-}
 export function buildPhiSiteModuleDiagnosticsRouteHandler({ loadAreaBridge, }) {
     return async function GET(request) {
         const bridges = await loadPhiSiteAreaBridges(loadAreaBridge);
         const anyRuntime = bridges.find(([, bridge]) => bridge.runtime)?.[1].runtime;
         if (!anyRuntime) {
-            return json({ error: "no_site_runtime" }, 503);
+            return jsonResponse({ error: "no_site_runtime" }, 503);
         }
         const { apiBaseUrl, internalToken, siteKey } = anyRuntime;
         // An operator's check, not a public one: it names which Modules a Site lost and why.
         if (!internalToken || request.headers.get(PHIS_TOKEN_HEADER)?.trim() !== internalToken) {
-            return json({ error: "unauthorized" }, 401);
+            return jsonResponse({ error: "unauthorized" }, 401);
         }
         const snapshot = await getPhiCapabilitySnapshot({ apiBaseUrl, internalToken, siteKey })
             .catch(() => null);
@@ -56,6 +51,6 @@ export function buildPhiSiteModuleDiagnosticsRouteHandler({ loadAreaBridge, }) {
             offeredCapabilities,
             unavailable,
         };
-        return json(report, report.ok ? 200 : 409);
+        return jsonResponse(report, report.ok ? 200 : 409);
     };
 }