@beignet/react-hook-form 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @beignet/react-hook-form
 
+## 0.0.5
+
+## 0.0.4
+
+### Patch Changes
+
+- 8bcb31f: Mark package READMEs with Beignet's experimental alpha status and 0.0.x stability expectations.
+- c1a834d: Generate an app-owned client error helper and align form error handling docs with
+  the canonical React Query and React Hook Form mutation path.
+- d137044: Declare `@beignet/core` as a peer dependency with a lockstep version range in
+  every integration and provider package instead of a regular `"*"` dependency.
+  Installs now always resolve a single shared copy of core, so `instanceof`
+  checks such as `isContractError` and upload error identity keep working, and
+  mixed Beignet versions fail loudly at install time instead of at runtime.
+
+  If your package manager does not install peer dependencies automatically, add
+  `@beignet/core` to your app alongside these packages. `@beignet/nuqs` now also
+  declares `@beignet/react-query` as a peer dependency, and
+  `@beignet/provider-storage-s3` now expects you to install
+  `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` yourself, matching
+  how other providers treat their SDKs.
+
+- 1a79090: Emit Node-compatible ESM: all relative imports in published packages now carry explicit .js extensions, fixing ERR_MODULE_NOT_FOUND when running the CLI or importing package dist files under plain Node.
+- 9d1bf0b: Clarify React Hook Form submit-error handling and align generated form examples with Beignet client error semantics.
+- 89390fe: Type form values with the contract body schema's input/output split. Live field
+  values (`register`, `watch`, `setValue`, `getValues`, `defaultValues`) now use
+  the schema input, and `handleSubmit` callbacks receive the parsed schema
+  output, so coercing, transforming, and defaulting body schemas type correctly
+  end to end.
+- d6ad8bb: Standardize generated client helpers around `client/index.ts`, add a typed
+  React Query invalidation helper, and align package docs with the canonical app
+  client entrypoint.
+- 8063d38: Rename the contract front door to `defineContract`/`defineContractGroup`, rename operational commands to tasks (`@beignet/core/tasks`, `defineTasks`, `runTask`, `beignet task run`, `beignet make task`, `server/tasks.ts`, `features/<feature>/tasks/`, `paths.tasks`), and standardize context binding: context-free declarations stay top-level (`defineEvent`), while context-bound definitions come from per-capability factories (`createListeners`, `createJobs`, `createSchedules`, `createNotifications`, `createTasks`) called once in `lib/`. Top-level context-generic `defineListener`, `defineJob`, `defineSchedule`, and `defineNotification` are removed.
+- 192c6ad: Typed clients now attach idempotency keys automatically from contract metadata (override with `idempotencyKey`), React Query mutations keep the key stable across retry attempts, and the shared client error helpers `contractErrorMessage` and `rootFormError` are now exported by @beignet/core/client and @beignet/react-hook-form.
+
 ## 0.0.3
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,10 @@
 
 > React Hook Form integration for Beignet
 
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
 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
@@ -10,7 +14,6 @@ This package provides automatic form validation using your contract's body schem
 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.
@@ -35,7 +38,7 @@ function CreateTodoForm() {
   });
 
   const onSubmit = form.handleSubmit((values) => {
-    // values is typed as: { title: string; completed?: boolean }
+    // values is the parsed schema output: { title: string; completed?: boolean }
     console.log("Creating todo:", values);
   });
 
