@reformer/core 10.2.0 → 11.0.0-beta.10

package/README.md

@@ -4,7 +4,8 @@
 [![npm downloads](https://img.shields.io/npm/dm/@reformer/core.svg)](https://www.npmjs.com/package/@reformer/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Reactive form state management library for React with signals-based architecture.
+Reactive form state management on signals: a UI-agnostic core with React bindings in
+`@reformer/core/react`.
 
 ## Playground
 
@@ -17,10 +18,12 @@ Full documentation is available at [https://alexandrbukhtatyy.github.io/ReFormer
 ## Features
 
 - Signals-based reactive state management
-- Declarative form validation
+- Declarative form validation with typed rules and status results
+- Validation issues without text: codes and params, texts from a form dictionary and the locale
 - Dynamic form behaviors
+- Multi-step flows: step rules, transitions, `submit` with a result object
 - TypeScript support
-- Tree-shakeable exports
+- Tree-shakeable exports; the root entry has no React dependency
 
 ## Installation
 
@@ -30,27 +33,45 @@ npm install @reformer/core@beta # Active development is underway, so you can try
 
 ## Quick Start
 
-ReFormer is built around the **M1 architecture**: a reactive `FormModel` owns the values, a layout
-schema binds field config (component / props) to the model's signals, and `createForm({ model, schema })`
-wires them into a typed form. Validation is a **separate** ambient contract — `defineValidationSchema`,
-run on demand by `validateModel(model, schema)` — so the layout schema carries no validators.
+A reactive `FormModel` owns the values, a form schema — a tree of nodes — binds field config
+(component / props) to the model's handles (`model.$.<field>`), and `createForm` assembles the
+model, the form and the form level (`validate`, `submission`, step flow) in one call. Validation is a
+**separate** contract — `defineValidation` — so the form schema carries no validators. A rule
+reports a code, not a text: the text comes from a form dictionary (`defineIssueMessages`) on top of
+the locale.
 
 ```tsx
-import { useMemo } from 'react';
 import {
-  createModel,
   createForm,
-  useFormControl,
-  type FieldNode,
-  type ValidationError,
+  type FormControl,
+  type FormModel,
+  type FormSchemaNode,
+  type ValidationIssue,
 } from '@reformer/core';
-import { validate, cross, defineValidationSchema, validateModel } from '@reformer/core/validation';
+import { useFormBundle, useFormControl, useIssueMessage } from '@reformer/core/react';
+import { defineIssueMessages } from '@reformer/core/i18n';
+import { validate, defineValidation } from '@reformer/core/validation';
 import { required, email, minLength } from '@reformer/core/validators';
 import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
 
-// 0. Simple FormField component
-function FormField({ label, control }: { label: string; control: FieldNode<string> }) {
-  const { value, errors, shouldShowError } = useFormControl(control);
+// 1. Form data type — `interface` or `type`, both work
+interface RegistrationForm {
+  username: string;
+  email: string;
+  password: string;
+  confirmPassword: string;
+}
+
+// 2. Issue texts by code — the form dictionary (built-in codes fall back to the locale)
+const messages = defineIssueMessages({
+  'username.required': 'Enter a username',
+  'confirmPassword.mismatch': 'Passwords do not match',
+});
+
+// 3. Simple FormField component: the issue text comes from the resolver
+function FormField({ label, control }: { label: string; control: FormControl<string> }) {
+  const { value, issues, shouldShowError } = useFormControl(control);
+  const message = useIssueMessage(messages);
 
   return (
     <div>
@@ -60,78 +81,69 @@ function FormField({ label, control }: { label: string; control: FieldNode<strin
         onChange={(e) => control.setValue(e.target.value)}
         onBlur={() => control.markAsTouched()}
       />
-      {shouldShowError && <span className="error">{errors[0].message}</span>}
+      {shouldShowError && issues[0] && <span className="error">{message(issues[0])}</span>}
     </div>
   );
 }
 
-// 1. Define form interface
-interface RegistrationForm {
-  username: string;
-  email: string;
-  password: string;
-  confirmPassword: string;
-}
-
-// 2. Reactive model — the source of truth for values
-const model = createModel<RegistrationForm>({
-  username: '',
-  email: '',
-  password: '',
-  confirmPassword: '',
-});
-
-// 3. Layout schema — binds field config (component / props) to model signals
-//    (`model.$.<field>`). Layout carries NO validators; rules live in the
-//    validation schema below.
-const schema = {
+// 4. Form schema — a tree of nodes. A field node binds field config (component / props)
+//    to a model handle (`model: model.$.<field>`); nested nodes live in `children`.
+//    The schema carries NO validators; rules live in the validation schema below.
+const schema = (model: FormModel<RegistrationForm>): FormSchemaNode => ({
   children: [
-    { value: model.$.username, component: Input },
-    { value: model.$.email, component: Input },
-    { value: model.$.password, component: Input },
-    { value: model.$.confirmPassword, component: Input },
+    { model: model.$.username, component: 'input' },
+    { model: model.$.email, component: 'input' },
+    { model: model.$.password, component: 'input' },
+    { model: model.$.confirmPassword, component: 'input' },
   ],
-};
-
-// 4. Validation schema — a separate ambient contract from `@reformer/core/validation`,
-//    run on demand (not reactive). Field rules go through `validate(sig, [rules])`;
-//    cross-field rules through `cross(sig, snapshot => error | null)` where the snapshot
-//    is `model.get()`. Rule factories (`required()`/…) come from `@reformer/core/validators`.
-const passwordsMatch = (f: RegistrationForm): ValidationError | null =>
-  f.confirmPassword && f.password && f.confirmPassword !== f.password
-    ? { code: 'mismatch', message: 'Passwords do not match' }
+});
+
+// 5. Validation schema — a separate contract from `@reformer/core/validation`.
+//    Field rules go through `validate(sig, [rules])`; cross-field rules through
+//    `cross(sig, snapshot => issue | null)` taken from the schema argument — the snapshot is the
+//    model value, its type is inferred. Rule factories come from `@reformer/core/validators`.
+const passwordsMatch = (form: RegistrationForm): ValidationIssue | null =>
+  form.confirmPassword && form.password && form.confirmPassword !== form.password
+    ? { code: 'confirmPassword.mismatch' }
     : null;
 
-const validationSchema = defineValidationSchema<RegistrationForm>(({ model }) => {
-  validate(model.$.username, [required(), minLength(2)]);
+const validation = defineValidation<RegistrationForm>(({ model, cross }) => {
+  validate(model.$.username, [required({ code: 'username.required' }), minLength(2)]);
   validate(model.$.email, [required(), email()]);
   validate(model.$.password, [required(), minLength(8)]);
   validate(model.$.confirmPassword, [required()]);
   cross(model.$.confirmPassword, passwordsMatch);
 });
 
-// 5. Behavior — declarative reactive logic, run by `createForm({ behavior })`.
-//    Validation runs on demand, so the stale cross-field error on `confirmPassword`
-//    is cleared the moment `password` changes — a behavior→validation bridge.
+// 6. Behavior — declarative reactive logic, run by `createForm({ behavior })`.
+//    Validation runs on demand, so the stale cross-field issue on `confirmPassword`
+//    is cleared the moment `password` changes.
 const behavior = defineFormBehavior<RegistrationForm>(({ model, form }) => {
   onChange(model.$.password, () => {
-    form.confirmPassword.clearErrors();
+    form.confirmPassword.clearIssues();
   });
 });
 
-// 6. Registration form component
+// 7. One assembly: model, form, behavior, validation and the form level
+const createRegistration = () =>
+  createForm<RegistrationForm>({
+    initial: { username: '', email: '', password: '', confirmPassword: '' },
+    schema,
+    behavior,
+    validation,
+  });
+
 function RegistrationFormExample() {
-  const form = useMemo(() => createForm<RegistrationForm>({ model, schema, behavior }), []);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    form.touchAll();
-    // Validate the whole model against the validation schema (sync + async) on demand;
-    // errors route into the form nodes, so the UI highlights the offending fields.
-    const valid = await validateModel(model, validationSchema);
-    if (valid) {
-      console.log('Form data:', model.get());
-    }
+  // useFormBundle calls the factory exactly once and keeps the bundle stable between renders
+  const bundle = useFormBundle(createRegistration);
+  const { form } = bundle;
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    // One run of all the rules (sync + async). Issues land on the form nodes and, on a refusal,
+    // the whole form is marked touched; the handler is called only when the status is 'valid'.
+    const outcome = await bundle.submission.submit((values) => console.log('Form data:', values));
+    if (outcome.status === 'error') console.warn('Could not check the form, try again');
   };
 
   return (
@@ -146,6 +158,16 @@ function RegistrationFormExample() {
 }
 ```
 
+Submission is a separate object of the bundle: `bundle.submission.submit(handler)` returns a
+`SubmitResult`: `submitted` (with the handler's result), `invalid` / `error` / `cancelled` (with
+the validation result; the handler was not called) or `failed` (the handler threw). The handler
+receives the whole model, disabled fields included; `bundle.submission.submitting` is `true` while
+it runs. Multi-step forms declare their steps in the same call —
+`createForm({ flow: { steps: [{ id, rules }] } })` — and navigate with `bundle.flow.next()`.
+Outside React, the owner of the bundle releases it with `bundle.dispose()` when the form is no
+longer needed: the behavior, the node subscriptions and the live validation stop, the model keeps
+its values.
+
 ## License
 
 MIT

package/dist/behaviors-value-D05z3my6.js

@@ -0,0 +1,109 @@
+import { effect as s } from "@preact/signals-core";
+import { h as f } from "./safe-effect-BazLOv1g.js";
+function m(t, r, l, e) {
+  return s(() => {
+    const n = t.map((c) => c.value);
+    if (e?.when && !e.when(...n)) return;
+    const u = l(...n);
+    r.peek() !== u && (r.value = u);
+  });
+}
+function h(t, r, l) {
+  return s(() => {
+    const e = t.value;
+    if (l?.when && !l.when()) return;
+    const n = l?.transform ? l.transform(e) : e;
+    r.peek() !== n && (r.value = n);
+  });
+}
+function w(t, r, l) {
+  let e = !0;
+  return s(() => {
+    const n = t.value;
+    e && (e = !1, !l?.immediate) || r(n);
+  });
+}
+function k(t, r) {
+  let l = !1;
+  const e = f(), n = s(() => {
+    t.value, !l && e.schedule(() => {
+      const u = r(t.peek());
+      if (t.peek() !== u) {
+        l = !0;
+        try {
+          t.value = u;
+        } finally {
+          l = !1;
+        }
+      }
+    });
+  });
+  return () => {
+    n(), e.cancelAll();
+  };
+}
+function y(t, r, ...[l]) {
+  const e = l?.resetValue ?? null, n = f(), u = s(() => {
+    r(), n.schedule(() => {
+      r() && t.peek() !== e && (t.value = e);
+    });
+  });
+  return () => {
+    u(), n.cancelAll();
+  };
+}
+function A(t, r, l) {
+  const e = l?.transform;
+  let n = !1, u = !0;
+  const c = f(), o = s(() => {
+    t.value, !n && (c.cancelAll(), c.schedule(() => {
+      n = !0;
+      try {
+        const a = t.peek(), i = e ? e(a) : a;
+        r.peek() !== i && (r.value = i);
+      } finally {
+        n = !1;
+      }
+    }));
+  }), v = s(() => {
+    if (r.value, u) {
+      u = !1;
+      return;
+    }
+    n || (c.cancelAll(), c.schedule(() => {
+      n = !0;
+      try {
+        const a = r.peek(), i = t.peek();
+        if ((e ? e(i) : i) === a) return;
+        i !== a && (t.value = a);
+      } finally {
+        n = !1;
+      }
+    }));
+  });
+  return () => {
+    o(), v(), c.cancelAll();
+  };
+}
+function x(t, r) {
+  let l = !0;
+  const e = f(), n = s(() => {
+    if (t.forEach((u) => u.value), l) {
+      l = !1;
+      return;
+    }
+    e.schedule(() => r());
+  });
+  return () => {
+    n(), e.cancelAll();
+  };
+}
+export {
+  h as a,
+  x as b,
+  m as c,
+  y as r,
+  A as s,
+  k as t,
+  w
+};

package/dist/behaviors.d.ts

@@ -1,2 +1,2 @@
-export * from './form/behaviors'
+export * from './form/behaviors/index'
 export {}