@phis/ui 0.1.0

package/controls.js

@@ -0,0 +1,51 @@
+export { PhiTextControl } from "./components/controls/phi-text-control";
+export { PhiLabeledControl } from "./components/controls/phi-labeled-control";
+export { PHI_CONTROL_SIZES, PHI_FEEDBACK_LEVELS, readPhiControlSize, } from "./types/control";
+export { PhiNumberControl } from "./components/controls/phi-number-control";
+export { PhiPopoverControl } from "./components/controls/phi-popover-control";
+export { PHI_PICKER_PLACEMENTS } from "./components/controls/phi-picker-control-contract";
+export { PhiPaginationControl } from "./components/controls/phi-pagination-control";
+export { PhiTabsControl } from "./components/controls/phi-tabs-control";
+export { PhiDropdownControl, PhiPillDropdownControl } from "./components/controls/phi-dropdown-control";
+export { PhiMenuControl } from "./components/controls/phi-menu-control";
+export { PhiMediaPickerControl } from "./components/controls/phi-media-picker-control";
+export { PHI_MEDIA_PICKER_COLUMN_WIDTH_STEP, PHI_MEDIA_PICKER_DEFAULT_COLUMN_WIDTH, PHI_MEDIA_PICKER_MAX_COLUMN_WIDTH, PHI_MEDIA_PICKER_MIN_COLUMN_WIDTH, normalizePhiMediaPickerMinColumnWidth, } from "./components/controls/phi-media-picker-control-contract";
+export { PhiCollectionLayoutControl } from "./components/controls/phi-collection-layout-control";
+export { PhiCollectionHeaderControl } from "./components/controls/phi-collection-header-control";
+export { PhiCollectionViewControl } from "./components/controls/phi-collection-view-control";
+export { PhiMediaAssetCollectionSkeletonControl, PhiMediaAssetTileControl, } from "./components/controls/phi-media-asset-tile-control";
+export { PhiMaskPickerControl } from "./components/controls/phi-mask-picker-control";
+export { PhiColorControl } from "./components/controls/phi-color-control";
+export { PhiBackgroundControl } from "./components/controls/phi-background-control";
+export { PhiBorderControl } from "./components/controls/phi-border-control";
+export { PhiPaddingControl } from "./components/controls/phi-padding-control";
+export { PhiShadowControl } from "./components/controls/phi-shadow-control";
+export { PhiGeometryControl } from "./components/controls/phi-geometry-control";
+export { PhiSliderControl } from "./components/controls/phi-slider-control";
+export { PhiRateControl } from "./components/controls/phi-rate-control";
+export { PHI_RATE_DEFAULT_COUNT, normalizePhiRateCount, normalizePhiRateValue, } from "./components/controls/phi-rate-control-contract";
+export { PhiModalControl } from "./components/controls/phi-modal-control";
+export { PhiDrawerControl } from "./components/controls/phi-drawer-control";
+export { PHI_SLIDER_TOOLTIP_MODES } from "./components/controls/phi-slider-control-contract";
+export { PhiSelectControl } from "./components/controls/phi-select-control";
+export { PhiMultiSelectControl } from "./components/controls/phi-multi-select-control";
+export { PhiSegmentedControl } from "./components/controls/phi-segmented-control";
+export { PhiDragHandleControl } from "./components/controls/phi-drag-handle-control";
+export { PhiOtpControl } from "./components/controls/phi-otp-control";
+export { PhiSwitchControl } from "./components/controls/phi-switch-control";
+export { PhiCheckboxControl } from "./components/controls/phi-checkbox-control";
+export { PhiCheckboxGroupControl } from "./components/controls/phi-checkbox-group-control";
+export { PhiIconPickerControl } from "./components/controls/phi-icon-picker-control";
+export { PHI_ICON_PICKER_CONTROL_DEFAULT_LABELS, } from "./components/controls/phi-icon-picker-labels";
+export { PhiRadioGroupControl } from "./components/controls/phi-radio-group-control";
+export { PhiButtonControl } from "./components/controls/phi-button-control";
+export { PhiTagControl } from "./components/controls/phi-tag-control";
+export { PhiFormControl } from "./components/controls/phi-form-control";
+export { PhiAlertControl } from "./components/controls/phi-alert-control";
+export { PHI_CONFIRM_PLACEMENTS, PhiConfirmControl, } from "./components/controls/phi-confirm-control";
+export { PhiToolbarControl } from "./components/controls/phi-toolbar-control";
+export { PhiTableControl, readPhiTableControlValue } from "./components/controls/phi-table-control";
+export { PhiTreeControl, PhiTreeActionButton } from "./components/controls/phi-tree-control";
+export { PhiCascaderControl, normalizePhiCascaderValue, } from "./components/controls/phi-cascader-control";
+export { PhiDimensionControl } from "./components/controls/phi-dimension-control";
+export { PhiLengthControl } from "./components/controls/phi-length-control";