@@ -65,9 +68,9 @@ function CreateTodoForm() {
 ### With React Query mutation
 
 ```tsx
-import { createReactHookForm } from "@beignet/react-hook-form";
+import { createReactHookForm, rootFormError } from "@beignet/react-hook-form";
 import { useMutation } from "@tanstack/react-query";
-import { rq } from "@/client/rq";
+import { rq } from "@/client";
 import { createTodo } from "@/features/todos/contracts";
 
 const rhf = createReactHookForm();
@@ -79,10 +82,16 @@ function CreateTodoForm() {
   });
 
   const mutation = useMutation(
-    rq(createTodo).mutationOptions()
+    rq(createTodo).mutationOptions({
+      onSuccess: () => form.reset(),
+      onError: (error) => {
+        form.setError("root", rootFormError(error, "Could not create the todo."));
+      },
+    }),
   );
 
   const onSubmit = form.handleSubmit((values) => {
+    form.clearErrors("root");
     mutation.mutate({ body: values });
   });
 
@@ -92,19 +101,25 @@ function CreateTodoForm() {
       {form.formState.errors.title && (
         <p>{form.formState.errors.title.message}</p>
       )}
+      {form.formState.errors.root && (
+        <p>{form.formState.errors.root.message}</p>
+      )}
 
       <button type="submit" disabled={mutation.isPending}>
         {mutation.isPending ? "Creating..." : "Create"}
       </button>
-
-      {mutation.isError && (
-        <p className="error">{mutation.error.message}</p>
-      )}
     </form>
   );
 }
 ```
 
+React Hook Form only owns request body fields. Pass path params, query params,
+headers, and auth-derived values to the endpoint call or mutation variables.
+Submit failures come back as Beignet client errors, so map route-owned catalog
+errors, framework validation errors, network failures, and contract drift
+through `rootFormError(...)`, then set `form.setError("root", ...)` or a
+specific field when your server response identifies one.
+
 ### Disabling validation
 
 If you need to disable the schema resolver (e.g., for partial form handling):
@@ -164,9 +179,33 @@ const form = adapter.useForm({
 });
 ```
 
+### `rootFormError(error, fallback, overrides?)`
+
+Maps a failed endpoint call or mutation error to the
+`form.setError("root", ...)` shape. Wraps `contractErrorMessage` from
+`@beignet/core/client`: non-contract errors return the fallback copy,
+client-side input validation failures return a generic "check the highlighted
+fields" message, and catalog codes can override copy per form.
+
+```ts
+form.setError(
+  "root",
+  rootFormError(error, "Could not update profile.", {
+    HANDLE_UNAVAILABLE: "That handle is already taken.",
+  }),
+);
+```
+
 ## Type inference
 
-Form values are automatically typed based on the contract's body schema:
+Form types come from the contract's body schema and follow React Hook Form's
+input/output split:
+
+- Live field values — `register`, `watch`, `setValue`, `getValues`, and
+  `defaultValues` — use the schema **input**: what the user edits before
+  validation runs.
+- `handleSubmit` callbacks receive the schema **output**: the parsed values
+  after coercion, transforms, and defaults run.
 
 ```ts
 // Contract definition
@@ -187,6 +226,45 @@ form.register("description"); // ✓ Valid
 form.register("invalid");     // ✗ Type error
 ```
 
+For plain schemas like the one above, input and output are identical. For
+coercing or transforming schemas they differ:
+
+```ts
+const createPayment = payments
+  .post("/api/payments")
+  .body(z.object({
+    amount: z.string().transform(Number),
+    note: z.string().optional(),
+  }))
+  .responses({ 201: PaymentSchema });
+
+const form = rhf(createPayment).useForm({
+  defaultValues: { amount: "" }, // input: string
+});
+
+form.watch("amount"); // string (input)
+
+form.handleSubmit((values) => {
+  values.amount; // number (output)
+});
+```
+
+### Submitting transforming schemas
+
+The typed client posts the schema input — the server validates and transforms
+the body when it receives the request. Parsed output from `handleSubmit` is
+still valid input for plain, defaulted, and coerced schemas, so
+`mutation.mutate({ body: values })` keeps working for those. When a transform
+changes a field's type, the parsed output no longer matches the contract body
+and TypeScript rejects it. Send the raw field values instead — validation has
+already passed by the time the submit handler runs:
+
+```tsx
+const onSubmit = form.handleSubmit(() => {
+  mutation.mutate({ body: form.getValues() });
+});
+```
+
 ## Standard Schema support
 
 This package uses the `@hookform/resolvers/standard-schema` resolver, which works with any Standard Schema compatible library:
@@ -197,11 +275,11 @@ This package uses the `@hookform/resolvers/standard-schema` resolver, which work
 
 ## 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
+React Hook Form controls when the generated resolver runs. With the default
+React Hook Form settings, the resolver validates before submit and then
+revalidates changed fields after a failed submit. Pass normal React Hook Form
+options such as `mode: "onBlur"` or `reValidateMode: "onChange"` when a form
+needs different timing.
 
 Validation errors are available via `form.formState.errors`:
 
@@ -218,7 +296,8 @@ Validation errors are available via `form.formState.errors`:
 ```tsx
 import { createReactHookForm } from "@beignet/react-hook-form";
 import { useMutation } from "@tanstack/react-query";
-import { rq } from "@/client/rq";
+import { rq } from "@/client";
+import { rootFormError } from "@/client/errors";
 import { updateProfile } from "@/features/profile/contracts";
 
 const rhf = createReactHookForm();
@@ -238,10 +317,14 @@ function ProfileForm({ profile }) {
       onSuccess: () => {
         toast.success("Profile updated!");
       },
+      onError: (error) => {
+        form.setError("root", rootFormError(error, "Could not update the profile."));
+      },
     })
   );
 
   const onSubmit = form.handleSubmit((values) => {
+    form.clearErrors("root");
     mutation.mutate({ body: values });
   });
 
