@echojs-ecosystem/form 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+<div align="center">
+
+# @echojs-ecosystem/form
+
+**Signal-native forms — fields, validation, and Hyperdom bindings.**
+
+[![npm](https://img.shields.io/npm/v/@echojs-ecosystem/form)](https://www.npmjs.com/package/@echojs-ecosystem/form)
+[![docs](https://img.shields.io/badge/docs-echojs.dev-blue)](https://echojs.dev/docs/guides/forms)
+
+</div>
+
+---
+
+Framework-agnostic form primitives for EchoJS. **Fields are reactive objects** with `.value()`, `.meta()`, validation via [Standard Schema](https://github.com/standard-schema/standard-schema), and optional Hyperdom bindings.
+
+## Features
+
+- **`createField`** — single value with validation & meta (touched, errors, dirty)
+- **`createFieldArray`** — dynamic lists of fields
+- **`createForm`** — grouped fields with submit & schema validation
+- **`bindField`** — Hyperdom binding for `@echojs-ecosystem/ui` inputs
+- **Persistence-ready** — extend fields with `@echojs-ecosystem/persist`
+
+## Install
+
+```bash
+npm install @echojs-ecosystem/form @echojs-ecosystem/reactivity
+# optional UI bindings
+npm install @echojs-ecosystem/hyperdom @echojs-ecosystem/ui
+```
+
+## Quick start
+
+```ts
+import { createField, createForm } from "@echojs-ecosystem/form";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.string().email(),
+  remember: z.boolean(),
+});
+
+export const loginForm = createForm(
+  {
+    email: createField(""),
+    remember: createField(false),
+  },
+  { name: "LoginForm", validationSchema: schema },
+);
+
+// In a view
+loginForm.fields.email.value();
+loginForm.fields.email.meta().errors;
+await loginForm.submit();
+```
+
+### Hyperdom + UI
+
+```ts
+import { bindField } from "@echojs-ecosystem/form";
+
+bindField(loginForm.fields.email, { variant: "email" });
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `createField` | Single reactive field |
+| `createFieldArray` | Array of fields |
+| `createFieldSet` | Field grouping |
+| `createForm` | Form with validation |
+| `bindField` | Hyperdom control binding |
+| `createFieldKit` | Reusable field factories |
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| [`@echojs-ecosystem/persist`](https://www.npmjs.com/package/@echojs-ecosystem/persist) | Save field/form state to storage |
+| [`@echojs-ecosystem/ui`](https://www.npmjs.com/package/@echojs-ecosystem/ui) | Accessible inputs via `bindField` |
+| [`@echojs-ecosystem/hyperdom`](https://www.npmjs.com/package/@echojs-ecosystem/hyperdom) | View layer |
+
+## Documentation
+
+[echojs.dev/docs/guides/forms](https://echojs.dev/docs/guides/forms)

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import { Signal, ReadValue } from '@echojs-ecosystem/reactivity';
+import { PersistExtension, PersistExtensionResult } from '@echojs-ecosystem/persist';
+import { ZodEnum } from 'zod';
+
+/** Persist API поверх `createField`: `value` / `subscribe`; запись — через `field.set()`. */
+type FieldPersistMethods<T> = {
+    value(): T;
+    subscribe(listener: (value: T, prevValue: T) => void): () => void;
+    extend<Snapshot = T>(extension: PersistExtension<T, Snapshot>): Field<T> & PersistExtensionResult<T, Snapshot>;
+};
+type FieldArrayPersistMethods<T> = {
+    value(): T[];
+    set(next: T[]): void;
+    subscribe(listener: (value: T[], prevValue: T[]) => void): () => void;
+    extend<Snapshot = T[]>(extension: PersistExtension<T[], Snapshot>): FieldArray<T> & PersistExtensionResult<T[], Snapshot>;
+};
+
+type FieldValidator<T> = (value: ReadValue<T>) => string | null;
+type StandardSchemaLike<T = unknown> = {
+    "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            readonly value: T;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+                readonly path?: ReadonlyArray<unknown>;
+            }>;
+        } | Promise<{
+            readonly value: T;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+                readonly path?: ReadonlyArray<unknown>;
+            }>;
+        }>;
+    };
+};
+type StandardSchemaIssue = {
+    message: string;
+    path?: readonly (string | number | symbol)[];
+};
+type FieldMeta = {
+    dirty: boolean;
+    touched: boolean;
+    focused: boolean;
+    errors: readonly string[];
+};
+type FieldBinding = {
+    /** Text-like inputs: update value on input/change without forcing controlled `value:` on every render. */
+    onInputText: (e: {
+        currentTarget: HTMLInputElement | HTMLTextAreaElement;
+    }) => void;
+    onChangeText: (e: {
+        currentTarget: HTMLInputElement | HTMLTextAreaElement;
+    }) => void;
+    onFocus: () => void;
+    onBlur: () => void;
+};
+type FieldValidationMode = "manual" | "onChange" | "onBlur";
+type FormValidationMode = "manual" | "onChange" | "onBlur" | "onFocus" | "all";
+type FieldCore<T> = {
+    $value: Signal<T>;
+    $meta: Signal<FieldMeta>;
+    /** Shortcut for `$value.value()` — use in views and `bindField`. */
+    value: () => ReadValue<T>;
+    /** Shortcut for `$meta.value()`. */
+    meta: () => FieldMeta;
+    /** Same handlers as `bind()` — for Hyperdom `bindField` and custom inputs. */
+    handlers: FieldBinding;
+    set: (next: T) => void;
+    reset: (next?: T) => void;
+    focus: () => void;
+    blur: () => void;
+    touch: () => void;
+    /** @deprecated Prefer `.handlers` — kept for backward compatibility. */
+    bind: () => FieldBinding;
+    validate: () => string[];
+    validateAsync: () => Promise<string[]>;
+    clearErrors: () => void;
+};
+type Field<T> = FieldCore<T> & FieldPersistMethods<T>;
+type FieldArrayCore<Item> = {
+    $items: Signal<Item[]>;
+    append: (item: Item) => void;
+    prepend: (item: Item) => void;
+    removeAt: (index: number) => void;
+    move: (from: number, to: number) => void;
+    updateAt: (index: number, fn: (prev: Item) => Item) => void;
+    replace: (next: Item[]) => void;
+    reset: () => void;
+};
+type FieldArray<Item> = FieldArrayCore<Item> & FieldArrayPersistMethods<Item>;
+/** Операции над вложенными `FieldArray`, см. `defineNestedFieldArrayOps`. */
+type NestedFieldArrayOps<Row extends Record<string, unknown> = Record<string, unknown>> = {
+    append: (item?: Row) => void;
+    removeAt: (index: number) => void;
+    remove: (index: number) => void;
+    at: (index: number) => Record<string, NestedFieldArrayOps> | undefined;
+};
+type FieldSet<Shape extends Record<string, any>> = {
+    fields: Shape;
+    validate: () => Record<string, string[]>;
+    reset: () => void;
+};
+type FormSubmitResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: Record<string, unknown>;
+};
+type Form<TValue, TFields extends Record<string, any>, TArrayActions extends Record<string, unknown> = {}> = {
+    /** Имя формы из `createForm(fields, { name, ... })`. */
+    displayName: string;
+    fields: TFields;
+    $submitting: Signal<boolean>;
+    $submitCount: Signal<number>;
+    $errors: Signal<Record<string, unknown> | undefined>;
+    $schemaErrors: Signal<Record<string, string[]> | undefined>;
+    /** Фабрики строк и append/remove, объявленные в `createForm({ arrayActions })`. */
+    arrayActions: TArrayActions;
+    validate: () => Record<string, unknown>;
+    validateAsync: () => Promise<Record<string, unknown>>;
+    reset: () => void;
+    /** Подмешать значения после создания формы (тот же формат, что у `defaultAsyncValues`). */
+    hydrate: (partial: Partial<TValue>) => void;
+    submit: (handler: (value: TValue) => void | Promise<void>) => Promise<FormSubmitResult<TValue>>;
+};
+
+/**
+ * Одно поле формы: значение и мета в сигналах, биндинг к DOM без встроенной схемы.
+ * Валидацию на submit задавайте через `createForm(..., { schema | validate })`.
+ */
+declare const createField: <T>(initial: T) => Field<T>;
+
+/**
+ * Creates a dynamic array helper for form state (append/remove/move/update).
+ *
+ * This primitive only manages the array itself; compose it with fields/fieldSets for rich models.
+ */
+declare const createFieldArray: <Item>(initial?: Item[]) => FieldArray<Item>;
+
+/**
+ * Конфиг вложенных `createFieldArray`: на каждом уровне — фабрика строки и при необходимости дочерние массивы по ключам строки.
+ */
+type FieldArrayBranchConfig<Row extends Record<string, unknown>> = {
+    newRow: () => Row;
+    children?: Partial<{
+        [K in keyof Row]: Row[K] extends FieldArray<infer Child> ? Child extends Record<string, unknown> ? FieldArrayBranchConfig<Child> : FieldArrayBranchConfig<Record<string, never>> : never;
+    }>;
+};
+/**
+ * Строит цепочку операций над вложенными `FieldArray` по конфигу (фабрики строк + дерево дочерних ключей).
+ *
+ * @example
+ * ```ts
+ * const d = form.nestedArrays!.departments;
+ * d.append();
+ * d.at(0)?.employees.append();
+ * d.at(0)?.employees.at(0)?.tickets.removeAt(1);
+ * ```
+ */
+declare const defineNestedFieldArrayOps: <Row extends Record<string, unknown>>(fieldArray: FieldArray<Row>, cfg: FieldArrayBranchConfig<Row>) => NestedFieldArrayOps<Row>;
+
+/**
+ * Groups fields (or nested fieldSets) into a single unit.
+ *
+ * This version is intentionally simple: it calls `validate()`/`reset()` on children when present.
+ */
+declare const createFieldSet: <Shape extends Record<string, any>>(fields: Shape) => FieldSet<Shape>;
+
+type CreateFormOptions<TValue, TFields extends Record<string, any>, TArrayActions extends Record<string, unknown> = {}> = {
+    /** Имя формы (отладка, логирование). */
+    name: string;
+    /**
+     * Снимок значения для `submit` / `validationSchema`.
+     *
+     * Если не указан, используется {@link collectFormValueFromFields}: структура полей должна
+     * совпадать с `TValue` (см. JSDoc у `collectFormValueFromFields`). Иначе передайте свою функцию.
+     */
+    validate?: (fields: TFields) => Record<string, unknown>;
+    validateAsync?: (fields: TFields) => Promise<Record<string, unknown>>;
+    /** Back-compat alias for `validationSchema`. */
+    schema?: StandardSchemaLike<TValue>;
+    /** Общая Standard Schema (Zod и др.) при submit: ошибки попадают в `errors.$schema` (плоская карта путей). */
+    validationSchema?: StandardSchemaLike<TValue>;
+    /**
+     * When to auto-run validation (incl. `validationSchema`) and keep `$errors/$schemaErrors` updated.
+     *
+     * Default: "manual" (only `submit()` triggers validation).
+     */
+    validationOn?: FormValidationMode;
+    /**
+     * Override how a submit "value snapshot" is built from the field tree.
+     *
+     * By default we use `collectFormValueFromFields(...)`.
+     */
+    getValue?: () => TValue;
+    /**
+     * Начальные значения: записываются в дерево полей через `hydrateFormFields` сразу после создания формы.
+     */
+    defaultValues?: Partial<TValue>;
+    /**
+     * Асинхронная подгрузка значений (частичный объект). Применяется через `hydrateFormFields`.
+     */
+    defaultAsyncValues?: () => Promise<Partial<TValue>>;
+    /**
+     * Фабрики строк для `FieldArray` при гидратации `defaultValues` / `defaultAsyncValues`.
+     */
+    fieldArrayFactories?: Record<string, () => unknown>;
+    /**
+     * Фабрики строк (`createTicket`, …) и append/remove через `arrayGenerator` из `@echojs-ecosystem/form`.
+     *
+     * @example
+     * ```ts
+     * arrayActions: (form) => {
+     *   const createRow = () => ({ title: createField("") });
+     *   return {
+     *     createRow,
+     *     appendRow: arrayGenerator.append(form, createRow, "items"),
+     *     removeRow: arrayGenerator.remove(form, "items"),
+     *   };
+     * },
+     * ```
+     */
+    arrayActions?: (form: Form<TValue, TFields, TArrayActions>) => TArrayActions;
+};
+/**
+ * Обёртка над деревом полей: submit, валидация полей (`createField` / `createFieldArray`) и опционально схема на submit.
+ *
+ * @example
+ * ```ts
+ * const form = createForm(
+ *   { title: createField(""), items: createFieldArray([]) },
+ *   { name: "MyForm", validationSchema: z.object({ ... }), defaultValues: { title: "a" } },
+ * );
+ * ```
+ */
+declare function createForm<TValue, TFields extends Record<string, any>, TArrayActions extends Record<string, unknown> = {}>(fields: TFields, opts: CreateFormOptions<TValue, TFields, TArrayActions>): Form<TValue, TFields, TArrayActions>;
+
+type StrKey<T> = Extract<keyof T, string>;
+type UnwrapFieldSet<T> = T extends FieldSet<infer Shape> ? Shape : T extends {
+    fields: infer F;
+} ? F : T;
+type RowShape<T> = T extends FieldArray<infer Row> ? UnwrapFieldSet<Row> : never;
+type NextRecord<T> = T extends Record<string, any> ? T : never;
+type Join<P extends string, K extends string> = P extends "" ? K : `${P}.${K}`;
+type ArrayPathsFromRecord<TRecord, Prefix extends string = ""> = TRecord extends Record<string, any> ? {
+    [K in StrKey<TRecord>]: TRecord[K] extends FieldArray<any> ? Join<Prefix, K> | ArrayPathsFromRecord<NextRecord<RowShape<TRecord[K]>>, Join<Prefix, K>> : never;
+}[StrKey<TRecord>] : never;
+/**
+ * Union of dot-separated paths that resolve to a `FieldArray` inside a field tree.
+ *
+ * Example: `"departments" | "departments.employees" | "departments.employees.tickets"`.
+ */
+type ArrayPath<TFields extends Record<string, any>> = ArrayPathsFromRecord<TFields>;
+
+/** Утилиты для append/remove по вложенным `FieldArray` (пути — `ArrayPath`). */
+declare const arrayGenerator: {
+    append<TValue, TFields extends Record<string, any>, Row>(form: Form<TValue, TFields, any>, makeRow: () => Row, path: ArrayPath<TFields>): (...indices: number[]) => void;
+    remove<TValue, TFields extends Record<string, any>>(form: Form<TValue, TFields, any>, path: ArrayPath<TFields>): (...indices: number[]) => void;
+};
+
+/**
+ * Generates an append function for a nested FieldArray path.
+ *
+ * `path` is a dot-separated chain of array names, where the last segment is the target array.
+ * Example: "departments.employees.tickets" => appendTicket(deptIndex, employeeIndex)
+ *
+ * The returned function expects N indices where N = segments.length - 1.
+ */
+declare const generateAppendToArray: <TValue, TFields extends Record<string, any>, Row>(form: Form<TValue, TFields, any>, makeRow: () => Row, path: ArrayPath<TFields>) => (...indices: number[]) => void;
+
+/**
+ * Generates a remove function for a nested FieldArray path.
+ *
+ * `path` is a dot-separated chain of array names, where the last segment is the target array.
+ * Example: "departments.employees.tickets" => removeTicket(deptIndex, employeeIndex, ticketIndex)
+ *
+ * The returned function expects N indices where N = segments.length.
+ */
+declare const generateRemoveFromArray: <TValue, TFields extends Record<string, any>>(form: Form<TValue, TFields, any>, path: ArrayPath<TFields>) => (...indices: number[]) => void;
+
+type FieldKitFieldOpts<T> = {
+    validationMode?: FieldValidationMode;
+    parseDOMValue?: (raw: string) => T;
+    parseDOMChecked?: (checked: boolean) => T;
+    validate?: FieldValidator<T>[];
+    schemaIssuePrefix?: string;
+};
+/**
+ * Helpers to build fields from `defaultValues` / `defaultAsyncValues` without repeating
+ * `seed.foo ?? ""` for every key. Pass as the second argument to the `fields` factory.
+ */
+type FieldKit<TSeed extends Record<string, unknown>> = {
+    str: (key: string, schema: StandardSchemaLike<string>, parent?: object, extra?: FieldKitFieldOpts<string>) => Field<string>;
+    num: (key: string, schema: StandardSchemaLike<number>, parent?: object, extra?: FieldKitFieldOpts<number>) => Field<number>;
+    bool: (key: string, schema: StandardSchemaLike<boolean>, parent?: object, extra?: FieldKitFieldOpts<boolean>) => Field<boolean>;
+    /**
+     * `z.enum` / string union fields: reads `parent[key]` when it matches an enum option, else `fallback`.
+     */
+    pick: <T extends string>(key: string, schema: ZodEnum<[T, ...T[]]>, parent: object | undefined, fallback: T, extra?: FieldKitFieldOpts<T>) => Field<T>;
+    list: <Row>(key: string, rowFactory: (rowSeed: Record<string, unknown>, index: number) => Row, parent?: object) => FieldArray<Row>;
+};
+declare const createFieldKit: <TSeed extends Record<string, unknown>>(seed: TSeed) => FieldKit<TSeed>;
+
+/**
+ * Собирает «сырое» значение формы из дерева примитивов (`Field` / `FieldSet` / `FieldArray`).
+ *
+ * Соглашение по форме:
+ * - ключи объекта `fields` совпадают с ключами итогового JSON;
+ * - `FieldSet` сериализуется как **один уровень** его `fields` (без ключа `fields` в выходе);
+ * - `FieldArray` → массив, каждый элемент — объект строки (рекурсивно).
+ *
+ * Если дерево полей **не совпадает** со схемой (например, `credentials.email` в UI, а в Zod плоский `email`),
+ * задайте свой `getValue` во втором аргументе `createForm(fields, { getValue })`.
+ */
+declare const collectFormValueFromFields: (node: unknown) => unknown;
+
+/**
+ * Рекурсивно записывает `partial` в дерево полей (Field / FieldSet / FieldArray).
+ *
+ * Для расширения массива нужен `rowFactory` из второго аргумента `createForm(fields, { fieldArrayFactories })`.
+ */
+declare const hydrateFormFields: (fields: Record<string, unknown>, partial: unknown, fieldArrayFactories?: Record<string, () => unknown>) => void;
+
+/**
+ * Схлопывает дерево результатов `deepValidateSync/Async` в плоскую карту `путь → сообщения`.
+ *
+ * Пути строятся через точку; индексы массивов — как числовые сегменты (`tags.0.tag`).
+ */
+declare const flattenValidationErrors: (node: unknown, prefix?: string) => Record<string, string[]>;
+/**
+ * Оставляет только те ошибки общей `validationSchema`, которые **не перекрыты** ошибками полей.
+ *
+ * Правило: если у поля есть ошибка по пути `fk`, то отбрасываем любую ошибку схемы по пути `sk`, если
+ * `fk === sk`, либо один путь является префиксом другого (вложенность / массивы).
+ */
+declare const filterRootSchemaErrorsDeferredToFieldErrors: (fieldFlat: Record<string, string[]>, schemaFlat: Record<string, string[]>) => Record<string, string[]>;
+
+declare const normalizeStandardSchemaPathSegments: (path?: ReadonlyArray<unknown> | undefined) => string[];
+/**
+ * Normalize common Standard Schema validation result shapes into a flat `{ issues[] }`.
+ *
+ * Covers:
+ * - `{ issues: [...] }`
+ * - `{ errors: [...] }` (some wrappers)
+ * - `{ value }` → no issues (success-ish)
+ */
+declare const normalizeStandardSchemaIssues: (result: unknown) => StandardSchemaIssue[];
+/**
+ * Runs `StandardSchema`'s `.validate()` and normalizes failures into `{ issues }`.
+ *
+ * Handles Promise results automatically.
+ */
+declare const standardSchemaIssuesForUnknown: (schema: StandardSchemaLike<unknown>, value: unknown) => Promise<{
+    ok: boolean;
+    issues: StandardSchemaIssue[];
+}>;
+/**
+ * Same as `standardSchemaIssuesForUnknown()`, but resolves immediately when the vendor returns sync results.
+ *
+ * Throws if validation returns a Promise (use `standardSchemaIssuesForUnknown()` / `validateAsync()` instead).
+ */
+declare const standardSchemaIssuesForUnknownSync: (schema: StandardSchemaLike<unknown>, value: unknown) => {
+    ok: boolean;
+    issues: StandardSchemaIssue[];
+};
+
+/**
+ * Turns Standard Schema-ish issues into a flat map keyed by dotted paths.
+ *
+ * Issues without paths are aggregated under `"$root"` (useful for form-level errors).
+ */
+declare const flattenFieldErrors: (issues: readonly StandardSchemaIssue[]) => Record<string, string[]>;
+
+/** Поле формы для Hyperdom (`createField` / `form.fields.*`). */
+type HyperdomFormFieldRef<T> = Field<T>;
+type bindFieldOptions = {
+    variant: "text" | "email" | "password" | "search" | "url";
+    controlledValue?: boolean;
+} | {
+    variant: "textarea";
+    controlledValue?: boolean;
+} | {
+    variant: "checkbox";
+} | {
+    variant: "select";
+    /** По умолчанию `true`: селект почти всегда должен быть controlled. */
+    controlledValue?: boolean;
+} | {
+    variant: "number";
+    controlledValue?: boolean;
+} | {
+    variant: "range";
+    min?: number;
+    max?: number;
+    step?: number;
+    controlledValue?: boolean;
+};
+/**
+ * Унифицированный биндинг поля `@echojs-ecosystem/form` к пропсам Hyperdom (`input`, `textarea`, `select`, …).
+ *
+ * Для списков внутри `List` рекомендуется `controlledValue: true` у текстовых вариантов, чтобы значения
+ * не терялись при пересоздании DOM.
+ *
+ * Возвращаемый тип намеренно широкий: Hyperdom различает обработчики `onChange` для `input` / `select` / `textarea`,
+ * а контроллер выбирается по `variant` в рантайме.
+ */
+declare const bindField: <T>(field: HyperdomFormFieldRef<T>, opts: bindFieldOptions) => any;
+
+export { type ArrayPath, type CreateFormOptions, type Field, type FieldArray, type FieldArrayBranchConfig, type FieldBinding, type FieldKit, type FieldKitFieldOpts, type FieldMeta, type FieldSet, type FieldValidationMode, type FieldValidator, type Form, type FormSubmitResult, type HyperdomFormFieldRef, type NestedFieldArrayOps, type StandardSchemaLike, arrayGenerator, bindField, type bindFieldOptions, collectFormValueFromFields, createField, createFieldArray, createFieldKit, createFieldSet, createForm, defineNestedFieldArrayOps, filterRootSchemaErrorsDeferredToFieldErrors, flattenFieldErrors, flattenValidationErrors, generateAppendToArray, generateRemoveFromArray, hydrateFormFields, normalizeStandardSchemaIssues, normalizeStandardSchemaPathSegments, standardSchemaIssuesForUnknown, standardSchemaIssuesForUnknownSync };