@streetui/forms 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StreetUI contributors
+
+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,158 @@
+# @streetui/forms
+
+A reactive form model and a small synchronous validation system, built
+**entirely** on `@streetui/state` signals. There is no second state system: every
+piece of form state — `values`, `errors`, `touched`, `dirty`, `valid`, and the
+submission lifecycle — is a signal or a derived signal, so it composes with the
+renderer's existing reactive bindings and needs no special integration.
+
+```bash
+# part of the StreetUI monorepo — no separate install
+```
+
+---
+
+## The form model
+
+`createForm<T>()` takes typed initial values, optional per-field validators, and
+an `onSubmit` handler. `T` must extend `Record<string, string>` (HTML input
+values are strings), and every reactive accessor is typed against it.
+
+```ts
+import { createForm, required, email, minLength } from '@streetui/forms';
+
+interface SignupValues {
+  name: string;
+  email: string;
+  password: string;
+  [key: string]: string;
+}
+
+const form = createForm<SignupValues>({
+  initialValues: { name: '', email: '', password: '' },
+  validators: {
+    name: required('Name is required'),
+    email: [required('Email is required'), email()],   // ordered — first error wins
+    password: [required(), minLength(8, 'At least 8 characters')],
+  },
+  onSubmit: async (values) => {
+    await createAccount(values);   // any async function; may throw
+  },
+});
+```
+
+### Form-level reactive state
+
+| Accessor | Type | Meaning |
+|---|---|---|
+| `form.values` | `ReadonlySignal<T>` | Current values of every field. |
+| `form.errors` | `ReadonlySignal<Partial<Record<keyof T, string>>>` | Only the fields that currently have an error. |
+| `form.touched` | `ReadonlySignal<Partial<Record<keyof T, boolean>>>` | Per-field touched flags. |
+| `form.dirty` | `ReadonlySignal<boolean>` | True if any field differs from its initial value. |
+| `form.valid` | `ReadonlySignal<boolean>` | True when every field passes validation. |
+| `form.submitting` | `ReadonlySignal<boolean>` | True while `onSubmit` is in flight. |
+| `form.submitted` | `ReadonlySignal<boolean>` | True after a successful submit. |
+| `form.status` | `ReadonlySignal<'idle' \| 'submitting' \| 'success' \| 'error'>` | The submission lifecycle. |
+| `form.submitError` | `ReadonlySignal<unknown>` | Whatever `onSubmit` threw, if anything. |
+
+Because these are the same signals used everywhere else in StreetUI, they drop
+straight into DSL bindings and `derived()`.
+
+---
+
+## Fields and input binding
+
+`form.field(name)` returns the reactive state and setters for one field. The
+field's `value` is a writable `Signal<string>` — pass it directly to the DSL's
+`input({ bind })`. That is the **one** binding the renderer already wires:
+typing updates form state, and programmatic updates update the input. No
+duplicate event listeners are added.
+
+```ts
+const emailField = form.field('email');
+
+page.input({ bind: emailField.value, type: 'email' });
+page.when(
+  derived(() => emailField.touched.get() && emailField.error.get() !== undefined),
+  (err) => err.text(derived(() => emailField.error.get() ?? ''), { role: 'alert' }),
+);
+```
+
+A `Field` exposes `value` (writable signal), `error`, `touched`, `dirty`, `valid`
+(read-only signals), and the imperative helpers `setValue()`, `markTouched()`,
+and `reset()`. Errors are computed reactively from the validators, so surfacing
+them is a matter of reading `field.error` — usually gated on `field.touched` so
+a pristine field is not flagged before the user has interacted with it.
+
+---
+
+## Submission lifecycle
+
+`form.submit()` marks every field touched (so validation errors become visible),
+then:
+
+- if the form is **invalid**, it stays `idle` and returns without calling
+  `onSubmit` — the now-visible field errors tell the user what to fix;
+- if **valid**, it transitions `idle → submitting`, awaits `onSubmit(values)`,
+  and settles on `success` or — if `onSubmit` throws — `error`, capturing the
+  thrown value in `form.submitError`.
+
+Wire it to both the button and the native form submit event; the renderer's
+event system already calls `preventDefault()` for submit events, so no manual
+handling is needed:
+
+```ts
+page.form('signup', (fb) => {
+  // ...fields...
+  fb.button(
+    derived(() => (form.submitting.get() ? 'Creating…' : 'Create account')),
+    { disabled: form.submitting, onClick: () => void form.submit() },
+  );
+}, { onSubmit: () => void form.submit() });
+```
+
+---
+
+## Validators
+
+A `Validator` is just `(value: string) => string | undefined` — return a message
+to fail, `undefined` to pass. Built-ins cover the common cases; anything else is
+a plain function.
+
+| Validator | Fails when |
+|---|---|
+| `required(message?)` | the trimmed value is empty |
+| `minLength(n, message?)` | shorter than `n` characters |
+| `maxLength(n, message?)` | longer than `n` characters |
+| `email(message?)` | a non-empty value is not a plausible email |
+| `pattern(regex, message?)` | a non-empty value does not match `regex` |
+
+Per-field validators run **in order and the first error wins**, so list
+`required` first for mandatory fields. A custom validator needs no wrapper:
+
+```ts
+const noSpaces: Validator = (v) => (/\s/.test(v) ? 'No spaces allowed' : undefined);
+
+createForm({ initialValues: { handle: '' }, validators: { handle: [required(), noSpaces] } });
+```
+
+### Async validation
+
+Async validation is intentionally **not** part of this core, to keep the
+validity model synchronous and predictable. Layer it on with `@streetui/state`'s
+`resource()`: kick off a resource on value change and surface `resource.error`
+alongside `field.error`. This keeps network-driven checks out of the synchronous
+`valid` computation.
+
+---
+
+## Lifecycle
+
+`createForm()` allocates field subscriptions and derived signals. Call
+`form.dispose()` when the owning subtree is torn down — inside a route this is
+`ctx.onCleanup(() => form.dispose())` — to release every subscription and derived
+signal. `form.reset()` restores initial values and clears errors, touched, dirty,
+and submission state without disposing.
+
+A complete, runnable form (real HTTP submit, validation, error state, SSR +
+hydration, i18n'd messages) lives in `examples/streetui-account`.

package/dist/index.cjs

@@ -0,0 +1,223 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createForm: () => createForm,
+  email: () => email,
+  maxLength: () => maxLength,
+  minLength: () => minLength,
+  pattern: () => pattern,
+  required: () => required,
+  runValidators: () => runValidators
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/validators.ts
+function required(message = "This field is required") {
+  return (value) => value.trim().length === 0 ? message : void 0;
+}
+function minLength(length, message) {
+  return (value) => value.length < length ? message ?? `Must be at least ${length} characters` : void 0;
+}
+function maxLength(length, message) {
+  return (value) => value.length > length ? message ?? `Must be at most ${length} characters` : void 0;
+}
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function email(message = "Enter a valid email address") {
+  return (value) => value.length === 0 || EMAIL_RE.test(value) ? void 0 : message;
+}
+function pattern(regex, message = "Invalid format") {
+  return (value) => value.length === 0 || regex.test(value) ? void 0 : message;
+}
+function runValidators(value, validators) {
+  if (validators === void 0) return void 0;
+  const list = Array.isArray(validators) ? validators : [validators];
+  for (const validate of list) {
+    const error = validate(value);
+    if (error !== void 0) return error;
+  }
+  return void 0;
+}
+
+// src/form.ts
+var import_state = require("@streetui/state");
+function createForm(config) {
+  const names = Object.keys(config.initialValues);
+  const validators = config.validators ?? {};
+  let programmatic = false;
+  const fields = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const initial = config.initialValues[name];
+    const value = (0, import_state.signal)(initial);
+    const touched = (0, import_state.signal)(false);
+    const error = (0, import_state.derived)(
+      () => runValidators(value.get(), validators[name])
+    );
+    const valid2 = (0, import_state.derived)(() => error.get() === void 0);
+    const dirty2 = (0, import_state.derived)(() => value.get() !== initial);
+    const unsub = value.subscribe(() => {
+      if (!programmatic) touched.set(true);
+    });
+    const api = {
+      name,
+      value,
+      error,
+      touched,
+      dirty: dirty2,
+      valid: valid2,
+      setValue(next) {
+        value.set(next);
+      },
+      markTouched(next = true) {
+        touched.set(next);
+      },
+      reset() {
+        programmatic = true;
+        try {
+          (0, import_state.batch)(() => {
+            value.set(initial);
+            touched.set(false);
+          });
+        } finally {
+          programmatic = false;
+        }
+      }
+    };
+    fields.set(name, { api, value, touched, error, valid: valid2, dirty: dirty2, initial, unsub });
+  }
+  const field = (name) => {
+    const f = fields.get(name);
+    if (f === void 0) throw new Error(`Unknown form field: ${name}`);
+    return f;
+  };
+  const values = (0, import_state.derived)(() => {
+    const out = {};
+    for (const name of names) out[name] = field(name).value.get();
+    return out;
+  });
+  const errors = (0, import_state.derived)(() => {
+    const out = {};
+    for (const name of names) {
+      const e = field(name).error.get();
+      if (e !== void 0) out[name] = e;
+    }
+    return out;
+  });
+  const touchedMap = (0, import_state.derived)(() => {
+    const out = {};
+    for (const name of names) out[name] = field(name).touched.get();
+    return out;
+  });
+  const dirty = (0, import_state.derived)(() => names.some((n) => field(n).dirty.get()));
+  const valid = (0, import_state.derived)(() => names.every((n) => field(n).valid.get()));
+  const status = (0, import_state.signal)("idle");
+  const submitting = (0, import_state.derived)(() => status.get() === "submitting");
+  const submitted = (0, import_state.derived)(() => status.get() === "success");
+  const submitError = (0, import_state.signal)(void 0);
+  function setValues(partial) {
+    programmatic = true;
+    try {
+      (0, import_state.batch)(() => {
+        for (const name of names) {
+          const next = partial[name];
+          if (next !== void 0) field(name).value.set(next);
+        }
+      });
+    } finally {
+      programmatic = false;
+    }
+  }
+  function reset() {
+    programmatic = true;
+    try {
+      (0, import_state.batch)(() => {
+        for (const name of names) {
+          const f = field(name);
+          f.value.set(f.initial);
+          f.touched.set(false);
+        }
+        status.set("idle");
+        submitError.set(void 0);
+      });
+    } finally {
+      programmatic = false;
+    }
+  }
+  async function submit() {
+    (0, import_state.batch)(() => {
+      for (const name of names) field(name).touched.set(true);
+    });
+    if (!valid.peek()) {
+      return;
+    }
+    submitError.set(void 0);
+    status.set("submitting");
+    try {
+      await config.onSubmit?.(values.peek());
+      status.set("success");
+    } catch (err) {
+      submitError.set(err);
+      status.set("error");
+    }
+  }
+  function dispose() {
+    for (const f of fields.values()) {
+      f.unsub();
+      f.error.dispose();
+      f.valid.dispose();
+      f.dirty.dispose();
+    }
+    values.dispose();
+    errors.dispose();
+    touchedMap.dispose();
+    dirty.dispose();
+    valid.dispose();
+    submitting.dispose();
+    submitted.dispose();
+  }
+  return {
+    values,
+    errors,
+    touched: touchedMap,
+    dirty,
+    valid,
+    submitting,
+    submitted,
+    status,
+    submitError,
+    field: (name) => field(name).api,
+    setValues,
+    submit,
+    reset,
+    dispose
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createForm,
+  email,
+  maxLength,
+  minLength,
+  pattern,
+  required,
+  runValidators
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/validators.ts","../src/form.ts"],"sourcesContent":["export * from './validators.js';\nexport * from './form.js';\n","/**\n * A small, sync validation system.\n *\n * A `Validator` maps a string field value to an error message, or `undefined`\n * when the value is acceptable. This is deliberately tiny — the built-ins cover\n * the common cases (`required`, `minLength`, `maxLength`, `email`, `pattern`)\n * and anything else is just a plain function `(value: string) => string | undefined`.\n *\n * Validators for a field run in order and the FIRST error wins, so list\n * `required` first if a field is mandatory.\n *\n * Async validation is intentionally NOT part of this core. It can be layered on\n * top with `@streetui/state`'s `resource()` (kick off a resource on value\n * change and surface `resource.error` alongside the field error) without\n * destabilising the synchronous validity model here.\n */\n\nexport type Validator = (value: string) => string | undefined;\n\n/** Fails when the trimmed value is empty. */\nexport function required(message = 'This field is required'): Validator {\n  return (value) => (value.trim().length === 0 ? message : undefined);\n}\n\n/** Fails when the value is shorter than `length` characters. */\nexport function minLength(length: number, message?: string): Validator {\n  return (value) =>\n    value.length < length\n      ? (message ?? `Must be at least ${length} characters`)\n      : undefined;\n}\n\n/** Fails when the value is longer than `length` characters. */\nexport function maxLength(length: number, message?: string): Validator {\n  return (value) =>\n    value.length > length\n      ? (message ?? `Must be at most ${length} characters`)\n      : undefined;\n}\n\n// Pragmatic, dependency-free email shape check (not a full RFC 5322 parser).\nconst EMAIL_RE = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\n/** Fails when a non-empty value is not a plausible email address. */\nexport function email(message = 'Enter a valid email address'): Validator {\n  return (value) => (value.length === 0 || EMAIL_RE.test(value) ? undefined : message);\n}\n\n/** Fails when a non-empty value does not match `regex`. */\nexport function pattern(regex: RegExp, message = 'Invalid format'): Validator {\n  return (value) => (value.length === 0 || regex.test(value) ? undefined : message);\n}\n\n/** Run a validator (or ordered list) and return the first error, if any. */\nexport function runValidators(\n  value: string,\n  validators: Validator | ReadonlyArray<Validator> | undefined,\n): string | undefined {\n  if (validators === undefined) return undefined;\n  const list = Array.isArray(validators) ? validators : [validators];\n  for (const validate of list) {\n    const error = validate(value);\n    if (error !== undefined) return error;\n  }\n  return undefined;\n}\n","/**\n * Reactive form model built entirely on `@streetui/state` signals.\n *\n * There is no second state system here: every piece of form state (`values`,\n * `errors`, `touched`, `dirty`, `valid`, submission status) is a signal or a\n * derived signal, so it composes with the renderer's existing reactive bindings.\n * A field's `value` is a writable `Signal<string>`, which plugs straight into\n * the DSL's `input({ bind })` — typing updates form state and programmatic\n * updates update the input, through the one binding the renderer already wires.\n */\n\nimport {\n  signal,\n  derived,\n  batch,\n  DerivedSignal,\n  type Signal,\n  type ReadonlySignal,\n  type Unsubscribe,\n} from '@streetui/state';\nimport { type Validator, runValidators } from './validators.js';\n\n/** Form values are a flat, typed record of string fields (HTML input values). */\nexport type FormValues = Record<string, string>;\n\nexport interface Field {\n  readonly name: string;\n  /** Writable value signal — pass to `input({ bind: field.value })`. */\n  readonly value: Signal<string>;\n  /** Current validation error, or `undefined` when the field is valid. */\n  readonly error: ReadonlySignal<string | undefined>;\n  /** True once the field has received a genuine user interaction. */\n  readonly touched: ReadonlySignal<boolean>;\n  /** True when the value differs from its initial value. */\n  readonly dirty: ReadonlySignal<boolean>;\n  /** True when the field has no validation error. */\n  readonly valid: ReadonlySignal<boolean>;\n  /** Programmatically set the value (does not mark the field touched). */\n  setValue(next: string): void;\n  /** Force the touched flag (defaults to true). */\n  markTouched(touched?: boolean): void;\n  /** Restore this field's initial value and clear its touched flag. */\n  reset(): void;\n}\n\nexport type FormValidators<T extends FormValues> = {\n  readonly [K in keyof T]?: Validator | ReadonlyArray<Validator>;\n};\n\nexport interface FormConfig<T extends FormValues> {\n  readonly initialValues: T;\n  readonly validators?: FormValidators<T>;\n  /** Called by `submit()` once all fields are valid. May be async. */\n  readonly onSubmit?: (values: T) => void | Promise<void>;\n}\n\nexport type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';\n\nexport interface Form<T extends FormValues> {\n  readonly values: ReadonlySignal<T>;\n  readonly errors: ReadonlySignal<Partial<Record<keyof T, string>>>;\n  readonly touched: ReadonlySignal<Partial<Record<keyof T, boolean>>>;\n  readonly dirty: ReadonlySignal<boolean>;\n  readonly valid: ReadonlySignal<boolean>;\n  readonly submitting: ReadonlySignal<boolean>;\n  readonly submitted: ReadonlySignal<boolean>;\n  readonly status: ReadonlySignal<SubmitStatus>;\n  readonly submitError: ReadonlySignal<unknown>;\n  /** Access the reactive state + setters for one field. */\n  field<K extends keyof T & string>(name: K): Field;\n  /** Merge a partial set of values in (does not mark fields touched). */\n  setValues(partial: Partial<T>): void;\n  /** Validate, mark all fields touched, then run `onSubmit` if valid. */\n  submit(): Promise<void>;\n  /** Restore initial values and clear errors/touched/dirty/submission state. */\n  reset(): void;\n  /** Tear down all field subscriptions and derived signals. */\n  dispose(): void;\n}\n\ninterface FieldInternal {\n  readonly api: Field;\n  readonly value: Signal<string>;\n  readonly touched: Signal<boolean>;\n  readonly error: DerivedSignal<string | undefined>;\n  readonly valid: DerivedSignal<boolean>;\n  readonly dirty: DerivedSignal<boolean>;\n  readonly initial: string;\n  readonly unsub: Unsubscribe;\n}\n\n// __FORM_IMPL__\n\nexport function createForm<T extends FormValues>(config: FormConfig<T>): Form<T> {\n  const names = Object.keys(config.initialValues) as Array<keyof T & string>;\n  const validators = config.validators ?? ({} as FormValidators<T>);\n\n  // While true, value changes originate from setValues()/reset() and must NOT\n  // mark a field touched. Batch flushes run synchronously inside batch(), i.e.\n  // before this flag is reset, so guarding around batch() is sound.\n  let programmatic = false;\n\n  const fields = new Map<string, FieldInternal>();\n\n  for (const name of names) {\n    // Keys come from Object.keys(initialValues), so the value is always present;\n    // the annotation defeats noUncheckedIndexedAccess widening to `| undefined`.\n    const initial: string = config.initialValues[name] as string;\n    const value = signal<string>(initial);\n    const touched = signal<boolean>(false);\n    const error = derived<string | undefined>(() =>\n      runValidators(value.get(), validators[name]),\n    );\n    const valid = derived<boolean>(() => error.get() === undefined);\n    const dirty = derived<boolean>(() => value.get() !== initial);\n\n    // Mark touched on the first genuine (non-programmatic) value change.\n    const unsub = value.subscribe(() => {\n      if (!programmatic) touched.set(true);\n    });\n\n    const api: Field = {\n      name,\n      value,\n      error,\n      touched,\n      dirty,\n      valid,\n      setValue(next: string): void {\n        value.set(next);\n      },\n      markTouched(next = true): void {\n        touched.set(next);\n      },\n      reset(): void {\n        programmatic = true;\n        try {\n          batch(() => {\n            value.set(initial);\n            touched.set(false);\n          });\n        } finally {\n          programmatic = false;\n        }\n      },\n    };\n\n    fields.set(name, { api, value, touched, error, valid, dirty, initial, unsub });\n  }\n\n  const field = (name: string): FieldInternal => {\n    const f = fields.get(name);\n    if (f === undefined) throw new Error(`Unknown form field: ${name}`);\n    return f;\n  };\n\n  const values = derived<T>(() => {\n    const out: Record<string, string> = {};\n    for (const name of names) out[name] = field(name).value.get();\n    return out as T;\n  });\n\n  const errors = derived<Partial<Record<keyof T, string>>>(() => {\n    const out: Partial<Record<keyof T, string>> = {};\n    for (const name of names) {\n      const e = field(name).error.get();\n      if (e !== undefined) out[name] = e;\n    }\n    return out;\n  });\n\n  const touchedMap = derived<Partial<Record<keyof T, boolean>>>(() => {\n    const out: Partial<Record<keyof T, boolean>> = {};\n    for (const name of names) out[name] = field(name).touched.get();\n    return out;\n  });\n\n  const dirty = derived<boolean>(() => names.some((n) => field(n).dirty.get()));\n  const valid = derived<boolean>(() => names.every((n) => field(n).valid.get()));\n\n  const status = signal<SubmitStatus>('idle');\n  const submitting = derived<boolean>(() => status.get() === 'submitting');\n  const submitted = derived<boolean>(() => status.get() === 'success');\n  const submitError = signal<unknown>(undefined);\n\n  function setValues(partial: Partial<T>): void {\n    programmatic = true;\n    try {\n      batch(() => {\n        for (const name of names) {\n          const next = partial[name];\n          if (next !== undefined) field(name).value.set(next);\n        }\n      });\n    } finally {\n      programmatic = false;\n    }\n  }\n\n  function reset(): void {\n    programmatic = true;\n    try {\n      batch(() => {\n        for (const name of names) {\n          const f = field(name);\n          f.value.set(f.initial);\n          f.touched.set(false);\n        }\n        status.set('idle');\n        submitError.set(undefined);\n      });\n    } finally {\n      programmatic = false;\n    }\n  }\n\n  async function submit(): Promise<void> {\n    // Touch every field so validation errors become visible on submit attempts.\n    batch(() => {\n      for (const name of names) field(name).touched.set(true);\n    });\n    if (!valid.peek()) {\n      // Invalid — do not enter the submitting lifecycle; field errors now show.\n      return;\n    }\n    submitError.set(undefined);\n    status.set('submitting');\n    try {\n      await config.onSubmit?.(values.peek());\n      status.set('success');\n    } catch (err) {\n      submitError.set(err);\n      status.set('error');\n    }\n  }\n\n  function dispose(): void {\n    for (const f of fields.values()) {\n      f.unsub();\n      f.error.dispose();\n      f.valid.dispose();\n      f.dirty.dispose();\n    }\n    values.dispose();\n    errors.dispose();\n    touchedMap.dispose();\n    dirty.dispose();\n    valid.dispose();\n    submitting.dispose();\n    submitted.dispose();\n  }\n\n  return {\n    values,\n    errors,\n    touched: touchedMap,\n    dirty,\n    valid,\n    submitting,\n    submitted,\n    status,\n    submitError,\n    field: (name) => field(name).api,\n    setValues,\n    submit,\n    reset,\n    dispose,\n  };\n}\n\n"],"mappings":"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","names":["valid","dirty"]}

package/dist/index.d.cts

@@ -0,0 +1,98 @@
+import { Signal, ReadonlySignal } from '@streetui/state';
+
+/**
+ * A small, sync validation system.
+ *
+ * A `Validator` maps a string field value to an error message, or `undefined`
+ * when the value is acceptable. This is deliberately tiny — the built-ins cover
+ * the common cases (`required`, `minLength`, `maxLength`, `email`, `pattern`)
+ * and anything else is just a plain function `(value: string) => string | undefined`.
+ *
+ * Validators for a field run in order and the FIRST error wins, so list
+ * `required` first if a field is mandatory.
+ *
+ * Async validation is intentionally NOT part of this core. It can be layered on
+ * top with `@streetui/state`'s `resource()` (kick off a resource on value
+ * change and surface `resource.error` alongside the field error) without
+ * destabilising the synchronous validity model here.
+ */
+type Validator = (value: string) => string | undefined;
+/** Fails when the trimmed value is empty. */
+declare function required(message?: string): Validator;
+/** Fails when the value is shorter than `length` characters. */
+declare function minLength(length: number, message?: string): Validator;
+/** Fails when the value is longer than `length` characters. */
+declare function maxLength(length: number, message?: string): Validator;
+/** Fails when a non-empty value is not a plausible email address. */
+declare function email(message?: string): Validator;
+/** Fails when a non-empty value does not match `regex`. */
+declare function pattern(regex: RegExp, message?: string): Validator;
+/** Run a validator (or ordered list) and return the first error, if any. */
+declare function runValidators(value: string, validators: Validator | ReadonlyArray<Validator> | undefined): string | undefined;
+
+/**
+ * Reactive form model built entirely on `@streetui/state` signals.
+ *
+ * There is no second state system here: every piece of form state (`values`,
+ * `errors`, `touched`, `dirty`, `valid`, submission status) is a signal or a
+ * derived signal, so it composes with the renderer's existing reactive bindings.
+ * A field's `value` is a writable `Signal<string>`, which plugs straight into
+ * the DSL's `input({ bind })` — typing updates form state and programmatic
+ * updates update the input, through the one binding the renderer already wires.
+ */
+
+/** Form values are a flat, typed record of string fields (HTML input values). */
+type FormValues = Record<string, string>;
+interface Field {
+    readonly name: string;
+    /** Writable value signal — pass to `input({ bind: field.value })`. */
+    readonly value: Signal<string>;
+    /** Current validation error, or `undefined` when the field is valid. */
+    readonly error: ReadonlySignal<string | undefined>;
+    /** True once the field has received a genuine user interaction. */
+    readonly touched: ReadonlySignal<boolean>;
+    /** True when the value differs from its initial value. */
+    readonly dirty: ReadonlySignal<boolean>;
+    /** True when the field has no validation error. */
+    readonly valid: ReadonlySignal<boolean>;
+    /** Programmatically set the value (does not mark the field touched). */
+    setValue(next: string): void;
+    /** Force the touched flag (defaults to true). */
+    markTouched(touched?: boolean): void;
+    /** Restore this field's initial value and clear its touched flag. */
+    reset(): void;
+}
+type FormValidators<T extends FormValues> = {
+    readonly [K in keyof T]?: Validator | ReadonlyArray<Validator>;
+};
+interface FormConfig<T extends FormValues> {
+    readonly initialValues: T;
+    readonly validators?: FormValidators<T>;
+    /** Called by `submit()` once all fields are valid. May be async. */
+    readonly onSubmit?: (values: T) => void | Promise<void>;
+}
+type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';
+interface Form<T extends FormValues> {
+    readonly values: ReadonlySignal<T>;
+    readonly errors: ReadonlySignal<Partial<Record<keyof T, string>>>;
+    readonly touched: ReadonlySignal<Partial<Record<keyof T, boolean>>>;
+    readonly dirty: ReadonlySignal<boolean>;
+    readonly valid: ReadonlySignal<boolean>;
+    readonly submitting: ReadonlySignal<boolean>;
+    readonly submitted: ReadonlySignal<boolean>;
+    readonly status: ReadonlySignal<SubmitStatus>;
+    readonly submitError: ReadonlySignal<unknown>;
+    /** Access the reactive state + setters for one field. */
+    field<K extends keyof T & string>(name: K): Field;
+    /** Merge a partial set of values in (does not mark fields touched). */
+    setValues(partial: Partial<T>): void;
+    /** Validate, mark all fields touched, then run `onSubmit` if valid. */
+    submit(): Promise<void>;
+    /** Restore initial values and clear errors/touched/dirty/submission state. */
+    reset(): void;
+    /** Tear down all field subscriptions and derived signals. */
+    dispose(): void;
+}
+declare function createForm<T extends FormValues>(config: FormConfig<T>): Form<T>;
+
+export { type Field, type Form, type FormConfig, type FormValidators, type FormValues, type SubmitStatus, type Validator, createForm, email, maxLength, minLength, pattern, required, runValidators };

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import { Signal, ReadonlySignal } from '@streetui/state';
+
+/**
+ * A small, sync validation system.
+ *
+ * A `Validator` maps a string field value to an error message, or `undefined`
+ * when the value is acceptable. This is deliberately tiny — the built-ins cover
+ * the common cases (`required`, `minLength`, `maxLength`, `email`, `pattern`)
+ * and anything else is just a plain function `(value: string) => string | undefined`.
+ *
+ * Validators for a field run in order and the FIRST error wins, so list
+ * `required` first if a field is mandatory.
+ *
+ * Async validation is intentionally NOT part of this core. It can be layered on
+ * top with `@streetui/state`'s `resource()` (kick off a resource on value
+ * change and surface `resource.error` alongside the field error) without
+ * destabilising the synchronous validity model here.
+ */
+type Validator = (value: string) => string | undefined;
+/** Fails when the trimmed value is empty. */
+declare function required(message?: string): Validator;
+/** Fails when the value is shorter than `length` characters. */
+declare function minLength(length: number, message?: string): Validator;
+/** Fails when the value is longer than `length` characters. */
+declare function maxLength(length: number, message?: string): Validator;
+/** Fails when a non-empty value is not a plausible email address. */
+declare function email(message?: string): Validator;
+/** Fails when a non-empty value does not match `regex`. */
+declare function pattern(regex: RegExp, message?: string): Validator;
+/** Run a validator (or ordered list) and return the first error, if any. */
+declare function runValidators(value: string, validators: Validator | ReadonlyArray<Validator> | undefined): string | undefined;
+
+/**
+ * Reactive form model built entirely on `@streetui/state` signals.
+ *
+ * There is no second state system here: every piece of form state (`values`,
+ * `errors`, `touched`, `dirty`, `valid`, submission status) is a signal or a
+ * derived signal, so it composes with the renderer's existing reactive bindings.
+ * A field's `value` is a writable `Signal<string>`, which plugs straight into
+ * the DSL's `input({ bind })` — typing updates form state and programmatic
+ * updates update the input, through the one binding the renderer already wires.
+ */
+
+/** Form values are a flat, typed record of string fields (HTML input values). */
+type FormValues = Record<string, string>;
+interface Field {
+    readonly name: string;
+    /** Writable value signal — pass to `input({ bind: field.value })`. */
+    readonly value: Signal<string>;
+    /** Current validation error, or `undefined` when the field is valid. */
+    readonly error: ReadonlySignal<string | undefined>;
+    /** True once the field has received a genuine user interaction. */
+    readonly touched: ReadonlySignal<boolean>;
+    /** True when the value differs from its initial value. */
+    readonly dirty: ReadonlySignal<boolean>;
+    /** True when the field has no validation error. */
+    readonly valid: ReadonlySignal<boolean>;
+    /** Programmatically set the value (does not mark the field touched). */
+    setValue(next: string): void;
+    /** Force the touched flag (defaults to true). */
+    markTouched(touched?: boolean): void;
+    /** Restore this field's initial value and clear its touched flag. */
+    reset(): void;
+}
+type FormValidators<T extends FormValues> = {
+    readonly [K in keyof T]?: Validator | ReadonlyArray<Validator>;
+};
+interface FormConfig<T extends FormValues> {
+    readonly initialValues: T;
+    readonly validators?: FormValidators<T>;
+    /** Called by `submit()` once all fields are valid. May be async. */
+    readonly onSubmit?: (values: T) => void | Promise<void>;
+}
+type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';
+interface Form<T extends FormValues> {
+    readonly values: ReadonlySignal<T>;
+    readonly errors: ReadonlySignal<Partial<Record<keyof T, string>>>;
+    readonly touched: ReadonlySignal<Partial<Record<keyof T, boolean>>>;
+    readonly dirty: ReadonlySignal<boolean>;
+    readonly valid: ReadonlySignal<boolean>;
+    readonly submitting: ReadonlySignal<boolean>;
+    readonly submitted: ReadonlySignal<boolean>;
+    readonly status: ReadonlySignal<SubmitStatus>;
+    readonly submitError: ReadonlySignal<unknown>;
+    /** Access the reactive state + setters for one field. */
+    field<K extends keyof T & string>(name: K): Field;
+    /** Merge a partial set of values in (does not mark fields touched). */
+    setValues(partial: Partial<T>): void;
+    /** Validate, mark all fields touched, then run `onSubmit` if valid. */
+    submit(): Promise<void>;
+    /** Restore initial values and clear errors/touched/dirty/submission state. */
+    reset(): void;
+    /** Tear down all field subscriptions and derived signals. */
+    dispose(): void;
+}
+declare function createForm<T extends FormValues>(config: FormConfig<T>): Form<T>;
+
+export { type Field, type Form, type FormConfig, type FormValidators, type FormValues, type SubmitStatus, type Validator, createForm, email, maxLength, minLength, pattern, required, runValidators };

package/dist/index.js

@@ -0,0 +1,194 @@
+// src/validators.ts
+function required(message = "This field is required") {
+  return (value) => value.trim().length === 0 ? message : void 0;
+}
+function minLength(length, message) {
+  return (value) => value.length < length ? message ?? `Must be at least ${length} characters` : void 0;
+}
+function maxLength(length, message) {
+  return (value) => value.length > length ? message ?? `Must be at most ${length} characters` : void 0;
+}
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function email(message = "Enter a valid email address") {
+  return (value) => value.length === 0 || EMAIL_RE.test(value) ? void 0 : message;
+}
+function pattern(regex, message = "Invalid format") {
+  return (value) => value.length === 0 || regex.test(value) ? void 0 : message;
+}
+function runValidators(value, validators) {
+  if (validators === void 0) return void 0;
+  const list = Array.isArray(validators) ? validators : [validators];
+  for (const validate of list) {
+    const error = validate(value);
+    if (error !== void 0) return error;
+  }
+  return void 0;
+}
+
+// src/form.ts
+import {
+  signal,
+  derived,
+  batch
+} from "@streetui/state";
+function createForm(config) {
+  const names = Object.keys(config.initialValues);
+  const validators = config.validators ?? {};
+  let programmatic = false;
+  const fields = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const initial = config.initialValues[name];
+    const value = signal(initial);
+    const touched = signal(false);
+    const error = derived(
+      () => runValidators(value.get(), validators[name])
+    );
+    const valid2 = derived(() => error.get() === void 0);
+    const dirty2 = derived(() => value.get() !== initial);
+    const unsub = value.subscribe(() => {
+      if (!programmatic) touched.set(true);
+    });
+    const api = {
+      name,
+      value,
+      error,
+      touched,
+      dirty: dirty2,
+      valid: valid2,
+      setValue(next) {
+        value.set(next);
+      },
+      markTouched(next = true) {
+        touched.set(next);
+      },
+      reset() {
+        programmatic = true;
+        try {
+          batch(() => {
+            value.set(initial);
+            touched.set(false);
+          });
+        } finally {
+          programmatic = false;
+        }
+      }
+    };
+    fields.set(name, { api, value, touched, error, valid: valid2, dirty: dirty2, initial, unsub });
+  }
+  const field = (name) => {
+    const f = fields.get(name);
+    if (f === void 0) throw new Error(`Unknown form field: ${name}`);
+    return f;
+  };
+  const values = derived(() => {
+    const out = {};
+    for (const name of names) out[name] = field(name).value.get();
+    return out;
+  });
+  const errors = derived(() => {
+    const out = {};
+    for (const name of names) {
+      const e = field(name).error.get();
+      if (e !== void 0) out[name] = e;
+    }
+    return out;
+  });
+  const touchedMap = derived(() => {
+    const out = {};
+    for (const name of names) out[name] = field(name).touched.get();
+    return out;
+  });
+  const dirty = derived(() => names.some((n) => field(n).dirty.get()));
+  const valid = derived(() => names.every((n) => field(n).valid.get()));
+  const status = signal("idle");
+  const submitting = derived(() => status.get() === "submitting");
+  const submitted = derived(() => status.get() === "success");
+  const submitError = signal(void 0);
+  function setValues(partial) {
+    programmatic = true;
+    try {
+      batch(() => {
+        for (const name of names) {
+          const next = partial[name];
+          if (next !== void 0) field(name).value.set(next);
+        }
+      });
+    } finally {
+      programmatic = false;
+    }
+  }
+  function reset() {
+    programmatic = true;
+    try {
+      batch(() => {
+        for (const name of names) {
+          const f = field(name);
+          f.value.set(f.initial);
+          f.touched.set(false);
+        }
+        status.set("idle");
+        submitError.set(void 0);
+      });
+    } finally {
+      programmatic = false;
+    }
+  }
+  async function submit() {
+    batch(() => {
+      for (const name of names) field(name).touched.set(true);
+    });
+    if (!valid.peek()) {
+      return;
+    }
+    submitError.set(void 0);
+    status.set("submitting");
+    try {
+      await config.onSubmit?.(values.peek());
+      status.set("success");
+    } catch (err) {
+      submitError.set(err);
+      status.set("error");
+    }
+  }
+  function dispose() {
+    for (const f of fields.values()) {
+      f.unsub();
+      f.error.dispose();
+      f.valid.dispose();
+      f.dirty.dispose();
+    }
+    values.dispose();
+    errors.dispose();
+    touchedMap.dispose();
+    dirty.dispose();
+    valid.dispose();
+    submitting.dispose();
+    submitted.dispose();
+  }
+  return {
+    values,
+    errors,
+    touched: touchedMap,
+    dirty,
+    valid,
+    submitting,
+    submitted,
+    status,
+    submitError,
+    field: (name) => field(name).api,
+    setValues,
+    submit,
+    reset,
+    dispose
+  };
+}
+export {
+  createForm,
+  email,
+  maxLength,
+  minLength,
+  pattern,
+  required,
+  runValidators
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/validators.ts","../src/form.ts"],"sourcesContent":["/**\n * A small, sync validation system.\n *\n * A `Validator` maps a string field value to an error message, or `undefined`\n * when the value is acceptable. This is deliberately tiny — the built-ins cover\n * the common cases (`required`, `minLength`, `maxLength`, `email`, `pattern`)\n * and anything else is just a plain function `(value: string) => string | undefined`.\n *\n * Validators for a field run in order and the FIRST error wins, so list\n * `required` first if a field is mandatory.\n *\n * Async validation is intentionally NOT part of this core. It can be layered on\n * top with `@streetui/state`'s `resource()` (kick off a resource on value\n * change and surface `resource.error` alongside the field error) without\n * destabilising the synchronous validity model here.\n */\n\nexport type Validator = (value: string) => string | undefined;\n\n/** Fails when the trimmed value is empty. */\nexport function required(message = 'This field is required'): Validator {\n  return (value) => (value.trim().length === 0 ? message : undefined);\n}\n\n/** Fails when the value is shorter than `length` characters. */\nexport function minLength(length: number, message?: string): Validator {\n  return (value) =>\n    value.length < length\n      ? (message ?? `Must be at least ${length} characters`)\n      : undefined;\n}\n\n/** Fails when the value is longer than `length` characters. */\nexport function maxLength(length: number, message?: string): Validator {\n  return (value) =>\n    value.length > length\n      ? (message ?? `Must be at most ${length} characters`)\n      : undefined;\n}\n\n// Pragmatic, dependency-free email shape check (not a full RFC 5322 parser).\nconst EMAIL_RE = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\n/** Fails when a non-empty value is not a plausible email address. */\nexport function email(message = 'Enter a valid email address'): Validator {\n  return (value) => (value.length === 0 || EMAIL_RE.test(value) ? undefined : message);\n}\n\n/** Fails when a non-empty value does not match `regex`. */\nexport function pattern(regex: RegExp, message = 'Invalid format'): Validator {\n  return (value) => (value.length === 0 || regex.test(value) ? undefined : message);\n}\n\n/** Run a validator (or ordered list) and return the first error, if any. */\nexport function runValidators(\n  value: string,\n  validators: Validator | ReadonlyArray<Validator> | undefined,\n): string | undefined {\n  if (validators === undefined) return undefined;\n  const list = Array.isArray(validators) ? validators : [validators];\n  for (const validate of list) {\n    const error = validate(value);\n    if (error !== undefined) return error;\n  }\n  return undefined;\n}\n","/**\n * Reactive form model built entirely on `@streetui/state` signals.\n *\n * There is no second state system here: every piece of form state (`values`,\n * `errors`, `touched`, `dirty`, `valid`, submission status) is a signal or a\n * derived signal, so it composes with the renderer's existing reactive bindings.\n * A field's `value` is a writable `Signal<string>`, which plugs straight into\n * the DSL's `input({ bind })` — typing updates form state and programmatic\n * updates update the input, through the one binding the renderer already wires.\n */\n\nimport {\n  signal,\n  derived,\n  batch,\n  DerivedSignal,\n  type Signal,\n  type ReadonlySignal,\n  type Unsubscribe,\n} from '@streetui/state';\nimport { type Validator, runValidators } from './validators.js';\n\n/** Form values are a flat, typed record of string fields (HTML input values). */\nexport type FormValues = Record<string, string>;\n\nexport interface Field {\n  readonly name: string;\n  /** Writable value signal — pass to `input({ bind: field.value })`. */\n  readonly value: Signal<string>;\n  /** Current validation error, or `undefined` when the field is valid. */\n  readonly error: ReadonlySignal<string | undefined>;\n  /** True once the field has received a genuine user interaction. */\n  readonly touched: ReadonlySignal<boolean>;\n  /** True when the value differs from its initial value. */\n  readonly dirty: ReadonlySignal<boolean>;\n  /** True when the field has no validation error. */\n  readonly valid: ReadonlySignal<boolean>;\n  /** Programmatically set the value (does not mark the field touched). */\n  setValue(next: string): void;\n  /** Force the touched flag (defaults to true). */\n  markTouched(touched?: boolean): void;\n  /** Restore this field's initial value and clear its touched flag. */\n  reset(): void;\n}\n\nexport type FormValidators<T extends FormValues> = {\n  readonly [K in keyof T]?: Validator | ReadonlyArray<Validator>;\n};\n\nexport interface FormConfig<T extends FormValues> {\n  readonly initialValues: T;\n  readonly validators?: FormValidators<T>;\n  /** Called by `submit()` once all fields are valid. May be async. */\n  readonly onSubmit?: (values: T) => void | Promise<void>;\n}\n\nexport type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';\n\nexport interface Form<T extends FormValues> {\n  readonly values: ReadonlySignal<T>;\n  readonly errors: ReadonlySignal<Partial<Record<keyof T, string>>>;\n  readonly touched: ReadonlySignal<Partial<Record<keyof T, boolean>>>;\n  readonly dirty: ReadonlySignal<boolean>;\n  readonly valid: ReadonlySignal<boolean>;\n  readonly submitting: ReadonlySignal<boolean>;\n  readonly submitted: ReadonlySignal<boolean>;\n  readonly status: ReadonlySignal<SubmitStatus>;\n  readonly submitError: ReadonlySignal<unknown>;\n  /** Access the reactive state + setters for one field. */\n  field<K extends keyof T & string>(name: K): Field;\n  /** Merge a partial set of values in (does not mark fields touched). */\n  setValues(partial: Partial<T>): void;\n  /** Validate, mark all fields touched, then run `onSubmit` if valid. */\n  submit(): Promise<void>;\n  /** Restore initial values and clear errors/touched/dirty/submission state. */\n  reset(): void;\n  /** Tear down all field subscriptions and derived signals. */\n  dispose(): void;\n}\n\ninterface FieldInternal {\n  readonly api: Field;\n  readonly value: Signal<string>;\n  readonly touched: Signal<boolean>;\n  readonly error: DerivedSignal<string | undefined>;\n  readonly valid: DerivedSignal<boolean>;\n  readonly dirty: DerivedSignal<boolean>;\n  readonly initial: string;\n  readonly unsub: Unsubscribe;\n}\n\n// __FORM_IMPL__\n\nexport function createForm<T extends FormValues>(config: FormConfig<T>): Form<T> {\n  const names = Object.keys(config.initialValues) as Array<keyof T & string>;\n  const validators = config.validators ?? ({} as FormValidators<T>);\n\n  // While true, value changes originate from setValues()/reset() and must NOT\n  // mark a field touched. Batch flushes run synchronously inside batch(), i.e.\n  // before this flag is reset, so guarding around batch() is sound.\n  let programmatic = false;\n\n  const fields = new Map<string, FieldInternal>();\n\n  for (const name of names) {\n    // Keys come from Object.keys(initialValues), so the value is always present;\n    // the annotation defeats noUncheckedIndexedAccess widening to `| undefined`.\n    const initial: string = config.initialValues[name] as string;\n    const value = signal<string>(initial);\n    const touched = signal<boolean>(false);\n    const error = derived<string | undefined>(() =>\n      runValidators(value.get(), validators[name]),\n    );\n    const valid = derived<boolean>(() => error.get() === undefined);\n    const dirty = derived<boolean>(() => value.get() !== initial);\n\n    // Mark touched on the first genuine (non-programmatic) value change.\n    const unsub = value.subscribe(() => {\n      if (!programmatic) touched.set(true);\n    });\n\n    const api: Field = {\n      name,\n      value,\n      error,\n      touched,\n      dirty,\n      valid,\n      setValue(next: string): void {\n        value.set(next);\n      },\n      markTouched(next = true): void {\n        touched.set(next);\n      },\n      reset(): void {\n        programmatic = true;\n        try {\n          batch(() => {\n            value.set(initial);\n            touched.set(false);\n          });\n        } finally {\n          programmatic = false;\n        }\n      },\n    };\n\n    fields.set(name, { api, value, touched, error, valid, dirty, initial, unsub });\n  }\n\n  const field = (name: string): FieldInternal => {\n    const f = fields.get(name);\n    if (f === undefined) throw new Error(`Unknown form field: ${name}`);\n    return f;\n  };\n\n  const values = derived<T>(() => {\n    const out: Record<string, string> = {};\n    for (const name of names) out[name] = field(name).value.get();\n    return out as T;\n  });\n\n  const errors = derived<Partial<Record<keyof T, string>>>(() => {\n    const out: Partial<Record<keyof T, string>> = {};\n    for (const name of names) {\n      const e = field(name).error.get();\n      if (e !== undefined) out[name] = e;\n    }\n    return out;\n  });\n\n  const touchedMap = derived<Partial<Record<keyof T, boolean>>>(() => {\n    const out: Partial<Record<keyof T, boolean>> = {};\n    for (const name of names) out[name] = field(name).touched.get();\n    return out;\n  });\n\n  const dirty = derived<boolean>(() => names.some((n) => field(n).dirty.get()));\n  const valid = derived<boolean>(() => names.every((n) => field(n).valid.get()));\n\n  const status = signal<SubmitStatus>('idle');\n  const submitting = derived<boolean>(() => status.get() === 'submitting');\n  const submitted = derived<boolean>(() => status.get() === 'success');\n  const submitError = signal<unknown>(undefined);\n\n  function setValues(partial: Partial<T>): void {\n    programmatic = true;\n    try {\n      batch(() => {\n        for (const name of names) {\n          const next = partial[name];\n          if (next !== undefined) field(name).value.set(next);\n        }\n      });\n    } finally {\n      programmatic = false;\n    }\n  }\n\n  function reset(): void {\n    programmatic = true;\n    try {\n      batch(() => {\n        for (const name of names) {\n          const f = field(name);\n          f.value.set(f.initial);\n          f.touched.set(false);\n        }\n        status.set('idle');\n        submitError.set(undefined);\n      });\n    } finally {\n      programmatic = false;\n    }\n  }\n\n  async function submit(): Promise<void> {\n    // Touch every field so validation errors become visible on submit attempts.\n    batch(() => {\n      for (const name of names) field(name).touched.set(true);\n    });\n    if (!valid.peek()) {\n      // Invalid — do not enter the submitting lifecycle; field errors now show.\n      return;\n    }\n    submitError.set(undefined);\n    status.set('submitting');\n    try {\n      await config.onSubmit?.(values.peek());\n      status.set('success');\n    } catch (err) {\n      submitError.set(err);\n      status.set('error');\n    }\n  }\n\n  function dispose(): void {\n    for (const f of fields.values()) {\n      f.unsub();\n      f.error.dispose();\n      f.valid.dispose();\n      f.dirty.dispose();\n    }\n    values.dispose();\n    errors.dispose();\n    touchedMap.dispose();\n    dirty.dispose();\n    valid.dispose();\n    submitting.dispose();\n    submitted.dispose();\n  }\n\n  return {\n    values,\n    errors,\n    touched: touchedMap,\n    dirty,\n    valid,\n    submitting,\n    submitted,\n    status,\n    submitError,\n    field: (name) => field(name).api,\n    setValues,\n    submit,\n    reset,\n    dispose,\n  };\n}\n\n"],"mappings":"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","names":["valid","dirty"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@streetui/forms",
+  "version": "1.0.0",
+  "description": "StreetUI forms — reactive form state, validation, and submission lifecycle built on signals",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@streetui/state": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "*",
+    "tsup": "*",
+    "vitest": "*"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}