@explita/formly 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2026-01-16
+
+### Added
+
+- **Field Arrays**: Full support for dynamic lists with a comprehensive API (`push`, `insert`, `remove`, `swap`, `move`, `moveUp`, `moveDown`, etc.).
+- **Form persistence (Drafts)**: Built-in support for saving and restoring form progress locally using `persistKey`.
+- **Computed Fields**: Support for fields that derive their value from other fields, including wildcard support for arrays (`array.*.field`).
+- **Form Registry**: Ability to access and control any form instance globally by its unique ID.
+- **Improved Performance**: Switched to a flat-state internal representation with precise pub/sub notifications to minimize re-renders.
+- **Deep Path Utilities**: Enhanced handling of nested objects and arrays in form state.
+
+### Changed
+
+- Refactored internal state Management for better scalability and performance.
+- Simplified `useForm` initialization logic.
+
+## [0.1.1] - 2026-01-11
+
+### Fixed
+
+- Initial maintenance and stabilization improvements.
+
+## [0.1.0] - 2026-01-11
+
+### Added
+
+- Initial release of `@explita/formly`.
+- **Core Hooks**:
+  - `useForm`: Core hook for form state management, validation, and submission.
+  - `useField`: Hook for managing individual field state and interactions.
+  - `useFormContext`: Hook for accessing form state within the `Form` provider.
+  - `useFormById`: Utility hook to access a form instance globally by its ID.
+- **Components**:
+  - `Form`: Provider component for the form context.
+  - `Field`: Declarative component for field management.
+  - `FieldError`: Component for displaying field validation messages.
+  - `FormSpy`: Component to monitor form state changes without triggering global re-renders.
+  - `Label`: Accessible label component integrated with form field state.
+- **Validation**:
+  - First-class support for `zod` schema validation.
+- **Features**:
+  - Support for complex, nested data structures.
+  - Optimized performance through precise subscription-based updates.
+  - Fully type-safe API for form values, errors, and handlers.

package/dist/hooks/use-form-initialization.js

