@paragrav/rhf-utils 0.65.0 → 0.67.0

package/README.md

@@ -9,7 +9,7 @@ Integration and utility library for [react-hook-form](https://www.react-hook-for
 - TypeScript-first
 - global configuration (🔗 [`RhfUtilsClientConfig`](#config) section)
   - RHF (`UseFormProps`) and utilities (`RhfUtilsFormOptions`) options defaults
-  - inject your own hooks and UI (`FormChildren`)
+  - inject your own hooks and UI (`FormInjector`)
   - server error transformation (`onSubmitErrorUnknown`) ✨
   - handle cancel prompt (`useCanFormBeCancelled`) ✨
   - RHF `FormState.errors` logging/throwing (`RhfUtilsClientConfig.fieldErrors`) ✨
@@ -76,7 +76,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
 
   // inject your own hooks and components
   // into all RhfUtilsZodForm instances
-  FormChildren: (
+  FormInjector: (
     // RhfUtilsFormInjectorProps
     {
       Outlet, //          Form instance (RhfUtilsZodForm.Children) "outlet"
@@ -116,6 +116,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   // (i.e., calling your own hook in `FormComponent`)
   useCanFormBeCancelled: () => {
     const { isDirty } = useFormState();
+    const myPrompter = useMyPrompter();
 
     // return callback to be called at event-time
     return ({ options }) =>

package/dist/tsdown/FormRelayOptions-mBqiP41Z.d.ts

@@ -0,0 +1,29 @@
+import { i as SafeFieldValues, t as RhfUtilsContext } from "./RhfUtilsContextType-BFmDtONY.js";
+import { FormState } from "react-hook-form";
+
+//#region src/form/relay/types.d.ts
+type FormRelay<TFieldValues extends SafeFieldValues = SafeFieldValues> = {
+  state: FormRelayStateSelected<TFieldValues>;
+  options: FormRelayOptions;
+  utils: RhfUtilsContext;
+};
+type FormRelayStateSelected<TFieldValues extends SafeFieldValues = SafeFieldValues> = Partial<FormState<TFieldValues> & {
+  isMounted: true;
+}>;
+//#endregion
+//#region src/form/relay/FormRelayOptions.d.ts
+type FormRelayOptions = {
+  /**
+   * Determines what part of RHF's form state is relayed.
+   * Also acts to activate RHF proxy values.
+   */
+  select: (formState: FormState<SafeFieldValues>) => FormRelayStateSelected;
+  /**
+   * Arbitrary group name(s) for this form.
+   * Think of it like class or category names.
+   * (e.g., "parent" or "children")
+   */
+  groups?: string[];
+};
+//#endregion
+export { FormRelay as n, FormRelayStateSelected as r, FormRelayOptions as t };

package/dist/tsdown/FormRelaySetter-BKO0Wodf.js

@@ -0,0 +1,192 @@
+import React from "react";
+import { jsx } from "react/jsx-runtime";
+import { get, useFormState } from "react-hook-form";
+import { flatten } from "flat";
+//#region src/utils/createContext.ts
+/**
+* Create a strictly-typed context that throws error if no provider is found.
+* @returns A tuple with a function to get the context and the context provider.
+*/
+function createContext() {
+	const context = React.createContext(void 0);
+	const useMaybe = () => React.useContext(context);
+	const useRequired = () => {
+		const c = useMaybe();
+		if (c === void 0) throw new Error();
+		return c;
+	};
+	return {
+		Provider: context.Provider,
+		useMaybe,
+		useRequired
+	};
+}
+//#endregion
+//#region src/form/relay/context/useFormRelayContext.ts
+const { Provider: _FormRelayContextProvider, useRequired: useFormRelayContext } = createContext();
+//#endregion
+//#region src/form/relay/context/FormRelayContextProvider.tsx
+const FormRelayContextProvider = ({ children }) => {
+	const [state, setState] = React.useState({});
+	return /* @__PURE__ */ jsx(_FormRelayContextProvider, {
+		value: {
+			add: React.useCallback((formState, utils, options) => {
+				if (state[utils.formId]) throw new Error("Form id already exists.");
+				setState((forms) => ({
+					...forms,
+					[utils.formId]: {
+						state: formState,
+						utils,
+						options
+					}
+				}));
+			}, [state]),
+			update: React.useCallback((id, state) => {
+				setState((forms) => {
+					const current = forms[id];
+					if (!current) throw new Error("Form id doesn't exist");
+					return {
+						...forms,
+						[id]: {
+							...current,
+							state
+						}
+					};
+				});
+			}, []),
+			remove: React.useCallback((id) => {
+				setState((forms) => Object.fromEntries(Object.entries(forms).filter(([entryId]) => entryId !== id)));
+			}, []),
+			state
+		},
+		children
+	});
+};
+//#endregion
+//#region src/form/context/utils/useRhfUtilsContext.tsx
+const { Provider: _RhfUtilsContextProvider, useRequired: useRhfUtilsContext, useMaybe: useRhfUtilsMaybeContext } = createContext();
+//#endregion
+//#region src/utils/isEmptyObject.ts
+const isEmptyObject = (obj) => Object.keys(obj).length === 0;
+//#endregion
+//#region src/errors/flat/flattenFieldErrors.ts
+/**
+* Flatten a {@link FieldErrors} object.
+*
+* @returns e.g.,
+* ```ts
+* {
+*   "address.street.type": "too_short",
+*   "address.street.ref.value": "123",
+*   "address.street.message": "Required."
+* }
+* ```
+*/
+const flattenFieldErrors = (errors) => flatten(errors);
+//#endregion
+//#region src/errors/flat/getFlatFieldErrors.ts
+/**
+* Get {@link FlatFieldErrors} from {@link FieldErrors}.
+* This makes it easy to work with potentially deeply-nested {@link FieldErrors}.
+*
+* @param errors {@link FieldErrors} object.
+*
+* @returns `FlatFieldErrors` object.
+*
+* @example
+* ```
+* {
+*   "address.street": {
+*     type: "too_short",
+*     ref: { value: "123" },
+*     message: "Required." }
+*   }
+* }
+* ```
+*/
+const getFlatFieldErrors = (errors) => {
+	const flattened = flattenFieldErrors(errors);
+	return Object.fromEntries(Object.keys(flattened).reduce((entriesAccumulator, flattenedKey) => {
+		/**
+		* Maybe path.
+		*
+		* Derived from flattened key by removing leaf node suffix (if present).
+		*
+		* @example
+		* path: `address.street.message` -> `address.street`
+		* @example
+		* not path: `address.street.ref` -> `address.street.ref` (no suffix match to replace)
+		*/
+		const maybePath = flattenedKey.replace(regexMaybeFieldErrorLeafNodeSuffix, "");
+		if (maybePath === flattenedKey) return entriesAccumulator;
+		const fieldError = get(errors, maybePath, void 0);
+		if (!fieldError) return entriesAccumulator;
+		/**
+		* Add entry to accumulator.
+		*
+		* (If it's a duplicate (e.g., `.type` leaf node matched before `.message`),
+		* it doesn't matter because `Object.fromEntries` will just overwrite
+		* first entry with second matching key/value.)
+		*/
+		entriesAccumulator.push([maybePath, fieldError]);
+		return entriesAccumulator;
+	}, []));
+};
+/**
+* Regular expression to maybe match the end of a leaf node path.
+*
+* i.e., `name.type`, `address.street.message`
+*
+* iow: dot [?: non-capturing]("type" | "message")[\b word boundary][$ end of string]
+*/
+const regexMaybeFieldErrorLeafNodeSuffix = /\.(?:type|message)\b$/;
+const getFlatFieldErrorsSansRef = (errors) => Object.fromEntries(Object.entries(getFlatFieldErrors(errors)).map(([name, error]) => [name, {
+	type: error.type,
+	message: error.message,
+	hasRef: !!error.ref
+}]));
+//#endregion
+//#region src/form/relay/set/useFormRelaySet.ts
+const useFormRelaySet = (options) => {
+	if (!options) return;
+	const [memoOptions] = React.useState(options);
+	useFormRelayOnMount(memoOptions);
+	useFormRelayOnChange(memoOptions);
+};
+const useFormRelayOnMount = (options) => {
+	const utils = useRhfUtilsContext();
+	const relay = useFormRelayContext();
+	const formStateForRelay = useFormStateForRelay(options);
+	React.useEffect(() => {
+		relay.add(formStateForRelay, utils, options);
+		return () => {
+			relay.remove(utils.formId);
+		};
+	}, []);
+};
+const useFormRelayOnChange = (options) => {
+	const utils = useRhfUtilsContext();
+	const relay = useFormRelayContext();
+	const formStateForRelay = useFormStateForRelay(options);
+	React.useEffect(() => {
+		relay.update(utils.formId, formStateForRelay);
+	}, [formStateForRelay]);
+};
+/** Transform, memo-ize {@link useFormState}'s return to {@link FormRelayed} */
+const useFormStateForRelay = (options) => {
+	const formState = useFormState();
+	const formStateSelected = options.select(formState);
+	const formStateSelectedJson = JSON.stringify({
+		...formStateSelected,
+		errors: formStateSelected.errors && getFlatFieldErrorsSansRef(formStateSelected.errors)
+	});
+	return React.useMemo(() => formStateSelected, [formStateSelectedJson]);
+};
+//#endregion
+//#region src/form/relay/set/FormRelaySetter.tsx
+const FormRelaySetter = ({ options }) => {
+	useFormRelaySet(options);
+	return null;
+};
+//#endregion
+export { _RhfUtilsContextProvider as a, FormRelayContextProvider as c, isEmptyObject as i, useFormRelayContext as l, useFormRelaySet as n, useRhfUtilsContext as o, getFlatFieldErrors as r, useRhfUtilsMaybeContext as s, FormRelaySetter as t, createContext as u };

package/dist/tsdown/RhfUtilsClientConfigType-CeOJzNAc.d.ts

@@ -0,0 +1,212 @@
+import { a as RhfUtilsFormOptions, i as SafeFieldValues, t as RhfUtilsContext } from "./RhfUtilsContextType-BFmDtONY.js";
+import React$1 from "react";
+import { ControllerProps, FieldError, FieldPath, UseFormProps, UseFormReturn } from "react-hook-form";
+
+//#region src/errors/output/types.d.ts
+/**
+ * Config object for error output.
+ */
+type RhfUtilsErrorsOutputConsoleConfig = {
+  type?: 'debug' | 'error';
+  message?: string;
+};
+//#endregion
+//#region src/errors/flat/types.d.ts
+/**
+ * Flattened field errors object.
+ *
+ * @example
+ * ```ts
+ * {
+ *   'address.street': FieldError
+ * }
+ * ```
+ */
+type FlatFieldErrors = Record<string, FieldError>;
+//#endregion
+//#region src/errors/flat/context/useFlatFieldErrorsContext.d.ts
+type FlatFieldErrorsContext = {
+  all: FlatFieldErrors;
+  fields: FlatFieldErrors;
+  roots: FlatFieldErrors;
+  orphans: FlatFieldErrors;
+  hasErrors: boolean;
+  hasOrphans: boolean;
+};
+declare const _FormErrorsFlatContextProvider: import("react").Provider<FlatFieldErrorsContext | undefined>, useFlatFieldErrorsContext: () => FlatFieldErrorsContext;
+//#endregion
+//#region src/errors/flat/context/FlatFieldErrorsOutputConfig.d.ts
+type FlatFieldErrorsOutputConfig = {
+  /**
+   * 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?: (context: FlatFieldErrorsContext) => RhfUtilsErrorsOutputConsoleConfig | null | false | undefined;
+  /**
+   * Configure how/if errors should be thrown.
+   *
+   * Example use case:
+   * - bring attention to certain errors in development environment.
+   */
+  throw?: (context: FlatFieldErrorsContext) => true | string | false | undefined;
+};
+//#endregion
+//#region src/form/rhf/UseFormPropsType.d.ts
+type RhfUseFormGlobalProps = Pick<UseFormProps, 'mode' | 'reValidateMode' | 'resetOptions' | 'context' | 'shouldFocusError' | 'shouldUnregister' | 'shouldUseNativeValidation' | 'progressive' | 'criteriaMode' | 'delayError'>;
+type RhfUseFormInstanceProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = Omit<UseFormProps<TFieldValues, unknown, TTransformedValues>, 'defaultValues' | 'resolver'>;
+//#endregion
+//#region src/form/defaults/UseRhfUtilsFormGlobalDefaults.d.ts
+/**
+ * Globally-relevant subset of defaults.
+ */
+type UseRhfUtilsFormGlobalDefaults = {
+  /**
+   * Default RHF `useForm` settings.
+   *
+   * (Exposes only non-local props.)
+   */
+  rhf?: RhfUseFormGlobalProps;
+  /**
+   * Global settings and defaults.
+   *
+   * (Extend this type via `Register` type to inject custom options/functionality via `Children` component.)
+   */
+  options?: RhfUtilsFormOptions;
+  /**
+   * Default props for form element.
+   */
+  form?: Pick<React$1.PropsWithoutRef<React$1.JSX.IntrinsicElements['form']>, 'className' | 'noValidate' | 'role'>;
+};
+//#endregion
+//#region src/submit/error/FormSubmitFieldErrors.d.ts
+/**
+ * Field errors structure based on RHF's `FieldErrors`.
+ *
+ * - Uses {@link SafeFieldValues} instead of more permissive `FieldValues`.
+ * - `root.<string>` keys allowed.
+ *   - `root` is reserved for special use cases.
+ * - simplified `ErrorOption` value.
+ */
+type FormSubmitFieldErrors<TFieldValues extends SafeFieldValues = SafeFieldValues> = Record<FieldPath<TFieldValues> | `root.${string}`, {
+  message: string;
+  type?: string;
+}>;
+//#endregion
+//#region src/submit/error/FormSubmitError.d.ts
+declare class FormSubmitError<TFieldValues extends SafeFieldValues = SafeFieldValues, TApiValues extends undefined | SafeFieldValues = undefined, TAllValues extends SafeFieldValues = (TApiValues extends undefined ? TFieldValues : TFieldValues | TApiValues)> extends Error {
+  errors: FormSubmitFieldErrors<TAllValues>;
+  constructor(errors: FormSubmitFieldErrors<TAllValues>, message?: string);
+}
+//#endregion
+//#region src/submit/UseRhfUtilsFormOnSubmitContextType.d.ts
+/**
+ * Props for onSubmit other than `data` and `event`.
+ *
+ * Consider keeping shape in line with `UseRhfUtilsFormChildrenProps` and `UseRhfUtilsFormReturn`.
+ */
+type UseRhfUtilsFormOnSubmitContext<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = TFieldValues, TApiValues extends undefined | SafeFieldValues = undefined> = {
+  utils: RhfUtilsContext;
+  rhf: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
+  FormSubmitError: typeof FormSubmitError<TFieldValues, TApiValues>;
+};
+/**
+ * Props for onSubmitError other than `error` and `event`.
+ */
+type UseRhfUtilsFormOnSubmitErrorContext<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = {
+  utils: RhfUtilsContext;
+  rhf: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
+  errors?: FormSubmitFieldErrors;
+};
+//#endregion
+//#region src/utils/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/** Merge {@link C} into {@link B} into {@link A} (last taking highest precedence). */
+type Merge<A, B, C = unknown, D = unknown> = D & Omit<C, keyof D> & Omit<Omit<B, keyof C>, keyof D> & Omit<Omit<Omit<A, keyof B>, keyof C>, keyof D>;
+//#endregion
+//#region src/form/_Controller.d.ts
+type _ControllerProps<TFieldValues extends SafeFieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = Omit<ControllerProps<TFieldValues, TName>, 'control'>;
+declare const _Controller: <TFieldValues extends SafeFieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>(props: _ControllerProps<TFieldValues, TName>) => import("react").JSX.Element;
+//#endregion
+//#region src/client/config/RhfUtilsFormInjectorProps.d.ts
+/**
+ * RhfUtilsClientConfig's FormComponent props.
+ */
+type RhfUtilsFormInjectorProps<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = TFieldValues> = Merge<{
+  /** Form instance children (`RhfUtilsZodForm.Children`) to output amid globally-injected code. */Outlet: React.FC;
+}, RhfUtilsContext, {
+  rhf: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
+  Controller: typeof _Controller<TFieldValues>;
+  FormSubmitError: typeof FormSubmitError<TFieldValues>;
+}>;
+//#endregion
+//#region src/client/config/RhfUtilsClientConfigType.d.ts
+/**
+ * Client configuration object.
+ *
+ * Options under `defaults` can be overridden at form level.
+ */
+type RhfUtilsClientConfig = {
+  /**
+   * Default options for all forms. (Are overridden by form-specific options.)
+   */
+  defaults?: UseRhfUtilsFormGlobalDefaults;
+  /**
+   * Supply your own `<form>` component.
+   *
+   * (By default, a native {@link HTMLFormElement} is used.)
+   */
+  FormComponent?: React.FC<React.PropsWithChildren<React.HTMLAttributes<HTMLFormElement>>>;
+  /**
+   * Inject your own hooks, components, etc., into every form instance.
+   *
+   * @description
+   *
+   * (NOTE: context params are not schema-typed as not possible at this level.)
+   *
+   * @example
+   *
+   * See README.
+   */
+  FormInjector?: React.FC<RhfUtilsFormInjectorProps>;
+  /**
+   * A hook that returns a callback that determines whether form can be cancelled at event-time.
+   *
+   * @description
+   *
+   * Cancellation of forms often doesn't involve navigation, making it more challenging to centrally handle.
+   * Your hook's returned callback should internally prompt user and return response as `boolean`
+   * indicating whether cancellation should be blocked. See `README.md` for example.
+   *
+   * @returns Callback that, given {@link RhfUtilsFormContext} at event-time, returns `boolean` value indicating whether form can be cancelled.
+   *
+   * Callback should return:
+   * `true`: if form can be cancelled (e.g., form not dirty or user confirmed via prompt); {@link UseRhfUtilsFormProps.onCancel} is called.
+   * `false`: form cannot be cancelled (e.g., user denied); {@link UseRhfUtilsFormProps.onCancel} is not called.
+   */
+  useCanFormBeCancelled?: () => (props: UseRhfUtilsFormOnSubmitContext) => MaybePromise<boolean>;
+  /**
+   * Global submit error handler when/if submit handler throws an error other than {@link FormSubmitError}.
+   *
+   * Example use case:
+   * - transform API errors to {@link FormSubmitFieldErrors}.
+   *
+   * @returns
+   * - if {@link FormSubmitFieldErrors}: merge into context errors.
+   * - if `undefined`: do nothing.
+   */
+  onSubmitErrorUnknown?: (error: unknown) => FormSubmitFieldErrors | undefined;
+  /**
+   * Configuration regarding RHF form state errors (`useFormContext().formState.errors`).
+   */
+  fieldErrors?: {
+    /**
+     * Configure how/if errors should be outputted for debugging/reporting (i.e., console and/or throwing).
+     */
+    output?: FlatFieldErrorsOutputConfig;
+  };
+};
+//#endregion
+export { UseRhfUtilsFormOnSubmitContext as a, FormSubmitFieldErrors as c, MaybePromise as i, RhfUseFormInstanceProps as l, RhfUtilsFormInjectorProps as n, UseRhfUtilsFormOnSubmitErrorContext as o, _Controller as r, FormSubmitError as s, RhfUtilsClientConfig as t, useFlatFieldErrorsContext as u };

package/dist/tsdown/RhfUtilsContextType-BFmDtONY.d.ts

@@ -0,0 +1,81 @@
+import React, { RefObject } from "react";
+import { DevtoolUIProps } from "@hookform/devtools/dist/devToolUI";
+import { Register } from "@/Register";
+
+//#region src/submit/useResetFormOnSubmitted.d.ts
+/**
+ * Configuration options for {@link useResetFormOnSubmitted}.
+ */
+type UseResetFormOnSubmittedOptions = undefined | {
+  /**
+   * Reset values on successful submit.
+   * - `defaults`: reset current values to defaults
+   * - `current`: reset defaults to current values
+   */
+  success?: {
+    values: 'defaults' | 'current';
+  };
+  /**
+   * Reset values to defaults on submit error.
+   */
+  error?: {
+    values: 'defaults';
+  };
+};
+//#endregion
+//#region src/submit/useSubmitFormOnWatch.d.ts
+type UseSubmitFormOnWatchOptions = {
+  /** Milliseconds to debounce form submission. (Default is none.) */debounce: number;
+};
+//#endregion
+//#region src/form/options/RhfUtilsFormOptionsType.d.ts
+/**
+ * Options for enabling utils functionality provided by this library.
+ *
+ * Can be extended via {@link Register}.
+ */
+type RhfUtilsFormOptions = {
+  /** Stop propagation of submit event. */stopSubmitPropagation?: boolean;
+  /**
+   * Request submit when user changes form values.
+   */
+  submitOnWatch?: UseSubmitFormOnWatchOptions; /** Reset form values and state (e.g., `isDirty`) after submit -- on success and/or error. */
+  resetOnSubmitted?: UseResetFormOnSubmittedOptions;
+  /**
+   * Control dev tool options.
+   * (Lazy-loaded when truthy value supplied.
+   * For zero bundle size in prod, be sure to check for dev environment.)
+   */
+  devTool?: boolean | Pick<DevtoolUIProps, 'placement' | 'styles'>;
+} & (Register extends {
+  RhfUtilsFormOptions: infer _RhfUtilsFormOptions;
+} ? _RhfUtilsFormOptions : {});
+//#endregion
+//#region src/form/rhf/SafeFieldValuesType.d.ts
+/**
+ * Equivalent to RHF's `FieldValues` except for `unknown` (instead of `any`) value.
+ */
+type SafeFieldValues = Record<string, unknown>;
+//#endregion
+//#region src/form/context/utils/LastSubmitStateType.d.ts
+type LastSubmitState = null | 'submitting' | 'success' | 'error';
+//#endregion
+//#region src/form/context/utils/RhfUtilsContextProvider.d.ts
+type RhfUtilsContextProviderProps = {
+  formId: string;
+  formRef: React.RefObject<HTMLFormElement | null>; /** Consumer-supplied options and values. */
+  options: RhfUtilsFormOptions;
+};
+//#endregion
+//#region src/form/context/utils/RhfUtilsContextType.d.ts
+type RhfUtilsContext = RhfUtilsContextProviderProps & {
+  /**
+   * Current form submit state.
+   *
+   * e.g., can be used to determine whether safe to redirect (navigate) without prompter.
+   * Unlike RHF's `isSubmitSuccessful`, is computed/set immediately after `onSubmit` succeeds/fails.
+   */
+  lastSubmitStateRef: RefObject<LastSubmitState>;
+};
+//#endregion
+export { RhfUtilsFormOptions as a, SafeFieldValues as i, RhfUtilsContextProviderProps as n, LastSubmitState as r, RhfUtilsContext as t };