@samline/forms 2.4.0 → 2.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Olvera (samline)
+
+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

@@ -1,8 +1,8 @@
 # Forms
 
-> A small, framework-free form controller for vanilla JS and direct browser usage.
+> A TypeScript-first, framework-free controller for native HTML forms.
 
-> 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.
+> Add validation, reactive field state, accessible error handling, serialization, auto-submit, and optional input formatting without adopting a UI framework.
 
 ---
 
@@ -42,10 +42,10 @@ Requires Node 20+ when bundling. Runtime target is ES2020.
 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@2.4.0/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.7.0/dist/browser/global.global.js"></script>
 ```
 
-> Pin the version in production. Replace `2.4.0` with the version you ship.
+> Pin the version in production. Replace `2.7.0` with the version you ship.
 
 The browser bundle exposes a single global: `window.Forms`.
 
@@ -55,7 +55,7 @@ The browser bundle exposes a single global: `window.Forms`.
   <button type="submit">Send</button>
 </form>
 
-<script src="https://unpkg.com/@samline/forms@2.4.0/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.7.0/dist/browser/global.global.js"></script>
 <script>
   const contactForm = window.Forms.newForm({ id: 'contact-form' })
 
@@ -78,7 +78,8 @@ See [docs/browser.md](docs/browser.md) for the full browser surface.
 | Entrypoint | When to use |
 | --- | --- |
 | `@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. |
+| `@samline/forms/browser` | ESM/CJS browser module with registry exports, bundled types, and `window.Forms` registration. |
+| `@samline/forms/browser/global` | Pre-bundled IIFE for direct `<script>` usage; the CDN URL resolves to `dist/browser/global.global.js`. |
 
 The vanilla entrypoint also exports `browser`, the same `{ form, newForm, destroyForm, available }` surface as the IIFE but as a module-level singleton (no `globalThis` side-effect). Use it from a bundler when you want the registry helpers without the IIFE — see [docs/browser.md → Using the same shape from a bundler](docs/browser.md#using-the-same-shape-from-a-bundler).
 
@@ -133,7 +134,7 @@ The controller is built around one factory and a small set of focused methods. M
 
 | Group | Methods |
 | --- | --- |
-| Lifecycle | [`form`](docs/api/form.md) · [`destroy`](docs/api/destroy.md) · [`reset`](docs/api/reset.md) |
+| Lifecycle | [`form`](docs/api/form.md) · [`addCleanup`](docs/api/add-cleanup.md) · [`destroy`](docs/api/destroy.md) · [`reset`](docs/api/reset.md) |
 | Registry (vanilla) | [`browser`](docs/getting-started.md#browser-registry-helpers) — bundler-friendly `{ form, newForm, destroyForm, available }` singleton. |
 | 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) |
@@ -143,6 +144,8 @@ The controller is built around one factory and a small set of focused methods. M
 | 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) |
 
+Validation supports explicit cross-field dependencies with `dependsOn`, per-member collection rules with `each`, and strict decimal `numeric` / inclusive `min` / `max` rules. Async `onSubmit` handlers are reflected by `getState().isSubmitting`, while `addCleanup()` lets integrations register controller-owned teardown work.
+
 See the full per-method reference in [`docs/api/`](docs/api/index.md).
 
 ---
@@ -177,4 +180,4 @@ Full API reference, guides, and examples are available at **[samline.github.io/f
 
 ## License
 
-MIT
+MIT

package/dist/browser/global.d.ts

@@ -2,23 +2,11 @@ type FormatType = 'general' | 'phone' | 'numeral' | 'date' | 'time' | 'creditCar
 interface FieldFormatConfig {
     /** One of the supported `@samline/formatter` `FormatType` values. */
     type: FormatType;
-    /**
-     * Canonical name of the formatted field. The value the backend
-     * ultimately receives (the `raw` output of the formatter) is
-     * exposed under this name; the formatter is responsible for
-     * keeping it in sync with the visible input.
-     */
+    /** Canonical field name or fields whose raw values are submitted. */
     field: string | string[];
     /**
-     * Name of the visible input that shows the formatted value to
-     * the user. Defaults to `${fieldName}_displayed`.
-     *
-     * The visible is **renamed** from `field` to `displayField` on
-     * the first `format()` call (idempotent on re-binding). A hidden
-     * `<input type="hidden" name="<field>">` is created next to it
-     * to carry the raw value. Both names are first-class in the
-     * controller's API (`getValue`, `getField`, `setValue`, `watch`,
-     * `getData`) — see `docs/api/format.md` for the full contract.
+     * Name of the visible input for a single field. Array configurations
+     * must omit this option and derive one display name per field.
      */
     displayField?: string;
     /**
@@ -42,15 +30,30 @@ interface FieldValidationContext {
     field: string;
     value: FormFieldValue;
     values: FormValues;
+    /** Concrete control while validating one member through `each`. */
+    element?: FormFieldElement;
+    /** Zero-based member position while validating through `each`. */
+    index?: number;
 }
 type FieldValidator = (context: FieldValidationContext) => string | undefined | null | false | true;
-interface FieldValidationRules {
+interface ValueValidationRules {
     required?: RuleConfig<boolean>;
     minLength?: RuleConfig<number>;
     maxLength?: RuleConfig<number>;
     pattern?: RuleConfig<RegExp>;
+    numeric?: RuleConfig<boolean>;
+    min?: RuleConfig<number>;
+    max?: RuleConfig<number>;
     validate?: FieldValidator | FieldValidator[];
 }
+interface FieldValidationRules extends ValueValidationRules {
+    /** Field name whose non-empty value must equal this field's value. */
+    sameAs?: RuleConfig<string>;
+    /** Fields whose changes should revalidate this field. */
+    dependsOn?: string | string[];
+    /** Rules applied independently to each collection member. */
+    each?: ValueValidationRules;
+}
 type ValidationSchema = Record<string, FieldValidationRules>;
 interface VisualAttributes {
     filled: string;
@@ -89,6 +92,7 @@ interface FormStateSnapshot {
     isValid: boolean;
     isValidated: boolean;
     autoSubmit: boolean;
+    isSubmitting: boolean;
     submitCount: number;
 }
 type FormStateListener = (state: FormStateSnapshot) => void;
@@ -103,12 +107,14 @@ interface AppendContentOptions {
     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;
+type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void | Promise<void>;
+type FormCleanup = () => void;
 interface FormController {
     readonly element: HTMLFormElement | null;
     readonly f: HTMLFormElement | null;
     readonly options: FormControllerOptions;
     onSubmit: (callback: FormSubmitHandler, preventDefault?: boolean) => FormController;
+    addCleanup: (cleanup: FormCleanup) => () => void;
     watch: (field: string, callback: FormFieldWatcher) => FormController;
     observe: (field: string, callback: FormFieldWatcher) => () => void;
     unwatch: (field?: string, callback?: FormFieldWatcher) => FormController;
@@ -155,10 +161,14 @@ interface FormsApi {
 }
 
 declare const Forms: FormsApi;
+declare const form: (target: FormTarget, options?: FormControllerOptions) => FormController;
+declare const newForm: (input: NewFormInput) => FormController | undefined;
+declare const destroyForm: (id: string) => void;
+declare const available: FormsAvailable;
 declare global {
     interface Window {
         Forms: FormsApi;
     }
 }
 
-export { Forms as default };
+export { available, Forms as default, destroyForm, form, newForm };