@jarenjs/forms 0.9.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Joham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# @jarenjs/forms
+
+Framework-agnostic form generation for JSON Schema. Turns a schema into a renderable field tree and validates it in **three layers, one stack**:
+
+1. **Per field, every keystroke** — cheap, synchronous checks powered directly by [`@jarenjs/core`](../core) primitives (grapheme-aware string lengths, unicode patterns, deep equality) and the canonical format-tester registry of [`@jarenjs/formats`](../formats): everything one field can know about itself.
+2. **Cross field, every keystroke** — visibility, enablement, computed values, and preemptive assertions expressed as [Jaren JSON Query](../json/docs/QUERY-FORMAT.md) documents in an `x-form` annotation, compiled once per model by [`@jarenjs/json`](../json) and evaluated per keystroke as cheap closures.
+3. **Authoritative, on submit** — the complete compiled schema validation with [`@jarenjs/validate`](../validate), which owns `required` combinations, `dependentSchemas`, `if/then/else`, `unevaluatedProperties`, and (via the `$query` keyword) the very same cross-field rules.
+
+No DOM, no framework: render the model with React, Vue, vanilla JS or anything else. Forms never imports the validator — apps wire the authoritative layer themselves. See it in action in the [Jaren playground](https://jklarenbeek.github.io/jarenjs/#/playground).
+
+## Usage
+
+```javascript
+import {
+  buildFormModel,
+  createInitialData,
+  validateField,
+  parseFieldInput,
+  setValueAtPointer,
+} from '@jarenjs/forms';
+
+const schema = {
+  type: 'object',
+  title: 'Sign up',
+  properties: {
+    username: { type: 'string', minLength: 3, pattern: '^[a-z0-9_]+$' },
+    email: { type: 'string', format: 'email' },
+    age: { type: 'integer', minimum: 13 },
+  },
+  required: ['username', 'email'],
+};
+
+// 1. Build the field tree once
+const model = buildFormModel(schema);
+// model.children -> [{ pointer: '/username', label: 'Username', control: 'text',
+//                      required: true, constraints: {...} }, ...]
+
+// 2. Start with the schema's defaults (untouched fields stay absent)
+let data = createInitialData(model);
+
+// 3. On every keystroke: coerce the raw input and validate the field
+const field = model.children.find((f) => f.key === 'email');
+const value = parseFieldInput(field, 'not-an-email');   // '' -> undefined, numbers -> Number, ...
+const errors = validateField(field, value);
+// [{ keyword: 'format', message: 'Must be a valid email' }]
+
+data = setValueAtPointer(data, field.pointer, value);   // immutable update
+
+// 4. On submit (or continuously): the authoritative validation
+import { JarenValidator } from '@jarenjs/validate';
+const validate = new JarenValidator({ skipErrors: false, collectErrors: true }).compile(schema);
+const result = validate(data); // { valid, errors: [{ instancePath, keyword, message, ... }] }
+```
+
+## The form model
+
+`buildFormModel(schema)` resolves local `$ref`s (`#/$defs/...`), merges `allOf` branches, and returns a tree of field descriptors:
+
+| Property | Meaning |
+|---|---|
+| `pointer` | JSON pointer into the data (`/user/name`) |
+| `label` | `title` or a humanized property name (`firstName` → "First Name") |
+| `kind` | `string` `number` `integer` `boolean` `enum` `const` `object` `array` |
+| `control` | Rendering hint: `text` `email` `url` `password` `textarea` `number` `checkbox` `select` `date` `color` `json` |
+| `required` | Whether the parent object requires this property |
+| `constraints` | `minLength`/`maxLength`/`pattern`/`format`/`minimum`/`maximum`/`multipleOf`/`minItems`/... |
+| `rules` | The raw `x-form` rules annotation, if any (see below) |
+| `enumValues` / `constValue` / `defaultValue` / `placeholder` | Values for the UI |
+| `children` | Child fields (object kinds) |
+| `item` / `tuple` | Item template and tuple prefix fields (array kinds) |
+
+Field kinds are inferred from structural keywords when `type` is absent, and `format` maps to input controls and placeholders through the same registry the preemptive validation uses (`getFormatInfo`).
+
+## Layer 1 — preemptive per-field validation
+
+`validateField(field, value)` returns `[{ keyword, message }]` using `@jarenjs/core` directly:
+
+- **strings**: grapheme-aware `minLength`/`maxLength` (`getStringLength`), unicode `pattern` (`createRegExp`, cached), and 50+ `format` testers from the [`@jarenjs/formats`](../formats) `formatTesters` registry — the same name → predicate table the authoritative validator's format compilers wrap, so both layers accept exactly the same strings
+- **numbers**: type/integer checks, bounds, `multipleOf`
+- **enum/const**: deep equality (`equalsDeep`)
+- **arrays**: `minItems`/`maxItems`/`uniqueItems` (`isUniqueDeepArray`)
+
+`validateAllFields(model, data)` walks the whole tree and returns a `{ '/pointer': errors }` map — ideal for rendering inline errors next to every field.
+
+## Layer 2 — `x-form` rules: cross-field behavior per keystroke
+
+One namespaced annotation keyword — safe under every metaschema, invisible to validators — on any subschema. Its members are [Jaren JSON Query](../json/docs/QUERY-FORMAT.md) documents (a bare RFC 9535 JSONPath string is the degenerate query):
+
+```json
+{ "type": "object",
+  "properties": {
+    "company":  { "type": "string" },
+    "vatId":    { "type": "string",
+                  "x-form": { "visible": { "$ne": ["$.company", ""] },
+                              "assert":  { "$or": [ { "$eq": ["$.company", ""] },
+                                                    { "$ne": ["$.vatId", ""] } ] },
+                              "message": "VAT id is required for companies" } },
+    "total":    { "type": "number",
+                  "x-form": { "computed": { "$sum": "$.lines[*].amount" } } }
+  } }
+```
+
+Recognized members — unknown members are ignored for forward compatibility:
+
+| Member | Kind | Meaning |
+|---|---|---|
+| `visible` | EBV query | Should the field be shown? |
+| `enabled` | EBV query | Should the field accept input? |
+| `assert` | EBV query | Cross-field preemptive validation |
+| `computed` | query | The field's derived value, mapped to plain JSON |
+| `message` | string | Shown when `assert` fails |
+
+Rules compile **once per model** and evaluate per keystroke:
+
+```javascript
+import { buildFormModel, compileFormRules, evaluateFormRules } from '@jarenjs/forms';
+
+const model = buildFormModel(schema);
+const rules = compileFormRules(model);          // throws on malformed rules, with the field pointer
+
+// per keystroke, after updating `data`:
+const state = evaluateFormRules(rules, data);
+// { '/vatId': { visible: true, errors: [{ keyword: 'x-form/assert',
+//               message: 'VAT id is required for companies' }] },
+//   '/total': { computed: 20 } }
+```
+
+### The rule query context
+
+Every rule kind shares one context:
+
+- **`$`** — the input document is the **whole form data root**: cross-field is the point.
+- **`$value`** — the field's current value, bound as an external per evaluation. An absent field binds `null` (`undefined` is not a JSON value).
+- **`$pointer`** — the field's data pointer string (`'/vatId'`).
+
+These two externals are the whole vocabulary: any other free name in a rule is a **compile-time** error naming it.
+
+`visible`/`enabled`/`assert` are asserted by **effective boolean value** (EBV, [QUERY-FORMAT.md §2.2](../json/docs/QUERY-FORMAT.md)): the empty sequence is `false`, a singleton counts per its type, a multi-item sequence is runtime error `JQ2003`. Runtime errors follow a fixed policy: `visible`/`enabled` **fail open** (evaluate to `true` — a broken rule must never hide data or lock a control), `assert` **fails closed** (an assertion that cannot be computed has not been satisfied), and `computed` leaves the value absent.
+
+### Array item templates
+
+A rule on an array item template (`/lines/-/amount`) compiles **once** and evaluates **per element** of the actual array, binding `$value`/`$pointer` per index — results are keyed by the expanded pointer (`/lines/2/amount`). That compiled-once/dispatch-per-node generalization now exists as the [`@jarenjs/json/jslt`](../json/docs/JSLT-FORMAT.md) `$apply` engine: a future forms computed-view layer can generalize `x-form.computed` into schema-dispatched view-model stylesheets without changing forms' validator-independent boundary.
+
+### Schema literals in rules
+
+Rules may use the query engine's schema operators (`$valid`/`$as`) by passing the same `compileTypeTest` hook the engine defines ([QUERY-FORMAT.md §8.11](../json/docs/QUERY-FORMAT.md)) — this is the only door through which a validator reaches forms, and the app holds the key:
+
+```javascript
+import { createTypeTestCompiler } from '@jarenjs/validate/query'; // app-side, not a forms dependency
+const rules = compileFormRules(model, { compileTypeTest: createTypeTestCompiler() });
+```
+
+### Composing rule errors with field errors
+
+`validateAllFields` and `evaluateFormRules` stay separate on purpose (a render loop usually wants them at different times). Both speak the same error shape, so merging is one spread per pointer:
+
+```javascript
+const fieldErrors = validateAllFields(model, data);   // layer 1
+const ruleState = evaluateFormRules(rules, data);     // layer 2
+const errorsAt = (pointer) => [
+  ...(fieldErrors[pointer] ?? []),
+  ...(ruleState[pointer]?.errors ?? []),
+];
+```
+
+## Layer 3 — write the rule once, enforce it on submit
+
+The same constraint can be spelled twice — `x-form.assert` for keystroke feedback, the [`$query` keyword](../validate) for authoritative submit validation — or written **once** and copied:
+
+```javascript
+import { formRulesToQueryAssertions } from '@jarenjs/forms';
+
+// pure schema-to-schema transform: every x-form.assert is copied into a
+// root-level $query (joined to an existing one through allOf), with
+// value/pointer rebound to the field's location
+const submitSchema = formRulesToQueryAssertions(schema);
+
+import { JarenValidator } from '@jarenjs/validate';                // app-side
+const validate = new JarenValidator().compile(submitSchema);
+validate({ company: 'ACME', vatId: '' }); // false - the vatId assert, now authoritative
+```
+
+Item-template asserts quantify with `$every` over the actual elements. Two divergences from the keystroke path are inherent to the copy: on submit an absent field binds `$value` to the empty sequence (not `null`), and `$pointer` for template elements stays the template pointer (element indexes are a render-time notion).
+
+## Data helpers
+
+Form data keeps plain JSON semantics — an untouched field is *absent*, not an empty string. Pointers parse and read through the [`@jarenjs/json`](../json) compiled pointer engine (RFC 6901, one implementation repo-wide); reads hit a compiled-getter cache and allocate nothing:
+
+- `createInitialData(model)` — defaults and `const` values filled in, everything else absent
+- `parseFieldInput(field, raw)` — input coercion (`''` → undefined, numeric strings → numbers, enum options → typed values)
+- `getValueAtPointer` / `setValueAtPointer` / `appendItem` / `removeItemAt` — immutable updates addressed by JSON pointer
+- `createItemValue(field.item)` — starter value for a new array item
+
+## Development
+
+Unit tests live in `test/forms/` at the repository root. See the repository [README](../../README.md) for the full Jaren documentation, and the [ROADMAP](../../ROADMAP.md) for planned forms work (rule dependency memoization, hidden-field pruning on submit, computed views through JSLT).

package/dist/types/data.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Split a JSON pointer into decoded segments per RFC 6901. '' -> [].
+ * @param {string} pointer
+ * @returns {string[]}
+ * @throws {import('@jarenjs/json/pointer').JSONPointerSyntaxError}
+ *   When the pointer violates the RFC 6901 grammar
+ */
+export declare function parsePointer(pointer: string): string[];
+/**
+ * Read the value at a JSON pointer.
+ * @param {any} data
+ * @param {string} pointer - e.g. '/user/address/0/street'
+ * @returns {any} The value, or undefined when the path does not exist
+ */
+export declare function getValueAtPointer(data: any, pointer: string): any;
+/**
+ * Return a copy of `data` with the value at `pointer` replaced.
+ * Setting `undefined` REMOVES the property (array items become undefined
+ * holes only when explicitly set; use removeItemAt to delete them).
+ * Missing intermediate containers are created (objects for name segments,
+ * arrays for numeric segments).
+ * @param {any} data
+ * @param {string} pointer
+ * @param {any} value
+ * @returns {any} The new root value
+ */
+export declare function setValueAtPointer(data: any, pointer: string, value: any): any;
+/**
+ * Return a copy of `data` with the item at `index` removed from the array
+ * at `pointer`.
+ * @param {any} data
+ * @param {string} pointer - Pointer to the ARRAY
+ * @param {number} index
+ * @returns {any}
+ */
+export declare function removeItemAt(data: any, pointer: string, index: number): any;
+/**
+ * Return a copy of `data` with `value` appended to the array at `pointer`
+ * (the array is created when absent).
+ * @param {any} data
+ * @param {string} pointer - Pointer to the ARRAY
+ * @param {any} value
+ * @returns {any}
+ */
+export declare function appendItem(data: any, pointer: string, value: any): any;
+/**
+ * Create initial data for a form model: schema defaults and const values
+ * are filled in, everything else stays absent.
+ * @param {import('./model.js').FormField} field - A field from buildFormModel
+ * @returns {any}
+ */
+export declare function createInitialData(field: import('./model.js').FormField): any;
+/**
+ * Create a sensible starter value for one array item of the given field.
+ * @param {import('./model.js').FormField} itemField
+ * @returns {any}
+ */
+export declare function createItemValue(itemField: import('./model.js').FormField): any;
+/**
+ * Coerce a raw input string (what an HTML input yields) into the typed
+ * value for a field. An empty string means "absent" (undefined) so that
+ * required/optional semantics stay correct.
+ * @param {import('./model.js').FormField} field
+ * @param {any} raw - Raw input value (string, or boolean for checkboxes)
+ * @returns {any}
+ */
+export declare function parseFieldInput(field: import('./model.js').FormField, raw: any): any;

package/dist/types/formats.d.ts

@@ -0,0 +1,22 @@
+export type FormatInfo = {
+    /**
+     * - Synchronous validity test
+     */
+    test: (value: string) => boolean;
+    /**
+     * - Suggested HTML input control
+     */
+    control: string;
+    /**
+     * - Suggested placeholder text
+     */
+    placeholder?: string;
+};
+/** @type {Record<string, FormatInfo>} */
+export declare const FORM_FORMATS: Record<string, FormatInfo>;
+/**
+ * Look up the format info for a JSON Schema format name.
+ * @param {string|undefined} format - The format name
+ * @returns {FormatInfo|null} The format info, or null when unknown
+ */
+export declare function getFormatInfo(format: string | undefined): FormatInfo | null;

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @jarenjs/forms - framework-agnostic form model generation for JSON Schema.
+ *
+ * buildFormModel(schema) turns a schema into a renderable field tree;
+ * validateField gives immediate per-field feedback powered by @jarenjs/core
+ * primitives, and the `x-form` rules (rules.js) add cross-field behavior -
+ * visibility, enablement, computed values, preemptive assertions - as
+ * compiled Jaren JSON Queries, before the complete compiled schema
+ * validation runs (app-wired; forms never imports the validator). The
+ * data helpers keep form values in plain JSON semantics, addressed by
+ * JSON pointer through the @jarenjs/json compiled pointer engine.
+ */
+export { buildFormModel, resolveSchema, getFieldKind, humanizeKey, escapePointerKey, } from './model.js';
+export { compileFormRules, evaluateFormRules, formRulesToQueryAssertions, } from './rules.js';
+export { validateField, validateAllFields, } from './validate.js';
+export { createInitialData, createItemValue, parseFieldInput, parsePointer, getValueAtPointer, setValueAtPointer, appendItem, removeItemAt, } from './data.js';
+export { FORM_FORMATS, getFormatInfo, } from './formats.js';

package/dist/types/model.d.ts

@@ -0,0 +1,125 @@
+export type FormField = {
+    /**
+     * - JSON pointer into the DATA (e.g. '/user/name')
+     */
+    pointer: string;
+    /**
+     * - Property name (or '-' for an array item template)
+     */
+    key: string;
+    /**
+     * - Human friendly label (schema title or humanized key)
+     */
+    label: string;
+    description: string | undefined;
+    /**
+     * - The resolved subschema for this field
+     */
+    schema: object;
+    /**
+     * - 'string'|'number'|'integer'|'boolean'|'enum'|'const'|'object'|'array'|'unknown'
+     */
+    kind: string;
+    /**
+     * - Suggested control: 'text'|'email'|'url'|'password'|'textarea'|'number'|'checkbox'|'select'|'date'|'color'|'json'
+     */
+    control: string;
+    /**
+     * - Whether the parent object requires this property
+     */
+    required: boolean;
+    readOnly: boolean;
+    /**
+     * - Options for a select control
+     */
+    enumValues: Array<any> | null;
+    /**
+     * - Fixed value when the schema is a const
+     */
+    constValue: any;
+    defaultValue: any;
+    placeholder: string | undefined;
+    /**
+     * - minLength/maxLength/pattern/minimum/... extracted for the UI
+     */
+    constraints: object;
+    /**
+     * - The raw `x-form` rules annotation, if any (see rules.js)
+     */
+    rules: object | null;
+    /**
+     * - Child fields for object kinds
+     */
+    children: Array<FormField> | null;
+    /**
+     * - Template field for array items
+     */
+    item: FormField | null;
+    /**
+     * - Fixed prefix fields for tuple arrays
+     */
+    tuple: Array<FormField> | null;
+};
+/**
+ * @typedef {object} FormField
+ * @property {string} pointer - JSON pointer into the DATA (e.g. '/user/name')
+ * @property {string} key - Property name (or '-' for an array item template)
+ * @property {string} label - Human friendly label (schema title or humanized key)
+ * @property {string|undefined} description
+ * @property {object} schema - The resolved subschema for this field
+ * @property {string} kind - 'string'|'number'|'integer'|'boolean'|'enum'|'const'|'object'|'array'|'unknown'
+ * @property {string} control - Suggested control: 'text'|'email'|'url'|'password'|'textarea'|'number'|'checkbox'|'select'|'date'|'color'|'json'
+ * @property {boolean} required - Whether the parent object requires this property
+ * @property {boolean} readOnly
+ * @property {Array<any>|null} enumValues - Options for a select control
+ * @property {any} constValue - Fixed value when the schema is a const
+ * @property {any} defaultValue
+ * @property {string|undefined} placeholder
+ * @property {object} constraints - minLength/maxLength/pattern/minimum/... extracted for the UI
+ * @property {object|null} rules - The raw `x-form` rules annotation, if any (see rules.js)
+ * @property {Array<FormField>|null} children - Child fields for object kinds
+ * @property {FormField|null} item - Template field for array items
+ * @property {Array<FormField>|null} tuple - Fixed prefix fields for tuple arrays
+ */
+/**
+ * Convert 'firstName' / 'first_name' / 'first-name' to 'First Name'.
+ * @param {string} key
+ * @returns {string}
+ */
+export declare function humanizeKey(key: string): string;
+/**
+ * Resolve local $refs and shallowly merge allOf branches into a single
+ * effective schema object for form purposes.
+ * @param {object|boolean} schema
+ * @param {object} rootSchema
+ * @param {number} depth
+ * @returns {object|boolean}
+ */
+export declare function resolveSchema(schema: object | boolean, rootSchema: object, depth?: number): object | boolean;
+/**
+ * Derive the field kind from a resolved schema.
+ * @param {object|boolean} schema
+ * @returns {string}
+ */
+export declare function getFieldKind(schema: object | boolean): string;
+/**
+ * Encode a property name as an RFC 6901 reference token (`~` -> `~0`,
+ * `/` -> `~1`), the write-side inverse of the shared parse.
+ * @param {string} key
+ * @returns {string}
+ */
+export declare function escapePointerKey(key: string): string;
+/**
+ * Build the form model for a JSON schema.
+ *
+ * @param {object|boolean} schema - The root JSON schema
+ * @returns {FormField} The root field descriptor (kind 'object' for object schemas)
+ * @example
+ * const model = buildFormModel({
+ *   type: 'object',
+ *   properties: { email: { type: 'string', format: 'email' } },
+ *   required: ['email'],
+ * });
+ * model.children[0].control; // 'email'
+ */
+export declare function buildFormModel(schema: object | boolean): FormField;

package/dist/types/rules.d.ts

@@ -0,0 +1,131 @@
+export type RuleResult = {
+    /**
+     * - EBV of the field's `visible` rule
+     */
+    visible?: boolean;
+    /**
+     * - EBV of the field's `enabled` rule
+     */
+    enabled?: boolean;
+    /**
+     * - Plain-JSON result of the `computed` rule
+     */
+    computed?: any;
+    /**
+     * `[{ keyword: 'x-form/assert', message }]` when the `assert` rule fails
+     * (the validateField error shape, so error rendering works unchanged)
+     */
+    errors?: Array<import('./validate.js').FieldError>;
+};
+export type CompiledFieldRules = {
+    /**
+     * - The field's data pointer (template pointers keep `-`)
+     */
+    pointer: string;
+    /**
+     * - Decoded segments; ITEM marks an array-item slot
+     */
+    parts: Array<string | symbol>;
+    /**
+     * - Whether `parts` contains an ITEM slot
+     */
+    templated: boolean;
+    /**
+     * - Compiled getter (non-template fields)
+     */
+    getValue: ((root: any) => any) | null;
+    visible: Function | null;
+    enabled: Function | null;
+    assert: Function | null;
+    computed: Function | null;
+    message: string | null;
+};
+export type CompiledRules = {
+    rules: Array<CompiledFieldRules>;
+};
+/**
+ * @typedef {object} CompiledFieldRules
+ * @property {string} pointer - The field's data pointer (template pointers keep `-`)
+ * @property {Array<string|symbol>} parts - Decoded segments; ITEM marks an array-item slot
+ * @property {boolean} templated - Whether `parts` contains an ITEM slot
+ * @property {((root: any) => any)|null} getValue - Compiled getter (non-template fields)
+ * @property {function|null} visible
+ * @property {function|null} enabled
+ * @property {function|null} assert
+ * @property {function|null} computed
+ * @property {string|null} message
+ */
+/**
+ * @typedef {object} CompiledRules
+ * @property {Array<CompiledFieldRules>} rules
+ */
+/**
+ * Compile every `x-form` rule of a form model into reusable closures.
+ *
+ * Walks the field tree once and runs `compileJsonQuery` per rule
+ * document. `options.compileTypeTest` passes through to the query
+ * compiler, so rules may use `$valid`/`$assert`/`$as` with a
+ * caller-supplied type-test compiler (the validator package's `query`
+ * module exports `createTypeTestCompiler()`; forms itself never imports
+ * the validator).
+ * Without the hook, a schema-using rule surfaces the engine's JQ0008.
+ *
+ * @param {import('./model.js').FormField} model - Root field from buildFormModel
+ * @param {object} [options]
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - hook for schema literals inside rules
+ * @returns {CompiledRules}
+ * @throws {Error} On a malformed rule document (field pointer prepended)
+ *   or a rule referencing an external other than `value`/`pointer`
+ * @example
+ * const compiled = compileFormRules(model);
+ * const results = evaluateFormRules(compiled, data);
+ * results['/vatId']; // { visible: true, errors: [{ keyword: 'x-form/assert', ... }] }
+ */
+export declare function compileFormRules(model: import('./model.js').FormField, options?: {
+    compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
+}): CompiledRules;
+/**
+ * Evaluate compiled form rules against the current data root.
+ *
+ * Returns a map of data pointer -> RuleResult holding only the rules each
+ * field declares. Rules on array item templates are evaluated once per
+ * element of the actual array, keyed by the expanded pointer.
+ *
+ * @param {CompiledRules} compiled - From compileFormRules
+ * @param {any} data - The form data root (the query input `$`)
+ * @returns {Record<string, RuleResult>}
+ * @example
+ * const results = evaluateFormRules(compiled, { company: 'ACME', vatId: '' });
+ * results['/vatId'].errors; // [{ keyword: 'x-form/assert', message: '...' }]
+ */
+export declare function evaluateFormRules(compiled: CompiledRules, data: any): Record<string, RuleResult>;
+/**
+ * Copy every `x-form.assert` of a schema into a `$query` assertion, so a
+ * rule authored once for per-keystroke feedback is also enforced by the
+ * authoritative submit validation (the validator's `$query` keyword).
+ * Pure schema-to-schema transform - no validator import; the output only
+ * spells the keyword.
+ *
+ * The `$query` lands on the ROOT schema (where the query input `$` is the
+ * instance root, matching the rule context), with each assert wrapped to
+ * rebuild its bindings: `value` binds to the field's location, `pointer`
+ * to its pointer string. An assert on an array item template quantifies
+ * with `$every` over the actual elements (`pointer` then stays the
+ * template pointer - element indexes are a render-time notion). Multiple
+ * asserts conjoin under `$and`; an existing root `$query` is preserved by
+ * wrapping the new one in an `allOf` branch.
+ *
+ * The transform follows the same structural spine as buildFormModel
+ * (`properties`, `items`, `prefixItems`, `allOf`) but does not resolve
+ * `$ref`s - a `$def`'s data location depends on its use site.
+ *
+ * @param {object|boolean} schema - The root JSON schema
+ * @returns {object|boolean} A new root schema (input is not mutated;
+ *   untouched subtrees are shared) with the collected `$query`, or the
+ *   input itself when there is nothing to copy
+ * @example
+ * const submitSchema = formRulesToQueryAssertions(schema);
+ * const validate = new JarenValidator().compile(submitSchema); // caller-side
+ */
+export declare function formRulesToQueryAssertions(schema: object | boolean): object | boolean;

package/dist/types/validate.d.ts

@@ -0,0 +1,29 @@
+export type FieldError = {
+    /**
+     * - The JSON Schema keyword that failed
+     */
+    keyword: string;
+    /**
+     * - Human readable message
+     */
+    message: string;
+};
+/**
+ * Validate a single field value against its own constraints.
+ *
+ * @param {import('./model.js').FormField} field - Field from buildFormModel
+ * @param {any} value - The TYPED value (see parseFieldInput); undefined = absent
+ * @returns {FieldError[]} Empty when the value passes every per-field check
+ * @example
+ * const errors = validateField(emailField, 'not-an-email');
+ * // [{ keyword: 'format', message: 'Must be a valid email' }]
+ */
+export declare function validateField(field: import('./model.js').FormField, value: any): FieldError[];
+/**
+ * Validate every leaf field of a model against the current data.
+ * Returns a map of data-pointer -> FieldError[] for fields that fail.
+ * @param {import('./model.js').FormField} model - Root field from buildFormModel
+ * @param {any} data - Current form data
+ * @returns {Record<string, FieldError[]>}
+ */
+export declare function validateAllFields(model: import('./model.js').FormField, data: any): Record<string, FieldError[]>;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jarenjs/forms",
+  "private": false,
+  "version": "0.9.2",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/types/",
+    "src/"
+  ],
+  "description": "Framework-agnostic form model generator for JSON Schema with preemptive per-field validation powered by @jarenjs/core",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "packages/forms"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "json",
+    "schema",
+    "form",
+    "forms",
+    "generator",
+    "validation"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.9.2",
+    "@jarenjs/formats": "^0.9.2",
+    "@jarenjs/json": "^0.9.2"
+  }
+}