@phis/contracts 0.4.0 → 0.5.0

package/dist/forms.js

@@ -0,0 +1,508 @@
+/**
+ * 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 { collectPhiRuntimeValueConditions, readPhiRuntimeConditionExpression, } from "./conditions.js";
+import { parsePhiControlOptionsProviderConfig, } from "./controls.js";
+import { isPhiSpacingToken, resolvePhiResponsiveValue, } from "./layout.js";
+import { isPhiRecord } from "./record.js";
+export const PHI_FORM_DESCRIPTOR_SCHEMA_VERSION = 1;
+/** The number of tracks every form grid is divided into. */
+export const PHI_FORM_GRID_TRACKS = 24;
+/** What a submit says where the descriptor names nothing: the form's own word for it, else "Submit". */
+export const PHI_FORM_DEFAULT_SUBMIT_LABEL = {
+    kind: "label",
+    key: "actions.submitLabel",
+    fallback: "Submit",
+};
+/** The last grid line, one past the last track, because `end` is exclusive. */
+export const PHI_FORM_GRID_LAST_LINE = PHI_FORM_GRID_TRACKS + 1;
+function readRequiredString(value, path) {
+    const normalized = typeof value === "string" ? value.trim() : "";
+    if (!normalized) {
+        throw new Error(`${path} must be a non-empty string.`);
+    }
+    return normalized;
+}
+function readOptionalString(value, path) {
+    if (value == null) {
+        return undefined;
+    }
+    return readRequiredString(value, path);
+}
+function readProviderKey(value, path) {
+    const key = readRequiredString(value, path);
+    if (!key.includes("/")) {
+        throw new Error(`${path} must use a namespaced package/key form.`);
+    }
+    return key;
+}
+function readTextDescriptor(value, path) {
+    if (!isPhiRecord(value)) {
+        throw new Error(`${path} must be a Form text descriptor.`);
+    }
+    if (value.kind === "literal") {
+        return { kind: "literal", value: typeof value.value === "string" ? value.value : "" };
+    }
+    if (value.kind === "label" || value.kind === "config") {
+        return {
+            kind: value.kind,
+            key: readRequiredString(value.key, `${path}.key`),
+            fallback: typeof value.fallback === "string" ? value.fallback : "",
+        };
+    }
+    throw new Error(`${path}.kind must be "literal", "label" or "config".`);
+}
+function readGridRange(value, path) {
+    if (value == null) {
+        return undefined;
+    }
+    if (!isPhiRecord(value)) {
+        throw new Error(`${path} must be a grid range object.`);
+    }
+    return assertPhiFormGridRange({
+        start: typeof value.start === "number" ? value.start : Number.NaN,
+        end: typeof value.end === "number" ? value.end : Number.NaN,
+    }, path);
+}
+function readResponsiveGridRange(value, path) {
+    if (value == null) {
+        return undefined;
+    }
+    if (!isPhiRecord(value)) {
+        throw new Error(`${path} must be a responsive grid range object.`);
+    }
+    return {
+        compact: readGridRange(value.compact, `${path}.compact`),
+        medium: readGridRange(value.medium, `${path}.medium`),
+        wide: readGridRange(value.wide, `${path}.wide`),
+    };
+}
+function readFormConditionExpression(value, path) {
+    if (value == null)
+        return undefined;
+    const expression = readPhiRuntimeConditionExpression(value);
+    if (!expression)
+        throw new Error(`${path} must be a valid runtime condition expression.`);
+    for (const condition of collectPhiRuntimeValueConditions(expression)) {
+        if (condition.source !== "form" && condition.source !== "controller") {
+            throw new Error(`${path} may use only form or controller condition sources.`);
+        }
+    }
+    return expression;
+}
+function readResponsiveGap(value, path) {
+    if (value == null)
+        return undefined;
+    if (!isPhiRecord(value))
+        throw new Error(`${path} must be a responsive spacing object.`);
+    const readToken = (entry, entryPath) => {
+        if (entry == null)
+            return undefined;
+        if (!isPhiSpacingToken(entry))
+            throw new Error(`${entryPath} must be a Phi spacing token.`);
+        return entry;
+    };
+    return {
+        compact: readToken(value.compact, `${path}.compact`),
+        medium: readToken(value.medium, `${path}.medium`),
+        wide: readToken(value.wide, `${path}.wide`),
+    };
+}
+function readValidationRule(value, path) {
+    if (!isPhiRecord(value)) {
+        throw new Error(`${path} must be a validation rule object.`);
+    }
+    return {
+        providerKey: readProviderKey(value.providerKey, `${path}.providerKey`),
+        message: value.message == null ? undefined : readTextDescriptor(value.message, `${path}.message`),
+        config: value.config == null
+            ? undefined
+            : isPhiRecord(value.config)
+                ? value.config
+                : (() => { throw new Error(`${path}.config must be an object.`); })(),
+    };
+}
+function readOption(value, path) {
+    if (!isPhiRecord(value)) {
+        throw new Error(`${path} must be an option object.`);
+    }
+    return {
+        value: readRequiredString(value.value, `${path}.value`),
+        label: readTextDescriptor(value.label, `${path}.label`),
+        description: value.description == null
+            ? undefined
+            : readTextDescriptor(value.description, `${path}.description`),
+        disabled: typeof value.disabled === "boolean" ? value.disabled : undefined,
+        icon: readOptionalString(value.icon, `${path}.icon`),
+    };
+}
+function assertUniqueKeys(items, path) {
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item.key)) {
+            throw new Error(`${path} contains duplicate key "${item.key}".`);
+        }
+        seen.add(item.key);
+    }
+}
+/**
+ * One part of a field's placement, which, once written, names a range for at least one mode.
+ *
+ * An empty part would read as "stated" and still say nothing, and a stated part decides that the field
+ * has no column for the other one -- that is too much to hang on an object with nothing in it.
+ */
+function readPlacementPart(value, path) {
+    const range = readResponsiveGridRange(value, path);
+    if (range && !range.compact && !range.medium && !range.wide) {
+        throw new Error(`${path} must state a range for at least one of compact, medium, or wide.`);
+    }
+    return range;
+}
+/**
+ * A field's own placement: both parts, one part, or none.
+ *
+ * One part is a statement of its own and not half of two: a field that names only its control has no
+ * label column and draws its label above the control inside that range, and one that names only its
+ * label has no control column. Nothing is taken from the layout for the part left out -- a control moved
+ * to 7-19 beside a layout label at 1-9 would overlap it and stack without anyone having asked for it.
+ */
+function readFieldPlacement(value, path) {
+    if (value == null) {
+        return undefined;
+    }
+    if (!isPhiRecord(value)) {
+        throw new Error(`${path} must be an object.`);
+    }
+    const label = readPlacementPart(value.label, `${path}.label`);
+    const control = readPlacementPart(value.control, `${path}.control`);
+    if (!label && !control) {
+        return undefined;
+    }
+    return { ...(label ? { label } : {}), ...(control ? { control } : {}) };
+}
+function readField(value, path) {
+    if (!isPhiRecord(value)) {
+        throw new Error(`${path} must be a field object.`);
+    }
+    const options = Array.isArray(value.options)
+        ? value.options.map((option, index) => readOption(option, `${path}.options[${index}]`))
+        : undefined;
+    if (options) {
+        const optionKeys = options.map((option) => ({ key: option.value }));
+        assertUniqueKeys(optionKeys, `${path}.options`);
+    }
+    const optionsProvider = value.optionsProvider == null
+        ? undefined
+        : parsePhiControlOptionsProviderConfig(value.optionsProvider);
+    if (value.optionsProvider != null && !optionsProvider) {
+        throw new Error(`${path}.optionsProvider is invalid.`);
+    }
+    if (value.config != null && !isPhiRecord(value.config)) {
+        throw new Error(`${path}.config must be an object.`);
+    }
+    const placement = readFieldPlacement(value.placement, `${path}.placement`);
+    return {
+        key: readRequiredString(value.key, `${path}.key`),
+        fieldProviderKey: readProviderKey(value.fieldProviderKey, `${path}.fieldProviderKey`),
+        label: value.label == null ? undefined : readTextDescriptor(value.label, `${path}.label`),
+        controlLabel: value.controlLabel == null
+            ? undefined
+            : readTextDescriptor(value.controlLabel, `${path}.controlLabel`),
+        description: value.description == null
+            ? undefined
+            : readTextDescriptor(value.description, `${path}.description`),
+        placeholder: value.placeholder == null
+            ? undefined
+            : readTextDescriptor(value.placeholder, `${path}.placeholder`),
+        autoComplete: readOptionalString(value.autoComplete, `${path}.autoComplete`),
+        initialValue: value.initialValue,
+        options,
+        optionsProvider,
+        validation: Array.isArray(value.validation)
+            ? value.validation.map((rule, index) => readValidationRule(rule, `${path}.validation[${index}]`))
+            : undefined,
+        visibleWhen: readFormConditionExpression(value.visibleWhen, `${path}.visibleWhen`),
+        disabledWhen: readFormConditionExpression(value.disabledWhen, `${path}.disabledWhen`),
+        placement,
+        config: value.config,
+    };
+}
+function readSubmit(value) {
+    if (value == null)
+        return undefined;
+    if (!isPhiRecord(value))
+        throw new Error("submit must be an object.");
+    const align = value.align;
+    if (align != null && align !== "start" && align !== "center" && align !== "end") {
+        throw new Error("submit.align must be start, center or end.");
+    }
+    const label = value.label == null ? undefined : readTextDescriptor(value.label, "submit.label");
+    const control = readPlacementPart(value.control, "submit.control");
+    return {
+        ...(label ? { label } : {}),
+        ...(align ? { align } : {}),
+        ...(control ? { control } : {}),
+    };
+}
+export function parsePhiFormDescriptor(value) {
+    if (!isPhiRecord(value)) {
+        throw new Error("Form descriptor must be an object.");
+    }
+    if (value.schemaVersion !== PHI_FORM_DESCRIPTOR_SCHEMA_VERSION) {
+        throw new Error(`Form descriptor schemaVersion must be ${PHI_FORM_DESCRIPTOR_SCHEMA_VERSION}.`);
+    }
+    if (!Array.isArray(value.fields)) {
+        throw new Error("Form descriptor fields must be an array.");
+    }
+    if ("actions" in value) {
+        /*
+         * A form has one submit and it is described under `submit`; whether it is drawn is the Form
+         * Widget's placement. A list of actions would be a second vocabulary for the same thing.
+         */
+        throw new Error("Form descriptor actions are forbidden; describe the submit under submit.");
+    }
+    if ("presentation" in value) {
+        throw new Error("Form descriptor presentation is forbidden; use the owning Layout or Overlay.");
+    }
+    const fields = value.fields.map((field, index) => readField(field, `fields[${index}]`));
+    assertUniqueKeys(fields, "fields");
+    const labelSetKey = value.labelSetKey == null
+        ? undefined
+        : readProviderKey(value.labelSetKey, "labelSetKey");
+    const layout = value.layout == null
+        ? undefined
+        : isPhiRecord(value.layout)
+            ? {
+                gap: readResponsiveGap(value.layout.gap, "layout.gap"),
+                columnGap: readResponsiveGap(value.layout.columnGap, "layout.columnGap"),
+                labelAlign: value.layout.labelAlign == null
+                    ? undefined
+                    : value.layout.labelAlign === "start" || value.layout.labelAlign === "end"
+                        ? value.layout.labelAlign
+                        : (() => { throw new Error("layout.labelAlign must be start or end."); })(),
+                label: readResponsiveGridRange(value.layout.label, "layout.label"),
+                control: readResponsiveGridRange(value.layout.control, "layout.control"),
+            }
+            : (() => { throw new Error("layout must be an object."); })();
+    if (layout) {
+        resolvePhiFormLayout(layout);
+    }
+    const success = value.success == null
+        ? undefined
+        : isPhiRecord(value.success)
+            ? {
+                title: readTextDescriptor(value.success.title, "success.title"),
+                text: value.success.text == null
+                    ? undefined
+                    : readTextDescriptor(value.success.text, "success.text"),
+                reset: value.success.reset == null ? undefined : value.success.reset === true,
+                complete: value.success.complete == null ? undefined : value.success.complete === true,
+            }
+            : (() => { throw new Error("success must be an object."); })();
+    const errors = value.errors == null
+        ? undefined
+        : isPhiRecord(value.errors)
+            ? Object.fromEntries(Object.entries(value.errors).map(([code, text]) => [
+                code,
+                readTextDescriptor(text, `errors.${code}`),
+            ]))
+            : (() => { throw new Error("errors must be an object."); })();
+    return {
+        schemaVersion: PHI_FORM_DESCRIPTOR_SCHEMA_VERSION,
+        key: readRequiredString(value.key, "key"),
+        labelSetKey,
+        fields,
+        layout,
+        success,
+        errors,
+        persistDraft: value.persistDraft == null ? undefined : value.persistDraft === true,
+        guard: value.guard == null ? undefined : value.guard === true,
+        submit: readSubmit(value.submit),
+    };
+}
+/**
+ * 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 const PHI_FORM_DEFAULT_LAYOUT = {
+    gap: {
+        compact: "sm",
+        medium: "base",
+        wide: "base",
+    },
+    labelAlign: "start",
+    label: {
+        compact: { start: 1, end: PHI_FORM_GRID_LAST_LINE },
+        medium: { start: 1, end: 9 },
+        wide: { start: 1, end: 9 },
+    },
+    control: {
+        compact: { start: 1, end: PHI_FORM_GRID_LAST_LINE },
+        medium: { start: 9, end: PHI_FORM_GRID_LAST_LINE },
+        wide: { start: 9, end: PHI_FORM_GRID_LAST_LINE },
+    },
+};
+/**
+ * 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 const PHI_FORM_ROW_FULL = {
+    compact: { start: 1, end: PHI_FORM_GRID_LAST_LINE },
+    medium: { start: 1, end: PHI_FORM_GRID_LAST_LINE },
+    wide: { start: 1, end: PHI_FORM_GRID_LAST_LINE },
+};
+export const PHI_FORM_ROW_END_HALF = {
+    compact: { start: 1, end: PHI_FORM_GRID_LAST_LINE },
+    medium: { start: 13, end: PHI_FORM_GRID_LAST_LINE },
+    wide: { start: 13, end: PHI_FORM_GRID_LAST_LINE },
+};
+/** Labels above their controls at every width: one range for both parts of every field. */
+export const PHI_FORM_STACKED_LAYOUT = {
+    label: PHI_FORM_ROW_FULL,
+    control: PHI_FORM_ROW_FULL,
+};
+export const PHI_FORM_STACKED_END_HALF = {
+    label: PHI_FORM_ROW_END_HALF,
+    control: PHI_FORM_ROW_END_HALF,
+};
+/** One field of a two-column form whose labels stand beside their controls. */
+export const PHI_FORM_SIDE_START_HALF = {
+    label: {
+        compact: { start: 1, end: 7 },
+        medium: { start: 1, end: 5 },
+        wide: { start: 1, end: 5 },
+    },
+    control: {
+        compact: { start: 7, end: PHI_FORM_GRID_LAST_LINE },
+        medium: { start: 5, end: 13 },
+        wide: { start: 5, end: 13 },
+    },
+};
+export const PHI_FORM_SIDE_END_HALF = {
+    label: {
+        compact: { start: 1, end: 7 },
+        medium: { start: 13, end: 17 },
+        wide: { start: 13, end: 17 },
+    },
+    control: {
+        compact: { start: 7, end: PHI_FORM_GRID_LAST_LINE },
+        medium: { start: 17, end: PHI_FORM_GRID_LAST_LINE },
+        wide: { start: 17, end: PHI_FORM_GRID_LAST_LINE },
+    },
+};
+/**
+ * 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 function phiFormFlowHalfColumns(fields) {
+    let atRowStart = true;
+    return fields.map((field) => {
+        const stated = [
+            statedPhiFormGridRange(field.placement?.label, "medium"),
+            statedPhiFormGridRange(field.placement?.control, "medium"),
+        ].filter((range) => range != null);
+        if (stated.length > 0) {
+            const claimsWholeRow = Math.min(...stated.map((range) => range.start)) === 1 &&
+                Math.max(...stated.map((range) => range.end)) === PHI_FORM_GRID_LAST_LINE;
+            atRowStart = claimsWholeRow ? true : !atRowStart;
+            return field;
+        }
+        const placement = atRowStart ? PHI_FORM_SIDE_START_HALF : PHI_FORM_SIDE_END_HALF;
+        atRowStart = !atRowStart;
+        return { ...field, placement };
+    });
+}
+/** A field that takes the whole row in a form that is otherwise two columns. */
+export const PHI_FORM_STACKED_FULL = {
+    label: PHI_FORM_ROW_FULL,
+    control: PHI_FORM_ROW_FULL,
+};
+export const PHI_FORM_RESPONSIVE_MODES = ["compact", "medium", "wide"];
+export function assertPhiFormGridRange(range, path) {
+    const { start, end } = range;
+    if (!Number.isInteger(start) || start < 1 || start > PHI_FORM_GRID_TRACKS) {
+        throw new Error(`${path}.start must be an integer from 1 to ${PHI_FORM_GRID_TRACKS}.`);
+    }
+    if (!Number.isInteger(end) || end < 2 || end > PHI_FORM_GRID_LAST_LINE) {
+        throw new Error(`${path}.end must be an integer from 2 to ${PHI_FORM_GRID_LAST_LINE}.`);
+    }
+    if (end <= start) {
+        throw new Error(`${path}.end must be greater than ${path}.start.`);
+    }
+    return { start, end };
+}
+export function createPhiFormLiteralText(value) {
+    return { kind: "literal", value };
+}
+export function createPhiFormLabelText(key, fallback) {
+    return { kind: "label", key, fallback };
+}
+export function resolvePhiFormText(text, labels, formConfig) {
+    if (text.kind === "literal") {
+        return text.value;
+    }
+    if (text.kind === "config") {
+        const value = formConfig?.[text.key];
+        return typeof value === "string" && value.trim() ? value : text.fallback;
+    }
+    return labels?.[text.key] ?? text.fallback;
+}
+export function assertPhiFormLabelSetKey(value) {
+    const normalized = value.trim();
+    if (!normalized || !normalized.includes("/")) {
+        throw new Error(`Form label-set key "${value}" must use a namespaced package/key form.`);
+    }
+}
+export function resolvePhiFormResponsiveGridRange(value, fallback, path) {
+    const resolved = resolvePhiResponsiveValue(value, fallback);
+    return {
+        compact: assertPhiFormGridRange(resolved.compact, `${path}.compact`),
+        medium: assertPhiFormGridRange(resolved.medium, `${path}.medium`),
+        wide: assertPhiFormGridRange(resolved.wide, `${path}.wide`),
+    };
+}
+export function resolvePhiFormLayout(layout) {
+    const gap = resolvePhiResponsiveValue(layout?.gap, PHI_FORM_DEFAULT_LAYOUT.gap);
+    return {
+        gap,
+        /*
+         * The row gap answers for the column gap where nobody stated one, so the default is the number the
+         * form already carries rather than a second constant that could drift away from it.
+         */
+        columnGap: resolvePhiResponsiveValue(layout?.columnGap, gap),
+        labelAlign: layout?.labelAlign ?? PHI_FORM_DEFAULT_LAYOUT.labelAlign,
+        label: resolvePhiFormResponsiveGridRange(layout?.label, PHI_FORM_DEFAULT_LAYOUT.label, "layout.label"),
+        control: resolvePhiFormResponsiveGridRange(layout?.control, PHI_FORM_DEFAULT_LAYOUT.control, "layout.control"),
+    };
+}
+/**
+ * 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 function statedPhiFormGridRange(value, mode) {
+    if (!value)
+        return undefined;
+    if (mode === "compact")
+        return value.compact;
+    if (mode === "medium")
+        return value.medium ?? value.compact;
+    return value.wide ?? value.medium ?? value.compact;
+}

package/dist/http.d.ts

@@ -1,7 +1,7 @@
 /**
  * The request headers phis and the site UI must spell the same way.
  *
- * These five names are a wire protocol between processes that deploy independently. phis reads them in
+ * These names are a wire protocol between processes that deploy independently. phis reads them in
  * its guards and route handlers; the site UI writes them in its proxies, gateways and browser widgets.
  * A disagreement is not a type error and not a failing test -- it is a 403 from `guardApiV1` or a 400
  * from `requireSiteFromExplicitKeyRequest`, at runtime, in whichever direction the mismatch happens to
@@ -31,3 +31,12 @@ export declare const PHIS_AREA_HEADER: "x-phis-area";
  */
 export declare const PHIS_REQUEST_PATH_HEADER: "x-phis-request-path";
 export declare const PHIS_REQUEST_SEARCH_HEADER: "x-phis-request-search";
