@whatsaaaa/form-builder-schema 0.4.1 → 0.6.0

package/README.md

@@ -36,7 +36,7 @@ Empty optional fields output `undefined`. Rules never run on empty values, and a
 
 ## Field types
 
-There is a type for every native control, plus three display elements. Anything more specific is a `ui.widget` variant of one of them, or your own type: a star rating is a `number` with `ui: { widget: 'rating' }`, and a colour picker is a `text` with a `hexColor` rule.
+There is a type for every native control, two types that hold other fields, and three display elements. Anything more specific is a `ui.widget` variant of one of them, or your own type: a star rating is a `number` with `ui: { widget: 'rating' }`, and a colour picker is a `text` with a `hexColor` rule.
 
 | Type                                  | Kind                                   | Value                               | Props                    | Checks                           |
 | ------------------------------------- | -------------------------------------- | ----------------------------------- | ------------------------ | -------------------------------- |
@@ -69,6 +69,29 @@ There is a type for every native control, plus three display elements. Anything
 
 They need no `name`, add no output key, and can't have `rules` or `required`. Their `text` can be an i18n key: renderers resolve it with the same function you pass as `resolveMessage`. Whether a paragraph renders markdown is up to the renderer.
 
+### Groups and arrays
+
+| Type    | Kind   | Value                                  | Props                            |
+| ------- | ------ | -------------------------------------- | -------------------------------- |
+| `group` | object | an object with a key for each field    | `fields`                         |
+| `array` | array  | a list of single values, or of objects | exactly one of `of` and `fields` |
+
+```json
+{
+  "name": "address",
+  "type": "group",
+  "fields": [
+    { "name": "city", "type": "text", "required": true },
+    { "name": "zip", "type": "text" }
+  ]
+}
+```
+
+- **A group** builds `{ address: { city, zip } }`, so Formisch's path for the city is `['address', 'city']`. It is always there and its fields decide what is required, so it can't have `required` or `default`.
+- **An array with `of`** is a list of single values, such as tags. `of` is the field each item uses, and it needs no `name`. **An array with `fields`** is a list of objects, such as order lines.
+- **Rules on an array**, like `minLength`, count its items. A required array needs at least one item. A missing array is read as `[]`, so its rules still run.
+- Display elements can go inside both. A name only has to be unique among the fields next to it.
+
 ## Rules
 
 Every Valibot action whose arguments fit in JSON is a rule with the same name. Params go next to `rule`, and a rule without a `message` uses Valibot's message, so [`@valibot/i18n`](https://valibot.dev/guides/internationalization/) works.
@@ -106,7 +129,7 @@ const { build } = createSchemaBuilder({
 })
 ```
 
-The built-in `email` and `url` types use the `email` and `url` rules, so keep `formatRules` (or replace those types), or `createSchemaBuilder` throws a `TypeError`.
+The built-in `email` and `url` types use the `email` and `url` rules, so keep `formatRules` (or replace those types), or `createSchemaBuilder` throws a `TypeError`. `includeDefaultRules: false` leaves out the built-in form rules too; add them back with `formRules: defaultFormRules`.
 
 ### Listing rules
 
@@ -117,6 +140,43 @@ const { rulesForKind } = createSchemaBuilder()
 rulesForKind('file').map(([name, def]) => def.meta?.label) // ['Minimum size', …]
 ```
 
