@lapismd/design-core 0.2.0 → 0.3.1

package/dist/shared/forms/core/patch-review.js

@@ -0,0 +1,377 @@
+import { applyJsonPatch, pointerParts, pointerValue, } from "./json-patch";
+export function pendingReviewChanges(review) {
+    return review?.changes.filter((change) => change.status === "pending") ?? [];
+}
+export function activeReviewChanges(review) {
+    return review?.changes.filter((change) => change.status !== "rejected") ?? [];
+}
+export function acceptedReviewChanges(review) {
+    return review?.changes.filter((change) => change.status === "accepted") ?? [];
+}
+export function summarizeReviewChanges(review) {
+    return (review?.changes.map((change) => ({
+        id: change.id,
+        proposalId: change.proposalId,
+        title: change.title,
+        status: change.status,
+        paths: change.paths,
+    })) ?? []);
+}
+function now() {
+    return new Date().toISOString();
+}
+function operationPaths(operations) {
+    return Array.from(new Set(operations.map((operation) => operation.path)));
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function operationSignature(operation) {
+    return operation.op === "remove"
+        ? `${operation.op}:${operation.path}`
+        : `${operation.op}:${operation.path}:${stableStringify(operation.value)}`;
+}
+function changeSignature(operations) {
+    return operations.map(operationSignature).sort().join("|");
+}
+function encodePointerSegment(segment) {
+    return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function pathContains(parent, child) {
+    return child === parent || child.startsWith(`${parent}/`);
+}
+function valuesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function isComplexValue(value) {
+    return Boolean(value && typeof value === "object");
+}
+function childPath(path, key) {
+    return `${path}/${encodePointerSegment(String(key))}`;
+}
+function diffComplexValue(before, after, path) {
+    if (valuesEqual(before, after))
+        return [];
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const operations = [];
+        const sharedLength = Math.min(before.length, after.length);
+        for (let index = 0; index < sharedLength; index += 1) {
+            operations.push(...diffComplexValue(before[index], after[index], childPath(path, index)));
+        }
+        for (let index = before.length - 1; index >= after.length; index -= 1) {
+            operations.push({ op: "remove", path: childPath(path, index) });
+        }
+        for (let index = before.length; index < after.length; index += 1) {
+            operations.push({
+                op: "add",
+                path: childPath(path, index),
+                value: after[index],
+            });
+        }
+        return operations;
+    }
+    if (before &&
+        after &&
+        typeof before === "object" &&
+        typeof after === "object" &&
+        !Array.isArray(before) &&
+        !Array.isArray(after)) {
+        const operations = [];
+        const beforeRecord = before;
+        const afterRecord = after;
+        const keys = Array.from(new Set([...Object.keys(beforeRecord), ...Object.keys(afterRecord)]));
+        for (const key of keys) {
+            const pathForKey = childPath(path, key);
+            if (!(key in afterRecord)) {
+                operations.push({ op: "remove", path: pathForKey });
+            }
+            else if (!(key in beforeRecord)) {
+                operations.push({
+                    op: "add",
+                    path: pathForKey,
+                    value: afterRecord[key],
+                });
+            }
+            else {
+                operations.push(...diffComplexValue(beforeRecord[key], afterRecord[key], pathForKey));
+            }
+        }
+        return operations;
+    }
+    return [{ op: "replace", path, value: after }];
+}
+function expandOperationForReview(baseSource, operation) {
+    if (operation.op !== "replace" || !isComplexValue(operation.value)) {
+        return [operation];
+    }
+    const before = pointerValue(baseSource, operation.path);
+    if (!isComplexValue(before))
+        return [operation];
+    const expanded = diffComplexValue(before, operation.value, operation.path);
+    return expanded.length ? expanded : [operation];
+}
+function expandOperationsForReview(baseSource, operations) {
+    return operations.flatMap((operation) => expandOperationForReview(baseSource, operation));
+}
+function jsonPointerPartsExist(root, parts) {
+    let target = root;
+    for (const part of parts) {
+        if (Array.isArray(target)) {
+            const index = Number(part);
+            if (!Number.isInteger(index) || index < 0 || index >= target.length) {
+                return false;
+            }
+            target = target[index];
+        }
+        else if (target && typeof target === "object") {
+            if (!(part in target))
+                return false;
+            target = target[part];
+        }
+        else {
+            return false;
+        }
+    }
+    return true;
+}
+export function normalizeJsonReviewOperations(baseSource, operations) {
+    return operations.map((operation) => {
+        if (operation.op !== "replace")
+            return operation;
+        const parts = pointerParts(operation.path);
+        if (jsonPointerPartsExist(baseSource, parts))
+            return operation;
+        if (!jsonPointerPartsExist(baseSource, parts.slice(0, -1)))
+            return operation;
+        return { op: "add", path: operation.path, value: operation.value };
+    });
+}
+function operationsAreRelated(left, right) {
+    return left.some((leftOperation) => right.some((rightOperation) => pathContains(leftOperation.path, rightOperation.path) ||
+        pathContains(rightOperation.path, leftOperation.path)));
+}
+function splitProposalOperations(operations) {
+    const groups = [];
+    for (const operation of operations) {
+        const relatedIndexes = groups
+            .map((group, index) => operationsAreRelated(group, [operation]) ? index : -1)
+            .filter((index) => index >= 0);
+        if (!relatedIndexes.length) {
+            groups.push([operation]);
+            continue;
+        }
+        const firstIndex = relatedIndexes[0];
+        if (firstIndex === undefined)
+            continue;
+        const restIndexes = relatedIndexes.slice(1);
+        const firstGroup = groups[firstIndex];
+        if (!firstGroup)
+            continue;
+        firstGroup.push(operation);
+        for (const index of restIndexes.reverse()) {
+            const group = groups[index];
+            if (!group)
+                continue;
+            firstGroup.push(...group);
+            groups.splice(index, 1);
+        }
+    }
+    return groups;
+}
+function dedupeReviewChanges(changes) {
+    const seen = new Set();
+    const deduped = [];
+    for (const change of changes) {
+        const signature = changeSignature(change.operations);
+        if (seen.has(signature))
+            continue;
+        seen.add(signature);
+        deduped.push(change);
+    }
+    return deduped;
+}
+function changeTitle(proposal, operations, index) {
+    if (proposal.operations.length === operations.length) {
+        return proposal.title || "Proposed change";
+    }
+    const path = operationPaths(operations)[0] ?? "/";
+    const label = path
+        .split("/")
+        .filter(Boolean)
+        .at(-1)
+        ?.replace(/_/g, " ")
+        .replace(/\b\w/g, (letter) => letter.toUpperCase()) ??
+        `Change ${index + 1}`;
+    return label || `Change ${index + 1}`;
+}
+function isRootPath(path, requiredRoot) {
+    return path === `/${requiredRoot}` || path.startsWith(`/${requiredRoot}/`);
+}
+function assertOperationsForRoot(operations, requiredRoot) {
+    if (!requiredRoot)
+        return;
+    for (const operation of operations) {
+        if (!isRootPath(operation.path, requiredRoot)) {
+            throw new Error(`Patch path must target /${requiredRoot}: ${operation.path}`);
+        }
+    }
+}
+export function setReviewChangeStatus(review, changeId, status) {
+    const timestamp = now();
+    return {
+        ...review,
+        updatedAt: timestamp,
+        changes: review.changes.map((change) => change.id === changeId
+            ? { ...change, status, updatedAt: timestamp }
+            : change),
+    };
+}
+export function setReviewProposalStatus(review, proposalId, status) {
+    const timestamp = now();
+    return {
+        ...review,
+        updatedAt: timestamp,
+        changes: review.changes.map((change) => change.proposalId === proposalId
+            ? { ...change, status, updatedAt: timestamp }
+            : change),
+    };
+}
+export function proposalReviewStatus(review, proposalId) {
+    const changes = review?.changes.filter((change) => change.proposalId === proposalId) ?? [];
+    if (!changes.length)
+        return null;
+    if (changes.some((change) => change.status === "pending"))
+        return "pending";
+    if (changes.every((change) => change.status === "accepted"))
+        return "accepted";
+    if (changes.every((change) => change.status === "rejected"))
+        return "rejected";
+    return "mixed";
+}
+export function setAllReviewChangesStatus(review, status) {
+    const timestamp = now();
+    return {
+        ...review,
+        updatedAt: timestamp,
+        changes: review.changes.map((change) => ({
+            ...change,
+            status,
+            updatedAt: timestamp,
+        })),
+    };
+}
+export function reviewOperations(review, statuses) {
+    if (!review)
+        return [];
+    const allowed = new Set(statuses);
+    return review.changes
+        .filter((change) => allowed.has(change.status))
+        .flatMap((change) => change.operations);
+}
+export function reviewIsResolved(review) {
+    return Boolean(review && review.changes.every((change) => change.status !== "pending"));
+}
+export function createOrAppendJsonReview(review, fileId, baseValue, proposal, requiredRoot) {
+    if (!proposal.valid) {
+        throw new Error("Only valid proposals can be reviewed.");
+    }
+    if (!proposal.operations.length) {
+        throw new Error("Proposal did not include patch operations.");
+    }
+    assertOperationsForRoot(proposal.operations, requiredRoot);
+    if (review &&
+        (review.fileId !== fileId || review.requiredRoot !== requiredRoot)) {
+        throw new Error("Resolve pending changes before switching targets.");
+    }
+    const operations = expandOperationsForReview(baseValue, normalizeJsonReviewOperations(baseValue, proposal.operations));
+    const timestamp = now();
+    const nextReview = review ??
+        {
+            fileId,
+            ...(requiredRoot ? { requiredRoot } : {}),
+            baseValue,
+            ...(proposal.base?.sourceHash
+                ? { baseValueHash: proposal.base.sourceHash }
+                : {}),
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            changes: [],
+        };
+    if (nextReview.changes.some((change) => change.proposalId === proposal.id)) {
+        return nextReview;
+    }
+    const changeGroups = splitProposalOperations(operations);
+    return {
+        ...nextReview,
+        updatedAt: timestamp,
+        changes: dedupeReviewChanges([
+            ...nextReview.changes,
+            ...changeGroups.map((groupOps, index) => ({
+                id: changeGroups.length === 1
+                    ? proposal.id
+                    : `${proposal.id}:${index + 1}`,
+                proposalId: proposal.id,
+                title: changeTitle(proposal, groupOps, index),
+                operations: groupOps,
+                paths: operationPaths(groupOps),
+                status: "pending",
+                ...(proposal.base ? { base: proposal.base } : {}),
+                createdAt: timestamp,
+                updatedAt: timestamp,
+            })),
+        ]),
+    };
+}
+export function previewJsonReviewValue(review) {
+    return applyJsonPatch(review.baseValue, normalizeJsonReviewOperations(review.baseValue, reviewOperations(review, ["pending", "accepted"])), review.requiredRoot);
+}
+export function previewJsonReviewChangeValue(review, change) {
+    return applyJsonPatch(review.baseValue, normalizeJsonReviewOperations(review.baseValue, change.operations), review.requiredRoot);
+}
+export function acceptedJsonReviewValue(review) {
+    return applyJsonPatch(review.baseValue, normalizeJsonReviewOperations(review.baseValue, reviewOperations(review, ["accepted"])), review.requiredRoot);
+}
+export function reviewAffectsPath(review, pathPrefix) {
+    return Boolean(review?.changes.some((change) => change.status === "pending" &&
+        change.operations.some((operation) => operation.path === pathPrefix ||
+            operation.path.startsWith(`${pathPrefix}/`))));
+}
+export function pendingChangesForPath(review, pathPrefix) {
+    return (review?.changes.filter((change) => change.status === "pending" &&
+        change.operations.some((operation) => operation.path === pathPrefix ||
+            operation.path.startsWith(`${pathPrefix}/`))) ?? []);
+}
+export function reviewChangeValuePreview(review, change, path) {
+    if (!review)
+        return null;
+    const changedValue = previewJsonReviewChangeValue(review, change);
+    return {
+        before: pointerValue(review.baseValue, path),
+        after: pointerValue(changedValue, path),
+    };
+}
+export function formatReviewValue(value) {
+    if (value === undefined)
+        return "(not set)";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return value || "(empty)";
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `${value.length} item${value.length === 1 ? "" : "s"}`;
+    }
+    if (typeof value === "object")
+        return "Object changed";
+    return String(value);
+}