package/forms.d.ts

@@ -0,0 +1,40 @@
+export type { PhiFormAvailabilityProps, PhiFormGuardProps, PhiSubmitFormProps, } from "./components/forms/contracts";
+export type * from "./types/form-descriptor";
+export type * from "./types/responsive";
+export type * from "./types/runtime-condition";
+export * from "./types/spacing";
+export * from "./types/form-id";
+export type { PhiFormRenderContext, PhiFormRenderOptions, PhiFormLabelSetLoader, } from "./components/forms/form-resolution";
+export { PHI_FORM_DESCRIPTOR_SCHEMA_VERSION } from "./types/form-descriptor";
+export { definePhiRuntimeModuleForm, } from "./components/forms/form-registry";
+export { buildPhiFormRenderTarget, resolvePhiFormDefinition, resolvePhiFormLabels, } from "./components/forms/form-resolution";
+export { PHI_FORM_CONTROLLER_KEY, PHI_FORM_SIGNAL_CHANNELS, PHI_RUNTIME_FORM_CONTROLLER_EMITS, PHI_RUNTIME_FORM_CONTROLLER_LISTENS, createPhiRuntimeFormControllerAddress, } from "./components/forms/runtime-form-controller-signals";
+export { PHI_FORM_BUILDER_CONTROLLER_INSTANCE_KEY, PHI_FORM_BUILDER_CONTROLLER_KEY, PHI_FORM_BUILDER_CONTROLLER_PLUGIN_KEY, PHI_FORM_BUILDER_CONTROLLER_TYPE, createPhiFormBuilderControllerAddress, } from "./components/forms/form-builder-controller-address";
+export { PHI_FORM_BUILDER_CONTROLLER_DEFINITION, parsePhiFormBuilderControllerConfig, } from "./components/forms/form-builder-controller-definition";
+export { PHI_AUTH_FORM_FIELD_PROVIDER_KEYS, PHI_AUTH_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS, PHI_FORM_FIELD_PROVIDER_KEYS, PHI_FORM_HANDLER_PROVIDER_KEYS, PHI_FORM_VALIDATION_PROVIDER_KEYS, PHI_AUTH_FORM_HANDLER_PROVIDER_DESCRIPTORS, PHI_CORE_FORM_PROVIDER_DESCRIPTORS, PHI_PUBLIC_FORM_HANDLER_PROVIDER_DESCRIPTORS, PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS, PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS, createPhiSharedFormProviderKey, } from "./components/forms/form-provider-contract";
+export { PHI_FORM_DEFAULT_LAYOUT, PHI_FORM_GRID_LAST_LINE, PHI_FORM_RESPONSIVE_MIN_WIDTH, PHI_FORM_RESPONSIVE_MODES, assertPhiFormLabelSetKey, createPhiFormLabelText, createPhiFormLiteralText, resolvePhiFormFieldExtent, resolvePhiFormFieldRanges, phiFormGridColumn, resolvePhiFormGridPlacement, phiFormGridRangesOverlap, resolvePhiFormLayout, resolvePhiFormResponsiveGridRange, resolvePhiFormText, parsePhiFormDescriptor, } from "./components/forms/form-descriptor-contract";
+export { createPhiFormProviderRegistry, extendPhiFormProviderRegistry, PhiFormProviderRegistryProvider, usePhiFormProviderRegistry, } from "./components/forms/form-provider-registry";
+export { PhiFormControl } from "./components/controls/phi-form-control";
+export { PHI_CONFIRM_FORM_DESCRIPTOR, PHI_CONTACT_FORM_DESCRIPTOR, PHI_FORM_LABEL_SET_KEYS, PHI_LOGIN_FORM_DESCRIPTOR, PHI_REGISTRATION_FORM_DESCRIPTOR, PHI_RESET_PASSWORD_CONFIRM_FORM_DESCRIPTOR, PHI_RESET_PASSWORD_FORM_DESCRIPTOR, } from "./components/forms/shared-form-descriptors";
+export { PHI_SHARED_FORM_IDS } from "./components/forms/shared-form-ids";
+export { PHI_RUNTIME_FORM_CONTROLLER_DEFINITION, parsePhiRuntimeFormControllerConfig, } from "./components/forms/runtime-form-controller-definition";
+export { PhiRuntimeFormControllerMount, } from "./components/forms/runtime-form-controller-mount";
+export { usePhiRuntimeFormClient, } from "./components/forms/runtime-form-client";
+export { fetchFormRegistry, getResolvedFormDefinition, listResolvedFormDefinitions, } from "./gateway/form-registry";
+export { buildPhiFormSubmitDescriptor, buildPhiFormPreviewDescriptor, buildPhiFormPreviewDescriptorFromDefinition, resolvePhiFormSubmitTarget, } from "./gateway/form-submit";
+export { buildPhiDataSourceUrl, normalizePhiDataSourceCacheMode, normalizePhiDataSourceTags, } from "./gateway/data-source";
+export { buildPhiMutationUrl, normalizePhiMutationMethod, normalizePhiMutationResponseShape, normalizePhiMutationTransport, } from "./gateway/mutation";
+export type { PhiRuntimeModuleFormDefinition } from "./components/forms/form-registry";
+export type { PhiFormDefinitionLike, PhiFormDefinitionSource, PhiFormRenderTarget, PhiResolvedFormDefinition, } from "./components/forms/form-resolution";
+export type { PhiRuntimeFormControllerConfig, } from "./components/forms/runtime-form-controller-definition";
+export type { PhiFormBuilderControllerConfig, } from "./components/forms/form-builder-controller-definition";
+export type { PhiFormFieldProviderProps, PhiFormFieldTypeProvider, PhiFormProviderRegistry, PhiFormValidationContext, PhiFormValidationProvider, } from "./components/forms/form-provider-registry";
+export type { PhiResolvedFormLayout, PhiResolvedFormResponsiveGridRange, } from "./components/forms/form-descriptor-contract";
+export type { PhiFormControlProps, } from "./components/controls/phi-form-control";
+export type { PhiRuntimeFormSubmitSignalValue, PhiRuntimeFormResultSignalValue, PhiRuntimeFormErrorSignalValue, PhiRuntimeFormControllerMountProps, } from "./components/forms/runtime-form-controller-mount";
+export type { PhiRuntimeFormClient, PhiRuntimeFormSubmitOptions, PhiRuntimeFormSubmitResult, } from "./components/forms/runtime-form-client";
+export type { PhiRuntimeFormFieldSignalValue, PhiRuntimeFormTouchedSignalValue, PhiRuntimeFormValiditySignalValue, PhiRuntimeFormValuesSignalValue, } from "./components/forms/runtime-form-state";
+export type { PhiFormRegistryRecord, GetResolvedFormDefinitionOptions, ListResolvedFormDefinitionsOptions, } from "./gateway/form-registry";
+export type { PhiFormSubmitCategory, PhiFormPreviewDescriptor, PhiFormSubmitDescriptor, PhiFormSubmitMethod, PhiFormSubmitTarget, PhiFormSubmitTransport, } from "./gateway/form-submit";
+export type { PhiDataLoadOptions, PhiDataQuery, PhiDataQueryValue, PhiDataResult, PhiDataSource, PhiDataSourceApiTransport, PhiDataSourceCache, PhiDataSourceCacheMode, PhiDataSourceRequestShape, PhiDataSourceResponseShape, } from "./gateway/data-source";
+export type { PhiMutation, PhiMutationFetchContext, PhiMutationLoadOptions, PhiMutationMethod, PhiMutationQuery, PhiMutationQueryValue, PhiMutationRequestShape, PhiMutationResponseShape, PhiMutationTransport, } from "./gateway/mutation";