+## Form rules
+
+A form rule checks a field against other fields, such as a repeated password or a date range. Form rules go in `formRules`, next to `fields`, and each one names the `field` its error shows on:
+
+```json
+{
+  "version": "1",
+  "fields": [
+    { "name": "password", "type": "password", "required": true },
+    { "name": "password2", "type": "password", "required": true },
+    { "name": "start", "type": "date" },
+    { "name": "end", "type": "date" }
+  ],
+  "formRules": [
+    { "rule": "sameAs", "field": "password2", "other": "password", "message": "Passwords differ" },
+    {
+      "rule": "compare",
+      "field": "end",
+      "op": "gt",
+      "other": "start",
+      "message": "After the start"
+    }
+  ]
+}
+```
+
+| Rule            | Params                                     | Kinds                         | Passes when       |
+| --------------- | ------------------------------------------ | ----------------------------- | ----------------- |
+| `sameAs`        | `other`                                    | string, number, boolean, date | `field === other` |
+| `differentFrom` | `other`                                    | string, number, boolean, date | `field !== other` |
+| `compare`       | `op` (`lt`, `lte`, `gt` or `gte`), `other` | number, date                  | `field op other`  |
+
+- **Paths** name fields by their value: `'password2'`, `'address.zip'` for a field in a group, and `'lines.*.qty'` for a field in the items of an array. A rule on a path with `*` runs once per item, and its error shows on that item's field. A path it reads with `*` means the same item, so `{ "field": "lines.*.qty", "op": "lte", "other": "lines.*.stock" }` compares each line with itself.
+- **A form rule runs last**, after every field's own rules, and only when the fields it reads have no issues. So a password that is too short never also shows "Passwords differ". It never runs on an empty value either: make the fields required when they must be filled.
+- **`message` is required.** It goes through `resolveMessage` like every other message, with the rule's field in `ctx.field`.
+- The fields a rule reads must have the same kind: `compare` on a number and a date is `kind_mismatch`. A date with `output: 'date'` is compared by its time, so compare it with another date that has `output: 'date'`.
+
 ## Checking definitions
 
 `validate(json)` never throws. It returns every problem in the definition, in document order:
@@ -128,13 +188,17 @@ if (!result.success) {
 }
 ```
 
-`build(json)` runs the same checks and throws one `DefinitionError` with all of them. Issue codes are `invalid_shape`, `unsupported_version`, `unknown_key`, `unknown_type`, `missing_name`, `duplicate_name`, `invalid_props`, `unknown_rule`, `unknown_param`, `invalid_params` and `kind_mismatch`.
+`build(json)` runs the same checks and throws one `DefinitionError` with all of them. Issue codes are `invalid_shape`, `unsupported_version`, `unknown_key`, `unknown_type`, `missing_name`, `invalid_name`, `duplicate_name`, `invalid_props`, `invalid_default`, `unknown_rule`, `unknown_param`, `invalid_params`, `kind_mismatch` and `unknown_field`. An issue in a nested field has its full path, such as `['fields', 2, 'fields', 0, 'rules', 1]`.
+
+- **Names** are one key of the value, so a name with `.`, `[` or `]` is `invalid_name`.
+- **Defaults** must pass the field's own schema, rules included, or they are `invalid_default`. An empty default, like `''`, counts as none.
+- **Form rules** report on `['formRules', 0]` and below. A `field` path that names no field with a value is `unknown_field` on `['formRules', 0, 'field']`, and a path the rule reads gets it on `['formRules', 0]`. When a field the rule reads has issues of its own, the rule adds none.
 
 Keys on a field must be reserved keys (`RESERVED_FIELD_KEYS`) or props of its type. Put renderer settings under `ui`, which is never checked.
 
 ## Extending
 
-`createSchemaBuilder({ kinds, fieldTypes, rules })` merges your entries over the defaults by key. The merged registries are returned as `kinds`, `fieldTypes` and `rules`.
+`createSchemaBuilder({ kinds, fieldTypes, rules, formRules })` merges your entries over the defaults by key. The merged registries are returned as `kinds`, `fieldTypes`, `rules` and `formRules`.
 
 ```ts
 const tags = defineFieldType({
@@ -165,8 +229,49 @@ const { build } = createSchemaBuilder({ fieldTypes: { tags }, rules: { even } })
   })
   ```
 
+- A **field type whose value holds other fields** sets `container: true` and builds them with `ctx.buildFields(fields, path)`, or `ctx.buildField(field, path)` for the items of a list. The builder checks those fields like any others, so their issues have their full path. A container's kind is `object` or `array`, its value is never empty, and Formisch keeps a field for each child.
+- To **test a field type on its own**, give its `schema()` a context from `createBuildContext()`. Its `buildFields` and `buildField` use the default registries and throw a `DefinitionError` when the child fields have issues:
+
+  ```ts
+  const schema = myType.schema?.(field, createBuildContext({ path: ['fields', 0] }))
+  ```
+
+- A **form rule** lists the paths it reads besides `field`, and checks their values with a plain function. The builder checks that the fields exist and have one of `kinds`, and runs `check` only when none of them has an issue or is empty:
+
+  ```ts
+  const sameZip = defineFormRule({
+    params: v.object({ others: v.array(v.string()) }),
+    reads: (params) => params.others,
+    kinds: ['string'],
+    check: (values) => new Set(values).size === 1, // the value of `field`, then the others
+    meta: { label: 'Same ZIP', category: 'comparison' },
+  })
+
+  const { build } = createSchemaBuilder({ formRules: { sameZip } })
+  ```
+
+  `sameKind: true` requires every field it reads to have the same kind. `rule`, `field` and `message` are reserved (`RESERVED_FORM_RULE_KEYS`), so params can't use them.
+
 - Mistakes in the registry, such as an unknown kind or a reserved props key, throw a `TypeError` from `createSchemaBuilder`.
 
+## Initial input and walking fields
+
+Two plain functions read a definition without a builder, for renderers and adapters:
+
+```ts
+import { getInitialInput, walkFields } from '@whatsaaaa/form-builder-schema'
+
+const form = useForm({ schema: build(json), initialInput: getInitialInput(json) })
+
+for (const { field, dataPath, definitionPath, depth } of walkFields(json)) {
+  // e.g. dataPath ['lines', '*', 'quantity'], definitionPath ['fields', 2, 'fields', 1], depth 1
+}
+```
+
+- `getInitialInput` gives each field's `default`, nested the way the value is. A group gives an object, and an array without a default gives `[]`. Other fields without a default are left out.
+- `walkFields` yields every field at every depth, in document order, with a group or array before its fields. The fields of an array's items come once, with `'*'` in place of the index. A field without a name, like a heading, has its parent's `dataPath`.
+- Both know the built-in `group` and `array` types only, and neither checks the definition, so run `validate()` first.
+
 ## Messages
 
 ```ts

