@phis/ui 0.1.0

package/components/forms/form-provider-contract.js

@@ -0,0 +1,246 @@
+import { PHI_CORE_RUNTIME_MODULE_ID } from "../../plugins/runtime-modules/core/ids";
+import { PHI_PUBLIC_RUNTIME_MODULE_ID } from "../../plugins/runtime-modules/public/ids";
+import { PHI_AUTH_RUNTIME_MODULE_ID } from "../../plugins/runtime-modules/auth/ids";
+import { createPhiModuleScopedKey } from "../../constants/runtime-module-ownership";
+export function createPhiSharedFormProviderKey(kind, key) {
+    const normalizedKey = key.trim();
+    if (!normalizedKey || normalizedKey.includes("/") || normalizedKey.includes(":")) {
+        throw new Error(`Invalid shared form provider key "${key}".`);
+    }
+    return createPhiModuleScopedKey(`form-${kind}`, normalizedKey);
+}
+export const PHI_FORM_FIELD_PROVIDER_KEYS = {
+    text: createPhiSharedFormProviderKey("field", "text"),
+    email: createPhiSharedFormProviderKey("field", "email"),
+    password: createPhiSharedFormProviderKey("field", "password"),
+    textarea: createPhiSharedFormProviderKey("field", "textarea"),
+    hidden: createPhiSharedFormProviderKey("field", "hidden"),
+    honeypot: createPhiSharedFormProviderKey("field", "honeypot"),
+    checkbox: createPhiSharedFormProviderKey("field", "checkbox"),
+    select: createPhiSharedFormProviderKey("field", "select"),
+    url: createPhiSharedFormProviderKey("field", "url"),
+    tel: createPhiSharedFormProviderKey("field", "tel"),
+    number: createPhiSharedFormProviderKey("field", "number"),
+    slider: createPhiSharedFormProviderKey("field", "slider"),
+    multiSelect: createPhiSharedFormProviderKey("field", "multi-select"),
+    checkboxGroup: createPhiSharedFormProviderKey("field", "checkbox-group"),
+    datetime: createPhiSharedFormProviderKey("field", "datetime"),
+    switch: createPhiSharedFormProviderKey("field", "switch"),
+    segmented: createPhiSharedFormProviderKey("field", "segmented"),
+    cascader: createPhiSharedFormProviderKey("field", "cascader"),
+    table: createPhiSharedFormProviderKey("field", "table"),
+    tree: createPhiSharedFormProviderKey("field", "tree"),
+};
+export const PHI_AUTH_FORM_FIELD_PROVIDER_KEYS = {
+    termsConsent: createPhiSharedFormProviderKey("field", "auth-terms-consent"),
+};
+export const PHI_AUTH_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS = [
+    {
+        key: PHI_AUTH_FORM_FIELD_PROVIDER_KEYS.termsConsent,
+        ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID,
+        title: "Terms consent",
+        valueType: "boolean",
+        presentation: "control",
+        settingsFields: [
+            { key: "text", type: "string", label: "Consent sentence, with %1 where the link goes" },
+            { key: "linkLabel", type: "string", label: "Link label" },
+            { key: "href", type: "url", label: "Link URL", required: true },
+        ],
+    },
+];
+export const PHI_FORM_VALIDATION_PROVIDER_KEYS = {
+    required: createPhiSharedFormProviderKey("validation", "required"),
+    email: createPhiSharedFormProviderKey("validation", "email"),
+    minLength: createPhiSharedFormProviderKey("validation", "min-length"),
+    maxLength: createPhiSharedFormProviderKey("validation", "max-length"),
+    exactLength: createPhiSharedFormProviderKey("validation", "exact-length"),
+    minLetters: createPhiSharedFormProviderKey("validation", "min-letters"),
+    matchesField: createPhiSharedFormProviderKey("validation", "matches-field"),
+    url: createPhiSharedFormProviderKey("validation", "url"),
+    tel: createPhiSharedFormProviderKey("validation", "tel"),
+    pattern: createPhiSharedFormProviderKey("validation", "pattern"),
+    number: createPhiSharedFormProviderKey("validation", "number"),
+};
+export const PHI_FORM_HANDLER_PROVIDER_KEYS = {
+    authAdminInstallationCreate: createPhiSharedFormProviderKey("handler", "auth-admin-installation-create"),
+    authAdminInstallationUpdate: createPhiSharedFormProviderKey("handler", "auth-admin-installation-update"),
+    authAdminPolicy: createPhiSharedFormProviderKey("handler", "auth-admin-policy"),
+    authAdminPasswordMethod: createPhiSharedFormProviderKey("handler", "auth-admin-password-method"),
+    authAdminTotpPolicy: createPhiSharedFormProviderKey("handler", "auth-admin-totp-policy"),
+    authLogin: createPhiSharedFormProviderKey("handler", "auth-login"),
+    authRegistration: createPhiSharedFormProviderKey("handler", "auth-registration"),
+    authRegistrationConfirm: createPhiSharedFormProviderKey("handler", "auth-registration-confirm"),
+    authConfirm: createPhiSharedFormProviderKey("handler", "auth-confirm"),
+    authConfirmPreview: createPhiSharedFormProviderKey("handler", "auth-confirm-preview"),
+    authResetPassword: createPhiSharedFormProviderKey("handler", "auth-reset-password"),
+    authResetPasswordConfirm: createPhiSharedFormProviderKey("handler", "auth-reset-password-confirm"),
+    authProviderLinkConfirm: createPhiSharedFormProviderKey("handler", "auth-provider-link-confirm"),
+    contact: createPhiSharedFormProviderKey("handler", "contact"),
+};
+export const PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS = [
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.text, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Text", valueType: "string", presentation: "control", settingsFields: [{ key: "minLength", type: "number", label: "Minimum characters", min: 0 }, { key: "maxLength", type: "number", label: "Maximum characters", min: 0 }] },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.email, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Email", valueType: "string", presentation: "control", settingsFields: [{ key: "minLength", type: "number", label: "Minimum characters", min: 0 }, { key: "maxLength", type: "number", label: "Maximum characters", min: 0 }] },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.password, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Password", valueType: "string", presentation: "control", settingsFields: [{ key: "minLength", type: "number", label: "Minimum characters", min: 0 }, { key: "maxLength", type: "number", label: "Maximum characters", min: 0 }] },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.textarea, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Text Area", valueType: "string", presentation: "control", settingsFields: [{ key: "rows", type: "number", label: "Rows", min: 1 }, { key: "minLength", type: "number", label: "Minimum characters", min: 0 }, { key: "maxLength", type: "number", label: "Maximum characters", min: 0 }] },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.hidden, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Hidden", valueType: "string", presentation: "hidden" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.checkbox, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Checkbox", valueType: "boolean", presentation: "control" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.select, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Select", valueType: "string", presentation: "control" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.honeypot, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Honeypot", valueType: "string", presentation: "honeypot" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.url, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "URL", valueType: "string", presentation: "control" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.tel, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Telephone", valueType: "string", presentation: "control" },
+    {
+        key: PHI_FORM_FIELD_PROVIDER_KEYS.number,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Number",
+        valueType: "number",
+        presentation: "control",
+        settingsFields: [
+            { key: "min", type: "number", label: "Minimum" },
+            { key: "max", type: "number", label: "Maximum" },
+            { key: "step", type: "number", label: "Step" },
+            { key: "precision", type: "number", label: "Precision", min: 0 },
+        ],
+    },
+    {
+        key: PHI_FORM_FIELD_PROVIDER_KEYS.slider,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Slider",
+        valueType: "number",
+        presentation: "control",
+        settingsFields: [
+            { key: "min", type: "number", label: "Minimum" },
+            { key: "max", type: "number", label: "Maximum" },
+            { key: "step", type: "number", label: "Step", min: 0 },
+            { key: "dots", type: "boolean", label: "Step dots" },
+            { key: "included", type: "boolean", label: "Highlight selected range" },
+            { key: "reverse", type: "boolean", label: "Reverse" },
+            {
+                key: "tooltipMode",
+                type: "choice",
+                label: "Tooltip",
+                options: [
+                    { value: "auto", label: "Automatic" },
+                    { value: "always", label: "Always" },
+                    { value: "hidden", label: "Hidden" },
+                ],
+            },
+            { key: "tooltipSuffix", type: "string", label: "Tooltip suffix" },
+            { key: "showInput", type: "boolean", label: "Show number input" },
+            { key: "precision", type: "number", label: "Input precision", min: 0 },
+        ],
+    },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.multiSelect, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Multi Select", valueType: "string[]", presentation: "control" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.checkboxGroup, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Checkbox Group", valueType: "string[]", presentation: "control" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.switch, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Switch", valueType: "boolean", presentation: "control" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.segmented, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Segmented", valueType: "string", presentation: "control" },
+    {
+        key: PHI_FORM_FIELD_PROVIDER_KEYS.cascader,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Cascader",
+        valueType: "string",
+        presentation: "control",
+        settingsFields: [
+            { key: "allowRoot", type: "boolean", label: "Allow Root" },
+            { key: "separator", type: "string", label: "Separator" },
+            { key: "rootValue", type: "string", label: "Root Value" },
+            {
+                key: "normalize",
+                type: "choice",
+                label: "Normalize",
+                options: [
+                    { value: "raw", label: "Raw" },
+                    { value: "path", label: "Path" },
+                ],
+            },
+        ],
+    },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.table, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Table value", valueType: "json", presentation: "control" },
+    { key: PHI_FORM_FIELD_PROVIDER_KEYS.tree, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Tree value", valueType: "json", presentation: "control" },
+    {
+        key: PHI_FORM_FIELD_PROVIDER_KEYS.datetime,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Date and time",
+        valueType: "string",
+        presentation: "control",
+        settingsFields: [{ key: "timeZone", type: "string", label: "Time zone" }],
+    },
+];
+export const PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS = [
+    { key: PHI_FORM_VALIDATION_PROVIDER_KEYS.required, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Required" },
+    { key: PHI_FORM_VALIDATION_PROVIDER_KEYS.email, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Email" },
+    {
+        key: PHI_FORM_VALIDATION_PROVIDER_KEYS.minLength,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Minimum Length",
+        settingsFields: [{ key: "min", type: "number", label: "Minimum", required: true }],
+    },
+    {
+        key: PHI_FORM_VALIDATION_PROVIDER_KEYS.minLetters,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Minimum Letters",
+        settingsFields: [{ key: "min", type: "number", label: "Minimum", required: true, min: 1 }],
+    },
+    {
+        key: PHI_FORM_VALIDATION_PROVIDER_KEYS.maxLength,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Maximum Length",
+        settingsFields: [{ key: "max", type: "number", label: "Maximum", required: true, min: 0 }],
+    },
+    {
+        key: PHI_FORM_VALIDATION_PROVIDER_KEYS.exactLength,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Exact Length",
+        settingsFields: [{ key: "length", type: "number", label: "Length", required: true, min: 0 }],
+    },
+    {
+        key: PHI_FORM_VALIDATION_PROVIDER_KEYS.matchesField,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Matches Field",
+        settingsFields: [{ key: "field", type: "string", label: "Field", required: true }],
+    },
+    { key: PHI_FORM_VALIDATION_PROVIDER_KEYS.url, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "URL" },
+    { key: PHI_FORM_VALIDATION_PROVIDER_KEYS.tel, ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID, title: "Telephone" },
+    {
+        key: PHI_FORM_VALIDATION_PROVIDER_KEYS.pattern,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Pattern",
+        settingsFields: [
+            { key: "source", type: "string", label: "Pattern", required: true },
+            { key: "flags", type: "string", label: "Flags" },
+        ],
+    },
+    {
+        key: PHI_FORM_VALIDATION_PROVIDER_KEYS.number,
+        ownerModuleId: PHI_CORE_RUNTIME_MODULE_ID,
+        title: "Number",
+        settingsFields: [
+            { key: "min", type: "number", label: "Minimum" },
+            { key: "max", type: "number", label: "Maximum" },
+            { key: "step", type: "number", label: "Step", min: 0 },
+            { key: "precision", type: "number", label: "Precision", min: 0 },
+            { key: "integer", type: "boolean", label: "Integer only" },
+        ],
+    },
+];
+export const PHI_AUTH_FORM_HANDLER_PROVIDER_DESCRIPTORS = [
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authAdminInstallationCreate, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Auth Admin installation create", phase: "submit", handlerKey: "auth.admin.installation-create", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/v1/auth/admin/installations", csrfPath: "/api/auth/csrf", requiresCsrf: true, credentialPolicy: "site-session" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authAdminInstallationUpdate, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Auth Admin installation update", phase: "submit", handlerKey: "auth.admin.installation-update", category: "auth", transport: "relay", method: "PATCH", endpointKey: null, upstreamPath: "/api/v1/auth/admin/installations", csrfPath: "/api/auth/csrf", requiresCsrf: true, credentialPolicy: "site-session" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authAdminPolicy, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Auth Admin policy", phase: "submit", handlerKey: "auth.admin.policy", category: "auth", transport: "relay", method: "PATCH", endpointKey: null, upstreamPath: "/api/v1/auth/admin/policy", csrfPath: "/api/auth/csrf", requiresCsrf: true, credentialPolicy: "site-session" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authAdminPasswordMethod, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Auth Admin password method", phase: "submit", handlerKey: "auth.admin.password-method", category: "auth", transport: "relay", method: "PATCH", endpointKey: null, upstreamPath: "/api/v1/auth/admin/password-method", csrfPath: "/api/auth/csrf", requiresCsrf: true, credentialPolicy: "site-session" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authAdminTotpPolicy, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Auth Admin two-factor policy", phase: "submit", handlerKey: "auth.admin.totp-policy", category: "auth", transport: "relay", method: "PATCH", endpointKey: null, upstreamPath: "/api/v1/auth/admin/totp-policy", csrfPath: "/api/auth/csrf", requiresCsrf: true, credentialPolicy: "site-session" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authLogin, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Login", phase: "submit", handlerKey: "auth.login", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/auth/login", csrfPath: "/api/auth/csrf", requiresCsrf: true, credentialPolicy: "none" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authRegistration, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Registration", phase: "submit", handlerKey: "auth.registration", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/v1/forms/register", csrfPath: null, requiresCsrf: false, credentialPolicy: "none" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authRegistrationConfirm, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Registration Confirm", phase: "confirm", handlerKey: "auth.registration.confirm", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/v1/forms/register/confirm", csrfPath: null, requiresCsrf: false, credentialPolicy: "none" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authConfirm, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Confirm", phase: "submit", handlerKey: "auth.confirm", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/v1/forms/register/confirm", csrfPath: null, requiresCsrf: false, credentialPolicy: "none" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authConfirmPreview, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Confirm Preview", phase: "preview", handlerKey: "auth.confirm.preview", category: "auth", transport: "relay", method: "GET", endpointKey: null, upstreamPath: "/api/v1/forms/register/confirm-preview", csrfPath: null, requiresCsrf: false, credentialPolicy: "none" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authResetPassword, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Reset Password", phase: "submit", handlerKey: "auth.reset-password", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/auth/password/reset/request", csrfPath: null, requiresCsrf: false, credentialPolicy: "none" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authResetPasswordConfirm, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Reset Password Confirm", phase: "confirm", handlerKey: "auth.reset-password.confirm", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/auth/password/reset/confirm", csrfPath: null, requiresCsrf: false, credentialPolicy: "none" },
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.authProviderLinkConfirm, ownerModuleId: PHI_AUTH_RUNTIME_MODULE_ID, title: "Provider Link Confirm", phase: "confirm", handlerKey: "auth.provider-link.confirm", category: "auth", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/v1/auth/providers/link/confirm", csrfPath: "/api/v1/auth/csrf", requiresCsrf: true, credentialPolicy: "auth-link" },
+];
+export const PHI_PUBLIC_FORM_HANDLER_PROVIDER_DESCRIPTORS = [
+    { key: PHI_FORM_HANDLER_PROVIDER_KEYS.contact, ownerModuleId: PHI_PUBLIC_RUNTIME_MODULE_ID, title: "Contact", phase: "submit", handlerKey: "forms.contact", category: "forms", transport: "relay", method: "POST", endpointKey: null, upstreamPath: "/api/v1/forms/contact", csrfPath: null, requiresCsrf: false, credentialPolicy: "none" },
+];
+export const PHI_CORE_FORM_PROVIDER_DESCRIPTORS = {
+    fieldTypes: PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS,
+    validationRules: PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS,
+};

package/components/forms/form-provider-registry.d.ts

@@ -0,0 +1,54 @@
+import { type ComponentType, type ReactNode } from "react";
+import type { Rule } from "antd/es/form";
+import type { PhiFormFieldDescriptor, PhiFormFieldTypeProviderDescriptor, PhiFormProviderKey, PhiFormValidationProviderDescriptor, PhiFormValidationRuleDescriptor } from "../../types/form-descriptor";
+import type { PhiControlOption } from "../controls/phi-control-options";
+export type PhiFormFieldProviderProps = {
+    field: PhiFormFieldDescriptor;
+    label?: string;
+    description?: string;
+    controlLabel?: string;
+    labels?: Readonly<Record<string, string>>;
+    placeholder?: string;
+    options?: readonly PhiControlOption[];
+    value?: unknown;
+    checked?: boolean;
+    onChange?: (...args: unknown[]) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Reports what has been typed. Absent where the field's provider is not searchable. */
+    onSearch?: (search: string) => void;
+    /** `false` where the provider answered the search itself, so the control must not filter it again. */
+    filterOptionsLocally?: boolean;
+    formContext?: {
+        getValues(): Record<string, unknown>;
+        setValues(values: Record<string, unknown>): void;
+    };
+    /** What the Widget was placed with, for text a field takes from its placement rather than its form. */
+    formConfig?: Readonly<Record<string, unknown>>;
+};
+export type PhiFormFieldTypeProvider = PhiFormFieldTypeProviderDescriptor & {
+    Control: ComponentType<PhiFormFieldProviderProps>;
+    valuePropName?: string;
+};
+export type PhiFormValidationContext = {
+    field: PhiFormFieldDescriptor;
+    rule: PhiFormValidationRuleDescriptor;
+    message?: string;
+};
+export type PhiFormValidationProvider = PhiFormValidationProviderDescriptor & {
+    createRule: (context: PhiFormValidationContext) => Rule;
+};
+export type PhiFormProviderRegistry = {
+    fieldTypesByKey: ReadonlyMap<PhiFormProviderKey, PhiFormFieldTypeProvider>;
+    validationRulesByKey: ReadonlyMap<PhiFormProviderKey, PhiFormValidationProvider>;
+};
+export declare function createPhiFormProviderRegistry({ fieldTypes, validationRules, }: {
+    fieldTypes?: readonly PhiFormFieldTypeProvider[];
+    validationRules?: readonly PhiFormValidationProvider[];
+}): PhiFormProviderRegistry;
+export declare function extendPhiFormProviderRegistry(...registries: readonly PhiFormProviderRegistry[]): PhiFormProviderRegistry;
+export declare function PhiFormProviderRegistryProvider({ registry, children, }: {
+    registry: PhiFormProviderRegistry;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function usePhiFormProviderRegistry(): PhiFormProviderRegistry | null;

package/components/forms/form-provider-registry.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, } from "react";
+const PhiFormProviderRegistryContext = createContext(null);
+function createUniqueProviderMap(kind, providers) {
+    const entries = new Map();
+    for (const provider of providers) {
+        if (entries.has(provider.key)) {
+            throw new Error(`Duplicate form ${kind} provider "${provider.key}".`);
+        }
+        entries.set(provider.key, provider);
+    }
+    return entries;
+}
+export function createPhiFormProviderRegistry({ fieldTypes = [], validationRules = [], }) {
+    return {
+        fieldTypesByKey: createUniqueProviderMap("field type", fieldTypes),
+        validationRulesByKey: createUniqueProviderMap("validation", validationRules),
+    };
+}
+export function extendPhiFormProviderRegistry(...registries) {
+    return createPhiFormProviderRegistry({
+        fieldTypes: registries.flatMap((registry) => [...registry.fieldTypesByKey.values()]),
+        validationRules: registries.flatMap((registry) => [...registry.validationRulesByKey.values()]),
+    });
+}
+export function PhiFormProviderRegistryProvider({ registry, children, }) {
+    const parent = useContext(PhiFormProviderRegistryContext);
+    const composed = useMemo(() => parent ? extendPhiFormProviderRegistry(parent, registry) : registry, [parent, registry]);
+    return (_jsx(PhiFormProviderRegistryContext.Provider, { value: composed, children: children }));
+}
+export function usePhiFormProviderRegistry() {
+    return useContext(PhiFormProviderRegistryContext);
+}

package/components/forms/form-registry.d.ts

@@ -0,0 +1,35 @@
+import type { PhiFormInitialValuesLoader, PhiFormLabelSetLoader } from "./form-resolution";
+import type { PhiFormDescriptor } from "../../types/form-descriptor";
+import type { PhiRuntimeModuleId } from "../../types/cms-module-descriptors";
+import { type PhiCmsAreaKey } from "../../constants/cms-areas";
+import type { PhiFormId } from "../../types/form-id";
+export type PhiRuntimeModuleFormDefinition = {
+    ownerModuleId: PhiRuntimeModuleId;
+    /**
+     * The Areas this Form belongs to.
+     *
+     * A Form is not machinery the way a Widget is. A Card renders whatever it is pointed at and belongs
+     * everywhere; a Form is one transaction with one handler and one audience, and "create an
+     * installation" has no business in an App picker. So a Form states where it belongs and the Area
+     * projection cuts it like a route.
+     */
+    areas: readonly PhiCmsAreaKey[];
+    formId: PhiFormId;
+    version: number;
+    flags: number;
+    title: string;
+    description: string | null;
+    category: string | null;
+    tags: string[];
+    descriptor: PhiFormDescriptor;
+    submitHandlerKey: string | null;
+    confirmHandlerKey: string | null;
+    previewHandlerKey: string | null;
+    defaultConfig: Record<string, unknown>;
+    variant: string | null;
+    config: Record<string, unknown>;
+    previewUpstreamPath: string | null;
+    loadLabels?: PhiFormLabelSetLoader;
+    loadInitialValues?: PhiFormInitialValuesLoader;
+};
+export declare function definePhiRuntimeModuleForm(definition: PhiRuntimeModuleFormDefinition): PhiRuntimeModuleFormDefinition;

package/components/forms/form-registry.js

@@ -0,0 +1,24 @@
+import { isPhiCmsAreaKey } from "../../constants/cms-areas";
+import { isPhiFormId, normalizePhiFormId } from "../../types/form-id";
+import { parsePhiFormDescriptor } from "./form-descriptor-contract";
+export function definePhiRuntimeModuleForm(definition) {
+    const formId = normalizePhiFormId(definition.formId);
+    if (!isPhiFormId(formId)) {
+        throw new Error(`Invalid namespaced Form id "${definition.formId}".`);
+    }
+    if (definition.areas.length === 0 || definition.areas.some((area) => !isPhiCmsAreaKey(area))) {
+        throw new Error(`Form "${formId}" must name the Areas it belongs to.`);
+    }
+    const descriptor = parsePhiFormDescriptor(definition.descriptor);
+    if (descriptor.key !== formId) {
+        throw new Error(`Form descriptor key "${descriptor.key}" must match formId "${formId}".`);
+    }
+    if (!Number.isInteger(definition.version) || definition.version < 1) {
+        throw new Error(`Form "${formId}" must declare a positive integer version.`);
+    }
+    return {
+        ...definition,
+        descriptor,
+        formId,
+    };
+}

package/components/forms/form-resolution.d.ts

@@ -0,0 +1,69 @@
+import "server-only";
+import type { PhiBlockRuntime, PhiSignalAddress } from "../../types";
+import type { PhiFormDescriptor } from "../../types/form-descriptor";
+import type { PhiRuntimeModuleId } from "../../types/cms-module-descriptors";
+export type PhiFormDefinitionSource = "shared" | "db";
+export type PhiFormRenderOptions = {
+    config?: Record<string, unknown>;
+    formControllerAddress?: PhiSignalAddress | null;
+    formInstanceKey?: string | null;
+};
+export type PhiFormRenderContext = {
+    runtime: Pick<PhiBlockRuntime, "site" | "locale"> & Partial<Pick<PhiBlockRuntime, "area">>;
+    resolvedForm: PhiResolvedFormDefinition<PhiFormDefinitionLike> | null;
+    options?: PhiFormRenderOptions;
+};
+/**
+ * Values a form needs from the server before anyone can fill it in.
+ *
+ * A guard token is the case that made this a contract: it is minted per render, it cannot be asked for
+ * from the browser without giving away what it protects, and the form is worthless without it. Reading
+ * it used to mean the form brought its own render function, and everything the Form Widget offers --
+ * signals, execution mode, submit -- was lost with that branch. This reads the values and nothing else.
+ */
+export type PhiFormInitialValuesLoader = (context: PhiFormRenderContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+export type PhiFormLabelSetLoader = (context: PhiFormRenderContext) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+export declare function resolvePhiFormLabels(context: PhiFormRenderContext): Promise<Readonly<Record<string, string>>>;
+export type PhiFormDefinitionLike = {
+    id?: number;
+    ownerModuleId: PhiRuntimeModuleId;
+    formId: string;
+    version: number;
+    status?: number;
+    flags: number;
+    title: string;
+    description: string | null;
+    category: string | null;
+    tags: string[];
+    descriptor: PhiFormDescriptor;
+    submitHandlerKey: string | null;
+    confirmHandlerKey: string | null;
+    previewHandlerKey: string | null;
+    defaultConfig: Record<string, unknown>;
+    variant: string | null;
+    config: Record<string, unknown>;
+    previewUpstreamPath: string | null;
+    loadLabels?: PhiFormLabelSetLoader;
+    loadInitialValues?: PhiFormInitialValuesLoader;
+};
+export type PhiFormRenderTarget = {
+    key: string;
+    id: number | null;
+    ownerModuleId: PhiRuntimeModuleId;
+    formId: string;
+    version: number;
+    source: PhiFormDefinitionSource;
+};
+export type PhiResolvedFormDefinition<TDefinition extends PhiFormDefinitionLike = PhiFormDefinitionLike> = {
+    source: PhiFormDefinitionSource;
+    presetDefinition: TDefinition | null;
+    overrideDefinition: TDefinition | null;
+    definition: TDefinition;
+    renderTarget: PhiFormRenderTarget;
+    effectiveConfig: Record<string, unknown>;
+};
+export declare function buildPhiFormRenderTarget<TDefinition extends PhiFormDefinitionLike>(definition: TDefinition, source: PhiFormDefinitionSource): PhiFormRenderTarget;
+export declare function resolvePhiFormDefinition<TDefinition extends PhiFormDefinitionLike>({ presetDefinition, overrideDefinition, }: {
+    presetDefinition: TDefinition | null;
+    overrideDefinition?: TDefinition | null;
+}): PhiResolvedFormDefinition<TDefinition> | null;

package/components/forms/form-resolution.js

@@ -0,0 +1,83 @@
+import "server-only";
+export async function resolvePhiFormLabels(context) {
+    const definition = context.resolvedForm?.definition;
+    if (!definition?.descriptor.labelSetKey) {
+        return {};
+    }
+    if (!definition.loadLabels) {
+        throw new Error(`Form label set "${definition.descriptor.labelSetKey}" has no loader in the active form definition.`);
+    }
+    return definition.loadLabels(context);
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function deepMergeRecords(base, override) {
+    const result = { ...base };
+    for (const [key, overrideValue] of Object.entries(override)) {
+        const baseValue = result[key];
+        if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+            result[key] = deepMergeRecords(baseValue, overrideValue);
+            continue;
+        }
+        result[key] = overrideValue;
+    }
+    return result;
+}
+function normalizeFormId(value) {
+    return value.trim().toLowerCase();
+}
+export function buildPhiFormRenderTarget(definition, source) {
+    return {
+        key: definition.formId,
+        id: definition.id ?? null,
+        ownerModuleId: definition.ownerModuleId,
+        formId: normalizeFormId(definition.formId),
+        version: definition.version,
+        source,
+    };
+}
+export function resolvePhiFormDefinition({ presetDefinition, overrideDefinition, }) {
+    if (!presetDefinition && !overrideDefinition) {
+        return null;
+    }
+    const resolvedSource = overrideDefinition ? "db" : "shared";
+    const baseDefinition = overrideDefinition ?? presetDefinition;
+    if (!baseDefinition) {
+        return null;
+    }
+    const resolvedDefinition = overrideDefinition && presetDefinition
+        ? {
+            ...presetDefinition,
+            ...overrideDefinition,
+            id: overrideDefinition.id,
+            ownerModuleId: overrideDefinition.ownerModuleId,
+            formId: normalizeFormId(overrideDefinition.formId || presetDefinition.formId),
+            title: overrideDefinition.title || presetDefinition.title,
+            description: overrideDefinition.description ?? presetDefinition.description,
+            category: overrideDefinition.category ?? presetDefinition.category,
+            tags: overrideDefinition.tags.length > 0 ? overrideDefinition.tags : presetDefinition.tags,
+            descriptor: overrideDefinition.descriptor,
+            submitHandlerKey: overrideDefinition.submitHandlerKey || presetDefinition.submitHandlerKey,
+            confirmHandlerKey: overrideDefinition.confirmHandlerKey ?? presetDefinition.confirmHandlerKey,
+            previewHandlerKey: overrideDefinition.previewHandlerKey ?? presetDefinition.previewHandlerKey,
+            defaultConfig: deepMergeRecords(presetDefinition.defaultConfig, overrideDefinition.defaultConfig),
+            variant: overrideDefinition.variant ?? presetDefinition.variant,
+            config: deepMergeRecords(deepMergeRecords(presetDefinition.defaultConfig, presetDefinition.config), deepMergeRecords(overrideDefinition.defaultConfig, overrideDefinition.config)),
+            loadLabels: overrideDefinition.loadLabels ?? presetDefinition.loadLabels,
+            loadInitialValues: overrideDefinition.loadInitialValues ?? presetDefinition.loadInitialValues,
+            previewUpstreamPath: overrideDefinition.previewUpstreamPath ?? presetDefinition.previewUpstreamPath,
+            status: overrideDefinition.status,
+            flags: overrideDefinition.flags,
+            version: overrideDefinition.version || presetDefinition.version,
+        }
+        : baseDefinition;
+    return {
+        source: resolvedSource,
+        presetDefinition,
+        overrideDefinition: overrideDefinition ?? null,
+        definition: resolvedDefinition,
+        renderTarget: buildPhiFormRenderTarget(resolvedDefinition, resolvedSource),
+        effectiveConfig: resolvedDefinition.config,
+    };
+}

package/components/forms/phi-form-widget-frame.d.ts

@@ -0,0 +1,60 @@
+import { type ReactNode } from "react";
+import type { PhiCmsFormWidgetSubmitConfig } from "../../plugins/runtime-modules/core/widgets/form/config";
+/**
+ * What a form body offers the Widget above it, so the Widget can draw a submit for it.
+ *
+ * A form describes fields. Whether there is a button, what it says and which column it stands in are the
+ * Widget's to decide -- which is why the body hands up a way to submit rather than a button, and why the
+ * label is only what this form would call it if the Widget's config says nothing.
+ */
+export type PhiFormWidgetSubmitRegistration = {
+    /** Asks the mounted form to submit. The same request the `submit` capability makes. */
+    submit: () => void;
+    /** What this form calls submitting, used where the Widget's config names nothing. */
+    label?: string;
+};
+type PhiFormWidgetSubmitSlot = {
+    register: (registration: PhiFormWidgetSubmitRegistration | null) => void;
+    setSubmitting: (submitting: boolean) => void;
+};
+/**
+ * Offers this form's submit to the Form Widget around it, and returns the slot so the caller can report
+ * that a submit is under way. Null where no Widget is listening, which is what a form rendered outside
+ * one gets: it simply has no submit of its own to draw instead.
+ */
+export declare function usePhiFormWidgetSubmit(submit: () => void, label?: string): PhiFormWidgetSubmitSlot | null;
+/**
+ * Where in a form body the Widget's submit appears.
+ *
+ * The Widget decides whether there is one, what it says and which column it stands in; the body decides
+ * only which of its own parts it follows. The Login needs that say: its external sign-in methods stand
+ * below the password form, and a submit appended to the end of the Widget would sit under them.
+ */
+export declare function PhiFormWidgetSubmitOutlet(): import("react").JSX.Element;
+/** A resolved way out of the form: what it says and where it leads, both already decided. */
+export type PhiFormWidgetLink = {
+    key: string;
+    label: string;
+    href: string;
+};
+export type PhiFormWidgetFrameProps = {
+    /** The submit the Widget carries, or null where it carries none. */
+    submit?: PhiCmsFormWidgetSubmitConfig | null;
+    /** The ways out it offers, drawn in the same column as the submit. */
+    links?: readonly PhiFormWidgetLink[];
+    children: ReactNode;
+};
+/**
+ * The Form Widget's own surface: the query container its form is measured in, and the submit it carries.
+ *
+ * The container sits here rather than in the form because a container cannot answer a question about its
+ * own width, and the submit stands beside the form rather than in it -- both have to know where the label
+ * column ends to line up under the inputs, and only an element above both can tell them.
+ *
+ * The submit opens its own row of the same twenty-four tracks. Its own grid rather than a row inside the
+ * form: the form describes fields, and a submit is not one. Sharing the track count and the label-column
+ * property is all it takes for the button to line up under the inputs and move with the column the Layout
+ * decides, because that column is a custom property both of them read.
+ */
+export declare function PhiFormWidgetFrame({ submit, links, children }: PhiFormWidgetFrameProps): import("react").JSX.Element;
+export {};