@uibit/form 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UIBit 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,26 @@
+# Form
+
+[Interactive Demonstration](https://rawlings.github.io/uibit/components/form)
+
+Form provides a composable, declarative wrapper around standard HTML `<form>` elements. It adds multi-step wizard navigation, asynchronous submission lifecycle states, and unsaved changes tracking to simplify form construction.
+
+## Value Delivery
+
+- **Progressive Enhancement** – Operates as a wrapper around native forms, falling back to default browser submission behavior if JavaScript has not loaded.
+- **Asynchronous Lifecycles** – Intercepts submissions to perform fetch requests, exposing state attributes (idle, pending, success, error) to allow custom interface feedback.
+- **Automated Multi-step Wizards** – Groups inputs within standard `<fieldset>` tags into structured wizard steps with navigation buttons and step validation.
+- **Safe Navigation** – Tracks changes across all internal fields, warning users before they navigate away with unsaved details.
+
+## Ideal Applications
+
+- **Onboarding flows** – Multi-step registration forms or surveys.
+- **Data editing screens** – Safe updates of profile records, settings panels, or metadata grids.
+- **Transactional submittals** – Fast user checkouts or feedback collection points.
+
+## Further Information
+
+Detailed design guidelines, customizable attributes, and integration examples are available on our documentation site.
+
+## Changelog
+
+Please see the [Changelog](CHANGELOG.md) for version history.

package/custom-elements.json

@@ -0,0 +1,407 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/form.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A declarative form wrapper that wraps a native `<form>` and adds wizards,\nsubmit lifecycle states, and dirty checking.",
+          "name": "Form",
+          "slots": [
+            {
+              "description": "Default slot where the native `<form>` element is placed.",
+              "name": ""
+            },
+            {
+              "description": "Custom success template displayed upon successful submission.",
+              "name": "success"
+            },
+            {
+              "description": "Custom error template displayed upon failed submission.",
+              "name": "error"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "warnUnsaved",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt-in warning prompt if the user tries to leave the page with unsaved changes.",
+              "attribute": "warn-unsaved"
+            },
+            {
+              "kind": "field",
+              "name": "step",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Active wizard step (1-indexed). Only active if multiple fieldsets exist.",
+              "attribute": "step",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "stepsCount",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "The total number of steps/fieldsets detected in the form.",
+              "attribute": "steps-count",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "_stepTitles",
+              "type": {
+                "text": "string[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_maxVisitedStep",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "1"
+            },
+            {
+              "kind": "field",
+              "name": "dirty",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Tracks whether the form has unsaved changes.",
+              "attribute": "dirty",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "status",
+              "type": {
+                "text": "'idle' | 'pending' | 'success' | 'error'"
+              },
+              "default": "'idle'",
+              "description": "Submission state: 'idle', 'pending', 'success', or 'error'.",
+              "attribute": "status",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "_slottedFormEl",
+              "type": {
+                "text": "HTMLFormElement | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_initialValues",
+              "privacy": "private",
+              "default": "new Map<Element, any>()"
+            },
+            {
+              "kind": "field",
+              "name": "_observer",
+              "type": {
+                "text": "MutationObserver | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_formListenersCleanups",
+              "type": {
+                "text": "Array<() => void>"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "method",
+              "name": "_cleanupFormListeners",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_initializeForm",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_detectSlottedForm",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_detectSteps",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_updateStepVisibility",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_getFormElements",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Array<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_captureInitialValues",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_getElementValue",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "any"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "el",
+                  "type": {
+                    "text": "HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_onFormInput",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_checkDirty",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_onBeforeUnload",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "BeforeUnloadEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_onSlotChange",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "nextStep"
+            },
+            {
+              "kind": "method",
+              "name": "prevStep"
+            },
+            {
+              "kind": "method",
+              "name": "goToStep",
+              "parameters": [
+                {
+                  "name": "stepNum",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "field",
+              "name": "_isResetting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "method",
+              "name": "reset"
+            },
+            {
+              "kind": "method",
+              "name": "submit"
+            },
+            {
+              "kind": "method",
+              "name": "_onSubmit",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_onFormClick",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            }
+          ],
+          "attributes": [
+            {
+              "name": "warn-unsaved",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt-in warning prompt if the user tries to leave the page with unsaved changes.",
+              "fieldName": "warnUnsaved"
+            },
+            {
+              "name": "step",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Active wizard step (1-indexed). Only active if multiple fieldsets exist.",
+              "fieldName": "step"
+            },
+            {
+              "name": "steps-count",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "The total number of steps/fieldsets detected in the form.",
+              "fieldName": "stepsCount"
+            },
+            {
+              "name": "dirty",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Tracks whether the form has unsaved changes.",
+              "fieldName": "dirty"
+            },
+            {
+              "name": "status",
+              "type": {
+                "text": "'idle' | 'pending' | 'success' | 'error'"
+              },
+              "default": "'idle'",
+              "description": "Submission state: 'idle', 'pending', 'success', or 'error'.",
+              "fieldName": "status"
+            }
+          ],
+          "superclass": {
+            "name": "UIBitElement",
+            "package": "@uibit/core"
+          },
+          "tagName": "uibit-form",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "Form",
+          "declaration": {
+            "name": "Form",
+            "module": "src/form.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "uibit-form",
+          "declaration": {
+            "name": "Form",
+            "module": "src/form.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/form"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/types"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/styles.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "styles",
+          "default": "css` :host { display: block; position: relative; font-size: var(--uibit-component-font-size, var(--uibit-font-size-base, 1rem)); font-weight: var(--uibit-component-font-weight, var(--uibit-font-weight-normal, 400)); line-height: var(--uibit-component-line-height, var(--uibit-line-height-relaxed, 1.625)); --uibit-form-wizard-margin: var(--uibit-form-wizard-margin-val, 2rem); } /* Premium Minimalist Stepper Header (Split Layout) */ .wizard-header { margin-bottom: var(--uibit-form-wizard-margin, 2rem); display: flex; justify-content: space-between; align-items: center; width: 100%; height: 1.5rem; } .wizard-meta { display: flex; align-items: center; gap: 0.75rem; } .wizard-controls { display: flex; align-items: center; gap: 0.25rem; } .wizard-back-btn, .wizard-next-btn { display: inline-flex; align-items: center; justify-content: center; background: transparent; border: none; padding: 0.25rem; cursor: pointer; color: #6b7280; border-radius: 999rem; transition: color 150ms ease, background-color 150ms ease, transform 150ms ease, opacity 150ms ease; } .wizard-back-btn:hover, .wizard-next-btn:hover { color: #111827; background-color: #f3f4f6; } .wizard-back-btn:active, .wizard-next-btn:active { transform: scale(0.95); } .wizard-back-btn:focus-visible, .wizard-next-btn:focus-visible { outline: 0.125rem solid #000000; } .wizard-step-info { font-size: var(--uibit-font-size-xs, 0.75rem); font-weight: 500; color: #9ca3af; display: inline-flex; align-items: center; gap: 0.25rem; user-select: none; } .wizard-step-num { color: #111827; font-weight: 600; } .wizard-step-sep { opacity: 0.5; } .wizard-step-total { opacity: 0.8; } ::slotted([slot^=\"step-title-\"]), .wizard-step-title { font-family: var(--uibit-font-family, Inter, sans-serif); font-size: var(--uibit-font-size-sm, 0.875rem); font-weight: 650; color: #111827; letter-spacing: -0.01em; user-select: none; } /* Stabilized layout hidden state */ .disabled-control { opacity: 0; pointer-events: none; visibility: hidden; } /* Premium inline error banner */ .error-banner { padding: 1rem 0; font-size: var(--uibit-font-size-sm, 0.875rem); color: #111827; margin-bottom: 0.5rem; } /* State content wrappers */ .state-content { display: none; } :host([status=\"pending\"]) .state-content[data-state=\"pending\"] { display: block; } :host([status=\"success\"]) .state-content[data-state=\"success\"] { display: block; } /* Correctly hide the slotted form element on success and pending states */ :host([status=\"success\"]) ::slotted(form), :host([status=\"pending\"]) ::slotted(form) { display: none !important; } `"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "styles",
+          "declaration": {
+            "name": "styles",
+            "module": "src/styles.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/types.ts",
+      "declarations": [],
+      "exports": []
+    }
+  ]
+}

package/dist/form.d.ts

@@ -0,0 +1,55 @@
+import type { PropertyValues } from 'lit';
+import { UIBitElement } from '@uibit/core';
+/**
+ * A declarative form wrapper that wraps a native `<form>` and adds wizards,
+ * submit lifecycle states, and dirty checking.
+ *
+ * @slot - Default slot where the native `<form>` element is placed.
+ * @slot success - Custom success template displayed upon successful submission.
+ * @slot error - Custom error template displayed upon failed submission.
+ */
+export declare class Form extends UIBitElement {
+    static styles: import("lit").CSSResult;
+    /** Opt-in warning prompt if the user tries to leave the page with unsaved changes. */
+    warnUnsaved: boolean;
+    /** Active wizard step (1-indexed). Only active if multiple fieldsets exist. */
+    step: number;
+    /** The total number of steps/fieldsets detected in the form. */
+    stepsCount: number;
+    private _stepTitles;
+    private _maxVisitedStep;
+    /** Tracks whether the form has unsaved changes. */
+    dirty: boolean;
+    /** Submission state: 'idle', 'pending', 'success', or 'error'. */
+    status: 'idle' | 'pending' | 'success' | 'error';
+    private _slottedFormEl;
+    private _initialValues;
+    private _observer?;
+    private _formListenersCleanups;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(changedProperties: PropertyValues): void;
+    private _cleanupFormListeners;
+    private _initializeForm;
+    private _detectSlottedForm;
+    private _detectSteps;
+    private _updateStepVisibility;
+    private _getFormElements;
+    private _captureInitialValues;
+    private _getElementValue;
+    private _onFormInput;
+    private _checkDirty;
+    private _onBeforeUnload;
+    private _onSlotChange;
+    nextStep(): void;
+    prevStep(): void;
+    goToStep(stepNum: number): void;
+    private _isResetting;
+    reset(): void;
+    submit(): Promise<void>;
+    private _onSubmit;
+    private _onFormClick;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    render(): import("lit").TemplateResult<1>;
+}
+//# sourceMappingURL=form.d.ts.map

package/dist/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../src/form.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAAsB,YAAY,EAAE,MAAM,aAAa,CAAC;AAI/D;;;;;;;GAOG;AACH,qBACa,IAAK,SAAQ,YAAY;IACpC,MAAM,CAAC,MAAM,0BAAU;IAGvB,sFAAsF;IAC9B,WAAW,UAAS;IAE5E,+EAA+E;IACpC,IAAI,SAAK;IAEpD,gEAAgE;IACK,UAAU,SAAK;IAE3E,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,eAAe,CAAK;IAErC,mDAAmD;IACP,KAAK,UAAS;IAE1D,kEAAkE;IACvB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAU;IAErG,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,cAAc,CAA2B;IACjD,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,sBAAsB,CAAyB;IAEvD,iBAAiB,SAYhB;IAED,oBAAoB,SAMnB;IAED,YAAY,CAAC,iBAAiB,EAAE,cAAc,QAG7C;IAED,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,qBAAqB;IAc7B,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IA8BnB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,aAAa;IAOrB,QAAQ,SAuBP;IAED,QAAQ,SAMP;IAED,QAAQ,CAAC,OAAO,EAAE,MAAM,QA2BvB;IAID,OAAO,CAAC,YAAY,CAAS;IAE7B,KAAK,SA+BJ;IAEK,MAAM,kBAqCX;IAED,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,YAAY;IAsBpB,SAAS,CAAC,UAAU,CAAC,iBAAiB,EAAE,cAAc,QAIrD;IAED,MAAM,oCAiEL;CACF"}