package/dist/index.d.ts

@@ -5,12 +5,6 @@ type AnyAction = v.GenericPipeAction;
  * A `v.object()` schema. The builder reads its `entries` to find unknown keys.
  */
 type AnyObjectSchema = v.ObjectSchema<v.ObjectEntries, v.ErrorMessage<v.ObjectIssue> | undefined>;
-interface KindDef {
-  /** True when the input means "no value". */
-  isEmpty(input: unknown): boolean;
-  /** Extra check for required fields after normalize rules ran. Omit it when isEmpty is enough. */
-  required?(message: string): AnyAction | null;
-}
 /**
  * The built-in kinds, plus any string so consumers can register their own.
  */
@@ -18,6 +12,8 @@ type ValueKind = 'string' | 'number' | 'boolean' | 'date' | 'array' | 'file' | '
 interface JsonForm {
   version: '1';
   fields: readonly JsonField[];
+  /** Rules that check a field against other fields. They run after every field's own rules. */
+  formRules?: readonly JsonFormRule[];
 }
 interface JsonField {
   name?: string;
@@ -40,10 +36,17 @@ interface JsonRule {
   message?: string;
   [param: string]: unknown;
 }
+interface JsonFormRule {
+  rule: string;
+  /** Where the error shows, as a dot path: `'password2'`, `'address.zip'` or `'lines.*.qty'`. */
+  field: string;
+  message: string;
+  [param: string]: unknown;
+}
 /** Where something is in a definition, e.g. `['fields', 0, 'rules', 1]`. */
 type DefinitionPath = readonly (string | number)[];
 /** Public API: adding a code is a minor change, renaming one is breaking. */
-type DefinitionIssueCode = 'invalid_shape' | 'unsupported_version' | 'unknown_key' | 'unknown_type' | 'missing_name' | 'duplicate_name' | 'invalid_props' | 'unknown_rule' | 'unknown_param' | 'invalid_params' | 'kind_mismatch';
+type DefinitionIssueCode = 'invalid_shape' | 'unsupported_version' | 'unknown_key' | 'unknown_type' | 'missing_name' | 'invalid_name' | 'duplicate_name' | 'invalid_props' | 'invalid_default' | 'unknown_rule' | 'unknown_param' | 'invalid_params' | 'kind_mismatch' | 'unknown_field';
 interface DefinitionIssue {
   code: DefinitionIssueCode;
   path: DefinitionPath;
@@ -89,6 +92,13 @@ interface FieldTypeDef<TProps extends AnyObjectSchema = AnyObjectSchema> {
   required?(message: string): AnyAction | null;
   /** Runs last, after every rule, e.g. to turn an ISO string into a `Date`. */
   finalize?(field: FieldWithProps<TProps>): AnyAction | undefined;
+  /**
+   * True for a type whose value holds other fields, built with `ctx.buildFields` or
+   * `ctx.buildField`. Its kind must be `'object'` or `'array'`. The value is never empty: a
+   * missing one becomes `{}` or `[]`, and the rules always run. Formisch then sees the object or
+   * array schema itself, so it keeps a field for each child.
+   */
+  container?: boolean;
 }
 /**
  * Picks the kind from the field. Declared as a method so it stays bivariant, like `schema()`.
@@ -101,6 +111,26 @@ type FieldWithProps<TProps extends AnyObjectSchema = AnyObjectSchema> = JsonFiel
 interface BuildContext {
   /** Where the field is in the definition, e.g. `['fields', 2]`. */
   readonly path: DefinitionPath;
+  /**
+   * Checks and builds child fields with the same registries, and returns their object schema.
+   * Their issues land in the same `validate()` result. `path` is where the list is in the
+   * definition, e.g. `[...ctx.path, 'fields']`.
+   */
+  buildFields(fields: readonly JsonField[], path: DefinitionPath): AnyObjectSchema;
+  /** Checks and builds one field for the items of a list. Its name isn't needed or used. */
+  buildField(field: JsonField, path: DefinitionPath): AnySchema;
+}
+/**
+ * A build context for testing a field type on its own, without a definition around it.
+ * `buildFields` and `buildField` use the default registries and throw a `DefinitionError` when
+ * the child fields have issues. `overrides` replaces any member, e.g. `path`.
+ */
+export declare function createBuildContext(overrides?: Partial<BuildContext>): BuildContext;
+interface KindDef {
+  /** True when the input means "no value". */
+  isEmpty(input: unknown): boolean;
+  /** Extra check for required fields after normalize rules ran. Omit it when isEmpty is enough. */
+  required?(message: string): AnyAction | null;
 }
 /**
  * `normalize` rules (trim, change case) run before the required check, so `'    '` with `trim` counts
@@ -129,15 +159,42 @@ interface RuleDef<TParams extends AnyObjectSchema = AnyObjectSchema> {
   /** Method syntax keeps `create` bivariant, so specific rules fit in a `Record<string, RuleDef>`. */
   create(params: v.InferOutput<TParams>, message?: string): AnyAction;
 }
