@paragrav/rhf-utils 0.0.118 → 0.0.120

package/README.md

@@ -1,5 +1,9 @@
 # README
 
+## About
+
+Integration and utility library for react-hook-form.
+
 ## Install
 
 ```sh
@@ -14,25 +18,32 @@ To configure, create a file `config.tsx` with desired configuration settings. Th
 
 ```tsx
 export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
-  // defaults -- overridable per form instance
+  // overridable per form instance
   defaults: {
-    // globally relevant subset of RHF's `UseFormProps` options
+    // globally-relevant subset of RHF's `UseFormProps` options
     rhf: {
-      mode: 'onBlur',
+      mode: 'onSubmit',
     },
 
     // RhfUtilsFormOptions (see further below)
     utils: {
-      // enable dev tool on dev env
+      stopSubmitPropagation: true,
       devTool: import.meta.env.DEV,
     },
+
+    // default form props
+    form: {
+      noValidate: true,
+      className: 'my-form-class',
+    },
   },
 
   // optional (defaults to primitive HTML form)
   FormComponent: Form.Root,
 
   // optional wrapper to inject your own hooks and components
-  // `children` prop is provided by RhfUtilsZodForm's Children prop
+  // around all RhfUtilsZodForm instances
+  // (see further below for more info)
   FormChildren: (
     // UseRhfUtilsFormChildrenProps
     {
@@ -42,32 +53,32 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
       options, //         RhfUtilsFormOptions
       Controller, //      strictly-typed controller
       FormSubmitError, // strictly-typed error class
-      children, //        RhfUtilsZodForm.Children
+      children, //        RhfUtilsZodForm's Children instance
     },
   ) => {
-    // navigation blocker (using custom option)
-    useFormRouterBlocker(!!options?.prompter);
+    // your navigation blocker (using custom option prop -- see "Extend RhfUtilsFormOptions" section)
+    useMyFormNavigationPrompt(!!options?.enableMyFormNavigationPrompt);
 
     return (
       <>
-        {/* specific form children -- e.g., fields, etc. */}
+        {/* RhfUtilsZodForm Children outlet */}
         {children}
 
-        {/* global error list */}
-        <RootErrorsListFromFlatFieldErrorsContext />
+        {/* root errors list */}
+        <RootErrorsList />
       </>
     );
   },
 
-  // non-FormSubmitError throw in onSubmit
-  // example use case: transform backend error
+  // non-FormSubmitError thrown in onSubmit
+  // use case: catch backend error and transform data for frontend
   onSubmitUnknownError: (
     error, // unknown
   ) => {
     // if other error, re-throw to handle in ErrorBoundary
     if (!(error instanceof MyServerError)) throw error;
 
-    // return FormSubmitErrors object to be merged into RHF context errors
+    // return FormSubmitErrors object to be merged to RHF context errors
     return transformServerErrorToFormSubmitErrors(error);
   },
 
@@ -101,26 +112,26 @@ Currently, only `zod` is supported.
 
 ```tsx
 <RhfUtilsZodForm
-  schema={authLoginFormSchema}
+  schema={loginFormSchema}
   defaultValues={{
     email: '',
   }}
   // submit handler
   onSubmit={async (
     data, //    schema output
-    context, // UseRhfUtilsFormOnSubmitContext (form id, form ref, context (rhf), utils options, strictly-typed FormSubmitError class)
+    context, // UseRhfUtilsFormOnSubmitContext (id, ref, rhf context, utils options, strictly-typed FormSubmitError class)
     event, //   SubmitEvent
   ) => {
     await authLoginService(data);
-    onSuccess();
+    props.onSuccess();
   }}
   // handle error declaratively (i.e., no throw/catch)
   onSubmitError={({
     error, //   unknown
-    context, // UseRhfUtilsFormOnSubmitErrorContext (form id, form ref, context (rhf), utils options)
+    context, // UseRhfUtilsFormOnSubmitErrorContext (id, ref, rhf context, utils options)
     event, //   SubmitEvent
   }) => {
-    onError(error);
+    props.onError(error);
   }}
   // fields
   Children={({
@@ -146,6 +157,19 @@ Currently, only `zod` is supported.
       <button type="submit">Login</button>
     </>
   )}
+  // options/overrides
+  rhf={{
+    mode: 'onBlur',
+  }}
+  utils={{
+    submitOnChange: true,
+    resetValuesOnSubmitError: true,
+    enableMyFormNavigationPrompt: true, // custom option prop (see "Extend RhfUtilsFormOptions" section)
+  }}
+  form={{
+    // class names are merged together with global defaults
+    className: 'my-special-form-class',
+  }}
 />
 ```
 
