@explita/formly 0.1.0

package/README.md

@@ -0,0 +1,261 @@
+# @explita/formly
+
+A lightweight, type-safe form toolkit for React built with developer ergonomics in mind. Provides a flexible form management solution with built-in validation, array manipulation, and nested form support.
+
+## Features
+
+- 🚀 **Type-safe** with TypeScript support
+- 🧩 **Composable** form components and hooks
+- 🔄 **Form State Management** with minimal re-renders
+- ✅ **Built-in Validation** with Zod integration
+- 📋 **Array & Nested Fields** support
+- 🔍 **Form Context** for easy access to form state
+- 🎯 **Field-level** and **Form-level** validation
+- ⚡ **Optimized Performance** with smart re-rendering
+
+## Installation
+
+```bash
+npm install @explita/formly
+# or
+yarn add @explita/formly
+# or
+pnpm add @explita/formly
+```
+
+## Quick Start
+
+```tsx
+import { Form, Field, useForm, useField } from "@explita/formly";
+import { z } from "zod";
+
+// Define your form schema with Zod
+const userSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  email: z.string().email("Invalid email"),
+  contacts: z
+    .array(
+      z.object({
+        phone: z.string().min(1, "Phone is required"),
+        type: z.enum(["home", "work", "mobile"]),
+      })
+    )
+    .min(1, "At least one contact is required"),
+});
+
+function UserForm() {
+  const form = useForm({
+    defaultValues: {
+      name: "",
+      email: "",
+      contacts: [{ phone: "", type: "mobile" }],
+    },
+    // Optional: Uncomment to enable Zod validation
+    // schema: userSchema,
+    onSubmit: (data) => {
+      console.log("Form submitted:", data);
+    },
+  });
+
+  const contacts = form.array("contacts");
+
+  return (
+    <Form use={form}>
+      <Field name="name" label="Full Name" />
+      <Field name="email" type="email" label="Email" />
+
+      {/* Dynamic array fields */}
+      {contacts.value.map((contact, index) => (
+        <div key={index}>
+          <Field
+            name={`contacts.${index}.phone`}
+            label={`Phone ${index + 1}`}
+          />
+          <Field name={`contacts.${index}.type`} as="select" label="Type">
+            <option value="home">Home</option>
+            <option value="work">Work</option>
+            <option value="mobile">Mobile</option>
+          </Field>
+          <button type="button" onClick={() => contacts.remove(index)}>
+            Remove
+          </button>
+        </div>
+      ))}
+
+      <button
+        type="button"
+        onClick={() => contacts.push({ phone: "", type: "mobile" })}
+      >
+        Add Contact
+      </button>
+
+      <button type="submit">Submit</button>
+    </Form>
+  );
+}
+```
+
+## Core Concepts
+
+### `useForm` Hook
+
+The `useForm` hook is the heart of Formly. It manages the form state and provides methods to interact with the form.
+
+```tsx
+const form = useForm({
+  defaultValues: {
+    /* ... */
+  },
+  // Optional: Zod schema for validation
+  schema: userSchema,
+  // Optional: Custom validation function
+  check: (values) => {
+    const errors = {};
+    if (!values.name) errors.name = "Name is required";
+    return errors;
+  },
+  // Form submission handler
+  onSubmit: async (values, ctx) => {
+    console.log("Form values:", values);
+  },
+  // Persist form state
+  persistKey: "myFormState",
+});
+```
+
+### `Field` Component
+
+Render form inputs with automatic state management and validation.
+
+```tsx
+<Field
+  name="email"
+  label="Email Address"
+  placeholder="Enter your email"
+  required
+  render={(props, ctx) => <input {...props} type="email" />}
+/>
+```
+
+### `useField` Hook
+
+Access and modify a specific field's state and helpers.
+
+```tsx
+function EmailField() {
+  const { value, setValue, error, touched } = useField("email");
+
+  return (
+    <div>
+      <input
+        type="email"
+        value={value || ""}
+        onChange={(e) => setValue(e.target.value)}
+        className={touched && error ? "error" : ""}
+      />
+      {touched && error && <div className="error-message">{error}</div>}
+    </div>
+  );
+}
+```
+
+### Array Fields
+
+Easily manage dynamic arrays of fields.
+
+```tsx
+const todos = form.array("todos");
+
+// Add item
+todos.push({ text: "", completed: false });
+
+// Update item
+todos.update(0, { text: "Updated todo", completed: true });
+
+// Remove item
+todos.remove(0);
+
+// Move item
+todos.move(0, 1);
+```
+
+## Advanced Usage
+
+### Conditional Fields
+
+```tsx
+const showAddress = form.watch("hasAddress");
+
+return (
+  <>
+    <Field name="hasAddress" type="checkbox" label="Add address?" />
+
+    {showAddress && (
+      <div className="address-fields">
+        <Field name="address.street" label="Street" />
+        <Field name="address.city" label="City" />
+        <Field name="address.zip" label="ZIP Code" />
+      </div>
+    )}
+  </>
+);
+```
+
+## API Reference
+
+### `useForm` Options
+
+| Option             | Type                    | Description                               |
+| ------------------ | ----------------------- | ----------------------------------------- |
+| `defaultValues`    | `object`                | Initial form values                       |
+| `schema`           | `z.ZodSchema`           | Zod schema for validation                 |
+| `check`            | `(values) => object`    | Custom validation function                |
+| `onSubmit`         | `(values, ctx) => void` | Form submission handler                   |
+| `persistKey`       | `string`                | Key to persist form state in localStorage |
+| `autoFocusOnError` | `boolean`               | Auto-focus first invalid field            |
+
+### Form Methods
+
+| Method                       | Description                              |
+| ---------------------------- | ---------------------------------------- |
+| `submit()`                   | Submit the form programmatically         |
+| `reset(values?)`             | Reset form to initial or provided values |
+| `setValues(values)`          | Set multiple field values                |
+| `setFieldValue(path, value)` | Set a single field value                 |
+| `setErrors(errors)`          | Set form errors                          |
+| `setFieldError(path, error)` | Set error for a specific field           |
+| `validate()`                 | Trigger validation                       |
+| `watch(path?)`               | Watch form or specific field values      |
+| `array(path)`                | Get array field helpers                  |
+| `group(path)`                | Get nested form group helpers            |
+
+## TypeScript Support
+
+Formly is built with TypeScript and provides excellent type safety:
+
+```ts
+interface UserForm {
+  name: string;
+  email: string;
+  contacts: {
+    phone: string;
+    type: "home" | "work" | "mobile";
+  }[];
+}
+
+const form = useForm<UserForm>({
+  defaultValues: {
+    name: "",
+    email: "",
+    contacts: [],
+  },
+});
+```
+
+## License
+
+MIT © [Explita](https://github.com/explita)
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

package/README.old.md

@@ -0,0 +1,141 @@
+⚠️ 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)