package/forms.js

@@ -0,0 +1,21 @@
+export * from "./types/spacing";
+export * from "./types/form-id";
+export { PHI_FORM_DESCRIPTOR_SCHEMA_VERSION } from "./types/form-descriptor";
+export { definePhiRuntimeModuleForm, } from "./components/forms/form-registry";
+export { buildPhiFormRenderTarget, resolvePhiFormDefinition, resolvePhiFormLabels, } from "./components/forms/form-resolution";
+export { PHI_FORM_CONTROLLER_KEY, PHI_FORM_SIGNAL_CHANNELS, PHI_RUNTIME_FORM_CONTROLLER_EMITS, PHI_RUNTIME_FORM_CONTROLLER_LISTENS, createPhiRuntimeFormControllerAddress, } from "./components/forms/runtime-form-controller-signals";
+export { PHI_FORM_BUILDER_CONTROLLER_INSTANCE_KEY, PHI_FORM_BUILDER_CONTROLLER_KEY, PHI_FORM_BUILDER_CONTROLLER_PLUGIN_KEY, PHI_FORM_BUILDER_CONTROLLER_TYPE, createPhiFormBuilderControllerAddress, } from "./components/forms/form-builder-controller-address";
+export { PHI_FORM_BUILDER_CONTROLLER_DEFINITION, parsePhiFormBuilderControllerConfig, } from "./components/forms/form-builder-controller-definition";
+export { PHI_AUTH_FORM_FIELD_PROVIDER_KEYS, PHI_AUTH_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS, PHI_FORM_FIELD_PROVIDER_KEYS, PHI_FORM_HANDLER_PROVIDER_KEYS, PHI_FORM_VALIDATION_PROVIDER_KEYS, PHI_AUTH_FORM_HANDLER_PROVIDER_DESCRIPTORS, PHI_CORE_FORM_PROVIDER_DESCRIPTORS, PHI_PUBLIC_FORM_HANDLER_PROVIDER_DESCRIPTORS, PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS, PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS, createPhiSharedFormProviderKey, } from "./components/forms/form-provider-contract";
+export { PHI_FORM_DEFAULT_LAYOUT, PHI_FORM_GRID_LAST_LINE, PHI_FORM_RESPONSIVE_MIN_WIDTH, PHI_FORM_RESPONSIVE_MODES, assertPhiFormLabelSetKey, createPhiFormLabelText, createPhiFormLiteralText, resolvePhiFormFieldExtent, resolvePhiFormFieldRanges, phiFormGridColumn, resolvePhiFormGridPlacement, phiFormGridRangesOverlap, resolvePhiFormLayout, resolvePhiFormResponsiveGridRange, resolvePhiFormText, parsePhiFormDescriptor, } from "./components/forms/form-descriptor-contract";
+export { createPhiFormProviderRegistry, extendPhiFormProviderRegistry, PhiFormProviderRegistryProvider, usePhiFormProviderRegistry, } from "./components/forms/form-provider-registry";
+export { PhiFormControl } from "./components/controls/phi-form-control";
+export { PHI_CONFIRM_FORM_DESCRIPTOR, PHI_CONTACT_FORM_DESCRIPTOR, PHI_FORM_LABEL_SET_KEYS, PHI_LOGIN_FORM_DESCRIPTOR, PHI_REGISTRATION_FORM_DESCRIPTOR, PHI_RESET_PASSWORD_CONFIRM_FORM_DESCRIPTOR, PHI_RESET_PASSWORD_FORM_DESCRIPTOR, } from "./components/forms/shared-form-descriptors";
+export { PHI_SHARED_FORM_IDS } from "./components/forms/shared-form-ids";
+export { PHI_RUNTIME_FORM_CONTROLLER_DEFINITION, parsePhiRuntimeFormControllerConfig, } from "./components/forms/runtime-form-controller-definition";
+export { PhiRuntimeFormControllerMount, } from "./components/forms/runtime-form-controller-mount";
+export { usePhiRuntimeFormClient, } from "./components/forms/runtime-form-client";
+export { fetchFormRegistry, getResolvedFormDefinition, listResolvedFormDefinitions, } from "./gateway/form-registry";
+export { buildPhiFormSubmitDescriptor, buildPhiFormPreviewDescriptor, buildPhiFormPreviewDescriptorFromDefinition, resolvePhiFormSubmitTarget, } from "./gateway/form-submit";
+export { buildPhiDataSourceUrl, normalizePhiDataSourceCacheMode, normalizePhiDataSourceTags, } from "./gateway/data-source";
+export { buildPhiMutationUrl, normalizePhiMutationMethod, normalizePhiMutationResponseShape, normalizePhiMutationTransport, } from "./gateway/mutation";