+/**
+ * A rule that checks a field against other fields, e.g. that two passwords match. It goes in the
+ * definition's `formRules`, and its error shows on the field named by `field`.
+ */
+interface FormRuleDef<TParams extends AnyObjectSchema = AnyObjectSchema> {
+  /** Its params, next to `rule`, `field` and `message` in the definition. Unknown ones fail. */
+  params?: TParams;
+  /**
+   * The paths the rule reads besides `field`, e.g. `[params.other]`, so the builder can check
+   * that those fields exist. Method syntax keeps it bivariant, like `check()`.
+   */
+  reads(params: v.InferOutput<TParams>): readonly string[];
+  /** The kinds the fields it reads may have. Any kind when omitted. */
+  kinds?: readonly ValueKind[];
+  /** True when every field it reads must have the same kind, e.g. to compare them. */
+  sameKind?: boolean;
+  /**
+   * True when the values pass. `values` holds the value of `field`, then the values of the paths
+   * from `reads()`, in that order. It only runs when all of them are valid and none is empty.
+   */
+  check(values: readonly unknown[], params: v.InferOutput<TParams>): boolean;
+  meta?: RuleMeta;
+}
 interface MessageContext {
   field: JsonField;
   rule?: string;
   path: DefinitionPath;
 }
+/** The schema of a list of fields: an object with a key for each field that has a value. */
+type FieldsSchema = v.ObjectSchema<v.ObjectEntries, undefined>;
 interface SchemaBuilderOptions {
   kinds?: Record<string, KindDef>;
   fieldTypes?: Record<string, FieldTypeDef>;
   rules?: Record<string, RuleDef>;
+  formRules?: Record<string, FormRuleDef>;
+  /** With false, only your own rules and form rules are registered. Defaults to true. */
   includeDefaultRules?: boolean;
   messages?: {
     required?: string;
@@ -149,15 +206,56 @@ interface SchemaBuilderOptions {
   resolveMessage?(key: string, ctx: MessageContext): string | undefined;
 }
 export declare function createSchemaBuilder(options?: SchemaBuilderOptions): {
-  build: (json: JsonForm) => v.ObjectSchema<v.ObjectEntries, undefined>;
+  build: (json: JsonForm) => FieldsSchema;
   validate: (json: unknown) => ValidateResult;
   rulesForKind: (kind: ValueKind) => [name: string, def: RuleDef][];
   kinds: Readonly<Record<string, KindDef>>;
   fieldTypes: Readonly<Record<string, FieldTypeDef<AnyObjectSchema>>>;
   rules: Readonly<Record<string, RuleDef<AnyObjectSchema>>>;
+  formRules: Readonly<Record<string, FormRuleDef<AnyObjectSchema>>>;
 };
+/**
+ * Formisch's `initialInput` for a definition: each field's `default`, nested the way the value
+ * is. A group gives an object, and an array without a default gives `[]`. Other fields without
+ * a default are left out. Like `walkFields`, it reads the built-in `group` and `array` types
+ * and needs no builder.
+ */
+export declare function getInitialInput(definition: JsonForm): Record<string, unknown>;
+/** One field found by `walkFields`. */
+interface WalkedField {
+  field: JsonField;
+  /** The field's type, e.g. `'text'`. */
+  type: string;
+  /**
+   * Where the field's value is, as a Formisch path: `['address', 'city']`. The items of an array
+   * have no fixed index, so they have `'*'` in its place. A field without a name, like a
+   * heading, has its parent's path.
+   */
+  dataPath: readonly (string | number)[];
+  /** Where the field is in the definition: `['fields', 1, 'fields', 0]`. */
+  definitionPath: DefinitionPath;
+  /** 0 for the form's own fields, 1 for the fields inside them, and so on. */
+  depth: number;
+}
+/**
+ * Every field of a definition, at every depth, in document order. A group or an array comes
+ * before its fields, and the fields of an array's items come once. It reads the built-in
+ * `group` and `array` types and needs no builder, so it doesn't check the definition: run
+ * `validate()` first.
+ */
+export declare function walkFields(definition: JsonForm): Generator<WalkedField, void, undefined>;
 /** Every built-in field type. */
 export declare const defaultFieldTypes: {
+  group: FieldTypeDef<import("valibot").ObjectSchema<{
+    readonly fields: import("valibot").ArraySchema<import("valibot").CustomSchema<JsonField, undefined>, undefined>;
+  }, undefined>>;
+  array: FieldTypeDef<import("valibot").SchemaWithPipe<readonly [import("valibot").ObjectSchema<{
+    readonly of: import("valibot").OptionalSchema<import("valibot").CustomSchema<JsonField, undefined>, undefined>;
+    readonly fields: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").CustomSchema<JsonField, undefined>, undefined>, undefined>;
+  }, undefined>, import("valibot").CheckAction<{
+    of?: JsonField | undefined;
+    fields?: JsonField[] | undefined;
+  }, "Give exactly one of \"of\" and \"fields\"">]>>;
   heading: FieldTypeDef<import("valibot").ObjectSchema<{
     readonly text: import("valibot").StringSchema<undefined>;
     readonly level: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").IntegerAction<number, undefined>, import("valibot").MinValueAction<number, 1, undefined>, import("valibot").MaxValueAction<number, 6, undefined>]>, undefined>;
@@ -535,6 +633,7 @@ export declare const defaultRules: {
     readonly value: import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").IntegerAction<number, undefined>, import("valibot").MinValueAction<number, 0, undefined>]>;
   }, undefined>>;
 };
+export declare const defineFormRule: <T extends AnyObjectSchema>(def: FormRuleDef<T>) => FormRuleDef<T>;
 export declare const defineRule: <T extends AnyObjectSchema>(def: RuleDef<T>) => RuleDef<T>;
 /** Size and type of a File or Blob. */
 export declare const fileRules: {
@@ -587,6 +686,19 @@ export declare const formatRules: {
     readonly types: v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["md4", "md5", "sha1", "sha256", "sha384", "sha512", "ripemd128", "ripemd160", "tiger128", "tiger160", "tiger192", "crc32", "crc32b", "adler32"], undefined>, undefined>, v.MinLengthAction<("md4" | "md5" | "sha1" | "sha256" | "sha384" | "sha512" | "ripemd128" | "ripemd160" | "tiger128" | "tiger160" | "tiger192" | "crc32" | "crc32b" | "adler32")[], 1, "Pick at least one hash type">]>;
   }, undefined>>;
 };
+/** Every built-in form rule. */
+export declare const defaultFormRules: {
+  sameAs: FormRuleDef<v.ObjectSchema<{
+    readonly other: v.StringSchema<undefined>;
+  }, undefined>>;
+  differentFrom: FormRuleDef<v.ObjectSchema<{
+    readonly other: v.StringSchema<undefined>;
+  }, undefined>>;
+  compare: FormRuleDef<v.ObjectSchema<{
+    readonly op: v.PicklistSchema<["lt", "lte", "gt", "gte"], undefined>;
+    readonly other: v.StringSchema<undefined>;
+  }, undefined>>;
+};
 /** Characters of a string, or items of an array */
 export declare const lengthRules: {
   length: RuleDef<v.ObjectSchema<{
@@ -681,5 +793,9 @@ export declare const RESERVED_FIELD_KEYS: readonly ["name", "type", "label", "de
  * Rule keys this package owns. A rule's params can't use them.
  */
 export declare const RESERVED_RULE_KEYS: readonly ["rule", "message"];
-export type { AnyAction, AnyObjectSchema, AnySchema, BuildContext, DefinitionIssue, DefinitionIssueCode, DefinitionPath, FieldTypeDef, FieldWithProps, JsonField, JsonForm, JsonRule, KindDef, KindOf, MessageContext, RuleCategory, RuleDef, RuleMeta, RuleStage, SchemaBuilderOptions, ValidateResult, ValueKind };
+/**
+ * Form rule keys this package owns. A form rule's params can't use them.
+ */
+export declare const RESERVED_FORM_RULE_KEYS: readonly ["rule", "field", "message"];
+export type { AnyAction, AnyObjectSchema, AnySchema, BuildContext, DefinitionIssue, DefinitionIssueCode, DefinitionPath, FieldTypeDef, FieldWithProps, FormRuleDef, JsonField, JsonForm, JsonFormRule, JsonRule, KindDef, KindOf, MessageContext, RuleCategory, RuleDef, RuleMeta, RuleStage, SchemaBuilderOptions, ValidateResult, ValueKind, WalkedField };
 //# sourceMappingURL=index.d.ts.map