@@ -7,6 +7,7 @@ const react_1 = require("react");
 const utils_2 = require("../utils");
 function useFormInitialization({ defaultValues, persistKey, savedFormFirst, generatePlaceholders, computed, draftListeners, compute, onReady, setValues, createHandlerContext, }) {
     const previousDefaultValuesRef = (0, react_1.useRef)({});
+    const hasInitializedRef = (0, react_1.useRef)(false);
     (0, react_1.useEffect)(() => {
         var _a, _b;
         const saved = persistKey
@@ -18,15 +19,18 @@ function useFormInitialization({ defaultValues, persistKey, savedFormFirst, gene
             savedFormFirst,
             generatePlaceholders,
         });
-        // Restore persisted state
-        (_b = (_a = draftListeners.current).restore) === null || _b === void 0 ? void 0 : _b.call(_a, merged);
-        // Notify readiness
-        onReady === null || onReady === void 0 ? void 0 : onReady(merged, createHandlerContext(merged));
         const flattenedDefaults = (0, utils_1.flattenFormValues)(defaultValues);
         const defaultsUnchanged = (0, utils_1.shallowEqual)(previousDefaultValuesRef.current, flattenedDefaults);
         if (defaultsUnchanged)
             return;
         previousDefaultValuesRef.current = flattenedDefaults;
+        if (!hasInitializedRef.current) {
+            // Restore persisted state
+            (_b = (_a = draftListeners.current).restore) === null || _b === void 0 ? void 0 : _b.call(_a, merged);
+            // Notify readiness
+            onReady === null || onReady === void 0 ? void 0 : onReady(merged, createHandlerContext(merged));
+            hasInitializedRef.current = true;
+        }
         // Run computed fields
         if (computed) {
             for (const key in computed) {

package/dist/hooks/use-form.js

@@ -13,6 +13,7 @@ const components_1 = require("../components");
 const pub_sub_1 = require("../lib/pub-sub");
 const form_registry_1 = require("../lib/form-registry");
 const use_form_initialization_1 = require("./use-form-initialization");
+const meta_context_1 = require("../lib/meta-context");
 function useForm(options) {
     var _a;
     const { schema, validateOn = "change-submit", defaultValues = {}, errors = {}, mode = "controlled", errorParser, check, computed, onSubmit, onReady, autoFocusOnError = true, savedFormFirst = true, id, } = options || {};
@@ -814,31 +815,7 @@ function useForm(options) {
             },
         };
     }, []);
-    const formMetadata = {
-        get(key) {
-            return metaRef.current.get(key);
-        },
-        set(key, value, opts) {
-            metaRef.current.set(key, value);
-            if (!(opts === null || opts === void 0 ? void 0 : opts.silent))
-                triggerRerender();
-        },
-        delete(key) {
-            metaRef.current.delete(key);
-        },
-        has(key) {
-            return metaRef.current.has(key);
-        },
-        keys() {
-            return metaRef.current.keys();
-        },
-        values() {
-            return metaRef.current.values();
-        },
-        clear() {
-            metaRef.current.clear();
-        },
-    };
+    const formMetadata = (0, meta_context_1.createMetaContext)(metaRef, triggerRerender);
     //initialize form
     // Intentionally depends only on defaultValues.
     // Draft restoration & computed logic are internally guarded.

package/dist/lib/meta-context.d.ts

@@ -0,0 +1,11 @@
+export declare function createMetaContext(metaRef: React.RefObject<Map<string, unknown>>, triggerRerender: () => void): {
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown, opts?: {
+        silent?: boolean;
+    }): void;
+    delete(key: string): void;
+    has(key: string): boolean;
+    keys(): MapIterator<string>;
+    values(): MapIterator<unknown>;
+    clear(): void;
+};

package/dist/lib/meta-context.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMetaContext = createMetaContext;
+function createMetaContext(metaRef, triggerRerender) {
+    return {
+        get(key) {
+            return metaRef.current.get(key);
+        },
+        set(key, value, opts) {
+            metaRef.current.set(key, value);
+            if (!(opts === null || opts === void 0 ? void 0 : opts.silent))
+                triggerRerender();
+        },
+        delete(key) {
+            metaRef.current.delete(key);
+        },
+        has(key) {
+            return metaRef.current.has(key);
+        },
+        keys() {
+            return metaRef.current.keys();
+        },
+        values() {
+            return metaRef.current.values();
+        },
+        clear() {
+            metaRef.current.clear();
+        },
+    };
+}

package/dist/types/utils.d.ts

@@ -64,6 +64,9 @@ export type HandlerContext<T> = {
     array: <P extends Path<T>>(path: P) => HandlerArrayHelpers<ArrayItem<T, P>>;
     meta: FormMeta;
 };
+type ReadyContext<T> = {
+    meta: FormMeta;
+};
 export type FormMeta = {
     get<T = unknown>(key: string): T | undefined;
     set: (key: string, value: unknown, options?: {
@@ -259,14 +262,43 @@ export type SetValues<T> = (values: Partial<T>, options?: {
 }) => void;
 export type SetErrors<T> = (errors?: Partial<Record<Path<T>, string>> | z.ZodError["issues"]) => void;
 export type FormOptions<TSchema extends ZodObject<any> | undefined, TValues> = {
+    /**
+     * The schema to use for validation.
+     */
     schema?: TSchema;
+    /**
+     * The default values of the form.
+     */
     defaultValues?: TValues;
+    /**
+     * The errors of the form.
+     */
     errors?: Partial<Record<Path<SchemaType<TSchema, TValues>>, string>>;
+    /**
+     * The error parser to use for parsing errors.
+     */
     errorParser?: (message: string) => string;
+    /**
+     * The check function to use for checking the form.
+     */
     check?: CheckFn<SchemaType<TSchema, TValues>>;
+    /**
+     * The computed fields of the form.
+     */
     computed?: Record<string, Computed<SchemaType<TSchema, TValues>>>;
+    /**
+     * The submit handler of the form.
+     */
     onSubmit?: (values: SchemaType<TSchema, TValues>, ctx: HandlerContext<SchemaType<TSchema, TValues>>) => void;
-    onReady?: (values: SchemaType<TSchema, TValues>, ctx: HandlerContext<SchemaType<TSchema, TValues>>) => void;
+    /**
+     * Called when the form is ready/mounted.
+     */
+    onReady?: (values: SchemaType<TSchema, TValues>, ctx: ReadyContext<SchemaType<TSchema, TValues>>) => void;
+    /**
+     * The mode of the form.
+     *
+     * @default "uncontrolled"
+     */
     mode?: "controlled" | "uncontrolled";
     /**
      * The validation trigger.
@@ -278,8 +310,19 @@ export type FormOptions<TSchema extends ZodObject<any> | undefined, TValues> = {
      * Used to register the form so it can be accessed outside the hook.
      */
     id?: string;
+    /**
+     * The key used to persist the form state.
+     * If provided, the form state will be persisted to localStorage and restored on mount.
+     * If id is provided, it will be used as the key.
+     */
     persistKey?: string;
+    /**
+     * Whether to focus the first field with an error on submit.
+     */
     autoFocusOnError?: boolean;
+    /**
+     * Whether to use the saved form state first.
+     */
     savedFormFirst?: boolean;
 };
 type CheckFn<T> = (data: T, ctx: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explita/formly",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A lightweight form toolkit for React built with developer ergonomics in mind. Includes a flexible Form component, `useForm`, `useField`, and `useFormContext` hooks for managing form state and validation with ease. Designed to simplify complex forms while remaining unopinionated and extensible.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,6 +48,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ]
 }

package/README.old.md

@@ -1,141 +0,0 @@
-⚠️ Using register() is convenient for quick input wiring, but for large forms where performance matters, prefer useField or Field to avoid unnecessary re-renders.
-
-For performance and clarity, here’s the usual pattern I’d recommend:
-
-<form.Field /> (from form instance) or standalone <Field />
-
-Best for most use cases.
-
-Handles binding, errors, and local reactivity automatically.
-
-Encapsulates the field logic, so the parent form doesn’t rerender on every change.
-
-Easy to drop into JSX and add labels, wrappers, or custom styling.
-
-useField() inside a separate component
-
-Great when you want full programmatic control over the field.
-
-Can wrap a custom input or a complex component.
-
-Keeps reactivity local to the component.
-
-Allows you to do more advanced things like computed values, conditional logic, or side effects specific to that field.
-
-✅ Rule of thumb:
-
-If you just need a simple form input, use <Field /> — minimal boilerplate, good defaults.
-
-If you need custom behavior or a completely custom component, wrap it with a component using useField().
-
-This way, the form itself stays light and doesn’t rerender unnecessarily, while each field manages its own state efficiently.
-
-# @explita/formly
-
-A powerful and extensible React form hook for building scalable forms with Zod validation, persistence, and full control.
-
-## ✨ Features
-
-- ✅ Built-in Zod schema validation
-- ✅ Controlled and uncontrolled modes
-- ✅ Persistent form state via `localStorage`
-- ✅ Field-level error handling and parsing
-- ✅ Debounced input validation
-- ✅ Works seamlessly with any UI library (e.g. shadcn/ui)
-
-## 📦 Installation
-
-```bash
-npm install @explita/formly
-# or
-yarn add @explita/formly
-# or
-pnpm add @explita/formly
-```
-
-## 🧪 Usage
-
-```tsx
-import { z } from "zod";
-import { useForm, Form, Field } from "@explita/formly";
-import { Input } from "@/components/ui/input";
-
-const schema = z.object({
-  email: z.email({ error: "Invalid email" }),
-  password: z
-    .string()
-    .min(6, { error: "Password must be at least 6 characters" }),
-});
-
-export default function LoginForm() {
-  const form = useForm({
-    schema,
-    defaultValues: { email: "", password: "" },
-    onSubmit: async (values) => {
-      console.log("Submitted", values);
-      // call server action here or perform an HTTP request
-      // const response = await login(values)
-      // return response
-      return values;
-    },
-    onSuccess: (result, ctx) => {
-      console.log("Success", result);
-      // result is the result of onSubmit
-      // ctx.reset(); - reset the form, you don't need this if resetOnSuccess is true
-    },
-    onError: (error, ctx) => {
-      console.log("Error", error, ctx);
-      // error - the error object (usually from schema or server)
-      // ctx.setErrors({ email: "Email is required" }); - useful for server errors
-    },
-    persistKey: "login-form", // Optional – saves input across reloads
-    errorParser: (msg) => msg, // Optional – customize error messages
-    mode: "controlled", // Optional – "controlled" is the default
-    resetOnSuccess: true, // Optional – clears the form on success
-  });
-
-  //Field meta is an object that contains the value, error, and hasError properties
-
-  return (
-    <Form use={form}>
-      <Field name="email" label="Email" isRequired>
-        {(props, meta) => <Input {...props} />}
-      </Field>
-
-      <Field name="password" label="Password" isRequired>
-        {(props, meta) => <Input type="password" {...props} />}
-      </Field>
-
-      <button type="submit" disabled={form.isSubmitting}>
-        Submit
-      </button>
-    </Form>
-  );
-}
-```
-
-## 🧩 API Overview
-
-### `useForm(options)`
-
-| Option           | Type                                  | Description                                 |
-| ---------------- | ------------------------------------- | ------------------------------------------- |
-| `schema`         | `ZodObject`                           | Optional Zod schema for validation          |
-| `defaultValues`  | `Partial<T>`                          | Initial form values                         |
-| `onSubmit`       | `(values, formData) => Promise<void>` | Async submission handler                    |
-| `onSuccess`      | `(result) => void`                    | Called on successful submission             |
-| `onError`        | `(error, ctx) => void`                | Called on error, with access to `setErrors` |
-| `persistKey`     | `string`                              | Key to store form values under              |
-| `errorParser`    | `(msg: string) => string`             | Optional formatter for error messages       |
-| `mode`           | `controlled`\|`uncontrolled`          | Default to controlled                       |
-| `resetOnSuccess` | `boolean`                             | Clear the form on successful submission     |
-
-### `useFormContext()`
-
-Can be used in any component nested inside the `Form` component to access the form context.
-
-##
-
-### 📄 License
-
-MIT — Made with ❤️ by [Explita](https://explita.ng)