@paragrav/rhf-utils 0.0.102 → 0.0.104

package/README.md

@@ -10,11 +10,19 @@ yarn add @paragrav/rhf-utils     # yarn
 
 ## Config
 
-To configure, create a file like `src/integrations/paragrav-rhf-utils/config.tsx` with desired config:
+To configure, create a file like `src/integrations/paragrav-rhf-utils/config.tsx` with desired config. This is global configuration across all forms.
+
+```tsx
+export const config: RhfUtilsClientConfig = {
+  isDevelopment: import.meta.env.DEV,
 
-```ts
-const config: ClientConfig = {
   defaultOptions: {
+    // UseFormProps
+    rhf: {
+      mode: 'onBlur',
+    },
+
+    // UseFormOptions
     form: {
       devTool: {
         placement: 'top-right',
@@ -24,25 +32,33 @@ const config: ClientConfig = {
 
   FormComponent: Form.Root,
 
-  onSubmitError: (error) => {
+  // transform backend error
+  onSubmitError: (
+    error, // unknown
+  ) => {
+    // if other error, re-throw to handle
     if (!(error instanceof TRPCClientError)) throw error;
 
+    // transform
+    const errors = transformToFormSubmitError(error);
 
-    const errors = trcpClientErrorToRhfErrorTransformer.parse(error);
-
+    // return to be merged in RHF context errors
     return new FormSubmitError(errors);
   },
 
   Children: {
-    top: function Top({ options }) {
-      // navigation blocker
+    top: (
+      { options }, // UseFormFieldsProps
+    ) => {
+      // navigation blocker (using custom option)
       useFormRouterBlocker(!!options?.prompter);
 
       return null;
     },
+
     bottom: () => (
       <>
-        // global error list
+        {/* global error list */}
         <RootErrorsListFromFlatFieldErrorsContext />
       </>
     ),
@@ -52,7 +68,7 @@ const config: ClientConfig = {
 
 ## Provider
 
-And add our context provider to your stack:
+And add the context provider to your stack:
 
 ```tsx
 <RhfUtilsClientForZodContextProvider config={config}>
@@ -62,4 +78,68 @@ And add our context provider to your stack:
 
 ## Usage
 
-Coming soon.
+```tsx
+<RhfUtilsZodForm
+  schema={authLoginFormSchema}
+  defaultValues={{
+    email: '',
+  }}
+  // submit handler
+  onSubmit={async (data) => {
+    await authLoginService(data);
+    onSuccess();
+  }}
+  // handle error declaratively (i.e., no throw/catch)
+  onSubmitError={({
+    error, //   unknown
+    context, // rhf UseFormReturn
+    event, //   SubmitEvent
+  }) => {
+    onError(error);
+  }}
+  // fields
+  Fields={({
+    formId, //     unique id string
+    formRef, //    ref
+    context, //    rhf UseFormReturn
+    options, //    UseFormOptions
+    Controller, // strongly-typed controlled
+  }) => (
+    <>
+      <Controller
+        name="email" // strongly-typed field name
+        render={({ field, formState: { isSubmitting } }) => (
+          <input
+            autoFocus
+            label="Email"
+            autoComplete="email"
+            disabled={isSubmitting}
+            {...field}
+          />
+        )}
+      />
+
+      <button type="submit">Login</button>
+    </>
+  )}
+/>
+```
+
+`Fields` is a component which is rendered as a child of the form. It receives `UseFormFieldsProps` as props, including type-safe `Controller`.
+
+## Extend Options
+
+Extend `UseFormOptions` with custom options, which get passed to `Fields` component in `options` prop.
+
+```tsx
+import '@paragrav/rhf-utils';
+
+declare module '@paragrav/rhf-utils' {
+  export interface Register {
+    UseFormOptions: {
+      /** Enable user prompt to confirm navigating away from dirty form. */
+      prompter?: boolean;
+    };
+  }
+}
+```

package/dist/esm/client/zod/RhfUtilsZodForm.mjs

@@ -0,0 +1,12 @@
+import { jsx as e } from "react/jsx-runtime";
+import i from "./context/useRhfUtilsClientForZodContext.mjs";
+function f({
+  schema: o,
+  ...t
+}) {
+  const r = i();
+  return /* @__PURE__ */ e(r.FormWithProviders, { schema: o, ...t });
+}
+export {
+  f as default
+};

package/dist/esm/exports.mjs

@@ -1,24 +1,24 @@
 import { default as e } from "./client/zod/context/RhfUtilsClientForZodContextProvider.mjs";
-import { default as s } from "./client/zod/context/RhfUtilsZodFormWithProviders.mjs";
-import { default as f } from "./client/zod/context/useRhfUtilsClientForZodContext.mjs";
-import { default as m } from "./client/zod/context/useRhfUtilsZodForm.mjs";
+import { default as s } from "./client/zod/context/useRhfUtilsClientForZodContext.mjs";
+import { default as f } from "./client/zod/context/useRhfUtilsZodForm.mjs";
+import { default as m } from "./client/zod/RhfUtilsZodForm.mjs";
 import { default as d } from "./devtool/LazyDevTool.mjs";
 import { default as x } from "./errors/flat/context/useFlatFieldErrorsContext.mjs";
 import { default as i } from "./errors/flat/FlatFieldErrorsList.mjs";
 import { default as E } from "./errors/message/FormErrorMessage.mjs";
 import { default as C } from "./errors/message/FormErrorMessageByPath.mjs";
 import { default as G } from "./errors/nonfield/FormNonFieldErrorMarker.mjs";
-import { default as P } from "./errors/nonfield/FormNonFieldErrorMarkerHtmlAttribute.mjs";
-import { default as I } from "./errors/orphan/useFormHasOnlyOrphanFieldErrorsMemo.mjs";
+import { default as c } from "./errors/nonfield/FormNonFieldErrorMarkerHtmlAttribute.mjs";
+import { default as P } from "./errors/orphan/useFormHasOnlyOrphanFieldErrorsMemo.mjs";
 import { default as B } from "./errors/orphan/useOrphanFormErrorsMemo.mjs";
 import { default as b } from "./errors/root/RootErrorsListFromFlatFieldErrorsContext.mjs";
-import { default as O } from "./errors/root/useRootFormFieldErrorsMemo.mjs";
-import { default as T } from "./errors/useFormErrorsEffect.mjs";
-import { default as g } from "./errors/useFormErrorsIfAny.mjs";
+import { default as S } from "./errors/root/useRootFormFieldErrorsMemo.mjs";
+import { default as U } from "./errors/useFormErrorsEffect.mjs";
+import { default as v } from "./errors/useFormErrorsIfAny.mjs";
 import { default as A } from "./form/FormWithProviders.mjs";
 import { default as D } from "./form/useForm.mjs";
 import { default as N } from "./form/context/utils/useFormUtilsContext.mjs";
-import { default as z } from "./form/context/group/FormGroupContextProvider.mjs";
+import { default as W } from "./form/context/group/FormGroupContextProvider.mjs";
 import { default as q } from "./form/context/group/useFormGroupChildIsMountedTracker.mjs";
 import { default as J } from "./form/context/group/useFormGroupChildIsSubmittingTracker.mjs";
 import { default as Q } from "./form/context/group/useFormGroupChildTracker.mjs";
@@ -34,20 +34,20 @@ export {
   i as FlatFieldErrorsList,
   E as FormErrorMessage,
   C as FormErrorMessageByPath,
-  z as FormGroupContextProvider,
+  W as FormGroupContextProvider,
   G as FormNonFieldErrorMarker,
-  P as FormNonFieldErrorMarkerHtmlAttribute,
+  c as FormNonFieldErrorMarkerHtmlAttribute,
   mr as FormSubmitError,
   A as FormWithProviders,
   d as LazyDevTool,
   e as RhfUtilsClientForZodContextProvider,
-  s as RhfUtilsZodFormWithProviders,
+  m as RhfUtilsZodForm,
   b as RootErrorsListFromFlatFieldErrorsContext,
   fr as getSubmitterButtonData,
   x as useFlatFieldErrorsContext,
   D as useForm,
-  T as useFormErrorsEffect,
-  g as useFormErrorsIfAny,
+  U as useFormErrorsEffect,
+  v as useFormErrorsIfAny,
   q as useFormGroupChildIsMountedTracker,
   J as useFormGroupChildIsSubmittingTracker,
   Q as useFormGroupChildTracker,
@@ -55,12 +55,12 @@ export {
   _ as useFormGroupIsChildBusy,
   rr as useFormGroupIsParentBusy,
   er as useFormGroupParentTracker,
-  I as useFormHasOnlyOrphanFieldErrorsMemo,
+  P as useFormHasOnlyOrphanFieldErrorsMemo,
   dr as useFormOnSubmitSuccessful,
   sr as useFormOrParentIsBusy,
   N as useFormUtilsContext,
   B as useOrphanFormErrorsMemo,
-  f as useRhfUtilsClientForZodContext,
-  m as useRhfUtilsZodForm,
-  O as useRootFormFieldErrorsMemo
+  s as useRhfUtilsClientForZodContext,
+  f as useRhfUtilsZodForm,
+  S as useRootFormFieldErrorsMemo
 };

package/dist/esm/form/Form.mjs

@@ -1,4 +1,4 @@
-import { jsxs as F, jsx as o } from "react/jsx-runtime";
+import { jsxs as F, jsx as c } from "react/jsx-runtime";
 import "react";
 import { useFormContext as _ } from "react-hook-form";
 import j from "../client/config/useRhfUtilsClientConfigContext.mjs";
@@ -12,7 +12,7 @@ function q({
   formRef: C,
   //
   onSubmit: d,
-  onSubmitError: c,
+  onSubmitError: o,
   onSubmitInvalid: y,
   Fields: h,
   //
@@ -41,7 +41,7 @@ function q({
       // if error is not FormSubmitError, consumer can provide global handler
       (n = e == null ? void 0 : e.onSubmitError) == null ? void 0 : n.call(e, r)
     );
-    m && P(l, m), c == null || c(
+    m && P(l, m), o == null || o(
       r,
       l,
       a
@@ -49,13 +49,13 @@ function q({
   }, u = {
     formId: x,
     formRef: C,
-    ctx: l,
+    context: l,
     options: t,
     Controller: S
   }, i = (r) => {
     var m;
     const a = (m = e == null ? void 0 : e.Children) == null ? void 0 : m[r];
-    return a && /* @__PURE__ */ o(a, { ...u });
+    return a && /* @__PURE__ */ c(a, { ...u });
   };
   return /* @__PURE__ */ F(
     T,
@@ -71,7 +71,7 @@ function q({
       onSubmit: b,
       children: [
         i("top"),
-        (t == null ? void 0 : t.devTool) !== "disabled" && /* @__PURE__ */ o(
+        (t == null ? void 0 : t.devTool) !== "disabled" && /* @__PURE__ */ c(
           D,
           {
             placement: "top-right",
@@ -79,7 +79,7 @@ function q({
             ...t == null ? void 0 : t.devTool
           }
         ),
-        h && /* @__PURE__ */ o(h, { ...u }),
+        h && /* @__PURE__ */ c(h, { ...u }),
         f,
         i("bottom")
       ]

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

@@ -28,23 +28,47 @@ export type RhfUtilsClientConfig = {
         form?: UseFormOptions;
     };
     /**
-     * Components injected by slot across all forms.
-     * (Per-form injection can be done via Fields prop.)
+     * Supply your own `<form>` component.
      *
-     * top: e.g., block navigation on dirty form.
-     * bottom: e.g., root errors list.
+     * By default, a primitive `<form>` element is used.
      */
-    Children?: Partial<Record<FormChildrenSlots, React.FC<UseFormFieldsProps>>>;
+    FormComponent?: React.FC<React.PropsWithChildren<React.HTMLAttributes<HTMLFormElement>>>;
     /**
      * Handle non-{@link FormSubmitError} errors. Optionally, return {@link FormSubmitError} to merge into context errors.
+     *
+     * Example use case:
+     * - transform API errors to {@link FormSubmitError}.
      */
     onSubmitError?: (error: unknown) => FormSubmitError | undefined;
-    FormComponent?: React.FC<React.PropsWithChildren<React.HTMLAttributes<HTMLFormElement>>>;
+    /**
+     * Components injected by slot across all forms.
+     * (Per-form injection can be done via Fields prop.)
+     *
+     * - `top`: e.g., block navigation on dirty form.
+     * - `bottom`: e.g., root errors list.
+     */
+    Children?: Partial<Record<FormChildrenSlots, React.FC<UseFormFieldsProps>>>;
     errors?: {
+        /**
+         * Configure how/if errors should be outputted.
+         */
         output?: {
+            /**
+             * Configure how/if errors should be outputted to console.
+             *
+             * Example use cases:
+             * - console.debug errors in development environment.
+             * - console.error certain errors in production environment.
+             */
             console?: {
                 getConfig?: (context: RhfUtilsErrorsOutputConfigContext) => RhfUtilsErrorsOutputConsoleConfig | null;
             };
+            /**
+             * Configure how/if errors should be thrown.
+             *
+             * Example use case:
+             * - bring attention to certain errors in development environment.
+             */
             throw?: {
                 getConfig?: (context: RhfUtilsErrorsOutputConfigContext) => true | string | false;
             };

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

@@ -0,0 +1,8 @@
+import { UseFormProps } from '../../form/useForm';
+import { ZodTypeFieldValues } from './createRhfUtilsClientForZod';
+
+type Props<TSchema extends ZodTypeFieldValues> = {
+    schema: TSchema;
+} & Omit<UseFormProps<TSchema['_input'], TSchema['_output']>, 'config'>;
+declare function RhfUtilsZodForm<TSchema extends ZodTypeFieldValues>({ schema, ...props }: Props<TSchema>): import("react/jsx-runtime").JSX.Element;
+export default RhfUtilsZodForm;

package/dist/types/client/zod/UseFormFieldsZodProps.d.ts

@@ -0,0 +1,4 @@
+import { UseFormFieldsProps } from '../../form/useForm';
+import { ZodTypeFieldValues } from './createRhfUtilsClientForZod';
+
+export type UseFormFieldsZodProps<TSchema extends ZodTypeFieldValues> = UseFormFieldsProps<TSchema['_input'], TSchema['_output']>;

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

@@ -3,7 +3,6 @@ import { ZodTypeFieldValues } from '../createRhfUtilsClientForZod';
 
 type Props<TSchema extends ZodTypeFieldValues> = {
     schema: TSchema;
-    form: Omit<UseFormProps<TSchema['_input'], TSchema['_output']>, 'config'>;
-};
-declare function RhfUtilsZodFormWithProviders<TSchema extends ZodTypeFieldValues>({ schema, form, }: Props<TSchema>): import("react/jsx-runtime").JSX.Element;
+} & Omit<UseFormProps<TSchema['_input'], TSchema['_output']>, 'config'>;
+declare function RhfUtilsZodFormWithProviders<TSchema extends ZodTypeFieldValues>({ schema, ...props }: Props<TSchema>): import("react/jsx-runtime").JSX.Element;
 export default RhfUtilsZodFormWithProviders;

package/dist/types/errors/consoleErrors.d.ts

@@ -0,0 +1,14 @@
+import { FieldErrors } from 'react-hook-form';
+import { SafeFieldValues } from '../form/SafeFieldValues';
+
+/**
+ * Output form values and errors to console.
+ */
+declare const consoleErrors: (message: string, form: {
+    values: SafeFieldValues;
+    errors: FieldErrors;
+}, options?: {
+    other?: Record<string, unknown>;
+    isError?: boolean;
+}) => void;
+export default consoleErrors;

package/dist/types/errors/orphan/useOrphanFormErrorsToConsole.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+
+/**
+ * Logs out orphan errors to console.error.
+ *
+ * In development, it will also throw an error to bring attention to dev.
+ */
+declare const useOrphanFormErrorsToConsole: (formRef: React.RefObject<HTMLFormElement>, enabled?: boolean) => void;
+export default useOrphanFormErrorsToConsole;

package/dist/types/errors/outputErrors.d.ts

@@ -0,0 +1,14 @@
+import { FieldErrors } from 'react-hook-form';
+import { SafeFieldValues } from '../form/SafeFieldValues';
+
+/**
+ * Output form values and errors to console and throw in dev.
+ */
+declare const outputErrors: (message: string, form: {
+    values: SafeFieldValues;
+    errors: FieldErrors;
+}, options?: {
+    other?: Record<string, unknown>;
+    isError?: boolean;
+}) => void;
+export default outputErrors;

package/dist/types/errors/useFormErrorConsoleDebug.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Output form errors to console.debug() for easier debugging for certain condition.
+ * (e.g., in dev/staging environments or certain users)
+ *
+ * `console.debug()` is unlikely to trigger any automated console capture reporting.
+ */
+declare const useFormErrorConsoleDebug: (enabled?: boolean) => void;
+export default useFormErrorConsoleDebug;

package/dist/types/errors/useFormErrorsToConsole.d.ts

@@ -0,0 +1,13 @@
+import { FlatFieldErrors } from './flat/types';
+
+/**
+ * Logs out orphan errors to console.error.
+ *
+ * In development, it will also throw an error to bring attention to dev.
+ */
+declare const useFormErrorsToConsole: (message: string, flatErrors: FlatFieldErrors, options?: {
+    disabled?: boolean;
+    isError?: boolean;
+    data?: Record<string, unknown>;
+}) => void;
+export default useFormErrorsToConsole;

package/dist/types/exports.d.ts

@@ -1,9 +1,10 @@
 export type { Register } from './register';
 export type { RhfUtilsClientConfig } from './client/config/RhfUtilsClientConfig';
 export { default as RhfUtilsClientForZodContextProvider } from './client/zod/context/RhfUtilsClientForZodContextProvider';
-export { default as RhfUtilsZodFormWithProviders } from './client/zod/context/RhfUtilsZodFormWithProviders';
 export { default as useRhfUtilsClientForZodContext } from './client/zod/context/useRhfUtilsClientForZodContext';
 export { default as useRhfUtilsZodForm } from './client/zod/context/useRhfUtilsZodForm';
+export { default as RhfUtilsZodForm } from './client/zod/RhfUtilsZodForm';
+export type { UseFormFieldsZodProps } from './client/zod/UseFormFieldsZodProps';
 export { default as LazyDevTool } from './devtool/LazyDevTool';
 export { default as useFlatFieldErrorsContext } from './errors/flat/context/useFlatFieldErrorsContext';
 export { default as FlatFieldErrorsList } from './errors/flat/FlatFieldErrorsList';

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

@@ -10,7 +10,7 @@ import { UseFormOptions } from './useFormOptions';
 export type UseFormFieldsProps<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = SafeFieldValues> = {
     formId: string;
     formRef: React.RefObject<HTMLFormElement>;
-    ctx: RhfUseFormReturn<TFieldValues, unknown, TTransformedValues>;
+    context: RhfUseFormReturn<TFieldValues, unknown, TTransformedValues>;
     options?: UseFormOptions;
     Controller: typeof _Controller<TFieldValues>;
 };

package/dist/types/register.d.ts

@@ -1,5 +1,6 @@
 /**
  * Use this to extend internal types.
+ *
  * For example, `UseFormOptions`.
  */
 export interface Register {

package/package.json

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

package/dist/esm/client/zod/context/RhfUtilsZodFormWithProviders.mjs

@@ -1,12 +0,0 @@
-import { jsx as i } from "react/jsx-runtime";
-import e from "./useRhfUtilsClientForZodContext.mjs";
-function f({
-  schema: o,
-  form: t
-}) {
-  const r = e();
-  return /* @__PURE__ */ i(r.FormWithProviders, { schema: o, ...t });
-}
-export {
-  f as default
-};