@samline/forms 1.0.3 → 2.0.0

package/README.md

@@ -1,6 +1,10 @@
 # Forms
 
-Form controller for native HTML forms, React, Vue, Svelte, and direct browser usage.
+> A small, framework-free form controller for vanilla JS and direct browser usage.
+
+> It binds to an `HTMLFormElement`, keeps field state in sync with the DOM, runs validation, lets you react to changes via watchers or subscribers, and ships a serialized payload for `fetch` flows.
+
+---
 
 ## Table of Contents
 
@@ -8,12 +12,13 @@ Form controller for native HTML forms, React, Vue, Svelte, and direct browser us
 - [CDN / Browser](#cdn--browser)
 - [Entrypoints](#entrypoints)
 - [Quick Start](#quick-start)
-- [What You Can Do](#what-you-can-do)
-- [API Reference](#api-reference)
-- [Examples](#examples)
+- [What You Can Build](#what-you-can-build)
+- [API at a Glance](#api-at-a-glance)
 - [Documentation](#documentation)
 - [License](#license)
 
+---
+
 ## Installation
 
 ```bash
@@ -24,49 +29,58 @@ npm install @samline/forms
 pnpm add @samline/forms
 ```
 
-```bash
-yarn add @samline/forms
-```
-
 ```bash
 bun add @samline/forms
 ```
 
+Requires Node 20+ when bundling. Runtime target is ES2020.
+
+---
+
 ## CDN / Browser
 
-Use the browser build when you do not have a bundler and need to run the package directly in HTML.
+Use the browser build when you do not have a bundler and need to run the package directly in HTML, Shopify, WordPress, or any traditional template.
 
 ```html
-<script src="https://unpkg.com/@samline/forms@1.0.3/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.0.0/dist/browser/global.global.js"></script>
 ```
 
-Pin the version in production.
+> Pin the version in production. Replace `2.0.0` with the version you ship.
 
-The browser build exposes `window.forms`.
+The browser bundle exposes a single global: `window.Forms`.
 
 ```html
 <form id="contact-form">
   <input name="email" type="email" />
+  <button type="submit">Send</button>
 </form>
 
-<script src="https://unpkg.com/@samline/forms@1.0.3/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.0.0/dist/browser/global.global.js"></script>
 <script>
-  const contactForm = window.forms.form('contact-form')
+  const contactForm = window.Forms.newForm({ id: 'contact-form' })
+
+  contactForm.onSubmit(async (form, data, formData) => {
+    await fetch('/api/contact', { method: 'POST', body: formData })
+  })
+
   contactForm.validate()
 </script>
 ```
 
+The browser surface keeps a small registry under `Forms.available`, keyed by the `id` you pass to `Forms.newForm`. Each successful `newForm` call stores the returned controller there, and `Forms.destroyForm(id)` calls `destroy()` and removes the entry. Use `Forms.form` directly when you need the factory without the registry side-effect.
+
+See [docs/browser.md](docs/browser.md) for the full browser surface.
+
+---
+
 ## Entrypoints
 
-| Entrypoint | Use |
+| Entrypoint | When to use |
 | --- | --- |
-| `@samline/forms` | Main vanilla API |
-| `@samline/forms/core` | Types, serialization, and validation |
-| `@samline/forms/vanilla` | Explicit DOM API entrypoint |
-| `@samline/forms/react` | React hook |
-| `@samline/forms/vue` | Vue composable |
-| `@samline/forms/svelte` | Svelte store and action |
-| `@samline/forms/browser` | Browser global bundle |
+| `@samline/forms` | Main vanilla API for bundlers, ESM, or CJS consumers. |
+| `@samline/forms/browser` | Pre-bundled IIFE that registers `window.Forms` for direct `<script>` usage. |
+
+---
 
 ## Quick Start
 
@@ -82,207 +96,81 @@ const contactForm = form('contact-form', {
   }
 })
 
-contactForm.onSubmit((element, data, formData, state) => {
-  console.log(element, data, formData, state)
+contactForm.watch('email', value => {
+  console.log('email is now:', value)
 })
-```
-
-## What You Can Do
-
-- bind to a form by id, element, or ref-like target
-- read and write field values
-- serialize form values to both a plain object and `FormData`
-- watch individual fields and subscribe to global form state
-- prefill values from the current URL query string
-- mark filled and error states through DOM attributes for styling
-- run built-in validation rules and custom validators
-- trigger submit handlers with optional auto-submit behavior
-- reset, inspect, and destroy the controller cleanly
-
-## API Reference
-
-### form(target, options)
-
-Creates a controller from:
-
-- a form id string
-- a real `HTMLFormElement`
-- a ref-like object with `current`
 
-### Properties
-
-- `element`: the bound `HTMLFormElement | null`
-- `f`: alias of `element`
-- `options`: normalized controller options
-
-### Submission
-
-- `onSubmit(callback, preventDefault?)`
-- `autoSubmit(options?)`
-- `disableAutoSubmit()`
-
-`onSubmit` accepts an optional second argument named `preventDefault`.
-
-- `onSubmit(callback)` is equivalent to `onSubmit(callback, true)`
-- with `true`, valid submissions are intercepted, which is the right choice for `fetch` or AJAX flows
-- with `false`, valid submissions continue with the browser's native form submit behavior
-- invalid submissions are still prevented, even when you pass `false`
-
-### Field observation
-
-- `watch(field, callback)`
-- `observe(field, callback)`
-- `subscribe(listener)`
-- `unwatch(field?, callback?)`
-
-### Field values
-
-- `setValue(name, value)`
-- `getValue(name)`
-- `getField(name)`
-- `prefill(fieldName?)`
-
-### Validation and errors
-
-- `validate(fields?)`
-- `revalidate(fields?)`
-- `setErrors(fields)`
-- `clearErrors(fields?)`
-
-Manual errors created with `setErrors()` are cleared per field by default as soon as that field changes, including updates triggered through `setValue()`. Pass `clearManualErrorsOnChange: false` to keep manual errors until you clear them explicitly.
-
-### Form lifecycle and state
-
-- `getData()`
-- `getState()`
-- `append(options)`
-- `reset()`
-- `destroy()`
-
-### Validation options
-
-Built-in rules supported through `validators`:
-
-- `required`
-- `minLength`
-- `maxLength`
-- `pattern`
-- `validate` for custom callbacks
-
-Controller options also include:
-
-- `autoValidate` to validate on initialization and subsequent field changes
-- `clearErrorsOnSubmit` to reset manual errors before submit validation runs
-- `clearManualErrorsOnChange` to clear only the changed field's manual error before the normal validation flow continues
-
-```ts
-const profileForm = form('profile-form', {
-  clearManualErrorsOnChange: false
+contactForm.onSubmit(async (_element, _data, formData) => {
+  await fetch('/api/contact', { method: 'POST', body: formData })
 })
 ```
 
-## Examples
+What this does:
 
-### Bind by id
+- Binds to the form with id `contact-form`.
+- Adds `css-filled` / `css-error` attributes on fields so you can style them with CSS.
+- Validates `email` on every change and on submit.
+- Intercepts valid submits (the default for `onSubmit`) and hands a real `FormData` instance to your handler.
 
-```ts
-import { form } from '@samline/forms'
-
-const profileForm = form('profile-form')
-```
-
-### Bind by element
-
-```ts
-const element = document.querySelector('#profile-form') as HTMLFormElement
-const profileForm = form(element)
-```
-
-### Watch a field
-
-```ts
-const profileForm = form('profile-form')
-
-profileForm.watch('email', value => {
-  console.log('email changed:', value)
-})
-```
-
-### Validate with built-in rules
-
-```ts
-const profileForm = form('profile-form', {
-  validators: {
-    email: {
-      required: true,
-      pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
-    },
-    password: {
-      minLength: 8
-    }
-  }
-})
+---
 
-const result = profileForm.validate()
-console.log(result.isValid, result.errors)
-```
+## What You Can Build
 
-### Submit with fetch
+- Contact, newsletter, login, signup, checkout, and profile forms.
+- Forms that submit with `fetch` while keeping native `FormData` payloads.
+- Autosave / autosubmit flows with optional debounce.
+- Visual feedback driven by `css-filled` and `css-error` attributes.
+- Progressive enhancement on top of any existing HTML form.
+- Forms rendered server-side (Blade, Twig, ERB) that still want client-side validation.
 
-```ts
-const profileForm = form('profile-form')
+---
 
-profileForm.onSubmit(async (_element, _data, formData) => {
-  await fetch('/api/profile', {
-    method: 'POST',
-    body: formData
-  })
-})
-```
+## API at a Glance
 
-This uses the default `preventDefault = true`, so the package intercepts the valid submit and lets you handle the request yourself.
+The controller is built around one factory and a small set of focused methods. Most methods are chainable.
 
-### Submit with native form behavior
+| Group | Methods |
+| --- | --- |
+| Lifecycle | [`form`](docs/api/form.md) · [`destroy`](docs/api/destroy.md) · [`reset`](docs/api/reset.md) |
+| Properties | [`element`](docs/api/element.md) · [`options`](docs/options.md) |
+| Submission | [`onSubmit`](docs/api/on-submit.md) · [`autoSubmit`](docs/api/auto-submit.md) · [`disableAutoSubmit`](docs/api/disable-auto-submit.md) |
+| Field observation | [`watch`](docs/api/watch.md) · [`observe`](docs/api/observe.md) · [`unwatch`](docs/api/unwatch.md) · [`subscribe`](docs/api/subscribe.md) |
+| Field values | [`setValue`](docs/api/set-value.md) · [`getValue`](docs/api/get-value.md) · [`getField`](docs/api/get-field.md) · [`prefill`](docs/api/prefill.md) · [`format`](docs/api/format.md) · [`formatAll`](docs/api/format.md) |
+| Validation | [`validate`](docs/api/validate.md) · [`revalidate`](docs/api/revalidate.md) · [`setErrors`](docs/api/set-errors.md) · [`clearErrors`](docs/api/clear-errors.md) |
+| State and data | [`getData`](docs/api/get-data.md) · [`getState`](docs/api/get-state.md) · [`append`](docs/api/append.md) |
+| Pure helpers | [`parseFormData`](docs/api/parse-form-data.md) · [`validateValues`](docs/api/validate-values.md) · [`validateFieldValue`](docs/api/validate-field-value.md) |
 
-```ts
-const profileForm = form('profile-form')
+See the full per-method reference in [`docs/api/`](docs/api/index.md).
 
-profileForm.onSubmit(() => {
-  console.log('validation passed')
-}, false)
-```
+---
 
-Use `false` when the form should continue with its normal HTML submission after validation succeeds, for example in server-rendered applications such as Laravel with Blade.
+## Optional peer: `@samline/formatter`
 
-If validation fails, the package still prevents the submit.
+[`format`](docs/api/format.md) and [`formatAll`](docs/api/format.md) rely on the optional peer dependency [`@samline/formatter`](https://github.com/samline/formatter). Install it when you need input masks (phone, credit-card, date, time, numeral, general):
 
-### Prefill from the URL
-
-```ts
-const profileForm = form('profile-form')
-profileForm.prefill()
+```bash
+npm install @samline/formatter
 ```
 
-### Work with form state
-
-```ts
-const profileForm = form('profile-form')
-
-const unsubscribe = profileForm.subscribe(state => {
-  console.log(state.values)
-  console.log(state.errors)
-})
+If the peer is not installed, the methods log a single `console.error` explaining how to install it and return the controller unchanged — the rest of the form keeps working. See [docs/recipes.md → 13. Format inputs with `@samline/formatter`](docs/recipes.md#13-format-inputs-with-samlineformatter) for end-to-end examples.
 
-unsubscribe()
-```
+---
 
 ## Documentation
 
-- [docs/vanilla.md](docs/vanilla.md)
-- [docs/react.md](docs/react.md)
-- [docs/vue.md](docs/vue.md)
-- [docs/svelte.md](docs/svelte.md)
-- [docs/browser.md](docs/browser.md)
+Full API reference, guides, and examples are available at **[samline.github.io/forms](https://samline.github.io/forms)**.
+
+| Doc | Purpose |
+| --- | --- |
+| [docs/getting-started.md](docs/getting-started.md) | Concepts, observable contract, lifecycle, and side-effect overview. |
+| [docs/options.md](docs/options.md) | Full `FormControllerOptions` reference. |
+| [docs/css-styling.md](docs/css-styling.md) | `css-filled` and `css-error` styling recipes. |
+| [docs/typescript.md](docs/typescript.md) | Every exported TypeScript type, with examples. |
+| [docs/api/index.md](docs/api/index.md) | One page per public method. |
+| [docs/recipes.md](docs/recipes.md) | End-to-end patterns: fetch submit, server errors, autosave, multi-step, etc. |
+| [docs/browser.md](docs/browser.md) | Browser global (`window.Forms`) usage. |
+
+---
 
 ## License
 

package/dist/browser/global.d.ts

@@ -0,0 +1,152 @@
+type FormatType = 'general' | 'phone' | 'numeral' | 'date' | 'time' | 'creditCard' | 'creditCardType';
+interface FieldFormatConfig {
+    /** One of the supported `@samline/formatter` `FormatType` values. */
+    type: FormatType;
+    /** Name of the visible input(s) inside the bound form. */
+    field: string | string[];
+    /**
+     * Optional name for the hidden raw mirror. Defaults to
+     * `${fieldName}Raw`. The mirror is created on first `format()`
+     * call and reused on subsequent calls.
+     */
+    rawField?: string;
+    /**
+     * Format-specific options forwarded to `@samline/formatter`.
+     * Any key documented for the chosen `type` is accepted (e.g.
+     * `country`, `delimiter`, `numeralDecimalMark`, `datePattern`).
+     */
+    options?: Record<string, unknown>;
+}
+type FieldFormatConfigMap = Record<string, FieldFormatConfig>;
+type FormDataPrimitive = FormDataEntryValue;
+type SerializedFormValue = FormDataPrimitive | FormDataPrimitive[];
+type FormFieldValue = string | string[] | File[] | undefined;
+type FormValues = Record<string, FormFieldValue>;
+type FormErrors = Record<string, string[]>;
+type RuleConfig<T> = T | {
+    value: T;
+    message?: string;
+};
+interface FieldValidationContext {
+    field: string;
+    value: FormFieldValue;
+    values: FormValues;
+}
+type FieldValidator = (context: FieldValidationContext) => string | undefined | null | false | true;
+interface FieldValidationRules {
+    required?: RuleConfig<boolean>;
+    minLength?: RuleConfig<number>;
+    maxLength?: RuleConfig<number>;
+    pattern?: RuleConfig<RegExp>;
+    validate?: FieldValidator | FieldValidator[];
+}
+type ValidationSchema = Record<string, FieldValidationRules>;
+interface VisualAttributes {
+    filled: string;
+    error: string;
+}
+interface AutoSubmitOptions {
+    debounce?: number;
+}
+interface FormControllerOptions {
+    attributes?: Partial<VisualAttributes>;
+    autoValidate?: boolean;
+    autoSubmit?: boolean | AutoSubmitOptions;
+    clearManualErrorsOnChange?: boolean;
+    clearErrorsOnSubmit?: boolean;
+    validators?: ValidationSchema;
+    /**
+     * Declarative format configuration. Each entry is applied during
+     * `form()` initialization using the same logic as `controller.format(...)`.
+     * The key is just an identifier — the visible field name lives in
+     * `FieldFormatConfig.field`.
+     */
+    formats?: FieldFormatConfigMap;
+}
+interface SerializedFormResult {
+    data: Record<string, SerializedFormValue>;
+    formData: FormData;
+}
+interface ValidationResult {
+    isValid: boolean;
+    errors: FormErrors;
+}
+interface FormStateSnapshot {
+    values: FormValues;
+    errors: FormErrors;
+    filledFields: string[];
+    isValid: boolean;
+    isValidated: boolean;
+    autoSubmit: boolean;
+    submitCount: number;
+}
+type FormStateListener = (state: FormStateSnapshot) => void;
+type FormFieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+type FormTarget = string | HTMLFormElement | {
+    current: HTMLFormElement | null;
+} | null | undefined;
+interface AppendContentOptions {
+    tag: keyof HTMLElementTagNameMap;
+    content: string;
+    class?: string;
+    atStart?: boolean;
+}
+type FormFieldWatcher = (value: FormFieldValue, field: FormFieldElement | FormFieldElement[] | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
+type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void;
+interface FormController {
+    readonly element: HTMLFormElement | null;
+    readonly f: HTMLFormElement | null;
+    readonly options: FormControllerOptions;
+    onSubmit: (callback: FormSubmitHandler, preventDefault?: boolean) => FormController;
+    watch: (field: string, callback: FormFieldWatcher) => FormController;
+    observe: (field: string, callback: FormFieldWatcher) => () => void;
+    unwatch: (field?: string, callback?: FormFieldWatcher) => FormController;
+    subscribe: (listener: FormStateListener) => () => void;
+    prefill: (fieldName?: string) => FormController;
+    append: (options: AppendContentOptions) => HTMLElement | null;
+    setErrors: (fields: string[] | FormErrors) => FormController;
+    clearErrors: (fields?: string[]) => FormController;
+    setValue: (name: string, value: unknown) => FormController;
+    validate: (fields?: string[]) => ValidationResult;
+    revalidate: (fields?: string[]) => ValidationResult;
+    /**
+     * Apply the same `@samline/formatter` pipeline to a single field or
+     * to a list of fields sharing one configuration. Chainable.
+     *
+     * Requires the optional peer dependency `@samline/formatter`. When
+     * the peer is not installed the call logs a single `console.error`
+     * and returns the controller unchanged.
+     */
+    format: (config: FieldFormatConfig) => FormController;
+    formatAll: (config: FieldFormatConfig) => FormController;
+    reset: () => FormController;
+    autoSubmit: (options?: boolean | AutoSubmitOptions) => FormController;
+    disableAutoSubmit: () => FormController;
+    getValue: (name: string) => FormFieldValue;
+    getField: (name: string) => FormFieldElement | FormFieldElement[] | null;
+    getData: () => SerializedFormResult;
+    getState: () => FormStateSnapshot;
+    destroy: () => void;
+}
+
+interface NewFormInput {
+    id: string;
+    options?: FormControllerOptions;
+}
+interface FormsAvailable {
+    [id: string]: FormController;
+}
+interface FormsApi {
+    form: (target: FormTarget, options?: FormControllerOptions) => FormController;
+    newForm: (input: NewFormInput) => FormController | undefined;
+    destroyForm: (id: string) => void;
+    available: FormsAvailable;
+}
+declare const Forms: FormsApi;
+declare global {
+    interface Window {
+        Forms: FormsApi;
+    }
+}
+
+export { type FormsApi, type FormsAvailable, type NewFormInput, Forms as default };