+/**
+ * Marks a request the site UI's form relay forwards for a visitor.
+ *
+ * The relay calls phis with the internal token, and the internal token is exempt from the per-address
+ * limit because it measures a Site runtime rather than a person. This header tells phis that behind this
+ * one request stands a single visitor, so `guardApiV1` counts their submissions -- by session, or by
+ * address where there is none. Anybody may send it; all it can do is put the sender under a limit.
+ */
+export declare const PHIS_FORM_RELAY_HEADER: "x-phis-form-relay";

package/dist/http.js

@@ -1,7 +1,7 @@
 /**
  * The request headers phis and the site UI must spell the same way.
  *
- * These five names are a wire protocol between processes that deploy independently. phis reads them in
+ * These names are a wire protocol between processes that deploy independently. phis reads them in
  * its guards and route handlers; the site UI writes them in its proxies, gateways and browser widgets.
  * A disagreement is not a type error and not a failing test -- it is a 403 from `guardApiV1` or a 400
  * from `requireSiteFromExplicitKeyRequest`, at runtime, in whichever direction the mismatch happens to
@@ -31,3 +31,12 @@ export const PHIS_AREA_HEADER = "x-phis-area";
  */
 export const PHIS_REQUEST_PATH_HEADER = "x-phis-request-path";
 export const PHIS_REQUEST_SEARCH_HEADER = "x-phis-request-search";
