@phis/ui 0.1.0 → 0.2.0

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

@@ -1,23 +1,20 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { lazy, Suspense } from "react";
-import { createPhiFormProviderRegistry } from "./form-provider-registry";
-import { PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS, PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS, } from "./form-provider-contract";
+import { createPhiFormProviderRegistry, } from "./form-provider-registry";
+import { PHI_FORM_FIELD_PROVIDER_KEYS, PHI_FORM_VALIDATION_PROVIDER_KEYS, PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS, PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS, } from "./form-provider-contract";
 import { PhiTextControl } from "../controls/phi-text-control";
-import { PhiNumberControl } from "../controls/phi-number-control";
-import { PhiSelectControl } from "../controls/phi-select-control";
-import { PhiMultiSelectControl } from "../controls/phi-multi-select-control";
 import { PhiCheckboxControl } from "../controls/phi-checkbox-control";
 import { PhiCheckboxGroupControl } from "../controls/phi-checkbox-group-control";
 import { PhiSwitchControl } from "../controls/phi-switch-control";
-import { PhiSegmentedControl } from "../controls/phi-segmented-control";
 /**
  * A field Control whose code loads when a field of its kind is first rendered.
  *
- * The kinds below are rare in a form and heavy to ship: the slider and the cascader, the date and time
- * picker, and the compound Table and Tree fields, which bring the Table and Tree Controls with an editor
- * for every column kind. Text, choice and toggle fields stay in the registry itself, because nearly every
- * form has them and a round trip per field would cost more than it saves.
+ * Every kind below that has code of its own to ship: the choice and number fields, the slider and the
+ * cascader, the date and time picker, and the compound Table and Tree fields, which bring the Table and
+ * Tree Controls with an editor for every column kind. Only text and toggle fields stay in the registry
+ * itself. The choice fields stayed too once, as kinds nearly every form has -- but the form every
+ * Landing carries is the sign-in, which has none of them, and paid for the Select on every first visit.
  */
 function lazyPhiFormFieldControl(load, 
 /** How many control rows the field occupies once loaded, so the form keeps its height meanwhile. */
@@ -29,123 +26,150 @@ placeholderRows = 1) {
      */
     const placeholder = (_jsx("div", { "aria-busy": "true", style: {
             blockSize: `calc(var(--ant-control-height) * ${placeholderRows} + var(--ant-padding-sm) * ${placeholderRows - 1})`,
-            borderRadius: "var(--ant-border-radius)",
+            /*
+             * The Control shape, because this stands where a Control is about to stand. `grown-md` is half a
+             * Control line, which on the one-row placeholder is exactly the capsule and on a taller one is the
+             * capsule held -- the same answer the field itself will give when it arrives, so the shape does not
+             * change under the reader at the moment the chunk lands.
+             *
+             * Here the fallback is the plain surface radius and not the large one: this is an ordinary `div`,
+             * not an Ant Design Control, so nothing has redefined `--ant-border-radius` on it.
+             */
+            borderRadius: "var(--phi-control-radius-grown-md, var(--ant-border-radius))",
             background: "var(--ant-color-fill-quaternary)",
         } }));
     return function PhiLazyFormFieldControl(props) {
         return (_jsx(Suspense, { fallback: placeholder, children: _jsx(LazyControl, { ...props }) }));
     };
 }
+const PhiLazySelectFormControl = lazyPhiFormFieldControl(() => import("./choice-form-field-controls").then((module) => module.PhiSelectFormControl));
+const PhiLazyMultiSelectFormControl = lazyPhiFormFieldControl(() => import("./choice-form-field-controls").then((module) => module.PhiMultiSelectFormControl));
+const PhiLazySegmentedFormControl = lazyPhiFormFieldControl(() => import("./choice-form-field-controls").then((module) => module.PhiSegmentedFormControl));
+const PhiLazyNumberFormControl = lazyPhiFormFieldControl(() => import("./extended-form-field-controls").then((module) => module.PhiNumberFormControl));
+const PhiLazyStorageSizeFormControl = lazyPhiFormFieldControl(() => import("./extended-form-field-controls").then((module) => module.PhiStorageSizeFormControl));
 const PhiLazySliderFormControl = lazyPhiFormFieldControl(() => import("./extended-form-field-controls").then((module) => module.PhiSliderFormControl));
 const PhiLazyCascaderFormControl = lazyPhiFormFieldControl(() => import("./extended-form-field-controls").then((module) => module.PhiCascaderFormControl));
 const PhiLazyDateTimeFormControl = lazyPhiFormFieldControl(() => import("./datetime-form-control").then((module) => module.PhiDateTimeFormControl));
 // Collection header, then the Table's or Tree's head and at least one row.
 const PhiLazyCompoundTableFormControl = lazyPhiFormFieldControl(() => import("./compound-form-controls").then((module) => module.PhiCompoundTableFormControl), 3);
 const PhiLazyCompoundTreeFormControl = lazyPhiFormFieldControl(() => import("./compound-form-controls").then((module) => module.PhiCompoundTreeFormControl), 3);