package/gateway/addon-proxy.d.ts

@@ -0,0 +1,24 @@
+import { PhiNextProxy } from "../net/phi-next-proxy";
+export type BuildPhiAddonProxyHandlersOptions = {
+    upstreamBaseUrl: string;
+    timeoutMs: number;
+    buildHeaders: Parameters<typeof PhiNextProxy>[0]["buildHeaders"];
+    logLabel?: string;
+    missingBaseUrlMessage?: string;
+};
+/**
+ * The door a Site's own surfaces reach an Add-on's routes through.
+ *
+ * An Add-on's API lives on Core at `/api/v1/addons/*`, and until now nothing on a Site could reach it:
+ * a Site proxies `/api/site`, `/api/auth` and its Builder API, so a Module half calling its own Add-on
+ * half arrived at the Site's 404 page. The two halves ship in one package and are the ordinary way an
+ * Add-on gets a surface, so the door belongs in the scaffold rather than in each Site.
+ *
+ * Short on the outside and versioned upstream, as `/api/auth` already is: the version belongs to Core's
+ * contract with the Add-on and is not a thing a Site's URLs should have to carry.
+ *
+ * It forwards and decides nothing. Which authentication a route requires is declared in the Add-on's
+ * manifest and enforced by Core before dispatch, so a proxy that judged anything here would be a second
+ * opinion about a question that already has an answer.
+ */
+export declare function buildPhiAddonProxyHandlers({ upstreamBaseUrl, timeoutMs, buildHeaders, logLabel, missingBaseUrlMessage, }: BuildPhiAddonProxyHandlersOptions): import("../net").PhiNextProxyHandlers;

