chore: add docs & gh actions to automate publish

Author: mtayyabrawan

.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish
+
+on:
+    push:
+        branches: [main]
+        paths-ignore:
+            - "package.json"
+
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+                  token: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Install pnpm
+              uses: pnpm/action-setup@v4
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 24
+                  cache: "pnpm"
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile
+
+            - name: Build
+              run: pnpm run build
+
+            - name: Bump version and create tag
+              id: bump_version
+              run: |
+                  git config --global user.name "GitHub Actions"
+                  git config --global user.email "actions@github.com"
+
+                  # Automatically bumps the patch version (e.g., 1.0.0 -> 1.0.1)
+                  # Change 'patch' to 'minor' or 'major' depending on your needs
+                  pnpm version patch --no-git-tag-version
+
+                  # Read the newly bumped version
+                  NEW_VERSION=$(node -p "require('./package.json').version")
+                  echo "New version: $NEW_VERSION"
+
+                  # Commit and tag
+                  git add package.json
+                  git commit -m "chore(release): bump version to $NEW_VERSION [skip ci]"
+                  git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
+
+                  # Push changes securely
+                  git push origin HEAD:main --tags
+
+                  # Export for next steps
+                  echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+            - name: Publish to npm
+              run: |
+                  # Create npm registry auth configuration dynamically
+                  echo "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}" > .npmrc
+                  pnpm publish --no-git-checks
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.PNPM_TOKEN }}
+
+            - name: Create GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                  tag_name: "v${{ steps.bump_version.outputs.version }}"
+                  name: "Release v${{ steps.bump_version.outputs.version }}"
+                  body: |
+                      Automated release of **v${{ steps.bump_version.outputs.version }}** built from commit `${{ github.sha }}`.
+                  draft: false
+                  prerelease: false
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.nvmrc

@@ -0,0 +1 @@
+24.18.0

README.md

@@ -0,0 +1,152 @@
+# @mtayyabrawan/formhook
+
+A lightweight React hook for managing forms with built-in Zod validation. Simplify form state, validation, and submission handling in React and Next.js applications.
+
+## Features
+
+- **React Hook API**: `useForm<T>()` provides a simple interface for form state management.
+- **Zod Validation**: Integrates seamlessly with Zod schemas for type-safe validation.
+- **Type Safety**: Full TypeScript support with inferred types for form values and errors.
+- **Flexible API**: Supports field-level access via `formField`, error handling via `formErrors`, and easy reset functionality.
+- **Next.js Ready**: Works out of the box with Server Components and App Router.
+
+## Installation
+
+```bash
+npm install @mtayyabrawan/formhook
+# or
+yarn add @mtayyabrawan/formhook
+```
+
+## Peer Dependencies
+
+- React (^18 or ^19)
+- Zod (^3.25.0 or ^4)
+
+Make sure these are installed in your project.
+
+## Basic Usage
+
+```tsx
+import { useForm } from "@mtayyabrawan/formhook";
+import { z } from "zod";
+
+const schema = z.object({
+    name: z.string().min(3, "Name is required"),
+    email: z.string().email("Invalid email"),
+    age: z.number().int().min(18, "Must be 18+"),
+});
+
+export default function UserForm() {
+    const { reset, formField, formErrors, handleSubmit } = useForm({
+        initialData: { name: "", email: "", age: 0 },
+        validationSchema: schema,
+    });
+
+    const onSubmit = (data: { name: string; email: string; age: number }) => {
+        console.log("Form submitted:", data);
+    };
+
+    return (
+        <form onSubmit={handleSubmit(onSubmit)}>
+            <div>
+                <label>
+                    Name
+                    <input type="text" {...formField("name")} />
+                </label>
+                {formErrors.name && (
+                    <p className="text-red-500">{formErrors.name}</p>
+                )}
+            </div>
+
+            <div>
+                <label>
+                    Email
+                    <input type="email" {...formField("email")} />
+                </label>
+                {formErrors.email && (
+                    <p className="text-red-500">{formErrors.email}</p>
+                )}
+            </div>
+
+            <div>
+                <label>
+                    Age
+                    <input type="number" {...formField("age")} />
+                </label>
+                {formErrors.age && (
+                    <p className="text-red-500">{formErrors.age}</p>
+                )}
+            </div>
+
+            <button type="submit">Submit</button>
+            <button type="button" onClick={reset}>
+                Reset
+            </button>
+        </form>
+    );
+}
+```
+
+### Key API Elements
+
+- **`useForm<T>(props: UseFormProps<T>)`**: Returns an object with form state and methods.
+- **`formField<K extends keyof T>(fieldName: K)`**: Accessor for a specific field, returns `value`, `name`, and `onChange`.
+- **`formErrors: FormErrors<T>`**: Object containing validation errors keyed by field name.
+- **`reset()`**: Resets form to initial data and clears errors.
+- **`handleSubmit(callback: (data: T) => void)`**: Wraps submit handler to trigger validation and provide `event.preventDefault()`.
+
+### Using with Next.js App Router
+
+The hook works seamlessly with Next.js 13+ App Router. Since it's a client-side hook, wrap your form component in a `"use client"` directive:
+
+```tsx
+"use client";
+
+import { useForm } from "@mtayyabrawan/formhook";
+import { z } from "zod";
+
+const schema = z.object({
+    username: z.string().min(3),
+    password: z.string().min(8),
+});
+
+export default function LoginForm() {
+    const { formField, formErrors, handleSubmit } = useForm({
+        initialData: { username: "", password: "" },
+        validationSchema: schema,
+    });
+
+    const onSubmit = (data: { username: string; password: string }) => {
+        // Handle login logic
+    };
+
+    return (
+        <form onSubmit={handleSubmit(onSubmit)}>
+            <input {...formField("username")} />
+            {formErrors.username && <p>{formErrors.username}</p>}
+
+            <input type="password" {...formField("password")} />
+            {formErrors.password && <p>{formErrors.password}</p>}
+
+            <button type="submit">Login</button>
+        </form>
+    );
+}
+```
+
+## FAQ
+
+**Q: Is the hook compatible with React 19?**
+A: Yes, it supports React 18 and 19.
+
+**Q: How do I reset the form programmatically?**
+A: Call the `reset` method returned by `useForm`.
+
+## License
+
+MIT © [Muhammad Tayyab](https://linkedin.com/in/mtayyabrawan)
+
+---
+
+_Happy form building!_ 🚀