+/**
+ * Marks a request the site UI's form relay forwards for a visitor.
+ *
+ * The relay calls phis with the internal token, and the internal token is exempt from the per-address
+ * limit because it measures a Site runtime rather than a person. This header tells phis that behind this
+ * one request stands a single visitor, so `guardApiV1` counts their submissions -- by session, or by
+ * address where there is none. Anybody may send it; all it can do is put the sender under a limit.
+ */
+export const PHIS_FORM_RELAY_HEADER = "x-phis-form-relay";

package/dist/layout.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The layout vocabulary stored descriptors are written in: a value per measured width, and the named
+ * spacing steps.
+ *
+ * Here rather than in the site UI because a Form descriptor is stored by phis-server and states its
+ * gaps and ranges in these terms, so the server has to read them the way the renderer does.
+ */
+export type PhiResponsiveValue<TValue> = {
+    compact?: TValue;
+    medium?: TValue;
+    wide?: TValue;
+};
+export type PhiResolvedResponsiveValue<TValue> = {
+    compact: TValue;
+    medium: TValue;
+    wide: TValue;
+};
+/** A stated value cascades upwards to the wider modes; the fallback answers only where nothing is. */
+export declare function resolvePhiResponsiveValue<TValue>(value: PhiResponsiveValue<TValue> | undefined, fallback: PhiResolvedResponsiveValue<TValue>): PhiResolvedResponsiveValue<TValue>;
+export declare const PHI_SPACING_TOKENS: readonly ["none", "xxs", "xs", "sm", "base", "md", "lg", "xl", "xxl"];
+export type PhiSpacingToken = (typeof PHI_SPACING_TOKENS)[number];
+export declare function isPhiSpacingToken(value: unknown): value is PhiSpacingToken;