package/gateway/addon-proxy.js

@@ -0,0 +1,27 @@
+import { PhiNextProxy } from "../net/phi-next-proxy";
+/**
+ * The door a Site's own surfaces reach an Add-on's routes through.
+ *
+ * An Add-on's API lives on Core at `/api/v1/addons/*`, and until now nothing on a Site could reach it:
+ * a Site proxies `/api/site`, `/api/auth` and its Builder API, so a Module half calling its own Add-on
+ * half arrived at the Site's 404 page. The two halves ship in one package and are the ordinary way an
+ * Add-on gets a surface, so the door belongs in the scaffold rather than in each Site.
+ *
+ * Short on the outside and versioned upstream, as `/api/auth` already is: the version belongs to Core's
+ * contract with the Add-on and is not a thing a Site's URLs should have to carry.
+ *
+ * It forwards and decides nothing. Which authentication a route requires is declared in the Add-on's
+ * manifest and enforced by Core before dispatch, so a proxy that judged anything here would be a second
+ * opinion about a question that already has an answer.
+ */
+export function buildPhiAddonProxyHandlers({ upstreamBaseUrl, timeoutMs, buildHeaders, logLabel = "[phis-ui][/api/addons proxy]", missingBaseUrlMessage = "Missing apiBaseUrl for /api/addons proxy.", }) {
+    return PhiNextProxy({
+        upstreamBaseUrl,
+        upstreamPrefix: "/api/v1/addons",
+        timeoutMs,
+        logLabel,
+        missingBaseUrlMessage,
+        buildHeaders,
+        buildFetchInit: () => ({ cache: "no-store" }),
+    });
+}

package/gateway/auth-proxy.d.ts

@@ -0,0 +1,9 @@
+import { PhiNextProxy } from "../net/phi-next-proxy";
+export type BuildPhiAuthProxyHandlersOptions = {
+    upstreamBaseUrl: string;
+    timeoutMs: number;
+    buildHeaders: Parameters<typeof PhiNextProxy>[0]["buildHeaders"];
+    logLabel?: string;
+    missingBaseUrlMessage?: string;
+};
+export declare function buildPhiAuthProxyHandlers({ upstreamBaseUrl, timeoutMs, buildHeaders, logLabel, missingBaseUrlMessage, }: BuildPhiAuthProxyHandlersOptions): import("../net").PhiNextProxyHandlers;

package/gateway/auth-proxy.js

@@ -0,0 +1,12 @@
+import { PhiNextProxy } from "../net/phi-next-proxy";
+export function buildPhiAuthProxyHandlers({ upstreamBaseUrl, timeoutMs, buildHeaders, logLabel = "[phis-ui][/api/auth proxy]", missingBaseUrlMessage = "Missing apiBaseUrl for /api/auth proxy.", }) {
+    return PhiNextProxy({
+        upstreamBaseUrl,
+        upstreamPrefix: "/api/v1/auth",
+        timeoutMs,
+        logLabel,
+        missingBaseUrlMessage,
+        buildHeaders,
+        buildFetchInit: () => ({ cache: "no-store" }),
+    });
+}

package/gateway/auth-public-manifest.d.ts