@@ -169,7 +193,7 @@ Example:
 
 ```tsx
 <RhfUtilsZodForm
-  onSubmit={({ FormSubmitError }) => {
+  onSubmit={async ({ FormSubmitError }) => {
     if (isProblem())
       throw new FormSubmitError({
         root: { message: 'There was a problem with the form.' },
@@ -183,7 +207,7 @@ Example:
 
 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.)
+Most common use case will be transforming backend errors to frontend shape. (You can use `getOnSubmitTrpcClientErrorHandler` HOF provided by this library for TRPC backends.)
 
 ## `RhfUtilsFormOptions`
 
@@ -191,11 +215,6 @@ These options can be set globally and/or per form.
 
 ```ts
 type RhfUtilsFormOptions = {
-  /**
-   * Style via your own classes.
-   */
-  classNames?: string[];
-
   /** Request submit via listener on form change. */
   submitOnChange?: boolean;
 
@@ -208,10 +227,7 @@ type RhfUtilsFormOptions = {
   /** Reset form after successful submit. */
   resetFormAfterSubmitSuccessful?: UseResetFormAfterSubmitSuccessfulOptions;
 
-  /**
-   * Control dev tool options.
-   * (Lazy-loaded when truthy value supplied.)
-   */
+  /** Control dev tool options. (Lazy-loaded when truthy value supplied.) */
   devTool?: true | Pick<DevtoolUIProps, 'placement' | 'styles'>;
 };
 ```
@@ -231,7 +247,7 @@ declare module '@paragrav/rhf-utils' {
   export interface Register {
     RhfUtilsFormOptions: {
       /** Enable user prompt to confirm navigating away from dirty form. */
-      prompter?: boolean;
+      enableMyFormNavigationPrompt?: boolean;
     };
   }
 }
@@ -241,6 +257,8 @@ declare module '@paragrav/rhf-utils' {
 
 You can configure via `RhfUtilsClientConfig` (example at the top) when form context errors are outputted -- i.e., via console and/or thrown error.
 
+Use `useFlatFieldErrorsContext()` hook, which returns an object with errors grouped by `all`, `fields`, `root`, and `orphans`.
+
 ### Orphans
 
 The concept of orphan errors is any error that is not being shown to user. An example would be a stray field in a schema that is prohibiting users from successfully submitting a form.

package/dist/esm/client/index.mjs

@@ -1,50 +1,52 @@
-import { jsx as h } from "react/jsx-runtime";
-import f from "../form/FormWithProviders.mjs";
-import d from "../form/useRhfUtilsForm.mjs";
-const R = (e) => (r) => {
-  const m = F(e, r);
+import { jsx as u } from "react/jsx-runtime";
+import a from "../form/FormWithProviders.mjs";
+import F from "../form/useRhfUtilsForm.mjs";
+const v = (e) => (r) => {
+  const m = d(e, r);
   return {
-    useForm: (o, s) => {
-      const t = m(o, s);
+    useForm: (s, t) => {
+      const o = m(s, t);
       return {
-        ...d(t),
-        FormWithProviders: () => /* @__PURE__ */ h(f, { ...t })
+        ...F(o),
+        FormWithProviders: () => /* @__PURE__ */ u(a, { ...o })
       };
     },
-    FormWithProviders: a(e, r)
+    FormWithProviders: P(e, r)
   };
-}, F = (e, r) => function(o, s) {
-  var t, i, l, n, u;
+}, d = (e, r) => function(s, t) {
+  var o, i, f, l, n, h;
   return {
-    ...s,
+    ...t,
+    // merge global config with instance options...
     rhf: {
-      ...(t = r.defaults) == null ? void 0 : t.rhf,
-      ...s.rhf,
-      resolver: e(o)
+      resolver: e(s),
+      ...(o = r.defaults) == null ? void 0 : o.rhf,
+      ...t.rhf
     },
     utils: {
       ...(i = r.defaults) == null ? void 0 : i.utils,
-      ...s.utils,
-      classNames: [
-        ...((n = (l = r.defaults) == null ? void 0 : l.utils) == null ? void 0 : n.classNames) ?? [],
-        ...((u = s.utils) == null ? void 0 : u.classNames) ?? []
-      ]
+      ...t.utils
+    },
+    form: {
+      ...(f = r.defaults) == null ? void 0 : f.form,
+      ...t.form,
+      className: [(n = (l = r.defaults) == null ? void 0 : l.form) == null ? void 0 : n.className, (h = t.form) == null ? void 0 : h.className].filter(Boolean).join(" ")
     }
   };
-}, a = (e, r) => function({
-  schema: o,
-  children: s,
-  ...t
+}, P = (e, r) => function({
+  schema: s,
+  children: t,
+  ...o
 }) {
-  const i = F(e, r);
-  return /* @__PURE__ */ h(
-    f,
+  const i = d(e, r);
+  return /* @__PURE__ */ u(
+    a,
     {
-      ...i(o, t),
-      children: s
+      ...i(s, o),
+      children: t
     }
   );
 };
 export {
-  R as createRhfUtilsClient
+  v as createRhfUtilsClient
 };

package/dist/esm/form/Form.mjs

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

package/dist/esm/form/useRhfUtilsForm.mjs

@@ -2,10 +2,10 @@ import s from "react";
 import { useForm as d } from "react-hook-form";
 import { FormSubmitError as F } from "../submit/error/FormSubmitError.mjs";
 const v = ({
-  onSubmit: e,
-  onSubmitError: f,
-  onSubmitInvalid: p,
-  defaultValues: n,
+  defaultValues: e,
+  onSubmit: f,
+  onSubmitError: p,
+  onSubmitInvalid: n,
   Children: c,
   rhf: i,
   form: u,
@@ -13,7 +13,7 @@ const v = ({
 }) => {
   const r = s.useId(), m = d({
     ...i,
-    defaultValues: n
+    defaultValues: e
   }), o = s.useRef(null);
   return {
     id: r,
@@ -27,9 +27,9 @@ const v = ({
     },
     formProps: {
       Children: c,
-      onSubmit: e,
-      onSubmitError: f,
-      onSubmitInvalid: p,
+      onSubmit: f,
+      onSubmitError: p,
+      onSubmitInvalid: n,
       formId: r,
       formRef: o,
       form: u,

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

@@ -27,6 +27,10 @@ export type RhfUtilsClientConfig = {
          * (Extend this type via `Register` type to inject custom options/functionality via `Children` component.)
          */
         utils?: RhfUtilsFormOptions;
+        /**
+         * Default props for form element.
+         */
+        form?: Omit<React.PropsWithoutRef<JSX.IntrinsicElements['form']>, 'onSubmit'>;
     };
     /**
      * Supply your own `<form>` component.

package/dist/types/client/index.d.ts

@@ -14,7 +14,7 @@ export type ObjectSchema<TInputKey extends string, TOutputKey extends string> =
     [key in TOutputKey]: SafeFieldValues;
 };
 export type CreateRhfUtilsClient<TObjectSchema extends ObjectSchema<TObjectSchemaInputKey, TObjectSchemaOutputKey>, TObjectSchemaInputKey extends string, TObjectSchemaOutputKey extends string> = {
-    useForm: <TSchema extends TObjectSchema, TSchemaInput extends SafeFieldValues = TSchema[TObjectSchemaInputKey], TSchemaOutput extends SafeFieldValues = TSchema[TObjectSchemaOutputKey], UseRhfUtilsFormPropsForm extends UseRhfUtilsFormProps<TSchemaInput, TSchemaOutput> = UseRhfUtilsFormProps<TSchemaInput, TSchemaOutput>>(schema: TSchema, form: Omit<UseRhfUtilsFormPropsForm, 'config'>) => UseRhfUtilsFormReturn<TSchemaInput, TSchemaOutput> & {
+    useForm: <TSchema extends TObjectSchema, TSchemaInput extends SafeFieldValues = TSchema[TObjectSchemaInputKey], TSchemaOutput extends SafeFieldValues = TSchema[TObjectSchemaOutputKey], UseRhfUtilsFormPropsForm extends UseRhfUtilsFormProps<TSchemaInput, TSchemaOutput> = UseRhfUtilsFormProps<TSchemaInput, TSchemaOutput>>(schema: TSchema, form: UseRhfUtilsFormPropsForm) => UseRhfUtilsFormReturn<TSchemaInput, TSchemaOutput> & {
         FormWithProviders: React.FC<React.PropsWithChildren>;
     };
     FormWithProviders: <TSchema extends TObjectSchema, TSchemaInput extends SafeFieldValues = TSchema[TObjectSchemaInputKey], TSchemaOutput extends SafeFieldValues = TSchema[TObjectSchemaOutputKey]>(props: {

package/dist/types/client/zod/context/RhfUtilsZodForm.d.ts

@@ -4,6 +4,6 @@ import { ZodTypeFieldValues } from '../ZodTypeFieldValues';
 
 type Props<TSchema extends ZodTypeFieldValues> = {
     schema: TSchema;
-} & Omit<UseRhfUtilsFormProps<TSchema[typeof zodTypeInput], TSchema[typeof zodTypeOutput]>, 'config'>;
+} & UseRhfUtilsFormProps<TSchema[typeof zodTypeInput], TSchema[typeof zodTypeOutput]>;
 declare function RhfUtilsZodForm<TSchema extends ZodTypeFieldValues>({ schema, ...props }: Props<TSchema>): import("react/jsx-runtime").JSX.Element;
 export default RhfUtilsZodForm;

package/dist/types/client/zod/context/useRhfUtilsZodForm.d.ts

@@ -2,7 +2,7 @@ import { UseRhfUtilsFormProps } from '../../../form/UseRhfUtilsFormProps';
 import { zodTypeInput, zodTypeOutput } from '../consts';
 import { ZodTypeFieldValues } from '../ZodTypeFieldValues';
 
-declare const useRhfUtilsZodForm: <TSchema extends ZodTypeFieldValues>(schema: TSchema, form: Omit<UseRhfUtilsFormProps<TSchema[typeof zodTypeInput], TSchema[typeof zodTypeOutput]>, 'config'>) => import('../../../form/UseRhfUtilsFormReturn').UseRhfUtilsFormReturn<TSchema["_input"], TSchema["_output"]> & {
+declare const useRhfUtilsZodForm: <TSchema extends ZodTypeFieldValues>(schema: TSchema, form: UseRhfUtilsFormProps<TSchema[typeof zodTypeInput], TSchema[typeof zodTypeOutput]>) => import('../../../form/UseRhfUtilsFormReturn').UseRhfUtilsFormReturn<TSchema["_input"], TSchema["_output"]> & {
     FormWithProviders: import('react').FC<{
         children?: import('react').ReactNode;
     }>;

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

@@ -8,11 +8,6 @@ import { Register } from '../register';
  * Can be extended using {@link Register.RhfUtilsFormOptions}.
  */
 export type RhfUtilsFormOptions = {
-    /**
-     * Style via your own classes.
-     * (Defaults merged with individual class names.)
-     */
-    classNames?: string[];
     /** Request submit via listener on form change. */
     submitOnChange?: boolean;
     /** Reset form values if submit throw errors. (Use case: optimistic UI toggle form that submits on each change.) */

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

@@ -6,17 +6,17 @@ import { UseRhfUtilsFormChildrenProps } from './UseRhfUtilsFormChildrenProps';
 import { UseRhfUtilsFormOnSubmitContext, UseRhfUtilsFormOnSubmitErrorContext } from './UseRhfUtilsFormOnSubmitContext';
 
 export type UseRhfUtilsFormProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = {
+    defaultValues?: UseFormProps<TFieldValues>['defaultValues'];
     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: UseRhfUtilsFormOnSubmitErrorContext<TFieldValues, TTransformedValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => void;
     /** Submit handler when form is invalid. */
     onSubmitInvalid?: SubmitErrorHandler<TFieldValues>;
-    defaultValues?: UseFormProps<TFieldValues>['defaultValues'];
-    Children?: React.FC<UseRhfUtilsFormChildrenProps<TFieldValues, TTransformedValues>>;
+    Children: React.FC<UseRhfUtilsFormChildrenProps<TFieldValues, TTransformedValues>>;
     /** {@link RhfUseFormProps} props for RHF's {@link useForm}. */
     rhf?: Omit<UseFormProps<TFieldValues>, 'defaultValues'>;
-    /** {@link FormProps} props for Form. */
-    form?: React.PropsWithoutRef<JSX.IntrinsicElements['form']>;
     /** {@link RhfUtilsFormOptions} to enabled utils functionality. */
     utils?: RhfUtilsFormOptions;
+    /** {@link FormProps} props for Form. */
+    form?: Omit<React.PropsWithoutRef<JSX.IntrinsicElements['form']>, 'onSubmit'>;
 };

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

@@ -11,6 +11,6 @@ import { UseRhfUtilsFormReturn } from './UseRhfUtilsFormReturn';
  * see https://caniuse.com/?search=form%20attribute
  * @returns Form provider and form.
  */
-declare const useRhfUtilsForm: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ onSubmit, onSubmitError, onSubmitInvalid, defaultValues, Children, rhf, form, utils, }: UseRhfUtilsFormProps<TFieldValues, TTransformedValues>) => UseRhfUtilsFormReturn<TFieldValues, TTransformedValues>;
+declare const useRhfUtilsForm: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ defaultValues, onSubmit, onSubmitError, onSubmitInvalid, Children, rhf, form, utils, }: UseRhfUtilsFormProps<TFieldValues, TTransformedValues>) => UseRhfUtilsFormReturn<TFieldValues, TTransformedValues>;
 export default useRhfUtilsForm;
 export type UseRhfUtilsForm<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = typeof useRhfUtilsForm<TFieldValues, TTransformedValues>;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@paragrav/rhf-utils",
   "author": "paragrav.dev",
   "license": "MIT",
-  "version": "0.0.118",
+  "version": "0.0.120",
   "description": "Integration utilities for react-hook-form.",
   "type": "module",
   "sideEffects": false,