package/dist/shared/forms/core/path-config.d.ts

@@ -0,0 +1,238 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { ColorPickerFormat } from "../color-picker/color-value";
+import type { CyclePickerPreview } from "../cycle-picker/types";
+import type { InlineOptionPickerOption } from "../inline-option-picker/types";
+import type { ReferenceIndex } from "./reference-utils";
+import type { FormFieldAlign, FormFieldWrapper, FormRendererMap, FormValidationIssue, FormViewName } from "./types";
+import type { FieldPath, FieldPathByValue, FieldPathValue } from "./path-types";
+export type FormValidationMode = "onSubmit" | "onBlur" | "onChange" | "onTouched" | "all";
+/** Type-only definition used by the augmentable `FormFieldKindMap`. */
+export interface FormFieldKindDefinition<TValue, TOptions = object> {
+    readonly __value?: TValue;
+    readonly __options?: TOptions;
+}
+export interface FormFieldKindMap {
+    text: FormFieldKindDefinition<string>;
+    textarea: FormFieldKindDefinition<string>;
+    date: FormFieldKindDefinition<string>;
+    time: FormFieldKindDefinition<string>;
+    readonly: FormFieldKindDefinition<unknown>;
+    timestamp: FormFieldKindDefinition<string>;
+    boolean: FormFieldKindDefinition<boolean>;
+    color: FormFieldKindDefinition<string, {
+        colorFormat?: ColorPickerFormat;
+    }>;
+    options: FormFieldKindDefinition<string, {
+        optionPreview?: CyclePickerPreview;
+    }>;
+    segmented: FormFieldKindDefinition<string>;
+    choice: FormFieldKindDefinition<string>;
+    "string-list": FormFieldKindDefinition<string[]>;
+    "ordered-string-list": FormFieldKindDefinition<string[]>;
+    "tag-list": FormFieldKindDefinition<string[]>;
+    "chip-list": FormFieldKindDefinition<string[]>;
+    "reference-list": FormFieldKindDefinition<string[]>;
+    custom: FormFieldKindDefinition<unknown>;
+}
+export type RegisteredFormFieldKind = keyof FormFieldKindMap & string;
+type IsAny<TValue> = 0 extends 1 & TValue ? true : false;
+export type FormFieldKindValue<TKey extends RegisteredFormFieldKind> = FormFieldKindMap[TKey] extends FormFieldKindDefinition<infer TValue, object> ? TValue : never;
+export type FormFieldKindOptions<TKey extends RegisteredFormFieldKind> = FormFieldKindMap[TKey] extends FormFieldKindDefinition<unknown, infer TOptions> ? TOptions : object;
+export type CompatibleFormFieldKind<TValue> = {
+    [TKey in RegisteredFormFieldKind]: [NonNullable<TValue>] extends [
+        FormFieldKindValue<TKey>
+    ] ? TKey : never;
+}[RegisteredFormFieldKind];
+export type PathFieldValidationArgs<TValues, TContext, TPath extends FieldPath<TValues>> = {
+    root: TValues;
+    context: TContext;
+    path: TPath;
+};
+export type PathFieldValidator<TValues, TContext, TPath extends FieldPath<TValues>> = (value: FieldPathValue<TValues, TPath>, args: PathFieldValidationArgs<TValues, TContext, TPath>) => string | FormValidationIssue | null | undefined | Promise<string | FormValidationIssue | null | undefined>;
+type PathFieldBase<TValues, TContext, TPath extends FieldPath<TValues>, TGroup extends string> = {
+    id?: string;
+    label?: string;
+    group?: TGroup;
+    description?: string;
+    placeholder?: string;
+    ariaLabel?: string;
+    align?: FormFieldAlign;
+    as?: FormFieldWrapper;
+    inputType?: string;
+    autocomplete?: HTMLInputAttributes["autocomplete"];
+    rows?: number;
+    readonly?: boolean;
+    defaultValue?: FieldPathValue<TValues, TPath>;
+    materializeDefaultFrom?: FieldPath<TValues>;
+    validate?: PathFieldValidator<TValues, TContext, TPath>;
+    dependsOn?: FieldPath<TValues>[];
+    options?: InlineOptionPickerOption[] | ((args: {
+        root: TValues;
+        value: FieldPathValue<TValues, TPath>;
+        context: TContext;
+    }) => InlineOptionPickerOption[]);
+    suggestions?: string[] | ((args: {
+        root: TValues;
+        value: FieldPathValue<TValues, TPath>;
+        context: TContext;
+    }) => string[]);
+    referenceIndex?: ReferenceIndex | ((args: {
+        root: TValues;
+        value: FieldPathValue<TValues, TPath>;
+        context: TContext;
+    }) => ReferenceIndex);
+    addLabel?: string;
+    addHeading?: string;
+    searchPlaceholder?: string;
+    renderers?: FormRendererMap<TValues, TContext, FieldPathValue<TValues, TPath>>;
+};
+type LeafPathFormFieldConfig<TValues, TContext, TPath extends FieldPath<TValues>, TGroup extends string> = {
+    [TKind in CompatibleFormFieldKind<FieldPathValue<TValues, TPath>>]: PathFieldBase<TValues, TContext, TPath, TGroup> & FormFieldKindOptions<TKind> & {
+        kind: TKind;
+        presentation?: "menu" | "swap" | "cycle";
+    };
+}[CompatibleFormFieldKind<FieldPathValue<TValues, TPath>>];
+type FormArrayItem<TValue> = NonNullable<TValue> extends readonly (infer TItem)[] ? TItem : never;
+export type FormArrayItemTitle<TItem> = (TItem extends object ? FieldPathByValue<TItem, string | undefined | null> : never) | ((args: {
+    item: TItem;
+    index: number;
+}) => string);
+type PrimitiveArrayItemField<TItem> = {
+    [TKind in CompatibleFormFieldKind<TItem>]: FormFieldKindOptions<TKind> & {
+        kind: TKind;
+        label?: string;
+        placeholder?: string;
+        rows?: number;
+        ariaLabel?: string;
+        hideLabel?: boolean;
+    };
+}[CompatibleFormFieldKind<TItem>];
+export type FormArrayPresentation = "rows" | "sections";
+export type FormArrayAppearance = "default" | "subsection";
+export type FormAddButtonPresentation = "inline" | "panel";
+export type FormArrayMarkerSpacing = "default" | "wide";
+type ArrayPathFormFieldConfig<TValues, TContext, TPath extends FieldPath<TValues>, TGroup extends string, TItem = FormArrayItem<FieldPathValue<TValues, TPath>>> = NonNullable<FieldPathValue<TValues, TPath>> extends readonly unknown[] ? PathFieldBase<TValues, TContext, TPath, TGroup> & {
+    kind: "array";
+    presentation?: FormArrayPresentation;
+    appearance?: FormArrayAppearance;
+    createItem: () => TItem;
+    itemConfig?: TItem extends object ? PathFormConfig<TItem, TContext, string> : never;
+    itemField?: TItem extends object ? never : PrimitiveArrayItemField<TItem>;
+    itemTitle?: FormArrayItemTitle<TItem>;
+    editableTitlePath?: TItem extends object ? FieldPathByValue<TItem, string | undefined | null> : never;
+    getKey?: (item: TItem, index: number) => string;
+    marker?: (args: {
+        item: TItem;
+        index: number;
+        total: number;
+    }) => string | null;
+    markerSpacing?: FormArrayMarkerSpacing;
+    showLabel?: boolean;
+    hideItemLabels?: boolean;
+    addPlacement?: "header" | "footer";
+    addButtonPresentation?: FormAddButtonPresentation;
+    testId?: string;
+    itemTestId?: (args: {
+        item: TItem;
+        index: number;
+    }) => string;
+    collapsible?: boolean;
+    movable?: boolean;
+    removable?: boolean;
+} : never;
+type DiscriminatorKey<TItem> = TItem extends unknown ? {
+    [TKey in keyof TItem & string]: NonNullable<TItem[TKey]> extends string ? TKey : never;
+}[keyof TItem & string] : never;
+type DiscriminatorValue<TItem, TKey extends PropertyKey> = TItem extends unknown ? TKey extends keyof TItem ? NonNullable<TItem[TKey]> & string : never : never;
+type VariantItem<TItem, TDiscriminator extends PropertyKey, TValue extends string> = Extract<TItem, Record<TDiscriminator, TValue>>;
+type VariantPathFormFieldConfig<TValues, TContext, TPath extends FieldPath<TValues>, TGroup extends string, TItem = FormArrayItem<FieldPathValue<TValues, TPath>>> = NonNullable<FieldPathValue<TValues, TPath>> extends readonly unknown[] ? {
+    [TDiscriminator in DiscriminatorKey<TItem>]: PathFieldBase<TValues, TContext, TPath, TGroup> & {
+        kind: "variant-array";
+        discriminator: TDiscriminator;
+        presentation?: FormArrayPresentation;
+        appearance?: FormArrayAppearance;
+        getKey?: (item: TItem, index: number) => string;
+        itemTitle?: FormArrayItemTitle<TItem>;
+        editableTitlePath?: TItem extends object ? FieldPathByValue<TItem, string | undefined | null> : never;
+        collapsible?: boolean;
+        movable?: boolean;
+        removable?: boolean;
+        addLabel?: string;
+        addButtonPresentation?: FormAddButtonPresentation;
+        chooserTitle?: string;
+        showLabel?: boolean;
+        testId?: string;
+        itemTestId?: (args: {
+            item: TItem;
+            index: number;
+        }) => string;
+        variants: {
+            [TValue in DiscriminatorValue<TItem, TDiscriminator>]: {
+                label: string;
+                addLabel?: string;
+                createItem: () => VariantItem<TItem, TDiscriminator, TValue>;
+                itemConfig: PathFormConfig<VariantItem<TItem, TDiscriminator, TValue>, TContext, string>;
+            };
+        };
+    };
+}[DiscriminatorKey<TItem>] : never;
+export type PathFormFieldConfig<TValues, TPath extends FieldPath<TValues>, TContext = undefined, TGroup extends string = string> = IsAny<FieldPathValue<TValues, TPath>> extends true ? PathFieldBase<TValues, TContext, TPath, TGroup> & {
+    kind: RegisteredFormFieldKind | "array" | "variant-array";
+} : LeafPathFormFieldConfig<TValues, TContext, TPath, TGroup> | ArrayPathFormFieldConfig<TValues, TContext, TPath, TGroup> | VariantPathFormFieldConfig<TValues, TContext, TPath, TGroup>;
+export type FormFieldConfigMap<TValues, TContext = undefined, TGroup extends string = string> = Partial<Record<FieldPath<TValues>, unknown>> & {
+    readonly __formContext?: TContext;
+    readonly __formGroup?: TGroup;
+};
+export type FormGroupConfig = {
+    title: string;
+    collapsible?: boolean;
+    defaultOpen?: boolean;
+    hiddenHeader?: boolean;
+    appearance?: "default" | "subtle";
+};
+export type PathFormLayout = "grid" | "stacked";
+export type PathFormConfig<TValues, TContext = undefined, TGroup extends string = string> = {
+    id: string;
+    fields: FormFieldConfigMap<TValues, TContext, TGroup>;
+    groups?: Record<TGroup, FormGroupConfig>;
+    defaults?: Partial<TValues>;
+    layout?: PathFormLayout;
+    defaultView?: FormViewName;
+    validationMode?: FormValidationMode;
+    validate?: (value: TValues, context: TContext) => FormValidationIssue[] | Promise<FormValidationIssue[]> | null | undefined;
+};
+type ValidatedFormFieldConfigMap<TValues, TContext, TGroup extends string, TFields extends Record<string, unknown>> = {
+    [TPath in keyof TFields]: TPath extends FieldPath<TValues> ? TFields[TPath] & PathFormFieldConfig<TValues, TPath, TContext, TGroup> : never;
+};
+/** Erased renderer boundary; consumers should create values with `defineFormConfig`. */
+export type RuntimePathFormConfig<TValues, TContext = undefined> = {
+    id: string;
+    fields: Record<string, AnyPathFormFieldConfig | undefined>;
+    groups?: Record<string, FormGroupConfig>;
+    defaults?: Partial<TValues>;
+    layout?: PathFormLayout;
+    defaultView?: FormViewName;
+    validationMode?: FormValidationMode;
+    validate?: (value: TValues, context: TContext) => FormValidationIssue[] | Promise<FormValidationIssue[]> | null | undefined;
+};
+/** Defines a path-keyed form while retaining exact field and group inference. */
+export declare function defineFormConfig<TValues, TContext = undefined>(): <const TGroups extends Record<string, FormGroupConfig> = Record<never, never>, const TFields extends Record<string, unknown> = Record<never, never>>(config: Omit<PathFormConfig<TValues, TContext, keyof TGroups & string>, "fields" | "groups"> & {
+    groups?: TGroups;
+    fields: TFields & ValidatedFormFieldConfigMap<TValues, TContext, keyof TGroups & string, TFields>;
+}) => Omit<PathFormConfig<TValues, TContext, keyof TGroups & string>, "fields" | "groups"> & {
+    groups?: TGroups;
+    fields: TFields & ValidatedFormFieldConfigMap<TValues, TContext, keyof TGroups & string, TFields>;
+};
+export declare function isPathFormConfig<TValues, TContext>(config: RuntimePathFormConfig<TValues, TContext> | {
+    fields: readonly unknown[];
+}): config is RuntimePathFormConfig<TValues, TContext>;
+export type AnyPathFormConfig = RuntimePathFormConfig<unknown, unknown>;
+export type AnyPathFormFieldConfig = Record<string, unknown> & {
+    kind: string;
+    id?: string;
+    label?: string;
+    group?: string;
+    validate?: (...args: any[]) => unknown;
+    dependsOn?: string[];
+};
+export {};