@@ -270,6 +353,8 @@ function ProfileForm({ profile }) {
       <button type="submit" disabled={!isDirty || isSubmitting}>
         {isSubmitting ? "Saving..." : "Save Changes"}
       </button>
+
+      {errors.root && <span className="error">{errors.root.message}</span>}
     </form>
   );
 }
@@ -277,9 +362,9 @@ function ProfileForm({ profile }) {
 
 ## 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
+- [`@beignet/core/contracts`](https://beignetjs.com/contracts) - Core contract definitions
+- [`@beignet/react-query`](https://beignetjs.com/react-query) - TanStack Query integration
+- [`@beignet/core/client`](https://beignetjs.com/client) - HTTP client
 
 ## License
 

package/dist/index.d.ts

@@ -1,19 +1,34 @@
-import { type ContractLike, type HttpContractConfig, type InferOutput, type ResolveContract, type StandardSchemaV1 } from "@beignet/core/contracts";
+import { type ErrorMessageOverrides } from "@beignet/core/client";
+import { type ContractLike, type HttpContractConfig, type InferInput, type InferOutput, type ResolveContract, type StandardSchemaV1 } from "@beignet/core/contracts";
 import { type FieldValues, type UseFormProps, type UseFormReturn } from "react-hook-form";
 /**
- * Infer React Hook Form values from a contract body schema.
+ * Constrain a schema input type to React Hook Form field values without
+ * widening field name inference for object inputs.
  */
-type InferBody<TContract extends HttpContractConfig> = TContract["body"] extends StandardSchemaV1 ? InferOutput<TContract["body"]> & FieldValues : FieldValues;
-type FormValues<TContract extends HttpContractConfig> = InferBody<TContract>;
+type AsFieldValues<T> = T extends FieldValues ? T : T & FieldValues;
+/**
+ * Live form field values inferred from the contract body schema input.
+ *
+ * React Hook Form field values (`register`, `watch`, `setValue`,
+ * `defaultValues`) hold pre-validation input, so coercing or transforming body
+ * schemas type fields as what the user edits, not what the schema produces.
+ */
+type FormInput<TContract extends HttpContractConfig> = TContract["body"] extends StandardSchemaV1 ? AsFieldValues<InferInput<TContract["body"]>> : FieldValues;
+/**
+ * Validated submit values inferred from the contract body schema output.
+ *
+ * `handleSubmit` callbacks receive the resolver-parsed output.
+ */
+type FormOutput<TContract extends HttpContractConfig> = TContract["body"] extends StandardSchemaV1 ? InferOutput<TContract["body"]> : FieldValues;
 /**
  * React Hook Form options accepted by the Beignet adapter.
  */
-type RhfFormOptions<TContract extends HttpContractConfig> = Omit<UseFormProps<FormValues<TContract>>, "resolver"> & {
+type RhfFormOptions<TContract extends HttpContractConfig> = Omit<UseFormProps<FormInput<TContract>, unknown, FormOutput<TContract>>, "resolver"> & {
     /**
      * Optional override for the resolver. If supplied, this is used instead of
      * the default contract-based resolver.
      */
-    resolver?: UseFormProps<FormValues<TContract>>["resolver"];
+    resolver?: UseFormProps<FormInput<TContract>, unknown, FormOutput<TContract>>["resolver"];
     /**
      * Enables or disables automatic resolver generation from the contract body schema.
      * Defaults to true.
@@ -27,11 +42,11 @@ export type ReactHookFormContractAdapter<TContract extends HttpContractConfig> =
     /**
      * Generate `UseFormProps` for any React Hook Form usage.
      */
-    formOptions: (props?: RhfFormOptions<TContract>) => UseFormProps<FormValues<TContract>>;
+    formOptions: (props?: RhfFormOptions<TContract>) => UseFormProps<FormInput<TContract>, unknown, FormOutput<TContract>>;
     /**
      * Convenience wrapper around `useForm(formOptions(props))`.
      */
-    useForm: (props?: RhfFormOptions<TContract>) => UseFormReturn<FormValues<TContract>>;
+    useForm: (props?: RhfFormOptions<TContract>) => UseFormReturn<FormInput<TContract>, unknown, FormOutput<TContract>>;
 };
 /**
  * Create a React Hook Form adapter factory.
@@ -42,5 +57,28 @@ export type ReactHookFormContractAdapter<TContract extends HttpContractConfig> =
  * disable the generated resolver through `formOptions(...)` or `useForm(...)`.
  */
 export declare function createReactHookForm(): <TContractLike extends ContractLike>(contract: TContractLike) => ReactHookFormContractAdapter<ResolveContract<TContractLike>>;
+/**
+ * Root-level form error for `form.setError("root", ...)`.
+ */
+export type RootFormError = {
+    type: "server";
+    message: string;
+};
+/**
+ * Map a failed endpoint call or mutation error to a root-level form error.
+ *
+ * Wraps `contractErrorMessage` from `@beignet/core/client`, so non-contract
+ * errors get the fallback copy and catalog codes can be overridden per form:
+ *
+ * ```ts
+ * form.setError(
+ *   "root",
+ *   rootFormError(error, "Could not update profile.", {
+ *     HANDLE_UNAVAILABLE: "That handle is already taken.",
+ *   }),
+ * );
+ * ```
+ */
+export declare function rootFormError(error: unknown, fallback: string, overrides?: ErrorMessageOverrides): RootFormError;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,KACb,aAAa,SAAS,YAAY,EACpD,UAAU,aAAa,KACtB,4BAA4B,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAGhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,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;;;GAGG;AACH,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;AAEpE;;;;;;GAMG;AACH,KAAK,SAAS,CAAC,SAAS,SAAS,kBAAkB,IACjD,SAAS,CAAC,MAAM,CAAC,SAAS,gBAAgB,GACtC,aAAa,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,GAC5C,WAAW,CAAC;AAElB;;;;GAIG;AACH,KAAK,UAAU,CAAC,SAAS,SAAS,kBAAkB,IAClD,SAAS,CAAC,MAAM,CAAC,SAAS,gBAAgB,GACtC,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAC9B,WAAW,CAAC;AAElB;;GAEG;AACH,KAAK,cAAc,CAAC,SAAS,SAAS,kBAAkB,IAAI,IAAI,CAC9D,YAAY,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,EAClE,UAAU,CACX,GAAG;IACF;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CACrB,SAAS,CAAC,SAAS,CAAC,EACpB,OAAO,EACP,UAAU,CAAC,SAAS,CAAC,CACtB,CAAC,UAAU,CAAC,CAAC;IAEd;;;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,SAAS,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IAExE;;OAEG;IACH,OAAO,EAAE,CACP,KAAK,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,KAC9B,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;CAC1E,CAAC;AAsDJ;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,KACb,aAAa,SAAS,YAAY,EACpD,UAAU,aAAa,KACtB,4BAA4B,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAGhE;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,qBAAqB,GAChC,aAAa,CAKf"}

package/dist/index.js

@@ -1,3 +1,4 @@
+import { contractErrorMessage, } from "@beignet/core/client";
 import { resolveContract, } from "@beignet/core/contracts";
 import { standardSchemaResolver } from "@hookform/resolvers/standard-schema";
 import { useForm as rhfUseForm, } from "react-hook-form";
@@ -39,4 +40,25 @@ export function createReactHookForm() {
         return createReactHookFormAdapter(contract);
     };
 }
+/**
+ * Map a failed endpoint call or mutation error to a root-level form error.
+ *
+ * Wraps `contractErrorMessage` from `@beignet/core/client`, so non-contract
+ * errors get the fallback copy and catalog codes can be overridden per form:
+ *
+ * ```ts
+ * form.setError(
+ *   "root",
+ *   rootFormError(error, "Could not update profile.", {
+ *     HANDLE_UNAVAILABLE: "That handle is already taken.",
+ *   }),
+ * );
+ * ```
+ */
+export function rootFormError(error, fallback, overrides) {
+    return {
+        type: "server",
+        message: contractErrorMessage(error, fallback, overrides),
+    };
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,SAAS,GAAG,CACjB,QAAuB;QAEvB,OAAO,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAErB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAML,eAAe,GAEhB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAEL,OAAO,IAAI,UAAU,GAGtB,MAAM,iBAAiB,CAAC;AA0EzB,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;IAKD,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,CAAyB,UAAU,CAAC;gBAC5D,CAAC,CAAC,SAAS,CAAC,CAAC;QAEjB,OAAO;YACL,GAAI,IAA6C;YACjD,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,SAAS,OAAO,CACd,KAAsD;QAEtD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACnC,OAAO,UAAU,CAAyB,OAAO,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,SAAS,GAAG,CACjB,QAAuB;QAEvB,OAAO,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC,CAAC;AACJ,CAAC;AAUD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAc,EACd,QAAgB,EAChB,SAAiC;IAEjC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC;KAC1D,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/react-hook-form",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "React Hook Form integration for Beignet with Standard Schema support",
   "main": "./dist/index.js",
@@ -24,8 +24,9 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "clean": "rm -rf dist coverage .turbo",
-    "test": "bun test",
+    "test": "bun test && bun run typecheck:types",
     "test:coverage": "bun test --coverage",
+    "typecheck:types": "tsc -p tsconfig.type-tests.json",
     "lint": "biome check ."
   },
   "keywords": [
@@ -52,13 +53,11 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
+    "@beignet/core": ">=0.0.3 <1.0.0",
     "@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",

package/src/index.ts

@@ -1,6 +1,11 @@
+import {
+  contractErrorMessage,
+  type ErrorMessageOverrides,
+} from "@beignet/core/client";
 import {
   type ContractLike,
   type HttpContractConfig,
+  type InferInput,
   type InferOutput,
   type ResolveContract,
   resolveContract,
@@ -15,27 +20,49 @@ import {
 } from "react-hook-form";
 
 /**
- * Infer React Hook Form values from a contract body schema.
+ * Constrain a schema input type to React Hook Form field values without
+ * widening field name inference for object inputs.
+ */
+type AsFieldValues<T> = T extends FieldValues ? T : T & FieldValues;
+
+/**
+ * Live form field values inferred from the contract body schema input.
+ *
+ * React Hook Form field values (`register`, `watch`, `setValue`,
+ * `defaultValues`) hold pre-validation input, so coercing or transforming body
+ * schemas type fields as what the user edits, not what the schema produces.
  */
-type InferBody<TContract extends HttpContractConfig> =
+type FormInput<TContract extends HttpContractConfig> =
   TContract["body"] extends StandardSchemaV1
-    ? InferOutput<TContract["body"]> & FieldValues
+    ? AsFieldValues<InferInput<TContract["body"]>>
     : FieldValues;
 
-type FormValues<TContract extends HttpContractConfig> = InferBody<TContract>;
+/**
+ * Validated submit values inferred from the contract body schema output.
+ *
+ * `handleSubmit` callbacks receive the resolver-parsed output.
+ */
+type FormOutput<TContract extends HttpContractConfig> =
+  TContract["body"] extends StandardSchemaV1
+    ? InferOutput<TContract["body"]>
+    : FieldValues;
 
 /**
  * React Hook Form options accepted by the Beignet adapter.
  */
 type RhfFormOptions<TContract extends HttpContractConfig> = Omit<
-  UseFormProps<FormValues<TContract>>,
+  UseFormProps<FormInput<TContract>, unknown, FormOutput<TContract>>,
   "resolver"
 > & {
   /**
    * Optional override for the resolver. If supplied, this is used instead of
    * the default contract-based resolver.
    */
-  resolver?: UseFormProps<FormValues<TContract>>["resolver"];
+  resolver?: UseFormProps<
+    FormInput<TContract>,
+    unknown,
+    FormOutput<TContract>
+  >["resolver"];
 
   /**
    * Enables or disables automatic resolver generation from the contract body schema.
@@ -54,14 +81,14 @@ export type ReactHookFormContractAdapter<TContract extends HttpContractConfig> =
      */
     formOptions: (
       props?: RhfFormOptions<TContract>,
-    ) => UseFormProps<FormValues<TContract>>;
+    ) => UseFormProps<FormInput<TContract>, unknown, FormOutput<TContract>>;
 
     /**
      * Convenience wrapper around `useForm(formOptions(props))`.
      */
     useForm: (
       props?: RhfFormOptions<TContract>,
-    ) => UseFormReturn<FormValues<TContract>>;
+    ) => UseFormReturn<FormInput<TContract>, unknown, FormOutput<TContract>>;
   };
 
 function createReactHookFormAdapter<TContractLike extends ContractLike>(
@@ -77,13 +104,14 @@ function createReactHookFormAdapter<TContractLike extends ContractLike>(
     );
   }
 
-  type Values = FormValues<ResolveContract<TContractLike>>;
+  type Input = FormInput<ResolveContract<TContractLike>>;
+  type Output = FormOutput<ResolveContract<TContractLike>>;
 
   function formOptions(
     props?: RhfFormOptions<ResolveContract<TContractLike>>,
-  ): UseFormProps<Values> {
+  ): UseFormProps<Input, unknown, Output> {
     const bodySchema = resolvedContract.body as
-      | StandardSchemaV1<FieldValues>
+      | StandardSchemaV1<Input, Output>
       | null
       | undefined;
 
@@ -96,20 +124,20 @@ function createReactHookFormAdapter<TContractLike extends ContractLike>(
     const resolver =
       resolverOverride ??
       (bodySchema && resolverEnabled
-        ? standardSchemaResolver(bodySchema)
+        ? standardSchemaResolver<Input, unknown, Output>(bodySchema)
         : undefined);
 
     return {
-      ...(rest as UseFormProps<Values>),
+      ...(rest as UseFormProps<Input, unknown, Output>),
       resolver,
     };
   }
 
   function useForm(
     props?: RhfFormOptions<ResolveContract<TContractLike>>,
-  ): UseFormReturn<Values> {
+  ): UseFormReturn<Input, unknown, Output> {
     const options = formOptions(props);
-    return rhfUseForm<Values>(options);
+    return rhfUseForm<Input, unknown, Output>(options);
   }
 
   return { formOptions, useForm };
@@ -130,3 +158,37 @@ export function createReactHookForm() {
     return createReactHookFormAdapter(contract);
   };
 }
+
+/**
+ * Root-level form error for `form.setError("root", ...)`.
+ */
+export type RootFormError = {
+  type: "server";
+  message: string;
+};
+
+/**
+ * Map a failed endpoint call or mutation error to a root-level form error.
+ *
+ * Wraps `contractErrorMessage` from `@beignet/core/client`, so non-contract
+ * errors get the fallback copy and catalog codes can be overridden per form:
+ *
+ * ```ts
+ * form.setError(
+ *   "root",
+ *   rootFormError(error, "Could not update profile.", {
+ *     HANDLE_UNAVAILABLE: "That handle is already taken.",
+ *   }),
+ * );
+ * ```
+ */
+export function rootFormError(
+  error: unknown,
+  fallback: string,
+  overrides?: ErrorMessageOverrides,
+): RootFormError {
+  return {
+    type: "server",
+    message: contractErrorMessage(error, fallback, overrides),
+  };
+}