@paragrav/rhf-utils 0.0.113 → 0.0.115

package/README.md

@@ -33,13 +33,13 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   // optional (defaults to primitive HTML form)
   FormComponent: Form.Root,
 
-  // transform backend error
-  // use `getOnSubmitTrpcClientErrorHandler` HOF for TRPC backends
-  onSubmitError: (
+  // non-FormSubmitError throw in onSubmit
+  // use case: transform backend error
+  onSubmitUnknownError: (
     error, // unknown
   ) => {
     // if other error, re-throw to handle in ErrorBoundary
-    if (!(error instanceof ServerError)) throw error;
+    if (!(error instanceof MyServerError)) throw error;
 
     // return to be merged into RHF context errors
     return transformServerErrorToFormSubmitErrors(error);
@@ -75,7 +75,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
     output: {
       // callback to determine when to output form context errors to console ("debug" or "error")
       console: ({ isDevelopment, hasOrphans }) =>
-        (hasOrphans && { type: 'error' }) || // report orphan errors early
+        (hasOrphans && { type: 'error' }) || // report all orphan errors
         (isDevelopment && { type: 'debug' }), // facilitate debugging on dev
 
       // callback to determine when to throw an error based on context
@@ -97,7 +97,7 @@ And add the context provider to your stack:
 
 Currently, only `zod` is supported.
 
-## Usage
+## Form
 
 ```tsx
 <RhfUtilsZodForm
@@ -106,14 +106,18 @@ Currently, only `zod` is supported.
     email: '',
   }}
   // submit handler
-  onSubmit={async (data) => {
+  onSubmit={async (
+    data, //    schema output
+    context, // UseRhfUtilsFormOnSubmitContext (form id, form ref, context (rhf), utils options, strongly-typed FormSubmitError class)
+    event, //   SubmitEvent
+  ) => {
     await authLoginService(data);
     onSuccess();
   }}
   // handle error declaratively (i.e., no throw/catch)
   onSubmitError={({
     error, //   unknown
-    context, // rhf UseFormReturn
+    context, // UseRhfUtilsFormOnSubmitErrorContext (form id, form ref, context (rhf), utils options)
     event, //   SubmitEvent
   }) => {
     onError(error);
@@ -155,6 +159,32 @@ const Children: RhfUtilsUseFormChildrenZodFC<typeof schema> = ({ ... }) => { };
 function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
 ```
 
+## `FormSubmitError`
+
+This is a derived `Error` class you can use to throw a structured error in your submit handler. It is strongly-typed, so it only allows field names in schema and `root`/`root.{string}` keys.
+
+It uses `FormSubmitErrors` shape, which is a flat (dot notation) equivalent of RHF's `FieldErrors`.
+
+Example:
+
+```tsx
+<RhfUtilsZodForm
+  onSubmit={({ FormSubmitError }) => {
+    if (isProblem())
+      throw new FormSubmitError({
+        root: { message: 'There was a problem with the form.' },
+        'street.address': { message: 'Street address invalid.' },
+      });
+
+    await post('/backend');
+  }}
+/>
+```
+
+Any non-`FormSubmitError`s thrown from submit handler (e.g., fetch/axios error) can be transformed by `RhfUtilsClientConfig`'s `onSubmitUnknownError` callback. This takes an `unknown` error and can return a `FormSubmitErrors` object, which is merged in RHF's context errors.
+
+Most common use case will be transforming backend errors to frontend shape. (You can use `getOnSubmitTrpcClientErrorHandler` HOF for TRPC backends.)
+
 ## `RhfUtilsFormOptions`
 
 These options can be set globally and/or per form.

package/dist/esm/errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs

@@ -0,0 +1,6 @@
+import { TRPCClientError as o } from "@trpc/client";
+import { trpcClientErrorToFormSubmitErrorsSchemaTransformer as n } from "./trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs";
+const m = (t) => (r) => r instanceof o ? n.parse(r) : t(r);
+export {
+  m as getOnSubmitTrpcClientErrorHandler
+};

package/dist/esm/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs

@@ -0,0 +1,34 @@
+import { TRPCClientError as o } from "@trpc/client";
+import { z as e } from "zod";
+import { trpcClientErrorMessageSchema as a } from "./trpcClientErrorMessageSchema.mjs";
+const i = e.custom(
+  (r) => r instanceof o
+  // check instance type
+).transform((r) => r.message).transform((r) => {
+  try {
+    return JSON.parse(r);
+  } catch {
+    return [
+      {
+        validation: "root",
+        code: "server",
+        message: r,
+        path: ["root"]
+      }
+    ];
+  }
+}).pipe(e.array(a)).transform(
+  (r) => r.map(
+    (t) => [
+      t.path.join("."),
+      // flatten path (e.g., "street.name")
+      {
+        type: t.code,
+        message: t.message
+      }
+    ]
+  )
+).transform((r) => Object.fromEntries(r));
+export {
+  i as trpcClientErrorToFormSubmitErrorsSchemaTransformer
+};

package/dist/esm/form/Form.mjs

@@ -0,0 +1,102 @@
+import { jsxs as T, jsx as l } from "react/jsx-runtime";
+import "react";
+import { useFormContext as _ } from "react-hook-form";
+import D from "../client/config/useRhfUtilsClientConfigContext.mjs";
+import N from "../devtool/LazyDevTool.mjs";
+import { FormSubmitError as C } from "../submit/error/FormSubmitError.mjs";
+import P from "../submit/error/setCtxErrorsByFormSubmitErrors.mjs";
+import S from "./_Controller.mjs";
+import w from "./_FormBase.mjs";
+function A({
+  formId: s,
+  formRef: p,
+  //
+  onSubmit: c,
+  onSubmitError: d,
+  onSubmitInvalid: v,
+  Children: x,
+  //
+  form: m,
+  utils: o,
+  //
+  children: b
+}) {
+  const n = _(), t = D(), F = async (e) => {
+    o != null && o.stopSubmitPropagation && e.stopPropagation();
+    try {
+      await n.handleSubmit(j, v)(e);
+    } catch (r) {
+      B(r, e);
+    }
+  }, j = (e, r) => c == null ? void 0 : c(
+    e,
+    {
+      formId: s,
+      formRef: p,
+      context: n,
+      utils: o,
+      FormSubmitError: C
+    },
+    r
+  ), B = (e, r) => {
+    var y;
+    const a = e instanceof C ? (
+      // consumer can manually throw FormSubmitError (e.g., manual validation)
+      e.errors
+    ) : (
+      // if error is not FormSubmitError, consumer can provide global handler
+      (y = t == null ? void 0 : t.onSubmitUnknownError) == null ? void 0 : y.call(t, e)
+    );
+    a && P(n, a), d == null || d(
+      e,
+      {
+        formId: s,
+        formRef: p,
+        context: n,
+        utils: o
+      },
+      r
+    );
+  }, h = {
+    formId: s,
+    formRef: p,
+    context: n,
+    utils: o,
+    Controller: S,
+    FormSubmitError: C
+  }, i = (e) => {
+    var a;
+    const r = (a = t == null ? void 0 : t.Children) == null ? void 0 : a[e];
+    return r && /* @__PURE__ */ l(r, { ...h });
+  };
+  return /* @__PURE__ */ T(
+    w,
+    {
+      noValidate: !0,
+      style: {
+        position: "relative"
+      },
+      config: t,
+      formRef: p,
+      ...m,
+      className: [o == null ? void 0 : o.classNames, m == null ? void 0 : m.className].filter(Boolean).join(" "),
+      onSubmit: F,
+      children: [
+        i("top"),
+        (o == null ? void 0 : o.devTool) && /* @__PURE__ */ l(
+          N,
+          {
+            isDevelopment: t == null ? void 0 : t.isDevelopment,
+            props: typeof o.devTool == "object" ? o.devTool : void 0
+          }
+        ),
+        x && /* @__PURE__ */ l(x, { ...h }),
+        b,
+        i("bottom")
+      ]
+    }
+  );
+}
+export {
+  A as default
+};

package/dist/types/client/config/RhfUtilsClientConfig.d.ts

@@ -39,18 +39,16 @@ export type RhfUtilsClientConfig = {
      */
     FormComponent?: React.FC<React.PropsWithChildren<React.HTMLAttributes<HTMLFormElement>>>;
     /**
-     * Global submit error handler.
-     *
-     * Called when/if submit handler throws an error other than {@link FormSubmitError}.
+     * Global submit error handler when/if submit handler throws an error other than {@link FormSubmitError}.
      *
      * Example use case:
      * - transform API errors to {@link FormSubmitErrors}.
      *
      * @returns
-     * - {@link FormSubmitErrors}: merge into context errors.
-     * - `undefined`: do nothing.
+     * - if {@link FormSubmitErrors}: merge into context errors.
+     * - if `undefined`: do nothing.
      */
-    onSubmitError?: (error: unknown) => FormSubmitErrors | undefined;
+    onSubmitUnknownError?: (error: unknown) => FormSubmitErrors | undefined;
     /**
      * Components injected by slot across all forms.
      * (Per-form injection can be done via `Children` prop.)

package/dist/types/errors/trpc/getOnSubmitTrpcClientErrorHandler.d.ts

@@ -2,9 +2,9 @@ import { RhfUtilsClientConfig } from '../../client/config/RhfUtilsClientConfig';
 import { FormSubmitErrors } from '../../submit/error/FormSubmitErrors';
 
 /**
- * HOF that returns submit error handler for {@link RhfUtilsClientConfig.onSubmitError}.
+ * HOF that returns submit error handler for {@link RhfUtilsClientConfig.onSubmitUnknownError}.
  *
  * @param onError Fallback for handling non-TRPC errors.
  * @returns FormSubmitError
  */
-export declare const getOnSubmitTrpcClientErrorHandler: (onNotTrpcClientError: NonNullable<RhfUtilsClientConfig['onSubmitError']>) => (error: unknown) => FormSubmitErrors | undefined;
+export declare const getOnSubmitTrpcClientErrorHandler: (onNotTrpcClientError: NonNullable<RhfUtilsClientConfig['onSubmitUnknownError']>) => (error: unknown) => FormSubmitErrors | undefined;

package/dist/types/form/UseRhfUtilsFormChildrenProps.d.ts

@@ -8,7 +8,7 @@ import { SafeFieldValues } from './SafeFieldValues';
 /**
  * Component props for `Children`.
  *
- * Consider keeping shape in line with `UseRhfUtilsFormReturn`.
+ * Consider keeping shape in line with `UseRhfUtilsFormOnSubmitProps` and `UseRhfUtilsFormReturn`.
  */
 export type UseRhfUtilsFormChildrenProps<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = SafeFieldValues> = {
     formId: string;

package/dist/types/form/UseRhfUtilsFormOnSubmitContext.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+import { UseFormReturn } from 'react-hook-form';
+import { FormSubmitError } from '../submit/error/FormSubmitError';
+import { RhfUtilsFormOptions } from './RhfUtilsFormOptions';
+import { SafeFieldValues } from './SafeFieldValues';
+
+/**
+ * Props for onSubmit other than `data` and `event`.
+ *
+ * Consider keeping shape in line with `UseRhfUtilsFormChildrenProps` and `UseRhfUtilsFormReturn`.
+ */
+export type UseRhfUtilsFormOnSubmitContext<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = SafeFieldValues> = {
+    formId: string;
+    formRef: React.RefObject<HTMLFormElement>;
+    context: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
+    utils?: RhfUtilsFormOptions;
+    FormSubmitError: typeof FormSubmitError<TFieldValues>;
+};
+/**
+ * Props for onSubmitError other than `error` and `event`.
+ */
+export type UseRhfUtilsFormOnSubmitErrorContext<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = SafeFieldValues> = {
+    formId: string;
+    formRef: React.RefObject<HTMLFormElement>;
+    context: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
+    utils?: RhfUtilsFormOptions;
+};

package/dist/types/form/UseRhfUtilsFormProps.d.ts

@@ -1,13 +1,14 @@
 import { default as React } from 'react';
-import { SubmitErrorHandler, UseFormProps, UseFormReturn } from 'react-hook-form';
+import { SubmitErrorHandler, UseFormProps } from 'react-hook-form';
 import { RhfUtilsFormOptions } from './RhfUtilsFormOptions';
 import { SafeFieldValues } from './SafeFieldValues';
 import { UseRhfUtilsFormChildrenProps } from './UseRhfUtilsFormChildrenProps';
+import { UseRhfUtilsFormOnSubmitContext, UseRhfUtilsFormOnSubmitErrorContext } from './UseRhfUtilsFormOnSubmitContext';
 
 export type UseRhfUtilsFormProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = {
-    onSubmit?: (values: TTransformedValues, context: UseFormReturn<TFieldValues, unknown, TTransformedValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => unknown | Promise<unknown>;
+    onSubmit?: (values: TTransformedValues, context: UseRhfUtilsFormOnSubmitContext<TFieldValues, TTransformedValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => unknown | Promise<unknown>;
     /** Submit error handler. (Only for errors not of instance `FormError`, which are handled internally.) */
-    onSubmitError?: (error: unknown, context: UseFormReturn<TFieldValues, unknown, TTransformedValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => void;
+    onSubmitError?: (error: unknown, context: UseRhfUtilsFormOnSubmitErrorContext<TFieldValues, TTransformedValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => void;
     /** Submit handler when form is invalid. */
     onSubmitInvalid?: SubmitErrorHandler<TFieldValues>;
     defaultValues?: UseFormProps<TFieldValues>['defaultValues'];

package/dist/types/form/UseRhfUtilsFormReturn.d.ts

@@ -8,7 +8,7 @@ import { SafeFieldValues } from './SafeFieldValues';
 /**
  * Return type for `useRhfUtilsForm`.
  *
- * Consider keeping shape in line with `UseRhfUtilsFormChildrenProps`.
+ * Consider keeping shape in line with `UseRhfUtilsFormChildrenProps` and `UseRhfUtilsFormOnSubmitProps`.
  */
 export type UseRhfUtilsFormReturn<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = {
     id: string;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@paragrav/rhf-utils",
   "author": "paragrav.dev",
   "license": "MIT",
-  "version": "0.0.113",
+  "version": "0.0.115",
   "description": "Integration utilities for react-hook-form.",
   "type": "module",
   "sideEffects": false,
@@ -22,16 +22,14 @@
   "peerDependencies": {
     "@hookform/devtools": "4",
     "@hookform/resolvers": "3",
+    "@trpc/client": "next",
+    "@trpc/server": "next",
     "flat": "6",
     "react": "18",
     "react-dom": "18",
     "react-hook-form": "7",
     "zod": "3"
   },
-  "optionalDependencies": {
-    "@trpc/client": "next",
-    "@trpc/server": "next"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/paragrav/rhf-utils.git"

package/dist/esm/src/errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs

@@ -1,7 +0,0 @@
-import { TRPCClientError as o } from "../../../node_modules/.pnpm/@trpc_client@11.0.0-rc.390_@trpc_server@11.0.0-rc.390/node_modules/@trpc/client/dist/TRPCClientError.mjs";
-import "../../../node_modules/.pnpm/@trpc_server@11.0.0-rc.390/node_modules/@trpc/server/dist/unstable-core-do-not-import/rootConfig.mjs";
-import { trpcClientErrorToFormSubmitErrorsSchemaTransformer as n } from "./trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs";
-const p = (t) => (r) => r instanceof o ? n.parse(r) : t(r);
-export {
-  p as getOnSubmitTrpcClientErrorHandler
-};

package/dist/esm/src/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs

@@ -1,35 +0,0 @@
-import { TRPCClientError as e } from "../../../node_modules/.pnpm/@trpc_client@11.0.0-rc.390_@trpc_server@11.0.0-rc.390/node_modules/@trpc/client/dist/TRPCClientError.mjs";
-import "../../../node_modules/.pnpm/@trpc_server@11.0.0-rc.390/node_modules/@trpc/server/dist/unstable-core-do-not-import/rootConfig.mjs";
-import { z as o } from "zod";
-import { trpcClientErrorMessageSchema as m } from "./trpcClientErrorMessageSchema.mjs";
-const p = o.custom(
-  (r) => r instanceof e
-  // check instance type
-).transform((r) => r.message).transform((r) => {
-  try {
-    return JSON.parse(r);
-  } catch {
-    return [
-      {
-        validation: "root",
-        code: "server",
-        message: r,
-        path: ["root"]
-      }
-    ];
-  }
-}).pipe(o.array(m)).transform(
-  (r) => r.map(
-    (t) => [
-      t.path.join("."),
-      // flatten path (e.g., "street.name")
-      {
-        type: t.code,
-        message: t.message
-      }
-    ]
-  )
-).transform((r) => Object.fromEntries(r));
-export {
-  p as trpcClientErrorToFormSubmitErrorsSchemaTransformer
-};

package/dist/esm/src/form/Form.mjs

@@ -1,91 +0,0 @@
-import { jsxs as B, jsx as d } from "react/jsx-runtime";
-import "react";
-import { useFormContext as T } from "react-hook-form";
-import _ from "../client/config/useRhfUtilsClientConfigContext.mjs";
-import D from "../devtool/LazyDevTool.mjs";
-import { FormSubmitError as x } from "../submit/error/FormSubmitError.mjs";
-import N from "../submit/error/setCtxErrorsByFormSubmitErrors.mjs";
-import P from "./_Controller.mjs";
-import S from "./_FormBase.mjs";
-function A({
-  formId: y,
-  formRef: c,
-  //
-  onSubmit: p,
-  onSubmitError: s,
-  onSubmitInvalid: f,
-  Children: l,
-  //
-  form: m,
-  utils: o,
-  //
-  children: v
-}) {
-  const a = T(), t = _(), b = async (e) => {
-    o != null && o.stopSubmitPropagation && e.stopPropagation();
-    try {
-      await a.handleSubmit(F, f)(e);
-    } catch (r) {
-      j(r, e);
-    }
-  }, F = (e, r) => p == null ? void 0 : p(
-    e,
-    a,
-    r
-  ), j = (e, r) => {
-    var h;
-    const n = e instanceof x ? (
-      // consumer can manually throw FormSubmitError (e.g., manual validation)
-      e.errors
-    ) : (
-      // if error is not FormSubmitError, consumer can provide global handler
-      (h = t == null ? void 0 : t.onSubmitError) == null ? void 0 : h.call(t, e)
-    );
-    n && N(a, n), s == null || s(
-      e,
-      a,
-      r
-    );
-  }, i = {
-    formId: y,
-    formRef: c,
-    context: a,
-    utils: o,
-    Controller: P,
-    FormSubmitError: x
-  }, C = (e) => {
-    var n;
-    const r = (n = t == null ? void 0 : t.Children) == null ? void 0 : n[e];
-    return r && /* @__PURE__ */ d(r, { ...i });
-  };
-  return /* @__PURE__ */ B(
-    S,
-    {
-      noValidate: !0,
-      style: {
-        position: "relative"
-      },
-      config: t,
-      formRef: c,
-      ...m,
-      className: [o == null ? void 0 : o.classNames, m == null ? void 0 : m.className].filter(Boolean).join(" "),
-      onSubmit: b,
-      children: [
-        C("top"),
-        (o == null ? void 0 : o.devTool) && /* @__PURE__ */ d(
-          D,
-          {
-            isDevelopment: t == null ? void 0 : t.isDevelopment,
-            props: typeof o.devTool == "object" ? o.devTool : void 0
-          }
-        ),
-        l && /* @__PURE__ */ d(l, { ...i }),
-        v,
-        C("bottom")
-      ]
-    }
-  );
-}
-export {
-  A as default
-};