@@ -0,0 +1,27 @@
+import "server-only";
+import type { PhiAuthWorkflow, PhiPublicAuthManifest } from "../types/auth-manifest";
+export type FetchPhiPublicAuthOptions = {
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+};
+/**
+ * Which sign-in methods the Site offers, read while the Login page is being rendered.
+ *
+ * The widget used to ask for this itself, after hydration, and drew a skeleton until the answer came
+ * back. The endpoint answers in milliseconds, so almost all of that wait was the page becoming
+ * interactive first -- around three seconds in development, and a blank card either way. Nothing here
+ * depends on the viewer, so the server already knows it: rendered with the page, the form is in the
+ * first paint.
+ */
+export declare function fetchPhiPublicAuthManifest(options: FetchPhiPublicAuthOptions): Promise<PhiPublicAuthManifest>;
+/**
+ * The authentication already in progress for this request, or null when there is none.
+ *
+ * Needs the viewer's cookies, because an unfinished authentication is held in their Session. A visitor
+ * without one is the ordinary case and answers 401 -- which the widget used to provoke on every Login
+ * page view, two red lines in the console for a question whose answer was "nobody is signed in".
+ */
+export declare function fetchPhiAuthWorkflow(options: FetchPhiPublicAuthOptions & {
+    cookieHeader?: string;
+}): Promise<PhiAuthWorkflow | null>;

package/gateway/auth-public-manifest.js