package/dist/shared/forms/core/path-config.js

@@ -0,0 +1,7 @@
+/** Defines a path-keyed form while retaining exact field and group inference. */
+export function defineFormConfig() {
+    return (config) => config;
+}
+export function isPathFormConfig(config) {
+    return !Array.isArray(config.fields);
+}

package/dist/shared/forms/core/path-runtime.d.ts

@@ -0,0 +1,6 @@
+import type { AnyPathFormFieldConfig, RuntimePathFormConfig } from "./path-config";
+import type { FormFieldConfig } from "./types";
+export declare function formFieldLabel(path: string): string;
+export declare function formFieldId(formId: string, path: string): string;
+export declare function pathFormEntries<TValues, TContext>(config: RuntimePathFormConfig<TValues, TContext>): Array<[string, AnyPathFormFieldConfig]>;
+export declare function normalizePathField<TValues, TContext>(form: RuntimePathFormConfig<TValues, TContext>, path: string, source: AnyPathFormFieldConfig): FormFieldConfig<TValues, TContext, unknown> | null;

package/dist/shared/forms/core/path-runtime.js

@@ -0,0 +1,43 @@
+import { getFormValueAtPath, setFormValueWithDefault } from "./path-utils";
+export function formFieldLabel(path) {
+    const tail = path.split(".").at(-1) ?? path;
+    return tail
+        .replaceAll("_", " ")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/^./, (letter) => letter.toUpperCase());
+}
+export function formFieldId(formId, path) {
+    return `${formId}-${path}`.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+export function pathFormEntries(config) {
+    return Object.entries(config.fields).filter((entry) => Boolean(entry[1]));
+}
+export function normalizePathField(form, path, source) {
+    if (source.kind === "array" || source.kind === "variant-array")
+        return null;
+    const options = source.options;
+    const suggestions = source.suggestions;
+    const referenceIndex = source.referenceIndex;
+    return {
+        ...source,
+        id: source.id ?? formFieldId(form.id, path),
+        label: source.label ?? formFieldLabel(path),
+        kind: source.kind,
+        path,
+        get: (root) => getFormValueAtPath(root, path) ??
+            source.defaultValue ??
+            getFormValueAtPath(form.defaults, path),
+        set: (root, value) => setFormValueWithDefault(root, path, value, form.defaults, typeof source.materializeDefaultFrom === "string"
+            ? source.materializeDefaultFrom
+            : undefined),
+        options: typeof options === "function"
+            ? ({ root, value, context }) => options({ root, value, context })
+            : options,
+        suggestions: typeof suggestions === "function"
+            ? ({ root, value, context }) => suggestions({ root, value, context })
+            : suggestions,
+        referenceIndex: typeof referenceIndex === "function"
+            ? ({ root, value, context }) => referenceIndex({ root, value, context })
+            : referenceIndex,
+    };
+}