package/dist/layout.js

@@ -0,0 +1,30 @@
+/**
+ * The layout vocabulary stored descriptors are written in: a value per measured width, and the named
+ * spacing steps.
+ *
+ * Here rather than in the site UI because a Form descriptor is stored by phis-server and states its
+ * gaps and ranges in these terms, so the server has to read them the way the renderer does.
+ */
+/** A stated value cascades upwards to the wider modes; the fallback answers only where nothing is. */
+export function resolvePhiResponsiveValue(value, fallback) {
+    if (!value)
+        return fallback;
+    const compact = value.compact ?? fallback.compact;
+    const medium = value.medium ?? (value.compact === undefined ? fallback.medium : compact);
+    const wide = value.wide ?? (value.medium === undefined && value.compact === undefined ? fallback.wide : medium);
+    return { compact, medium, wide };
+}
+export const PHI_SPACING_TOKENS = [
+    "none",
+    "xxs",
+    "xs",
+    "sm",
+    "base",
+    "md",
+    "lg",
+    "xl",
+    "xxl",
+];
+export function isPhiSpacingToken(value) {
+    return typeof value === "string" && PHI_SPACING_TOKENS.includes(value);
+}

package/dist/record.d.ts

@@ -0,0 +1,8 @@
+export declare function isPhiRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * The value a dotted path names inside a record: `"author.name"` reads `input.author.name`.
+ *
+ * Empty segments are skipped, so `""` names the input itself, and only records are walked -- an array
+ * or a primitive on the way ends the walk with `undefined` rather than being indexed into.
+ */
+export declare function readPhiDotPath(input: unknown, path: string): unknown;

package/dist/record.js

@@ -0,0 +1,24 @@
+/*
+ * Shared by the parsers of this package and not exported from it: each consumer keeps its own, and
+ * the one question they all answer is settled the same way -- an array is not a keyed record.
+ */
+export function isPhiRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * The value a dotted path names inside a record: `"author.name"` reads `input.author.name`.
+ *
+ * Empty segments are skipped, so `""` names the input itself, and only records are walked -- an array
+ * or a primitive on the way ends the walk with `undefined` rather than being indexed into.
+ */
+export function readPhiDotPath(input, path) {
+    let current = input;
+    for (const segment of path.split(".")) {
+        if (!segment)
+            continue;
+        if (!isPhiRecord(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}