@@ -0,0 +1,81 @@
+import "server-only";
+import { PHIS_SITE_KEY_HEADER } from "../constants/http-headers";
+function buildHeaders(options, userAgent, cookieHeader) {
+    const headers = {
+        Accept: "application/json",
+        Authorization: `Bearer ${options.internalToken}`,
+        [PHIS_SITE_KEY_HEADER]: options.siteKey,
+        "user-agent": userAgent,
+    };
+    if (cookieHeader?.trim()) {
+        headers.cookie = cookieHeader.trim();
+    }
+    return headers;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readManifest(value) {
+    return isRecord(value) && value.version === 1 && Array.isArray(value.methods)
+        ? value
+        : null;
+}
+/**
+ * Which sign-in methods the Site offers, read while the Login page is being rendered.
+ *
+ * The widget used to ask for this itself, after hydration, and drew a skeleton until the answer came
+ * back. The endpoint answers in milliseconds, so almost all of that wait was the page becoming
+ * interactive first -- around three seconds in development, and a blank card either way. Nothing here
+ * depends on the viewer, so the server already knows it: rendered with the page, the form is in the
+ * first paint.
+ */
+export async function fetchPhiPublicAuthManifest(options) {
+    if (!options.apiBaseUrl.trim()) {
+        throw new Error("Missing apiBaseUrl for fetchPhiPublicAuthManifest.");
+    }
+    if (!options.siteKey.trim()) {
+        throw new Error("Missing siteKey for fetchPhiPublicAuthManifest.");
+    }
+    const response = await fetch(`${options.apiBaseUrl}/api/v1/auth/manifest`, {
+        method: "GET",
+        headers: buildHeaders(options, "phis-ui-auth-manifest/1.0"),
+        cache: "no-store",
+    });
+    if (!response.ok) {
+        throw new Error(`Auth manifest fetch failed (${response.status}).`);
+    }
+    const manifest = readManifest(await response.json().catch(() => null));
+    if (!manifest) {
+        throw new Error("Missing auth manifest payload.");
+    }
+    return manifest;
+}
+/**
+ * The authentication already in progress for this request, or null when there is none.
+ *
+ * Needs the viewer's cookies, because an unfinished authentication is held in their Session. A visitor
+ * without one is the ordinary case and answers 401 -- which the widget used to provoke on every Login
+ * page view, two red lines in the console for a question whose answer was "nobody is signed in".
+ */
+export async function fetchPhiAuthWorkflow(options) {
+    if (!options.apiBaseUrl.trim() || !options.siteKey.trim() || !options.cookieHeader?.trim()) {
+        return null;
+    }
+    const response = await fetch(`${options.apiBaseUrl}/api/v1/auth/workflow`, {
+        method: "GET",
+        headers: buildHeaders(options, "phis-ui-auth-workflow/1.0", options.cookieHeader),
+        cache: "no-store",
+    });
+    // 401 is the answer for a visitor who is not mid-authentication, which is most of them.
+    if (response.status === 401) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Auth workflow fetch failed (${response.status}).`);
+    }
+    const payload = await response.json().catch(() => null);
+    const workflow = isRecord(payload) && isRecord(payload.workflow)
+        ? payload.workflow
+        : null;
+    return workflow && workflow.state !== "complete" ? workflow : null;
+}

package/gateway/data-source-fetch.d.ts

@@ -0,0 +1,12 @@
+import "server-only";
+import { type PhiDataSource, type PhiDataLoadOptions } from "./data-source";
+export type PhiDataSourceFetchContext = {
+    apiBaseUrl: string;
+    internalToken: string;
+    siteKey?: string;
+    userAgent?: string;
+    extraHeaders?: Record<string, string>;
+};
+export declare function fetchPhiDataSourceJson<T>(source: Extract<PhiDataSource, {
+    kind: "api";
+}>, context: PhiDataSourceFetchContext, options?: PhiDataLoadOptions): Promise<T>;

package/gateway/data-source-fetch.js

@@ -0,0 +1,46 @@
+import "server-only";
+import { buildApiHeaders, buildApiUrl } from "../helpers/site-api";
+import { buildPhiDataSourceUrl, normalizePhiDataSourceCacheMode, } from "./data-source";
+export async function fetchPhiDataSourceJson(source, context, options = {}) {
+    if (!context.apiBaseUrl.trim()) {
+        throw new Error("Missing apiBaseUrl for fetchPhiDataSourceJson.");
+    }
+    const url = buildApiUrl(context.apiBaseUrl, buildPhiDataSourceUrl(source, { query: options.query }));
+    if (!url) {
+        throw new Error("Missing upstreamPath for fetchPhiDataSourceJson.");
+    }
+    const headers = buildApiHeaders({
+        token: context.internalToken,
+        siteKey: context.siteKey ?? "",
+        includeToken: Boolean(context.internalToken.trim()),
+        includeSiteKey: Boolean(context.siteKey?.trim()),
+        extra: {
+            Accept: "application/json",
+            ...(context.userAgent ? { "User-Agent": context.userAgent } : {}),
+            ...(context.extraHeaders ?? {}),
+            ...(options.headers ?? {}),
+        },
+    });
+    const cacheMode = normalizePhiDataSourceCacheMode(source.cache?.mode);
+    const cacheTags = source.cache?.tags?.length ? [...source.cache.tags] : undefined;
+    const nextOptions = cacheMode === "revalidate" || cacheTags
+        ? {
+            revalidate: typeof source.cache?.revalidateSeconds === "number" && source.cache.revalidateSeconds > 0
+                ? source.cache.revalidateSeconds
+                : undefined,
+            tags: cacheTags,
+        }
+        : undefined;
+    const response = await fetch(url, {
+        method: source.method ?? "GET",
+        headers,
+        body: source.method === "GET" ? undefined : options.body ? JSON.stringify(options.body) : undefined,
+        cache: cacheMode === "no-store" ? "no-store" : "force-cache",
+        ...(nextOptions ? { next: nextOptions } : {}),
+    });
+    if (!response.ok) {
+        const payload = (await response.json().catch(() => null));
+        throw new Error(payload?.error || `Failed to fetch data source at ${source.upstreamPath}.`);
+    }
+    return (await response.json());
+}

package/gateway/data-source.d.ts

@@ -0,0 +1,62 @@
+export type PhiDataSourceCacheMode = "no-store" | "force-cache" | "revalidate";
+export type PhiDataSourceCache = {
+    mode?: PhiDataSourceCacheMode;
+    revalidateSeconds?: number;
+    tags?: readonly string[];
+};
+export type PhiDataSourceApiTransport = "relay" | "site";
+export type PhiDataSourceRequestShape = {
+    queryMap?: Record<string, string>;
+};
+export type PhiDataSourceResponseShape = {
+    rowsKey?: string;
+    totalKey?: string;
+};
+export type PhiApiDataSource = {
+    kind: "api";
+    upstreamPath: string;
+    endpointKey: string;
+    method?: "GET" | "POST";
+    transport?: PhiDataSourceApiTransport;
+    requestShape?: PhiDataSourceRequestShape;
+    responseShape?: PhiDataSourceResponseShape;
+    cache?: PhiDataSourceCache;
+};
+export type PhiDataSource = {
+    kind: "api";
+    upstreamPath: string;
+    endpointKey: string;
+    method?: "GET" | "POST";
+    transport?: PhiDataSourceApiTransport;
+    requestShape?: PhiDataSourceRequestShape;
+    responseShape?: PhiDataSourceResponseShape;
+    cache?: PhiDataSourceCache;
+} | {
+    kind: "serverAction";
+    actionKey: string;
+} | {
+    kind: "inline";
+    rows: readonly unknown[];
+};
+export type PhiDataQueryValue = string | number | boolean | null | undefined;
+export type PhiDataQuery = Record<string, PhiDataQueryValue>;
+export type PhiDataLoadOptions = {
+    query?: PhiDataQuery;
+    body?: unknown;
+    headers?: Record<string, string>;
+    cache?: PhiDataSourceCache;
+};
+export type PhiDataResult<T = unknown> = {
+    ok: boolean;
+    data: T;
+    total?: number;
+    meta?: Record<string, unknown>;
+    error?: string | null;
+};
+export declare function normalizePhiDataSourceCacheMode(value: string | null | undefined): PhiDataSourceCacheMode;
+export declare function normalizePhiDataSourceTags(tags: readonly string[] | null | undefined): string[];
+export declare function buildPhiDataSourceUrl(source: Extract<PhiDataSource, {
+    kind: "api";
+}>, options?: {
+    query?: PhiDataQuery;
+}): string;

package/gateway/data-source.js

@@ -0,0 +1,23 @@
+export function normalizePhiDataSourceCacheMode(value) {
+    const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+    if (normalized === "no-store" || normalized === "force-cache" || normalized === "revalidate") {
+        return normalized;
+    }
+    return "no-store";
+}
+export function normalizePhiDataSourceTags(tags) {
+    if (!tags?.length) {
+        return [];
+    }
+    return tags
+        .map((tag) => tag.trim())
+        .filter(Boolean);
+}
+export function buildPhiDataSourceUrl(source, options) {
+    return buildPhiGatewayRequestUrl({
+        upstreamPath: source.upstreamPath,
+        queryMap: source.requestShape?.queryMap,
+        query: options?.query,
+    });
+}
+import { buildPhiGatewayRequestUrl } from "./request-url";

package/gateway/errors.d.ts

@@ -0,0 +1,8 @@
+import "server-only";
+export declare class PhiCmsGatewayError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function isPhiCmsGatewayError(error: unknown): error is PhiCmsGatewayError;
+export declare function isPhiCmsGatewayAuthError(error: unknown): error is PhiCmsGatewayError;
+export declare function throwPhiCmsGatewayError(message: string, status: number): never;

package/gateway/errors.js

@@ -0,0 +1,18 @@
+import "server-only";
+export class PhiCmsGatewayError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "PhiCmsGatewayError";
+        this.status = status;
+    }
+}
+export function isPhiCmsGatewayError(error) {
+    return error instanceof PhiCmsGatewayError;
+}
+export function isPhiCmsGatewayAuthError(error) {
+    return isPhiCmsGatewayError(error) && (error.status === 401 || error.status === 403);
+}
+export function throwPhiCmsGatewayError(message, status) {
+    throw new PhiCmsGatewayError(message, status);
+}

package/gateway/form-handler-resolution.d.ts

@@ -0,0 +1,32 @@
+import "server-only";
+import type { NextRequest } from "next/server";
+import { type PhiCmsAreaKey } from "../constants/cms-areas";
+import type { PhiRuntimeModuleCatalog } from "../plugins/runtime-modules/contracts";
+import type { PhiFormHandlerPhase, PhiFormHandlerProviderDescriptor } from "../types/form-descriptor";
+export type PhiResolvedServerFormHandler = {
+    formId: string;
+    area: PhiCmsAreaKey;
+    provider: PhiFormHandlerProviderDescriptor;
+};
+export declare function resolvePhiServerFormHandler(options: {
+    request: NextRequest;
+    upstreamBaseUrl: string;
+    internalToken: string;
+    siteKey: string;
+    formId: string;
+    phase: PhiFormHandlerPhase;
+    /**
+     * The catalog of the Area the request came from, loaded once that Area is known.
+     *
+     * A loader rather than a catalog, and required rather than defaulted. It used to fall back to the
+     * Builder's all-Areas catalog, which had two costs. It answered a question nobody asked -- a Module
+     * inactive in the requesting Area still resolved a handler, so activation was a display decision for
+     * Forms and a boundary everywhere else. And being a static import, it pulled every Area's Widget
+     * plugins into any graph that reached this file.
+     *
+     * A Form drawn on the Builder canvas needs no exception. The canvas is authoring: its runtime is a
+     * stand-in and a Form there must not submit, so resolving against the Builder's own Area is the
+     * correct refusal rather than a case to work around.
+     */
+    loadRuntimeModuleCatalog: (area: PhiCmsAreaKey) => Promise<PhiRuntimeModuleCatalog | null>;
+}): Promise<PhiResolvedServerFormHandler | null>;