package/dist/components/field-error.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare function FieldError(): React.JSX.Element | null;

package/dist/components/field-error.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldError = FieldError;
+const react_1 = __importDefault(require("react"));
+const __1 = require("../");
+function FieldError() {
+    const { message } = (0, __1.useFieldContext)();
+    if (!message)
+        return null;
+    return (react_1.default.createElement("p", { "data-error": "true", style: { color: "red", fontSize: "0.75rem" } }, message));
+}

package/dist/components/field.d.ts

@@ -0,0 +1,4 @@
+import { JSX } from "react";
+import { FieldContextType, FieldProps } from "../types/utils";
+export declare function useFieldContext(): FieldContextType;
+export declare function Field<T>({ name, id, label, as, required, hideError, className, children, render, ...rest }: FieldProps<T>): JSX.Element;

package/dist/components/field.js

@@ -0,0 +1,120 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFieldContext = useFieldContext;
+exports.Field = Field;
+const react_1 = __importStar(require("react"));
+const __1 = require("../");
+const FieldContext = (0, react_1.createContext)(null);
+function useFieldContext() {
+    const fieldContext = (0, react_1.use)(FieldContext);
+    if (!fieldContext) {
+        return {
+            name: "",
+            label: "",
+            id: "",
+            message: "",
+            required: false,
+            hasError: false,
+        };
+    }
+    return fieldContext;
+}
+function Field({ name, id, label, as, required, hideError = false, className, children, render, ...rest }) {
+    //@ts-ignore
+    const field = (0, __1.useField)(name, { ...rest });
+    // Pick whichever function/render prop is provided
+    const renderFn = children || render;
+    if (!renderFn)
+        return react_1.default.createElement(react_1.default.Fragment, null);
+    const bind = {
+        ...field.bind(),
+        id: id !== null && id !== void 0 ? id : field.refId,
+    };
+    const value = field.value;
+    const error = field.error;
+    const hasFieldError = error && (error === null || error === void 0 ? void 0 : error.length) > 0 ? true : false;
+    const hasError = !hideError && hasFieldError;
+    const setValue = field.setValue;
+    const isBoolean = as === "checkbox";
+    const fieldContextValue = {
+        name: name === null || name === void 0 ? void 0 : name.toString(),
+        label,
+        id: bind.id,
+        message: error,
+        required,
+        hasError,
+    };
+    const meta = {
+        internalRef: field.refId,
+        name,
+        value,
+        error,
+        hasError: hasFieldError !== null && hasFieldError !== void 0 ? hasFieldError : false,
+        onChange: field.setValue,
+    };
+    if (isBoolean) {
+        return (react_1.default.createElement(FieldContext, { value: fieldContextValue }, renderFn({
+            ...bind,
+            //@ts-ignore
+            checked: !!value,
+            onCheckedChange: (val) => {
+                setValue(val);
+            },
+        }, meta)));
+    }
+    if (as === "select" || as === "date") {
+        return (react_1.default.createElement(FieldContext, { value: fieldContextValue },
+            react_1.default.createElement("div", { "data-slot": "field", style: { display: "flex", flexDirection: "column", gap: "0.25rem" }, className: className },
+                react_1.default.createElement(__1.Label, null),
+                renderFn({
+                    ...bind,
+                    //@ts-ignore
+                    onValueChange: (val) => {
+                        setValue(val);
+                    },
+                    "data-input-error": hasError,
+                }, meta),
+                hasError && react_1.default.createElement(__1.FieldError, null))));
+    }
+    return (react_1.default.createElement(FieldContext, { value: fieldContextValue },
+        react_1.default.createElement("div", { "data-slot": "field", style: { display: "flex", flexDirection: "column", gap: "0.25rem" }, className: className },
+            react_1.default.createElement(__1.Label, null),
+            renderFn({
+                ...bind,
+                "data-input-error": hasError,
+            }, meta),
+            hasError && react_1.default.createElement(__1.FieldError, null))));
+}

