@paragrav/rhf-utils 0.0.102 → 0.0.103

package/README.md

@@ -10,11 +10,17 @@ 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: {
+    rhf: {
+      mode: 'onBlur',
+    },
+
     form: {
       devTool: {
         placement: 'top-right',
@@ -24,25 +30,29 @@ const config: ClientConfig = {
 
   FormComponent: Form.Root,
 
+  // transform backend error
   onSubmitError: (error) => {
+    // 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 }) => {
+      // navigation blocker (using custom option)
       useFormRouterBlocker(!!options?.prompter);
 
       return null;
     },
+
     bottom: () => (
       <>
-        // global error list
+        {/* global error list */}
         <RootErrorsListFromFlatFieldErrorsContext />
       </>
     ),
@@ -52,7 +62,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 +72,52 @@ And add our context provider to your stack:
 
 ## Usage
 
-Coming soon.
+```tsx
+<RhfUtilsZodFormWithProviders
+  schema={authLoginFormSchema}
+  onSubmit={async (data) => {
+    await authLoginService(data, { from });
+    onSuccess?.();
+  }}
+  onSubmitError={onError}
+  defaultValues={{
+    email: '',
+  }}
+  Fields={({ Controller }) => (
+    <>
+      <Controller
+        name="email" // strongly-typed field name
+        render={(props) => (
+          <InputControlledRender
+            controller={props}
+            autoFocus
+            label="Email"
+            autoComplete="email"
+          />
+        )}
+      />
+
+      <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/context/RhfUtilsZodFormWithProviders.mjs

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

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/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

@@ -4,6 +4,7 @@ export { default as RhfUtilsClientForZodContextProvider } from './client/zod/con
 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 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/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.103",
   "description": "Integration utilities for react-hook-form.",
   "type": "module",
   "sideEffects": false,