@beignet/react-hook-form 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/react-hook-form
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,286 @@
+# @beignet/react-hook-form
+
+> React Hook Form integration for Beignet
+
+This package provides automatic form validation using your contract's body schema. Works with any [Standard Schema](https://github.com/standard-schema/standard-schema) library (Zod, Valibot, ArkType, etc.).
+
+## Installation
+
+```bash
+npm install @beignet/react-hook-form @beignet/core react-hook-form @hookform/resolvers react
+```
+
+
+## TypeScript requirements
+
+This package requires TypeScript 5.0 or higher for proper type inference.
+
+## Usage
+
+### Basic form
+
+```tsx
+import { createReactHookForm } from "@beignet/react-hook-form";
+import { createTodo } from "@/features/todos/contracts";
+
+const rhf = createReactHookForm();
+
+function CreateTodoForm() {
+  const { useForm } = rhf(createTodo);
+  const form = useForm({
+    defaultValues: {
+      title: "",
+      completed: false,
+    },
+  });
+
+  const onSubmit = form.handleSubmit((values) => {
+    // values is typed as: { title: string; completed?: boolean }
+    console.log("Creating todo:", values);
+  });
+
+  return (
+    <form onSubmit={onSubmit}>
+      <input
+        {...form.register("title")}
+        placeholder="What needs to be done?"
+      />
+      {form.formState.errors.title && (
+        <p className="error">{form.formState.errors.title.message}</p>
+      )}
+
+      <label>
+        <input type="checkbox" {...form.register("completed")} />
+        Completed
+      </label>
+
+      <button type="submit" disabled={form.formState.isSubmitting}>
+        Create Todo
+      </button>
+    </form>
+  );
+}
+```
+
+### With React Query mutation
+
+```tsx
+import { createReactHookForm } from "@beignet/react-hook-form";
+import { useMutation } from "@tanstack/react-query";
+import { rq } from "@/client/rq";
+import { createTodo } from "@/features/todos/contracts";
+
+const rhf = createReactHookForm();
+
+function CreateTodoForm() {
+  const { useForm } = rhf(createTodo);
+  const form = useForm({
+    defaultValues: { title: "" },
+  });
+
+  const mutation = useMutation(
+    rq(createTodo).mutationOptions()
+  );
+
+  const onSubmit = form.handleSubmit((values) => {
+    mutation.mutate({ body: values });
+  });
+
+  return (
+    <form onSubmit={onSubmit}>
+      <input {...form.register("title")} placeholder="Title" />
+      {form.formState.errors.title && (
+        <p>{form.formState.errors.title.message}</p>
+      )}
+
+      <button type="submit" disabled={mutation.isPending}>
+        {mutation.isPending ? "Creating..." : "Create"}
+      </button>
+
+      {mutation.isError && (
+        <p className="error">{mutation.error.message}</p>
+      )}
+    </form>
+  );
+}
+```
+
+### Disabling validation
+
+If you need to disable the schema resolver (e.g., for partial form handling):
+
+```tsx
+const { useForm } = rhf(createTodo);
+const form = useForm({
+  resolverEnabled: false, // Disable schema validation
+  defaultValues: { title: "" },
+});
+```
+
+### Using contract config directly
+
+You can pass either a contract builder or its config:
+
+```tsx
+import { createReactHookForm } from "@beignet/react-hook-form";
+import { createTodo } from "@/features/todos/contracts";
+
+const rhf = createReactHookForm();
+
+// Using ContractBuilder directly
+const { useForm } = rhf(createTodo);
+
+// Or using the contract config
+const { useForm } = rhf(createTodo.config);
+```
+
+## API reference
+
+### `createReactHookForm()`
+
+Creates a React Hook Form adapter factory.
+
+```ts
+const rhf = createReactHookForm();
+```
+
+### `rhf(contract)`
+
+Creates a React Hook Form adapter for a contract.
+
+```ts
+const adapter = rhf(createTodo);
+```
+
+### `adapter.useForm(props?)`
+
+Returns a React Hook Form `useForm` result with the contract's body schema as resolver.
+
+```ts
+const form = adapter.useForm({
+  defaultValues?: { ... },
+  resolverEnabled?: boolean, // default: true
+  // ...other React Hook Form options
+});
+```
+
+## Type inference
+
+Form values are automatically typed based on the contract's body schema:
+
+```ts
+// Contract definition
+const createTodo = todos
+  .post("/api/todos")
+  .body(z.object({
+    title: z.string().min(1),
+    description: z.string().optional(),
+    completed: z.boolean().optional(),
+  }))
+  .responses({ 201: TodoSchema });
+
+// Form values are inferred
+const rhf = createReactHookForm();
+const form = rhf(createTodo).useForm();
+form.register("title");       // ✓ Valid
+form.register("description"); // ✓ Valid
+form.register("invalid");     // ✗ Type error
+```
+
+## Standard Schema support
+
+This package uses the `@hookform/resolvers/standard-schema` resolver, which works with any Standard Schema compatible library:
+
+- **Zod** - `z.object({ ... })`
+- **Valibot** - `v.object({ ... })`
+- **ArkType** - `type({ ... })`
+
+## Validation behavior
+
+The resolver validates:
+
+1. **On blur** - When a field loses focus
+2. **On change** - After first submission attempt
+3. **On submit** - Before calling your submit handler
+
+Validation errors are available via `form.formState.errors`:
+
+```tsx
+{form.formState.errors.title && (
+  <span className="error">
+    {form.formState.errors.title.message}
+  </span>
+)}
+```
+
+## Complete example
+
+```tsx
+import { createReactHookForm } from "@beignet/react-hook-form";
+import { useMutation } from "@tanstack/react-query";
+import { rq } from "@/client/rq";
+import { updateProfile } from "@/features/profile/contracts";
+
+const rhf = createReactHookForm();
+
+function ProfileForm({ profile }) {
+  const { useForm } = rhf(updateProfile);
+  const form = useForm({
+    defaultValues: {
+      name: profile.name,
+      email: profile.email,
+      bio: profile.bio ?? "",
+    },
+  });
+
+  const mutation = useMutation(
+    rq(updateProfile).mutationOptions({
+      onSuccess: () => {
+        toast.success("Profile updated!");
+      },
+    })
+  );
+
+  const onSubmit = form.handleSubmit((values) => {
+    mutation.mutate({ body: values });
+  });
+
+  const { errors, isDirty, isSubmitting } = form.formState;
+
+  return (
+    <form onSubmit={onSubmit}>
+      <div>
+        <label htmlFor="name">Name</label>
+        <input id="name" {...form.register("name")} />
+        {errors.name && <span className="error">{errors.name.message}</span>}
+      </div>
+
+      <div>
+        <label htmlFor="email">Email</label>
+        <input id="email" type="email" {...form.register("email")} />
+        {errors.email && <span className="error">{errors.email.message}</span>}
+      </div>
+
+      <div>
+        <label htmlFor="bio">Bio</label>
+        <textarea id="bio" {...form.register("bio")} />
+        {errors.bio && <span className="error">{errors.bio.message}</span>}
+      </div>
+
+      <button type="submit" disabled={!isDirty || isSubmitting}>
+        {isSubmitting ? "Saving..." : "Save Changes"}
+      </button>
+    </form>
+  );
+}
+```
+
+## Related packages
+
+- [`@beignet/core/contracts`](https://beignet.dev/contracts) - Core contract definitions
+- [`@beignet/react-query`](https://beignet.dev/react-query) - TanStack Query integration
+- [`@beignet/core/client`](https://beignet.dev/client) - HTTP client
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { type ContractLike, type HttpContractConfig, type InferOutput, type ResolveContract, type StandardSchemaV1 } from "@beignet/core/contracts";
+import { type FieldValues, type UseFormProps, type UseFormReturn } from "react-hook-form";
+/**
+ * Infer form values from contract body
+ */
+type InferBody<TContract extends HttpContractConfig> = TContract["body"] extends StandardSchemaV1 ? InferOutput<TContract["body"]> & FieldValues : FieldValues;
+type FormValues<TContract extends HttpContractConfig> = InferBody<TContract>;
+/**
+ * Options for React Hook Form with contract support
+ */
+type RhfFormOptions<TContract extends HttpContractConfig> = Omit<UseFormProps<FormValues<TContract>>, "resolver"> & {
+    /**
+     * Optional override for the resolver. If supplied, this is used instead of
+     * the default contract-based resolver.
+     */
+    resolver?: UseFormProps<FormValues<TContract>>["resolver"];
+    /**
+     * Enables or disables automatic resolver generation from the contract body schema.
+     * Defaults to true.
+     */
+    resolverEnabled?: boolean;
+};
+/**
+ * React Hook Form adapter for a contract
+ */
+export type ReactHookFormContractAdapter<TContract extends HttpContractConfig> = {
+    /**
+     * Generate UseFormProps<FormValues<TContract>> for any RHF usage.
+     */
+    formOptions: (props?: RhfFormOptions<TContract>) => UseFormProps<FormValues<TContract>>;
+    /**
+     * Convenience wrapper around useForm(formOptions(props)).
+     */
+    useForm: (props?: RhfFormOptions<TContract>) => UseFormReturn<FormValues<TContract>>;
+};
+/**
+ * Create a React Hook Form adapter factory.
+ *
+ * Mirrors the React integration pattern used by `createReactQuery()` and `createNuqs()`:
+ * create the adapter once, then bind individual contracts with `rhf(contract)`.
+ */
+export declare function createReactHookForm(): <TContractLike extends ContractLike>(contract: TContractLike) => ReactHookFormContractAdapter<ResolveContract<TContractLike>>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAEzB;;GAEG;AACH,KAAK,SAAS,CAAC,SAAS,SAAS,kBAAkB,IACjD,SAAS,CAAC,MAAM,CAAC,SAAS,gBAAgB,GACtC,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,WAAW,GAC5C,WAAW,CAAC;AAElB,KAAK,UAAU,CAAC,SAAS,SAAS,kBAAkB,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC;AAE7E;;GAEG;AACH,KAAK,cAAc,CAAC,SAAS,SAAS,kBAAkB,IAAI,IAAI,CAC9D,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EACnC,UAAU,CACX,GAAG;IACF;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAE3D;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,CAAC,SAAS,SAAS,kBAAkB,IAC3E;IACE;;OAEG;IACH,WAAW,EAAE,CACX,KAAK,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,KAC9B,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IAEzC;;OAEG;IACH,OAAO,EAAE,CACP,KAAK,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,KAC9B,aAAa,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;CAC3C,CAAC;AAqDJ;;;;;GAKG;AACH,wBAAgB,mBAAmB,KACb,aAAa,SAAS,YAAY,EACpD,UAAU,aAAa,KACtB,4BAA4B,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAGhE"}

package/dist/index.js

@@ -0,0 +1,40 @@
+import { resolveContract, } from "@beignet/core/contracts";
+import { standardSchemaResolver } from "@hookform/resolvers/standard-schema";
+import { useForm as rhfUseForm, } from "react-hook-form";
+function createReactHookFormAdapter(contract) {
+    const resolvedContract = resolveContract(contract);
+    if (!resolvedContract.body) {
+        throw new Error(`rhf(${resolvedContract.name}): Contract has no body schema. ` +
+            "React Hook Form requires a body schema to generate form fields and validation. " +
+            "Use .body(schema) on the contract builder to define the request body shape.");
+    }
+    function formOptions(props) {
+        const bodySchema = resolvedContract.body;
+        const { resolverEnabled = true, resolver: resolverOverride, ...rest } = props ?? {};
+        const resolver = resolverOverride ??
+            (bodySchema && resolverEnabled
+                ? standardSchemaResolver(bodySchema)
+                : undefined);
+        return {
+            ...rest,
+            resolver,
+        };
+    }
+    function useForm(props) {
+        const options = formOptions(props);
+        return rhfUseForm(options);
+    }
+    return { formOptions, useForm };
+}
+/**
+ * Create a React Hook Form adapter factory.
+ *
+ * Mirrors the React integration pattern used by `createReactQuery()` and `createNuqs()`:
+ * create the adapter once, then bind individual contracts with `rhf(contract)`.
+ */
+export function createReactHookForm() {
+    return function rhf(contract) {
+        return createReactHookFormAdapter(contract);
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,eAAe,GAEhB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAEL,OAAO,IAAI,UAAU,GAGtB,MAAM,iBAAiB,CAAC;AAoDzB,SAAS,0BAA0B,CACjC,QAAuB;IAEvB,MAAM,gBAAgB,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAEnD,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,OAAO,gBAAgB,CAAC,IAAI,kCAAkC;YAC5D,iFAAiF;YACjF,6EAA6E,CAChF,CAAC;IACJ,CAAC;IAID,SAAS,WAAW,CAClB,KAAsD;QAEtD,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAGvB,CAAC;QAEd,MAAM,EACJ,eAAe,GAAG,IAAI,EACtB,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,IAAI,EACR,GAAG,KAAK,IAAI,EAAE,CAAC;QAEhB,MAAM,QAAQ,GACZ,gBAAgB;YAChB,CAAC,UAAU,IAAI,eAAe;gBAC5B,CAAC,CAAC,sBAAsB,CAAC,UAAU,CAAC;gBACpC,CAAC,CAAC,SAAS,CAAC,CAAC;QAEjB,OAAO;YACL,GAAI,IAA6B;YACjC,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,SAAS,OAAO,CACd,KAAsD;QAEtD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACnC,OAAO,UAAU,CAAS,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,SAAS,GAAG,CACjB,QAAuB;QAEvB,OAAO,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@beignet/react-hook-form",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "React Hook Form integration for Beignet with Standard Schema support",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "contract",
+    "api",
+    "typescript",
+    "react-hook-form",
+    "standard-schema"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/react-hook-form"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@hookform/resolvers": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-hook-form": "^7.0.0"
+  },
+  "dependencies": {
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@hookform/resolvers": "^5.2.2",
+    "@testing-library/dom": "^9.3.4",
+    "@testing-library/react": "^14.3.1",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "@types/react": "^18.2.0",
+    "happy-dom": "^20.0.11",
+    "react": "^18.2.0",
+    "react-hook-form": "^7.48.0",
+    "typescript": "^5.3.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,130 @@
+import {
+  type ContractLike,
+  type HttpContractConfig,
+  type InferOutput,
+  type ResolveContract,
+  resolveContract,
+  type StandardSchemaV1,
+} from "@beignet/core/contracts";
+import { standardSchemaResolver } from "@hookform/resolvers/standard-schema";
+import {
+  type FieldValues,
+  useForm as rhfUseForm,
+  type UseFormProps,
+  type UseFormReturn,
+} from "react-hook-form";
+
+/**
+ * Infer form values from contract body
+ */
+type InferBody<TContract extends HttpContractConfig> =
+  TContract["body"] extends StandardSchemaV1
+    ? InferOutput<TContract["body"]> & FieldValues
+    : FieldValues;
+
+type FormValues<TContract extends HttpContractConfig> = InferBody<TContract>;
+
+/**
+ * Options for React Hook Form with contract support
+ */
+type RhfFormOptions<TContract extends HttpContractConfig> = Omit<
+  UseFormProps<FormValues<TContract>>,
+  "resolver"
+> & {
+  /**
+   * Optional override for the resolver. If supplied, this is used instead of
+   * the default contract-based resolver.
+   */
+  resolver?: UseFormProps<FormValues<TContract>>["resolver"];
+
+  /**
+   * Enables or disables automatic resolver generation from the contract body schema.
+   * Defaults to true.
+   */
+  resolverEnabled?: boolean;
+};
+
+/**
+ * React Hook Form adapter for a contract
+ */
+export type ReactHookFormContractAdapter<TContract extends HttpContractConfig> =
+  {
+    /**
+     * Generate UseFormProps<FormValues<TContract>> for any RHF usage.
+     */
+    formOptions: (
+      props?: RhfFormOptions<TContract>,
+    ) => UseFormProps<FormValues<TContract>>;
+
+    /**
+     * Convenience wrapper around useForm(formOptions(props)).
+     */
+    useForm: (
+      props?: RhfFormOptions<TContract>,
+    ) => UseFormReturn<FormValues<TContract>>;
+  };
+
+function createReactHookFormAdapter<TContractLike extends ContractLike>(
+  contract: TContractLike,
+): ReactHookFormContractAdapter<ResolveContract<TContractLike>> {
+  const resolvedContract = resolveContract(contract);
+
+  if (!resolvedContract.body) {
+    throw new Error(
+      `rhf(${resolvedContract.name}): Contract has no body schema. ` +
+        "React Hook Form requires a body schema to generate form fields and validation. " +
+        "Use .body(schema) on the contract builder to define the request body shape.",
+    );
+  }
+
+  type Values = FormValues<ResolveContract<TContractLike>>;
+
+  function formOptions(
+    props?: RhfFormOptions<ResolveContract<TContractLike>>,
+  ): UseFormProps<Values> {
+    const bodySchema = resolvedContract.body as
+      | StandardSchemaV1<FieldValues>
+      | null
+      | undefined;
+
+    const {
+      resolverEnabled = true,
+      resolver: resolverOverride,
+      ...rest
+    } = props ?? {};
+
+    const resolver =
+      resolverOverride ??
+      (bodySchema && resolverEnabled
+        ? standardSchemaResolver(bodySchema)
+        : undefined);
+
+    return {
+      ...(rest as UseFormProps<Values>),
+      resolver,
+    };
+  }
+
+  function useForm(
+    props?: RhfFormOptions<ResolveContract<TContractLike>>,
+  ): UseFormReturn<Values> {
+    const options = formOptions(props);
+    return rhfUseForm<Values>(options);
+  }
+
+  return { formOptions, useForm };
+}
+
+/**
+ * Create a React Hook Form adapter factory.
+ *
+ * Mirrors the React integration pattern used by `createReactQuery()` and `createNuqs()`:
+ * create the adapter once, then bind individual contracts with `rhf(contract)`.
+ */
+export function createReactHookForm() {
+  return function rhf<TContractLike extends ContractLike>(
+    contract: TContractLike,
+  ): ReactHookFormContractAdapter<ResolveContract<TContractLike>> {
+    return createReactHookFormAdapter(contract);
+  };
+}