@phis/contracts 0.4.0 → 0.6.0

package/dist/forms.d.ts

@@ -0,0 +1,496 @@
+/**
+ * The Form descriptor: what a form's fields are, how they are laid out on its grid, what it says when
+ * it succeeds or is refused -- and the one parser that decides whether a stored value is one.
+ *
+ * A descriptor is written by a Module's preset or by the Form Builder, stored by phis-server and drawn
+ * by the site UI. All three read it here, so a descriptor the server accepts is one the renderer can
+ * draw, and the other way round. What stays in the UI is how the grid becomes CSS.
+ */
+import { type PhiRuntimeConditionExpression } from "./conditions.js";
+import { type PhiControlOption, type PhiControlOptionsProviderConfig } from "./controls.js";
+import { type PhiResponsiveValue, type PhiSpacingToken } from "./layout.js";
+export type PhiFormProviderKey = `${string}/${string}`;
+export type PhiFormLabelSetKey = `${string}/${string}`;
+export declare const PHI_FORM_DESCRIPTOR_SCHEMA_VERSION: 1;
+/**
+ * Where a piece of a form's wording comes from.
+ *
+ * `literal` is the word itself. `label` is a key into the form's label set, which is how anything a
+ * visitor reads gets translated. `config` is a value the Widget was placed with -- the target of a
+ * consent link, say, which is a property of where the form stands rather than of the form: the same
+ * registration form points at one site's terms in one Area and another's elsewhere, and only the
+ * placement knows which, and in which language's path.
+ */
+export type PhiFormTextDescriptor = {
+    kind: "literal";
+    value: string;
+} | {
+    kind: "label";
+    key: string;
+    fallback: string;
+} | {
+    kind: "config";
+    key: string;
+    fallback: string;
+};
+/** The number of tracks every form grid is divided into. */
+export declare const PHI_FORM_GRID_TRACKS: 24;
+/**
+ * Where one element lies on the form grid, written the way CSS Grid writes it: `start` is the line the
+ * element begins at and `end` is the line it stops before, both counted from 1, so the last line is 25.
+ *
+ * A range rather than a width, because a width can only say how much room something takes and never
+ * where the room is. A label at 1-7 with an input at 7-19 leaves 19-25 empty, and a tool button can
+ * then say 21-25 and stand in that gap on the same row -- neither of which a span can express. Ranges
+ * also carry the responsive case without a second concept: a label at 1-25 above an input at 1-25 is
+ * the stacked form, because two elements that both claim the whole width cannot share a row.
+ */
+export type PhiFormGridRange = {
+    /** First line the element occupies, 1 to 24. */
+    start: number;
+    /** Line the element stops before, 2 to 25. Exclusive, as in CSS. */
+    end: number;
+};
+export type PhiFormResponsiveGridRange = PhiResponsiveValue<PhiFormGridRange>;
+export type PhiFormLogicalAlignment = "start" | "center" | "end";
+/**
+ * What a form's rows look like where a field says nothing of its own.
+ *
+ * There is no `columns` and no `labelPlacement` here any more: a two-column form is fields whose
+ * ranges lie in 1-13 and 13-25, and a stacked form is a label whose range is the full width. One
+ * mechanism decides all of it, and the responsive sets decide it per measured width.
+ */
+export type PhiFormLayoutDescriptor = {
+    gap?: PhiResponsiveValue<PhiSpacingToken>;
+    /**
+     * What stands between two columns of a row, where a row has two.
+     *
+     * The grid's own `column-gap` cannot say this: it would fall between every pair of adjacent elements,
+     * so a label beside its control would be pushed away from it by the same amount that separates one
+     * field from the next -- and that distance is already said, per cell, as the label's own gutter. This
+     * is the other distance, and it is laid on the cell that opens a column: a field placed at 13-25 is
+     * moved off the field placed at 1-13, and one placed at 1-13 is not moved at all.
+     *
+     * Absent, it follows `gap`: the space between two fields side by side is the space between two fields
+     * one above the other, which is the reading that needs no second number. A row's two columns are then
+     * further apart than a label is from its own control, which is half of it -- the hierarchy a
+     * two-column form needs to read as two columns.
+     */
+    columnGap?: PhiResponsiveValue<PhiSpacingToken>;
+    labelAlign?: Exclude<PhiFormLogicalAlignment, "center">;
+    label?: PhiFormResponsiveGridRange;
+    control?: PhiFormResponsiveGridRange;
+};
+/**
+ * Where this one field's parts lie, overriding the layout's defaults.
+ *
+ * `label` and `control` are column ranges on the 24-track grid, not content, and each mode is decided
+ * from what is stated for it:
+ * - both: the label in its range, the control in its range;
+ * - only `control`: the field has no label column. The control takes exactly that range, and a label,
+ *   where the field has one, stands above it inside the same range;
+ * - only `label`: the field has no control column. The label takes exactly that range, and whatever the
+ *   field draws as its control stands under it inside the same range;
+ * - neither, or no placement: the layout's ranges.
+ *
+ * The part left out is never taken from the layout: a control moved to 7-19 beside a layout label at 1-9
+ * would overlap it and fall onto a second row without anyone having asked for it.
+ *
+ * Elements are placed in declaration order and CSS Grid does not go back to fill a gap it has passed,
+ * so a field meant to stand beside the one before it is declared after it and the row fills from the
+ * inline start. That is the whole ordering rule.
+ */
+export type PhiFormFieldPlacementDescriptor = {
+    label?: PhiFormResponsiveGridRange;
+    control?: PhiFormResponsiveGridRange;
+};
+export type PhiFormValidationRuleDescriptor = {
+    providerKey: PhiFormProviderKey;
+    message?: PhiFormTextDescriptor;
+    config?: Record<string, unknown>;
+};
+export type PhiFormOptionDescriptor = Omit<PhiControlOption, "label" | "description"> & {
+    label: PhiFormTextDescriptor;
+    description?: PhiFormTextDescriptor;
+};
+export type PhiFormFieldDescriptor = {
+    key: string;
+    fieldProviderKey: PhiFormProviderKey;
+    label?: PhiFormTextDescriptor;
+    controlLabel?: PhiFormTextDescriptor;
+    description?: PhiFormTextDescriptor;
+    placeholder?: PhiFormTextDescriptor;
+    autoComplete?: string;
+    initialValue?: unknown;
+    options?: readonly PhiFormOptionDescriptor[];
+    optionsProvider?: PhiControlOptionsProviderConfig | null;
+    validation?: readonly PhiFormValidationRuleDescriptor[];
+    visibleWhen?: PhiRuntimeConditionExpression;
+    disabledWhen?: PhiRuntimeConditionExpression;
+    placement?: PhiFormFieldPlacementDescriptor;
+    config?: Record<string, unknown>;
+};
+/**
+ * What a form shows when a submit is accepted.
+ *
+ * Declared rather than coded, because every form that submits to a handler has this moment and each of
+ * them used to answer it in its own component: the Contact form with a toast, the Registration with an
+ * alert, each with its own wording and its own idea of whether the fields stay filled in.
+ *
+ * Absent means the form says nothing of its own. That is the right answer wherever something else is
+ * listening -- a Controller that closes an Overlay on `submitSuccess`, a page that navigates away.
+ */
+/**
+ * What the form's own submit looks like, where one is drawn.
+ *
+ * Whether one is drawn is not said here. That is the placement's question: the same form stands on a
+ * page of its own with a button under its fields, and in a dialog whose footer carries the button --
+ * or with no button anywhere, submitted by a Button Widget through the `submit` capability, or by
+ * Enter where the placement allows it. The Form Widget answers it (`inline` or `external`); the form
+ * answers only what its button says and where on its grid it stands, because that is geometry of the
+ * same grid its fields are laid out on.
+ */
+export type PhiFormSubmitDescriptor = {
+    /** What it says. Absent is `PHI_FORM_DEFAULT_SUBMIT_LABEL`. */
+    label?: PhiFormTextDescriptor;
+    /** Where inside its range it sits. Absent is `start`: under the first input, where the eye is. */
+    align?: PhiFormLogicalAlignment;
+    /**
+     * The tracks it stands on. Absent is the layout's control range -- the tracks a field that says
+     * nothing about itself puts its control on, including the label column a Form Layout may move.
+     */
+    control?: PhiFormResponsiveGridRange;
+};
+/** What a submit says where the descriptor names nothing: the form's own word for it, else "Submit". */
+export declare const PHI_FORM_DEFAULT_SUBMIT_LABEL: {
+    readonly kind: "label";
+    readonly key: "actions.submitLabel";
+    readonly fallback: "Submit";
+};
+export type PhiFormSuccessDescriptor = {
+    title: PhiFormTextDescriptor;
+    text?: PhiFormTextDescriptor;
+    /** Whether the fields go back to their initial values, ready for another entry. */
+    reset?: boolean;
+    /**
+     * Whether the form has done its one job once it succeeds: the success stays, the fields and the
+     * Widget's submit go. A confirmation link is spent by its first submit, and a button left standing
+     * would only offer to spend it again.
+     */
+    complete?: boolean;
+};
+export type PhiFormDescriptor = {
+    schemaVersion: typeof PHI_FORM_DESCRIPTOR_SCHEMA_VERSION;
+    key: string;
+    labelSetKey?: PhiFormLabelSetKey;
+    fields: readonly PhiFormFieldDescriptor[];
+    layout?: PhiFormLayoutDescriptor;
+    success?: PhiFormSuccessDescriptor;
+    /**
+     * What the form says when the server refuses it, by the `code` that refusal carries.
+     *
+     * The counterpart of `success`, and there for the same reason: what a visitor reads has to be in
+     * their language, and a response body cannot be. A handler answers `{ code: "invalid_credentials" }`
+     * and the wording is looked up here, in the form's own label set. A code nothing maps falls back to
+     * the body's `error` line, which is English because its other reader is a log.
+     */
+    errors?: Readonly<Record<string, PhiFormTextDescriptor>>;
+    /**
+     * Whether what has been typed survives leaving the page, for as long as the tab is open.
+     *
+     * For the long form somebody fills in once and would have to fill in again after following a link to
+     * read the terms. Session storage, never local: a half-finished registration on a shared machine is
+     * not something to leave behind, and it is cleared the moment the form is accepted.
+     */
+    persistDraft?: boolean;
+    /**
+     * That the server accepts this form only with a guard token: `issuedAt` and `formToken`, signed by
+     * phis-server when the form was shown and refused if it comes back too fast or too late.
+     *
+     * The browser asks for the token when the form mounts (`/api/site/forms?phase=guard`) and adds it to
+     * what it submits. It is not rendered into the page, so a page with a guarded form is the same for
+     * every visitor and can be cached.
+     */
+    guard?: boolean;
+    submit?: PhiFormSubmitDescriptor;
+};
+/** The last grid line, one past the last track, because `end` is exclusive. */
+export declare const PHI_FORM_GRID_LAST_LINE: number;
+export declare function parsePhiFormDescriptor(value: unknown): PhiFormDescriptor;
+/**
+ * What a form looks like when it says nothing: labels beside their controls at a third of the width,
+ * and stacked once the form is measured narrow, which is the one place a label beside a short input
+ * leaves the input no room. Line 9 of 24 is the third; the control takes everything after it.
+ *
+ * A third is the house column, the one the Login states for itself in `PHI_LOGIN_FORM_LAYOUT_CONFIG`:
+ * eight tracks hold a two-word label without wrapping it, and sixteen still read as the wider half.
+ */
+export declare const PHI_FORM_DEFAULT_LAYOUT: {
+    readonly gap: {
+        readonly compact: "sm";
+        readonly medium: "base";
+        readonly wide: "base";
+    };
+    readonly labelAlign: "start";
+    readonly label: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 1;
+            readonly end: 9;
+        };
+        readonly wide: {
+            readonly start: 1;
+            readonly end: 9;
+        };
+    };
+    readonly control: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 9;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 9;
+            readonly end: number;
+        };
+    };
+};
+/**
+ * The ranges a form reaches for again and again, named once.
+ *
+ * A field written as the same range for its label and its control is a stacked field, because the two
+ * cannot share a row; the half-width pairs are how a two-column form is said now that `columns` is
+ * gone. All three collapse to the full width when the form is measured narrow, which is the only
+ * width at which two columns of anything are worse than one.
+ */
+export declare const PHI_FORM_ROW_FULL: {
+    readonly compact: {
+        readonly start: 1;
+        readonly end: number;
+    };
+    readonly medium: {
+        readonly start: 1;
+        readonly end: number;
+    };
+    readonly wide: {
+        readonly start: 1;
+        readonly end: number;
+    };
+};
+export declare const PHI_FORM_ROW_END_HALF: {
+    readonly compact: {
+        readonly start: 1;
+        readonly end: number;
+    };
+    readonly medium: {
+        readonly start: 13;
+        readonly end: number;
+    };
+    readonly wide: {
+        readonly start: 13;
+        readonly end: number;
+    };
+};
+/** Labels above their controls at every width: one range for both parts of every field. */
+export declare const PHI_FORM_STACKED_LAYOUT: {
+    readonly label: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 1;
+            readonly end: number;
+        };
+    };
+    readonly control: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 1;
+            readonly end: number;
+        };
+    };
+};
+export declare const PHI_FORM_STACKED_END_HALF: {
+    readonly label: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 13;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 13;
+            readonly end: number;
+        };
+    };
+    readonly control: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 13;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 13;
+            readonly end: number;
+        };
+    };
+};
+/** One field of a two-column form whose labels stand beside their controls. */
+export declare const PHI_FORM_SIDE_START_HALF: {
+    readonly label: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: 7;
+        };
+        readonly medium: {
+            readonly start: 1;
+            readonly end: 5;
+        };
+        readonly wide: {
+            readonly start: 1;
+            readonly end: 5;
+        };
+    };
+    readonly control: {
+        readonly compact: {
+            readonly start: 7;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 5;
+            readonly end: 13;
+        };
+        readonly wide: {
+            readonly start: 5;
+            readonly end: 13;
+        };
+    };
+};
+export declare const PHI_FORM_SIDE_END_HALF: {
+    readonly label: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: 7;
+        };
+        readonly medium: {
+            readonly start: 13;
+            readonly end: 17;
+        };
+        readonly wide: {
+            readonly start: 13;
+            readonly end: 17;
+        };
+    };
+    readonly control: {
+        readonly compact: {
+            readonly start: 7;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 17;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 17;
+            readonly end: number;
+        };
+    };
+};
+/**
+ * Two columns filled the way a grid fills them, for a form long enough that saying it per field would
+ * be a list of alternations nobody can read or keep correct.
+ *
+ * A field that brings its own placement keeps it and, where it takes the whole width, starts the next
+ * field on a fresh row -- which is what the grid did when the column count decided this and not the
+ * field. Authoring sugar over the contract, never a second contract: what it produces is ordinary
+ * per-field placement.
+ */
+export declare function phiFormFlowHalfColumns(fields: readonly PhiFormFieldDescriptor[]): PhiFormFieldDescriptor[];
+/** A field that takes the whole row in a form that is otherwise two columns. */
+export declare const PHI_FORM_STACKED_FULL: {
+    readonly label: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 1;
+            readonly end: number;
+        };
+    };
+    readonly control: {
+        readonly compact: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly medium: {
+            readonly start: 1;
+            readonly end: number;
+        };
+        readonly wide: {
+            readonly start: 1;
+            readonly end: number;
+        };
+    };
+};
+export type PhiResolvedFormResponsiveGridRange = {
+    compact: PhiFormGridRange;
+    medium: PhiFormGridRange;
+    wide: PhiFormGridRange;
+};
+export declare const PHI_FORM_RESPONSIVE_MODES: readonly ["compact", "medium", "wide"];
+export type PhiFormResponsiveMode = (typeof PHI_FORM_RESPONSIVE_MODES)[number];
+export type PhiResolvedFormLayout = {
+    gap: {
+        compact: PhiSpacingToken;
+        medium: PhiSpacingToken;
+        wide: PhiSpacingToken;
+    };
+    columnGap: {
+        compact: PhiSpacingToken;
+        medium: PhiSpacingToken;
+        wide: PhiSpacingToken;
+    };
+    labelAlign: "start" | "end";
+    label: PhiResolvedFormResponsiveGridRange;
+    control: PhiResolvedFormResponsiveGridRange;
+};
+export declare function assertPhiFormGridRange(range: PhiFormGridRange, path: string): PhiFormGridRange;
+export declare function createPhiFormLiteralText(value: string): PhiFormTextDescriptor;
+export declare function createPhiFormLabelText(key: string, fallback: string): PhiFormTextDescriptor;
+export declare function resolvePhiFormText(text: PhiFormTextDescriptor, labels?: Readonly<Record<string, string>>, formConfig?: Readonly<Record<string, unknown>>): string;
+export declare function assertPhiFormLabelSetKey(value: string): asserts value is PhiFormLabelSetKey;
+export declare function resolvePhiFormResponsiveGridRange(value: PhiFormResponsiveGridRange | undefined, fallback: PhiResolvedFormResponsiveGridRange, path: string): PhiResolvedFormResponsiveGridRange;
+export declare function resolvePhiFormLayout(layout?: PhiFormLayoutDescriptor): PhiResolvedFormLayout;
+/**
+ * The range one part of a placement states for one mode, cascading only from the smaller modes of that
+ * same part -- never from the layout, which is the other part's business to decide.
+ */
+export declare function statedPhiFormGridRange(value: PhiFormResponsiveGridRange | undefined, mode: PhiFormResponsiveMode): PhiFormGridRange | undefined;