package/dist/components/form-spy.d.ts

@@ -0,0 +1,16 @@
+import { JSX, ReactNode } from "react";
+import { FormContextValue } from "../providers/form";
+import { Path, PathValue } from "../types/path";
+export declare function FormSpy<DefaultValues extends Record<string, any>, P extends Path<DefaultValues>>({ form, watch, render, }: {
+    form: FormContextValue<undefined, DefaultValues>;
+    render: (selected: PathValue<DefaultValues, P>) => ReactNode;
+    watch: P;
+}): JSX.Element;
+export declare function FormSpy<DefaultValues extends Record<string, any>, P extends Path<DefaultValues>>({ form, render, }: {
+    form: FormContextValue<undefined, DefaultValues>;
+    render: (selected: DefaultValues) => ReactNode;
+}): JSX.Element;
+export declare function FormSpyDebug<DefaultValues extends Record<string, any>>({ form, watch, }: {
+    form: FormContextValue<undefined, DefaultValues>;
+    watch?: Path<DefaultValues>;
+}): JSX.Element;

package/dist/components/form-spy.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormSpy = FormSpy;
+exports.FormSpyDebug = FormSpyDebug;
+const react_1 = __importStar(require("react"));
+function FormSpy({ form, watch, render, }) {
+    const [selected, setSelected] = (0, react_1.useState)(() => watch ? form.field(watch).get() : form.values);
+    const prevRef = (0, react_1.useRef)(selected);
+    (0, react_1.useEffect)(() => {
+        const unsubscribe = form.subscribe((values) => {
+            const next = watch ? form.field(watch).get() : values;
+            if (JSON.stringify(prevRef.current) !== JSON.stringify(next)) {
+                prevRef.current = next;
+                setSelected(next);
+            }
+        });
+        return unsubscribe;
+    }, [form, watch]);
+    return react_1.default.createElement(react_1.default.Fragment, null, render(selected));
+}
+function FormSpyDebug({ form, watch, }) {
+    return (react_1.default.createElement(FormSpy, { form: form, 
+        //@ts-ignore
+        watch: watch, render: (v) => (react_1.default.createElement("pre", { style: {
+                whiteSpace: "pre-wrap", // allow wrapping
+                wordBreak: "break-word", // break long words
+                overflowWrap: "break-word", // extra safety
+                background: "#f5f5f5",
+                padding: "10px",
+                borderRadius: "4px",
+                width: "100%",
+            } }, JSON.stringify(v, null, 2))) }));
+}

package/dist/components/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./field";
+export * from "./field-error";
+export * from "./form-spy";
+export * from "./label";

package/dist/components/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./field"), exports);
+__exportStar(require("./field-error"), exports);
+__exportStar(require("./form-spy"), exports);
+__exportStar(require("./label"), exports);

package/dist/components/label.d.ts

@@ -0,0 +1,2 @@
+import * as React from "react";
+export declare function Label({ className, ...props }: React.ComponentProps<"label">): React.JSX.Element | undefined;