+// The trigger, and above it the row the attachments occupy once there is one.
+const PhiLazyUploadFormControl = lazyPhiFormFieldControl(() => import("./upload-form-control").then((module) => module.PhiUploadFormControl), 2);
+/**
+ * What a field type is, named by its key, joined to how it renders.
+ *
+ * The two halves live apart on purpose: the descriptor says what a field type is and travels to the
+ * server and the authoring catalogs, while the Control is browser code this file is the only holder
+ * of. Joining them used to be a matter of counting -- `...DESCRIPTORS[10]` beside the number Control --
+ * and a position is not a name. Inserting a field type in the middle of that list re-paired every
+ * entry after it: a Control would be registered under its neighbour's key, one field type would be
+ * missing and another duplicated, and nothing in the repository noticed. Typecheck could not: all
+ * descriptors have the same shape and `key` is not a literal type. The contract validators walk
+ * catalogs rather than this file, and the unit suite is Node-only by design, so it never imports it.
+ *
+ * Naming the key makes the pairing readable, and makes a wrong one a thrown error at module load
+ * rather than a form that quietly renders the wrong control.
+ * `scripts/validate-form-provider-registry.mjs` keeps the positional spelling from coming back.
+ */
+function phiSharedFieldType(key, provider) {
+    const descriptor = PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS.find((entry) => entry.key === key);
+    if (!descriptor)
+        throw new Error(`No shared form field type descriptor for "${key}".`);
+    return { ...descriptor, ...provider };
+}
+/** The same pairing for a validation rule, whose descriptor list had drifted from its keys too. */
+function phiSharedValidationRule(key, provider) {
+    const descriptor = PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS.find((entry) => entry.key === key);
+    if (!descriptor)
+        throw new Error(`No shared form validation provider descriptor for "${key}".`);
+    return { ...descriptor, ...provider };
+}
 export const PHI_SHARED_FORM_PROVIDER_REGISTRY = createPhiFormProviderRegistry({
     fieldTypes: [
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[0],
-            Control: ({ field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { value: typeof value === "string" ? value : "", inputType: field.config?.inputType === "search" ? "search" : "text", allowClear: field.config?.allowClear === true, placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[1],
-            Control: ({ field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { value: typeof value === "string" ? value : "", inputType: "email", placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[2],
-            Control: ({ field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { presentation: "password", value: typeof value === "string" ? value : "", disabled: disabled, readOnly: readOnly, placeholder: placeholder, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[3],
-            Control: ({ field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { presentation: "textarea", value: typeof value === "string" ? value : "", disabled: disabled, readOnly: readOnly, placeholder: placeholder, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, rows: typeof field.config?.rows === "number" ? field.config.rows : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[4],
-            Control: ({ value, onChange }) => (_jsx(PhiTextControl, { presentation: "hidden", value: typeof value === "string" ? value : "", onChange: (nextValue) => onChange?.(nextValue) })),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.text, {
+            Control: ({ id, field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { id: id, value: typeof value === "string" ? value : "", inputType: field.config?.inputType === "search" ? "search" : "text", allowClear: field.config?.allowClear === true, placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.email, {
+            Control: ({ id, field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { id: id, value: typeof value === "string" ? value : "", inputType: "email", placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.password, {
+            Control: ({ id, field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { id: id, presentation: "password", value: typeof value === "string" ? value : "", disabled: disabled, readOnly: readOnly, placeholder: placeholder, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.textarea, {
+            Control: ({ id, field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { id: id, presentation: "textarea", value: typeof value === "string" ? value : "", disabled: disabled, readOnly: readOnly, placeholder: placeholder, autoComplete: field.autoComplete, minLength: typeof field.config?.minLength === "number" ? field.config.minLength : undefined, maxLength: typeof field.config?.maxLength === "number" ? field.config.maxLength : undefined, rows: typeof field.config?.rows === "number" ? field.config.rows : undefined, onChange: (nextValue) => onChange?.(nextValue) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.hidden, {
+            Control: ({ id, value, onChange }) => (_jsx(PhiTextControl, { id: id, presentation: "hidden", value: typeof value === "string" ? value : "", onChange: (nextValue) => onChange?.(nextValue) })),
             valuePropName: "value",
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[5],
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.checkbox, {
             Control: ({ checked, controlLabel, onChange, disabled }) => (_jsx(PhiCheckboxControl, { checked: checked, label: controlLabel, disabled: disabled, onChange: (nextChecked) => onChange?.(nextChecked) })),
             valuePropName: "checked",
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[6],
-            Control: ({ value, onChange, options, placeholder, disabled, readOnly, onSearch, filterOptionsLocally }) => (_jsx(PhiSelectControl, { value: typeof value === "string" ? value : undefined, placeholder: placeholder, disabled: disabled, readOnly: readOnly, options: options ?? [], onSearch: onSearch, filterOptionsLocally: filterOptionsLocally, onChange: (nextValue) => onChange?.(nextValue), style: { width: "100%" } })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[7],
-            Control: ({ value, onChange, disabled }) => (_jsx(PhiTextControl, { presentation: "hidden", tabIndex: -1, autoComplete: "off", value: typeof value === "string" ? value : "", disabled: disabled, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[8],
-            Control: ({ field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { value: typeof value === "string" ? value : "", inputType: "url", placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[9],
-            Control: ({ field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { value: typeof value === "string" ? value : "", inputType: "phone", placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[10],
-            Control: ({ field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiNumberControl, { value: typeof value === "number" ? value : null, disabled: disabled, readOnly: readOnly, placeholder: placeholder, min: typeof field.config?.min === "number" ? field.config.min : undefined, max: typeof field.config?.max === "number" ? field.config.max : undefined, step: typeof field.config?.step === "number" ? field.config.step : undefined, precision: typeof field.config?.precision === "number" ? field.config.precision : undefined, style: { width: "100%" }, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[11],
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.select, {
+            Control: PhiLazySelectFormControl,
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.honeypot, {
+            Control: ({ id, value, onChange, disabled }) => (_jsx(PhiTextControl, { id: id, presentation: "hidden", tabIndex: -1, autoComplete: "off", value: typeof value === "string" ? value : "", disabled: disabled, onChange: (nextValue) => onChange?.(nextValue) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.url, {
+            Control: ({ id, field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { id: id, value: typeof value === "string" ? value : "", inputType: "url", placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, onChange: (nextValue) => onChange?.(nextValue) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.tel, {
+            Control: ({ id, field, value, onChange, placeholder, disabled, readOnly }) => (_jsx(PhiTextControl, { id: id, value: typeof value === "string" ? value : "", inputType: "phone", placeholder: placeholder, disabled: disabled, readOnly: readOnly, autoComplete: field.autoComplete, onChange: (nextValue) => onChange?.(nextValue) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.number, {
+            Control: PhiLazyNumberFormControl,
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.slider, {
             Control: PhiLazySliderFormControl,
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[12],
-            Control: ({ value, onChange, options, placeholder, disabled, readOnly }) => (_jsx(PhiMultiSelectControl, { value: Array.isArray(value) ? value.map(String) : [], placeholder: placeholder, disabled: disabled, readOnly: readOnly, options: options ?? [], style: { width: "100%" }, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[13],
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.multiSelect, {
+            Control: PhiLazyMultiSelectFormControl,
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.checkboxGroup, {
             Control: ({ value, onChange, options, disabled, readOnly }) => (_jsx(PhiCheckboxGroupControl, { value: Array.isArray(value) ? value.map(String) : [], disabled: disabled, readOnly: readOnly, options: options ?? [], onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[14],
-            Control: ({ checked, onChange, disabled, readOnly }) => (_jsx(PhiSwitchControl, { checked: checked, disabled: disabled, readOnly: readOnly, onChange: (nextChecked) => onChange?.(nextChecked) })),
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.switch, {
+            Control: ({ id, checked, controlLabel, onChange, disabled, readOnly }) => (_jsx(PhiSwitchControl, { id: id, checked: checked, label: controlLabel, disabled: disabled, readOnly: readOnly, onChange: (nextChecked) => onChange?.(nextChecked) })),
             valuePropName: "checked",
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[15],
-            Control: ({ value, onChange, options, disabled, readOnly }) => (_jsx(PhiSegmentedControl, { value: typeof value === "string" ? value : undefined, disabled: disabled, readOnly: readOnly, options: options ?? [], block: true, onChange: (nextValue) => onChange?.(nextValue) })),
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[16],
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.segmented, {
+            Control: PhiLazySegmentedFormControl,
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.cascader, {
             Control: PhiLazyCascaderFormControl,
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[17],
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.table, {
             Control: PhiLazyCompoundTableFormControl,
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[18],
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.tree, {
             Control: PhiLazyCompoundTreeFormControl,
-        },
-        {
-            ...PHI_SHARED_FORM_FIELD_TYPE_PROVIDER_DESCRIPTORS[19],
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.datetime, {
             Control: PhiLazyDateTimeFormControl,
-        },
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.upload, {
+            Control: PhiLazyUploadFormControl,
+        }),
+        phiSharedFieldType(PHI_FORM_FIELD_PROVIDER_KEYS.storageSize, {
+            Control: PhiLazyStorageSizeFormControl,
+        }),
     ],
     validationRules: [
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[0],
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.required, {
             createRule: ({ message }) => ({ required: true, message }),
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[1],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.email, {
             createRule: ({ message }) => ({ type: "email", message }),
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[2],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.minLength, {
             createRule: ({ rule, message }) => {
                 const min = typeof rule.config?.min === "number" ? rule.config.min : 0;
                 return { type: "string", min, message };
             },
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[3],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.minLetters, {
             createRule: ({ rule, message }) => {
                 const min = typeof rule.config?.min === "number" ? Math.max(1, Math.trunc(rule.config.min)) : 1;
                 return {
@@ -158,23 +182,20 @@ export const PHI_SHARED_FORM_PROVIDER_REGISTRY = createPhiFormProviderRegistry({
                     },
                 };
             },
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[4],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.maxLength, {
             createRule: ({ rule, message }) => {
                 const max = typeof rule.config?.max === "number" ? rule.config.max : Number.MAX_SAFE_INTEGER;
                 return { type: "string", max, message };
             },
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[5],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.exactLength, {
             createRule: ({ rule, message }) => {
                 const length = typeof rule.config?.length === "number" ? rule.config.length : 0;
                 return { type: "string", len: length, message };
             },
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[6],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.matchesField, {
             createRule: ({ rule, message }) => {
                 const field = typeof rule.config?.field === "string" ? rule.config.field : "";
                 if (!message) {
@@ -189,22 +210,19 @@ export const PHI_SHARED_FORM_PROVIDER_REGISTRY = createPhiFormProviderRegistry({
                     },
                 });
             },
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[7],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.url, {
             createRule: ({ message }) => ({ type: "url", message }),
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[8],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.tel, {
             createRule: ({ message }) => {
                 if (!message) {
                     throw new Error("Telephone validation requires a translated message because the active Ant Design locales do not provide one.");
                 }
                 return { type: "tel", message };
             },
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[9],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.pattern, {
             createRule: ({ rule, message }) => {
                 const source = typeof rule.config?.source === "string" ? rule.config.source : "";
                 const flags = typeof rule.config?.flags === "string" ? rule.config.flags : "";
@@ -216,9 +234,8 @@ export const PHI_SHARED_FORM_PROVIDER_REGISTRY = createPhiFormProviderRegistry({
                 }
                 return { pattern: new RegExp(source, flags), message };
             },
-        },
-        {
-            ...PHI_SHARED_FORM_VALIDATION_PROVIDER_DESCRIPTORS[10],
+        }),
+        phiSharedValidationRule(PHI_FORM_VALIDATION_PROVIDER_KEYS.number, {
             createRule: ({ rule, message }) => ({
                 async validator(_, value) {
                     if (value === undefined || value === null || value === "")
@@ -239,6 +256,6 @@ export const PHI_SHARED_FORM_PROVIDER_REGISTRY = createPhiFormProviderRegistry({
                     }
                 },
             }),
-        },
+        }),
     ],
 });

package/components/forms/site-locales-config.d.ts

@@ -0,0 +1,18 @@
+import type { PhiControlOption } from "../controls/phi-control-options";
+/**
+ * Where a placement puts the Site's locales for the field that offers them.
+ *
+ * Named once, because two sides have to agree on it and they are far apart: a Page preset writes the
+ * list into the Form Widget's placement config, and the options provider reads it back out during the
+ * render. A string spelled twice would be a list that is silently empty on one Site and not another.
+ */
+export declare const PHI_SITE_LOCALES_CONFIG_KEY = "availableLocales";
+/**
+ * The locales a placement handed over, as options a Control can draw.
+ *
+ * It reads what arrives rather than trusting it: the config crossed a Server/Client boundary as plain
+ * JSON, and a Page that named the key but held nothing gets an empty list, not a broken select. An entry
+ * with no code is no option at all, and one with no label is offered under its code -- which is what a
+ * locale is called before anybody translates its name.
+ */
+export declare function readPhiSiteLocaleOptions(sourceConfig: Record<string, unknown> | null | undefined): PhiControlOption[];

package/components/forms/site-locales-config.js

@@ -0,0 +1,35 @@
+/**
+ * Where a placement puts the Site's locales for the field that offers them.
+ *
+ * Named once, because two sides have to agree on it and they are far apart: a Page preset writes the
+ * list into the Form Widget's placement config, and the options provider reads it back out during the
+ * render. A string spelled twice would be a list that is silently empty on one Site and not another.
+ */
+export const PHI_SITE_LOCALES_CONFIG_KEY = "availableLocales";
+/**
+ * The locales a placement handed over, as options a Control can draw.
+ *
+ * It reads what arrives rather than trusting it: the config crossed a Server/Client boundary as plain
+ * JSON, and a Page that named the key but held nothing gets an empty list, not a broken select. An entry
+ * with no code is no option at all, and one with no label is offered under its code -- which is what a
+ * locale is called before anybody translates its name.
+ */
+export function readPhiSiteLocaleOptions(sourceConfig) {
+    const configured = sourceConfig?.[PHI_SITE_LOCALES_CONFIG_KEY];
+    if (!Array.isArray(configured)) {
+        return [];
+    }
+    return configured.flatMap((entry) => {
+        if (!entry || typeof entry !== "object") {
+            return [];
+        }
+        const { code, label } = entry;
+        if (typeof code !== "string" || !code.trim()) {
+            return [];
+        }
+        return [{
+                value: code,
+                label: typeof label === "string" && label.trim() ? label : code,
+            }];
+    });
+}

package/components/forms/storage-size.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A byte count shown as megabytes, and read back as bytes.
+ *
+ * Every storage limit in the system is stored, validated and enforced in bytes, and that is right: a
+ * byte is what a file weighs and what a quota counts. It is not what an administrator thinks in. A
+ * field asking for 52428800 is asking somebody to do arithmetic to find out whether it says fifty
+ * megabytes or five hundred, and to do it again every time they read the page.
+ *
+ * So the conversion lives here and nowhere else. The value a form holds is always bytes -- the
+ * Control converts on the way in and on the way out, so nothing downstream ever sees a half-converted
+ * number, and a submit handler needs to know nothing about units.
+ */
+/**
+ * A megabyte is 1 048 576 bytes here, not 1 000 000.
+ *
+ * The decimal reading is what the SI prefix means, and the binary one is what every tool that sets a
+ * storage limit uses: nginx's `client_max_body_size`, PHP's `upload_max_filesize`, `ls -lh`. The
+ * limits already stored were written by somebody counting in the binary one, so dividing by a million
+ * would show 50 MiB as "52.43" and quietly shrink the limit the moment somebody rounded it back down.
+ *
+ * The label still says MB, because "MiB" appears in no upload dialog an author has ever seen.
+ */
+export declare const PHI_STORAGE_SIZE_UNIT_BYTES = 1048576;
+export declare const PHI_STORAGE_SIZE_UNIT_LABEL = "MB";
+/**
+ * How precisely a size may be stated, in the unit above.
+ *
+ * Two places is about ten kilobytes, which is finer than any limit anybody sets on purpose and coarse
+ * enough that the field does not show a number like 4.76837158203125. A stored size that is not a
+ * round count of megabytes therefore displays rounded -- but it is only ever written back when
+ * somebody edits the field, so reading the page cannot change what it says.
+ */
+export declare const PHI_STORAGE_SIZE_PRECISION = 2;
+export declare function phiBytesToStorageSize(bytes: unknown): number | null;
+/** Bytes are whole, so the product is rounded rather than carried at whatever fraction it lands on. */
+export declare function phiStorageSizeToBytes(size: number | null): number | null;

package/components/forms/storage-size.js

@@ -0,0 +1,46 @@
+/**
+ * A byte count shown as megabytes, and read back as bytes.
+ *
+ * Every storage limit in the system is stored, validated and enforced in bytes, and that is right: a
+ * byte is what a file weighs and what a quota counts. It is not what an administrator thinks in. A
+ * field asking for 52428800 is asking somebody to do arithmetic to find out whether it says fifty
+ * megabytes or five hundred, and to do it again every time they read the page.
+ *
+ * So the conversion lives here and nowhere else. The value a form holds is always bytes -- the
+ * Control converts on the way in and on the way out, so nothing downstream ever sees a half-converted
+ * number, and a submit handler needs to know nothing about units.
+ */
+/**
+ * A megabyte is 1 048 576 bytes here, not 1 000 000.
+ *
+ * The decimal reading is what the SI prefix means, and the binary one is what every tool that sets a
+ * storage limit uses: nginx's `client_max_body_size`, PHP's `upload_max_filesize`, `ls -lh`. The
+ * limits already stored were written by somebody counting in the binary one, so dividing by a million
+ * would show 50 MiB as "52.43" and quietly shrink the limit the moment somebody rounded it back down.
+ *
+ * The label still says MB, because "MiB" appears in no upload dialog an author has ever seen.
+ */
+export const PHI_STORAGE_SIZE_UNIT_BYTES = 1_048_576;
+export const PHI_STORAGE_SIZE_UNIT_LABEL = "MB";
+/**
+ * How precisely a size may be stated, in the unit above.
+ *
+ * Two places is about ten kilobytes, which is finer than any limit anybody sets on purpose and coarse
+ * enough that the field does not show a number like 4.76837158203125. A stored size that is not a
+ * round count of megabytes therefore displays rounded -- but it is only ever written back when
+ * somebody edits the field, so reading the page cannot change what it says.
+ */
+export const PHI_STORAGE_SIZE_PRECISION = 2;
+export function phiBytesToStorageSize(bytes) {
+    if (typeof bytes !== "number" || !Number.isFinite(bytes))
+        return null;
+    const units = bytes / PHI_STORAGE_SIZE_UNIT_BYTES;
+    const factor = 10 ** PHI_STORAGE_SIZE_PRECISION;
+    return Math.round(units * factor) / factor;
+}
+/** Bytes are whole, so the product is rounded rather than carried at whatever fraction it lands on. */
+export function phiStorageSizeToBytes(size) {
+    if (typeof size !== "number" || !Number.isFinite(size))
+        return null;
+    return Math.round(size * PHI_STORAGE_SIZE_UNIT_BYTES);
+}

package/components/forms/upload-form-control.d.ts

@@ -0,0 +1,24 @@
+import type { PhiFormFieldProviderProps } from "./form-provider-registry";
+/**
+ * What the Form value is: the Media Asset ids the finished uploads left behind.
+ *
+ * Exported because a handler and a test read the same shape, and because the one thing a caller must not
+ * do is guess it from a sample payload.
+ */
+export declare function readPhiFormUploadAssetIds(value: unknown): readonly number[];
+/**
+ * The shared upload field Control: attach a file, watch it arrive, take it back out again.
+ *
+ * It owns no value of its own. Every upload that finishes appends its Asset id to the Form value and
+ * every removal takes one out, which is what keeps `required`, a reset and a re-render honest -- the same
+ * arrangement the compound Table field uses for the same reason. What it does keep locally is the part
+ * that is not a value: the transfer in progress and the sentence that a refusal produced.
+ *
+ * Emptiness is `undefined` rather than `[]`. Ant Design's required rule accepts an empty array, so a
+ * Form asking for a mandatory attachment would submit without one.
+ *
+ * The file name comes from the upload that is still in this Control's hands. An id that arrived as an
+ * initial value has no name here, and inventing one would mean reading the Media Asset -- a second
+ * contract inside a field provider, which is not this Control's to open.
+ */
+export declare function PhiUploadFormControl({ field, value, onChange, placeholder, labels, disabled, readOnly, formContext, }: PhiFormFieldProviderProps): import("react").JSX.Element;