@paragrav/rhf-utils 0.60.0 → 0.62.0

package/README.md

@@ -9,11 +9,11 @@ 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 (`FormComponent`)
+  - inject your own hooks and UI (`FormChildren`)
   - server error transformation (`onSubmitErrorUnknown`) ✨
   - handle cancel prompt (`useCanFormBeCancelled`) ✨
   - RHF `FormState.errors` logging/throwing (`RhfUtilsClientConfig.fieldErrors`) ✨
-- form-level configuration (🔗 [`RhfUtilsZodForm`](#form) section)
+- form-level configuration (🔗 [`RhfUtilsZodForm`](#form-with-providers) section)
   - RHF and utilities options overrides
     - extendable utilities options type (`RhfUtilsFormOptions`)
   - throw error (`FormSubmitError`) in submit handler to add errors to RHF context and fail submit
@@ -21,7 +21,7 @@ Integration and utility library for [react-hook-form](https://www.react-hook-for
   - context injection for children (`RhfUtilsZodForm.Children`), including:
     - formId, formRef, RHF context, utilities options
     - schema-typed Controller component and FormSubmitError class
-- form state relay (🔗 [`FormStateRelayContextProvider`](#form-state-relay) section) ✨
+- form state relay (🔗 [`FormRelayContextProvider`](#form-state-relay) section) ✨
   - access specific form's state from outside that form/provider
   - assign forms into groups and watch collectively
 - simpler/flatter `FieldErrors` structure (🔗 [`FlatFieldErrors`](#flatfielderrors) section)
@@ -44,7 +44,7 @@ yarn add @paragrav/rhf-utils     # yarn
 - 🔗 [Config](#config) (`RhfUtilsClientConfig`): define your global config (optional)
   - 🔗 [Provider](#config-provider) (`RhfUtilsClientConfigProvider`): add to your global stack
 - 🔗 [Form With Providers](#form-with-providers) (`RhfUtilsZodFormWithProviders`): use as form component
-- 🔗 [Form State Relay](#form-state-relay) (`FormStateRelayContextProvider`): relay form state
+- 🔗 [Form State Relay](#form-state-relay) (`FormRelayContextProvider`): relay form state
 
 ## Config
 
@@ -72,14 +72,15 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   },
 
   // optional form component to use (defaults to primitive HTML form)
-  // also, is used to inject your own hooks and components
-  // for all RhfUtilsZodForm instances
-  FormComponent: (
+  FormComponent: Form.Root,
+
+  // inject your own hooks and components
+  // into all RhfUtilsZodForm instances
+  FormChildren: (
     // RhfUtilsFormComponentProps
     {
-      formProps, //       computed form props
       formId, //          unique id string
-      formRef, //         ref
+      formRef, //         form element ref
       context, //         rhf UseFormReturn (without proxy `formState`)
       options, //         RhfUtilsFormOptions (with any custom props)
       Controller, //      rhf controller (SafeFieldValues-typed; no schema at this level)
@@ -96,13 +97,13 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
     });
 
     return (
-      <Form.Root {...formProps} ref={formRef}>
+      <>
         {/* RhfUtilsZodForm.Children "outlet" (see "Component Hierarchy" section) */}
         {children}
 
         {/* root errors list */}
         <RootErrorsList />
-      </Form.Root>
+      </>
     );
   },
 
@@ -179,17 +180,18 @@ Currently, only `zod` schemas are supported.
   // cancel handler (passed to `Children` below)
   // execution routed through `RhfUtilsClientConfig.useCanFormBeCancelled`, if provided
   onCancel={handleCancel}
-  // submit handlers
+  // SUBMIT HANDLERS
+  // invariants
   onBeforeSubmitInvariants={async (
     { input, output, api }, // schema input (form values), output; api data (via getApiData)
     context, //                UseRhfUtilsFormOnSubmitContext (id, ref, rhf context (without proxy formState), utils options, schema-typed FormSubmitError class)
     event, //                  SubmitEvent
   ) => [
-    [
-      'passwordConfirm', // type safe
-      'Passwords must match.',
-      data.password === data.passwordConfirm,
-    ],
+    {
+      field: 'passwordConfirm', // type safe
+      message: 'Passwords must match.',
+      valid: data.password === data.passwordConfirm,
+    },
   ]}
   onBeforeSubmit={({ input, output, api }, context, event) => {
     if (!isValid(input.email))
@@ -326,7 +328,7 @@ Sometimes you need to control the nesting of the Form element. For example, to a
 </aside>
 ```
 
-For similar pattern, especially across more than one form, see [Form State Relay](#form-state-relay) section.
+To access forms' state outside its respective context, including in aggregate across more than one form, see [Form State Relay](#form-state-relay) section.
 
 ## `FormSubmitError`
 
@@ -382,7 +384,9 @@ type RhfUtilsFormOptions = {
 };
 ```
 
-If you need access to options deeper in your component structure, use `useRhfUtilsContext` to receive `RhfUtilsContext` object, which includes `formId`, `formRef`, and `options` settings.
+If you need access to options deeper in your component structure, use `useRhfUtilsContext` to receive `RhfUtilsContext` object, which includes `formId`, `formRef`, `options`, and `lastSubmitStateRef`.
+
+`lastSubmitStateRef` (a ref with possible value of `null | 'submitting' | 'success' | 'error'`) conveys current submit state via ref -- i.e., without needing to wait for next render cycle. If your form navigates away via `onSubmitSuccess`, RHF's `useFormContext` still shows form as `isDirty` and `isSubmitting`, which makes it difficult to distinguish from a user-initiated navigation before form is submitted successfully.
 
 Use `useRhfUtilsContextRequestSubmit` hook to get `requestSubmit` function for current form ref in context. This is useful when you need to trigger form submission programatically.
 
@@ -396,7 +400,7 @@ import '@paragrav/rhf-utils';
 declare module '@paragrav/rhf-utils' {
   export interface Register {
     RhfUtilsFormOptions: {
-      /** Custom props for your custom options/hooks/behaviors. */
+      /** Custom props for your custom options/hooks/behaviors per form instance. */
       enableMyPrompter?: boolean;
       enableMyOptionalFormHook?: boolean;
       configMyOptionalFormHook?: MyCustomFormHookConfig;
@@ -405,99 +409,56 @@ declare module '@paragrav/rhf-utils' {
 }
 ```
 
-## <a id="form-state-relay" /> Form State Relay _(~1.2kB min+gzip)_
+## <a id="form-state-relay"></a> Form State Relay
 
-Sometimes you need to access one or more forms' state outside the form (and its providers).
+Sometimes you need to access one or more forms' state outside its respective context.
 
-### Single form state
-
-Use case: display a form's errors (or any other state) outside form and its context.
-
-```tsx
-<FormStateRelayContextProvider> // relay provider
-  <ReactHookForm.FormProvider>  // rhf provider
-    <FormStateRelayPusher />    // push form state
-  <ReactHookForm.FormProvider>
-
-  <WatchOutsideFormContext />   // watch form state
-</FormStateRelayContextProvider>;
-```
-
-Push can be configured via `FormStateRelayPusher` component or `useFormStateRelayPush` hook with `FormStateRelayPushOptions` options.
+`FormRelayContextProvider` is included by default, but form's state is only relayed with opted-in. Configuration is done per form instance via `relay` prop.
 
 ```ts
-type FormStateRelayPushOptions = {
-  group?: string | string[]; // assign group(s) to watch multiple forms in aggregate
-  flaggedState?: {
-    isMounted?: true; // flag form when mounted -- e.g., forms that are hidden by default
-  };
-};
-```
-
-```tsx
-function WatchOutsideFormContext() {
-  // FormStateWithUtils (either via RHF -- when requested within form context -- or relay when not)
-  const formState = useFormStateWithUtilsViaRhfOrRelay();
-}
+type FormRelayOptions = {
+  /**
+   * Determines what part of RHF's form state is relayed.
+   * Also acts to activate RHF proxy values.
+   */
+  select: (formState: FormState<SafeFieldValues>) => FormRelayStateSelected;
 
-// when watching a single form, original RHF FormState with generally-typed SafeFieldValues
-type FormStateRelayed = FormState<SafeFieldValues>;
+  /**
+   * Arbitrary group name(s) for this form.
+   * Think of it like class or category names.
+   * (e.g., "parent" or "children")
+   */
+  groups?: string[];
+};
 ```
 
-The `useFormStateWithUtilsViaRhfOrRelay` hook uses `useFormStateRelayPullOnlyOrThrow` internally. It provides additional naivety when consumer doesn't know which context between RHF or Relay is present. (This is useful when building base components -- e.g., buttons -- which may exist outside of form context.)
+There are two main ways to get form state that has been relayed.
 
-### Multiple forms
+### Get form relay by id
 
-Use cases:
+You can retrieve a singular form's relay state via `useFormRelayId(formId)`. This will return a `FormRelay` object with that form's selected state (`FormRelayStateSelected`), options (`FormRelayOptions`), and utils (`RhfUtilsContext`).
 
-- disable parent form when ANY child is "flagged" (i.e., dirty)
-- disable ALL children when parent is "flagged" (i.e., submitting)
-- confirm navigation when ANY mounted form is "flagged" (i.e., dirty)
+### Get form relay by group
 
-```tsx
-function ParentForm() {
-  const childrenFormState = useFormStateRelayWatchGroup('children'); // FormStateRelayedAggregated
-
-  return (
-    <ReactHookForm.FormProvider>
-      <FormStateRelayPusher formId="parent" /> // pusher
-      <input type="submit" disabled={childrenFormState.isDirty} />
-    </ReactHookForm.FormProvider>
-  );
-}
+When retrieving by group, state is merged into a `FormRelayGroup` object (and no options or utils are provided, as these are form-specific).
 
-function ChildForm() {
-  const parentFormState = useFormStateRelayWatchId('parent'); // FormStateRelayed
+Use `useFormRelayGroup(callback)` and providing a callback that is is supplied with options (`FormRelayOptions`) and utils (`RhfUtilsContext`) of each form registered to relay, in order for you to determine whether it should be included in this arbitrary "group".
 
-  return (
-    <ReactHookForm.FormProvider>
-      <FormStateRelayPusher group="children" /> // pusher
-      <input type="submit" disabled={parentFormState.isSubmitting} />
-    </ReactHookForm.FormProvider>
-  );
-}
+You can also use `FormRelayGrouperContextProvider` if you want to make this group accessible via naive hook.
 
-type FormStateRelayedAggregated = FormStateRelayed & {
-  // object values reduced to booleans for non-empty-ness
-  dirtyFields: boolean;
-  touchedFields: boolean;
-  validatingFields: boolean;
-  error: boolean;
-  // composites
-  isSubmitUnsuccessful: boolean;
-  isMountedFlagged: boolean; // via RelayedFormOptions['flaggedState']['isMounted']
-};
+```tsx
+<FormRelayGrouperContextProvider
+  predicate={({ options, utils }) =>
+    !!options?.groups?.includes("parent") // find specific group
+  }
+>
+  {(state: FormRelayGroup) => ()}
+</FormRelayGrouperContextProvider>
 ```
 
-You can also aggregate any (i.e., all) forms via `useFormStateRelayPullAny`, which returns `FormStateRelayedAggregated` as well.
+Alternatively, instead render callback, you can use `useFormRelayGrouper`.
 
-```tsx
-<FormStateRelayContextProvider>
-  <ParentForm />
-  <ChildForm />
-  <Child2Form />
-</FormStateRelayContextProvider>
-```
+If you want to build some components to be independent of any one specific context -- i.e., RHF's context, `FormRelayGrouperContext`, or `FormRelayContext` -- you can use `useFirstFormStateGroup` to get `FormRelayGroup` from nearest available context. (If RHF's context is found, its singular state is transformed to `FormRelayGroup`.)
 
 ## Field Errors
 

package/dist/dts/_exports/relay.d.ts

@@ -1,8 +1,7 @@
-export { FormStateRelayContextProvider } from '../form/state/relay/FormStateRelayContextProvider';
-export type { FormStateRelayedAggregated } from '../form/state/relay/FormStateRelayedAggregatedType';
-export type { FormStateRelayedItemWithUtils } from '../form/state/relay/FormStateRelayedItemType';
-export type { FormStateRelayedOptions } from '../form/state/relay/FormStateRelayedOptionsType';
-export type { FormStateRelayed } from '../form/state/relay/FormStateRelayedType';
-export { useFormStateRelayPullAny, useFormStateRelayPullById, useFormStateRelayPullGroup, useFormStateRelayPullOnlyOrThrow, useFormStateWithUtilsViaRhfOrRelay, } from '../form/state/relay/pull/hooks';
-export { FormStateRelayPusher } from '../form/state/relay/push/FormStateRelayPusher';
-export { useFormStateRelayPusher } from '../form/state/relay/push/useFormStateRelayPusher';
+export { FormRelayContextProvider } from '../form/relay/context/FormRelayContextProvider';
+export type { FormRelayGroup } from '../form/relay/get/FormRelayGroupType';
+export { useFirstFormStateGroup } from '../form/relay/get/grouper/useFirstFormStateGroup';
+export { useFormRelayGroup, useFormRelayId, } from '../form/relay/get/useFormRelay';
+export { FormRelaySetter } from '../form/relay/set/FormRelaySetter';
+export { useFormRelaySet } from '../form/relay/set/useFormRelaySet';
+export type { FormRelay, FormRelayStateSelected } from '../form/relay/types';

package/dist/dts/_exports/types.d.ts

@@ -4,3 +4,4 @@ export type * from './relay';
 export type * from './submit';
 export type * from './trpc';
 export type * from './zod';
+export type { FlatFieldErrors } from '../errors/flat/types';

package/dist/dts/client/config/RhfUtilsClientConfigType.d.ts

@@ -15,15 +15,19 @@ export type RhfUtilsClientConfig = {
      */
     defaults?: UseRhfUtilsFormGlobalDefaults;
     /**
-     * Supply your own `<form>` component. (By default, a native {@link HTMLFormElement} is used.)
+     * Supply your own `<form>` component.
      *
-     * @description
+     * (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.
      *
-     * Can be used to inject your own hooks, components, etc.
+     * @description
      *
      * (NOTE: context params are not schema-typed as not possible at this level.)
      */
-    FormComponent?: React.FC<React.PropsWithChildren<RhfUtilsFormComponentProps>>;
+    FormChildren?: React.FC<React.PropsWithChildren<RhfUtilsFormComponentProps>>;
     /**
      * A hook that returns a callback that determines whether form can be cancelled at event-time.
      *

package/dist/dts/errors/flat/getFlatFieldErrors.d.ts

@@ -1,4 +1,5 @@
 import { FieldError, FieldErrors } from 'react-hook-form';
+import { SafeFieldValues } from '../../form/rhf/SafeFieldValuesType';
 import { FlatFieldErrors } from './types';
 /**
  * Get {@link FlatFieldErrors} from {@link FieldErrors}.
@@ -28,4 +29,7 @@ export declare const getFlatFieldErrors: (errors: FieldErrors) => FlatFieldError
  * iow: dot [?: non-capturing]("type" | "message")[\b word boundary][$ end of string]
  */
 export declare const regexMaybeFieldErrorLeafNodeSuffix: RegExp;
-export declare const getFlatFieldErrorsSansRef: (errors: FieldErrors) => Record<string, Omit<FieldError, "ref">>;
+export type FieldErrorsSansRef<TFieldValues extends SafeFieldValues = SafeFieldValues> = Record<keyof TFieldValues | 'root', Partial<Pick<FieldError, 'message' | 'type'>> & {
+    hasRef: boolean;
+}>;
+export declare const getFlatFieldErrorsSansRef: <TFieldValues extends SafeFieldValues>(errors: FieldErrors<TFieldValues>) => FieldErrorsSansRef<TFieldValues>;

package/dist/dts/form/RhfUtilsFormComponentPropsType.d.ts

@@ -1,17 +1,13 @@
 import { UseFormReturn } from 'react-hook-form';
 import { FormSubmitError } from '../submit/error/FormSubmitError';
 import { _Controller } from './_Controller';
-import { RhfUtilsContextProps } from './context/utils/RhfUtilsContextPropsType';
-import { UseRhfUtilsFormInstanceFormProps } from './defaults/form/UseRhfUtilsFormInstanceFormProps';
+import { RhfUtilsContext } from './context/utils/RhfUtilsContextType';
 import { SafeFieldValues } from './rhf/SafeFieldValuesType';
 /**
  * RhfUtilsClientConfig's FormComponent props.
  */
-export type RhfUtilsFormComponentProps<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = TFieldValues> = RhfUtilsContextProps & {
+export type RhfUtilsFormComponentProps<TFieldValues extends SafeFieldValues = SafeFieldValues, TTransformedValues extends SafeFieldValues = TFieldValues> = RhfUtilsContext & {
     rhf: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
-    formProps: UseRhfUtilsFormInstanceFormProps & {
-        onSubmit: NonNullable<React.PropsWithoutRef<React.JSX.IntrinsicElements['form']>['onSubmit']>;
-    };
     Controller: typeof _Controller<TFieldValues>;
     FormSubmitError: typeof FormSubmitError<TFieldValues>;
 };

package/dist/dts/form/UseRhfUtilsFormChildrenPropsType.d.ts

@@ -2,7 +2,7 @@ import { UseFormReturn } from 'react-hook-form';
 import { FormSubmitError } from '../submit/error/FormSubmitError';
 import { MaybePromise } from '../utils/types';
 import { _Controller } from './_Controller';
-import { RhfUtilsContextProps } from './context/utils/RhfUtilsContextPropsType';
+import { RhfUtilsContext } from './context/utils/RhfUtilsContextType';
 import { RhfUtilsFormOptions } from './options/RhfUtilsFormOptionsType';
 import { SafeFieldValues } from './rhf/SafeFieldValuesType';
 /**
@@ -10,7 +10,7 @@ import { SafeFieldValues } from './rhf/SafeFieldValuesType';
  *
  * (Consider keeping shape in line with `UseRhfUtilsFormOnSubmitProps` and `UseRhfUtilsFormReturn`.)
  */
-export type UseRhfUtilsFormChildrenProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues, TProps = undefined> = RhfUtilsContextProps & {
+export type UseRhfUtilsFormChildrenProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues, TProps = undefined> = RhfUtilsContext & {
     rhf: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
     options: RhfUtilsFormOptions;
     Controller: typeof _Controller<TFieldValues>;

package/dist/dts/form/context/utils/LastSubmitStateType.d.ts

@@ -0,0 +1 @@
+export type LastSubmitState = null | 'submitting' | 'success' | 'error';

package/dist/dts/form/context/utils/{RhfUtilsContextPropsType.d.ts → RhfUtilsContextType.d.ts}

@@ -1,11 +1,12 @@
 import { RefObject } from 'react';
+import { LastSubmitState } from './LastSubmitStateType';
 import { RhfUtilsContextProviderProps } from './RhfUtilsContextProvider';
-export type RhfUtilsContextProps = RhfUtilsContextProviderProps & {
+export 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<null | 'submitting' | 'success' | 'error'>;
+    lastSubmitStateRef: RefObject<LastSubmitState>;
 };

package/dist/dts/form/context/utils/useRhfUtilsContext.d.ts

@@ -1,5 +1,5 @@
-import { RhfUtilsContextProps } from './RhfUtilsContextPropsType';
-declare const _RhfUtilsContextProvider: import('react').Provider<RhfUtilsContextProps | undefined>, useRhfUtilsContext: () => import('./RhfUtilsContextProvider').RhfUtilsContextProviderProps & {
-    lastSubmitStateRef: import('react').RefObject<null | "submitting" | "success" | "error">;
-}, useRhfUtilsMaybeContext: () => RhfUtilsContextProps | undefined;
+import { RhfUtilsContext } from './RhfUtilsContextType';
+declare const _RhfUtilsContextProvider: import('react').Provider<RhfUtilsContext | undefined>, useRhfUtilsContext: () => import('./RhfUtilsContextProvider').RhfUtilsContextProviderProps & {
+    lastSubmitStateRef: import('react').RefObject<import('./LastSubmitStateType').LastSubmitState>;
+}, useRhfUtilsMaybeContext: () => RhfUtilsContext | undefined;
 export { _RhfUtilsContextProvider, useRhfUtilsContext, useRhfUtilsMaybeContext, };

package/dist/dts/form/defaults/form/useRhfUtilsFormResolvedFormProps.d.ts

@@ -30,7 +30,7 @@ export declare const useRhfUtilsFormResolvedFormProps: (formProps: UseRhfUtilsFo
     inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined | undefined;
     nonce?: string | undefined | undefined;
     tabIndex?: number | undefined | undefined;
-    onChange?: import('react').FormEventHandler<HTMLFormElement> | undefined;
+    onChange?: import('react').ChangeEventHandler<HTMLFormElement, Element> | undefined;
     onBlur?: import('react').FocusEventHandler<HTMLFormElement> | undefined;
     key?: import('react').Key | null | undefined;
     autoComplete?: string | undefined | undefined;
@@ -139,16 +139,16 @@ export declare const useRhfUtilsFormResolvedFormProps: (formProps: UseRhfUtilsFo
     onFocus?: import('react').FocusEventHandler<HTMLFormElement> | undefined;
     onFocusCapture?: import('react').FocusEventHandler<HTMLFormElement> | undefined;
     onBlurCapture?: import('react').FocusEventHandler<HTMLFormElement> | undefined;
-    onChangeCapture?: import('react').FormEventHandler<HTMLFormElement> | undefined;
+    onChangeCapture?: import('react').ChangeEventHandler<HTMLFormElement, Element> | undefined;
     onBeforeInput?: import('react').InputEventHandler<HTMLFormElement> | undefined;
-    onBeforeInputCapture?: import('react').FormEventHandler<HTMLFormElement> | undefined;
-    onInput?: import('react').FormEventHandler<HTMLFormElement> | undefined;
-    onInputCapture?: import('react').FormEventHandler<HTMLFormElement> | undefined;
-    onReset?: import('react').FormEventHandler<HTMLFormElement> | undefined;
-    onResetCapture?: import('react').FormEventHandler<HTMLFormElement> | undefined;
-    onSubmitCapture?: import('react').FormEventHandler<HTMLFormElement> | undefined;
-    onInvalid?: import('react').FormEventHandler<HTMLFormElement> | undefined;
-    onInvalidCapture?: import('react').FormEventHandler<HTMLFormElement> | undefined;
+    onBeforeInputCapture?: import('react').InputEventHandler<HTMLFormElement> | undefined;
+    onInput?: import('react').InputEventHandler<HTMLFormElement> | undefined;
+    onInputCapture?: import('react').InputEventHandler<HTMLFormElement> | undefined;
+    onReset?: import('react').ReactEventHandler<HTMLFormElement> | undefined;
+    onResetCapture?: import('react').ReactEventHandler<HTMLFormElement> | undefined;
+    onSubmitCapture?: import('react').SubmitEventHandler<HTMLFormElement> | undefined;
+    onInvalid?: import('react').ReactEventHandler<HTMLFormElement> | undefined;
+    onInvalidCapture?: import('react').ReactEventHandler<HTMLFormElement> | undefined;
     onLoad?: import('react').ReactEventHandler<HTMLFormElement> | undefined;
     onLoadCapture?: import('react').ReactEventHandler<HTMLFormElement> | undefined;
     onError?: import('react').ReactEventHandler<HTMLFormElement> | undefined;

package/dist/dts/form/providers/RhfUtilsFormProviders.d.ts

@@ -2,5 +2,5 @@ import { default as React } from 'react';
 import { SafeFieldValues } from '../rhf/SafeFieldValuesType';
 import { RhfUtilsFormProvidersProps } from './RhfUtilsFormProvidersPropsType';
 type Props<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = React.PropsWithChildren<RhfUtilsFormProvidersProps<TFieldValues, TTransformedValues>>;
-export declare function RhfUtilsFormProviders<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ formId, rhf, resolver, defaultValues, options, children, }: Props<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+export declare function RhfUtilsFormProviders<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ formId, rhf, resolver, defaultValues, options, relay, children, }: Props<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/dts/form/providers/RhfUtilsFormProvidersPropsType.d.ts

@@ -1,5 +1,6 @@
 import { Resolver, UseFormProps } from 'react-hook-form';
 import { RhfUtilsFormOptions } from '../options/RhfUtilsFormOptionsType';
+import { FormRelayOptions } from '../relay/FormRelayOptions';
 import { SafeFieldValues } from '../rhf/SafeFieldValuesType';
 import { RhfUseFormInstanceProps } from '../rhf/UseFormPropsType';
 /**
@@ -12,4 +13,5 @@ export type RhfUtilsFormProvidersProps<TFieldValues extends SafeFieldValues, TTr
     rhf?: RhfUseFormInstanceProps<TFieldValues, TTransformedValues>;
     defaultValues?: UseFormProps<TFieldValues, unknown, TTransformedValues>['defaultValues'];
     options?: RhfUtilsFormOptions;
+    relay?: FormRelayOptions;
 };

package/dist/dts/form/relay/FormRelayOptions.d.ts

@@ -0,0 +1,16 @@
+import { FormState } from 'react-hook-form';
+import { SafeFieldValues } from '../rhf/SafeFieldValuesType';
+import { FormRelayStateSelected } from './types';
+export 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[];
+};

package/dist/dts/form/{state/relay/FormStateRelayContextProvider.d.ts → relay/context/FormRelayContextProvider.d.ts}

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
 type Props = React.PropsWithChildren;
-export declare const FormStateRelayContextProvider: React.FC<Props>;
+export declare const FormRelayContextProvider: React.FC<Props>;
 export {};

package/dist/dts/form/relay/context/useFormRelayContext.d.ts

@@ -0,0 +1,12 @@
+import { RhfUtilsContext } from '../../context/utils/RhfUtilsContextType';
+import { FormRelayOptions } from '../FormRelayOptions';
+import { FormRelay, FormRelayStateSelected } from '../types';
+export type FormsRelayed = Record<string, // form id
+FormRelay>;
+export type FormRelayContext = {
+    add: (state: FormRelayStateSelected, utils: RhfUtilsContext, options: FormRelayOptions) => void;
+    update: (id: string, state: FormRelayStateSelected) => void;
+    remove: (id: string) => void;
+    state: FormsRelayed;
+};
+export declare const _FormRelayContextProvider: import('react').Provider<FormRelayContext | undefined>, useFormRelayContext: () => FormRelayContext;

package/dist/dts/form/relay/context/utils.d.ts

@@ -0,0 +1,4 @@
+import { FormRelayGroup } from '../get/FormRelayGroupType';
+import { FormRelayStateSelected } from '../types';
+/** Condense list of form states to singular booleans. */
+export declare const getFormRelayedAggregatedByRelayedItem: (formStates: FormRelayStateSelected[]) => FormRelayGroup;

package/dist/dts/form/relay/get/FormRelayGroupType.d.ts

@@ -0,0 +1,16 @@
+import { FormState } from 'react-hook-form';
+import { SafeFieldValues } from '../../rhf/SafeFieldValuesType';
+export type FormRelayGroup = Partial<Omit<FormState<SafeFieldValues>, 'defaultValues' | 'dirtyFields' | 'touchedFields' | 'validatingFields' | 'errors' | 'submitErrors'> & {
+    hasErrors: boolean;
+    hasDirtyFields: boolean;
+    hasTouchedFields: boolean;
+    hasValidatingFields: boolean;
+    /** Sum of all submit counts. */
+    submitCount: number;
+    /**
+     * Consider form flagged when mounted.
+     *
+     * (To use, return via `FormRelayOptions`'s `select`'s return's `FormRelayStateSelected`'s `isMounted` property.)
+     */
+    isMounted: boolean;
+}>;

package/dist/dts/form/relay/get/grouper/context/hooks.d.ts

@@ -0,0 +1,8 @@
+export declare const useFormRelayGrouper: () => Partial<Omit<import('react-hook-form').FormState<import('../../../../rhf/SafeFieldValuesType').SafeFieldValues>, "defaultValues" | "errors" | "dirtyFields" | "touchedFields" | "validatingFields" | "submitErrors"> & {
+    hasErrors: boolean;
+    hasDirtyFields: boolean;
+    hasTouchedFields: boolean;
+    hasValidatingFields: boolean;
+    submitCount: number;
+    isMounted: boolean;
+}>;

package/dist/dts/form/relay/get/grouper/context/index.d.ts

@@ -0,0 +1,5 @@
+import { FormRelayGroup } from '../../FormRelayGroupType';
+export type FormRelayGrouperContext = {
+    state: FormRelayGroup;
+};
+export declare const _FormRelayGrouperContextProvider: import('react').Provider<FormRelayGrouperContext | undefined>, _useFormRelayGrouperContext: () => FormRelayGrouperContext, _useFormRelayGrouperMaybeContext: () => FormRelayGrouperContext | undefined;

package/dist/dts/form/relay/get/grouper/context/provider.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { FormRelayGroup } from '../../FormRelayGroupType';
+import { FormRelayGroupCriteria } from '../../useFormRelay';
+type Props = {
+    criteria: FormRelayGroupCriteria;
+    children: ((state: FormRelayGroup) => React.ReactNode) | React.ReactNode;
+};
+export declare const FormRelayGrouperContextProvider: React.FC<Props>;
+export {};

package/dist/dts/form/relay/get/grouper/useFirstFormStateGroup.d.ts

@@ -0,0 +1,9 @@
+import { FormRelayGroup } from '../FormRelayGroupType';
+/**
+ * Use this when you don't (want to) know whether component is wrapped
+ * with RHF context, `FormRelayGrouperContext`, or `FormRelayContext`.
+ * Will return `FormRelayGroup`, regardless.
+ *
+ * Allows you to build naive components that are not tied to one specific context.
+ */
+export declare const useFirstFormStateGroup: () => FormRelayGroup;

package/dist/dts/form/relay/get/useFormRelay.d.ts

@@ -0,0 +1,13 @@
+import { RhfUtilsFormOptions } from '../../options/RhfUtilsFormOptionsType';
+import { FormRelayOptions } from '../FormRelayOptions';
+import { FormRelayGroup } from './FormRelayGroupType';
+export declare const useFormRelayId: (formId: string) => import('../types').FormRelay | undefined;
+export type FormRelayGroupCriteria = {
+    groups: string[];
+} | {
+    predicate: (context: {
+        groups: FormRelayOptions['groups'];
+        options: RhfUtilsFormOptions;
+    }) => boolean;
+};
+export declare const useFormRelayGroup: (criteria?: FormRelayGroupCriteria) => FormRelayGroup;

package/dist/dts/form/relay/set/FormRelaySetter.d.ts

@@ -0,0 +1,6 @@
+import { FormRelayOptions } from '../FormRelayOptions';
+type Props = {
+    options?: FormRelayOptions;
+};
+export declare const FormRelaySetter: React.FC<Props>;
+export {};

package/dist/dts/form/relay/set/useFormRelaySet.d.ts

@@ -0,0 +1,2 @@
+import { FormRelayOptions } from '../FormRelayOptions';
+export declare const useFormRelaySet: (options?: FormRelayOptions) => void;

package/dist/dts/form/relay/types.d.ts

@@ -0,0 +1,12 @@
+import { FormState } from 'react-hook-form';
+import { RhfUtilsContext } from '../context/utils/RhfUtilsContextType';
+import { SafeFieldValues } from '../rhf/SafeFieldValuesType';
+import { FormRelayOptions } from './FormRelayOptions';
+export type FormRelay<TFieldValues extends SafeFieldValues = SafeFieldValues> = {
+    state: FormRelayStateSelected<TFieldValues>;
+    options: FormRelayOptions;
+    utils: RhfUtilsContext;
+};
+export type FormRelayStateSelected<TFieldValues extends SafeFieldValues = SafeFieldValues> = Partial<FormState<TFieldValues> & {
+    isMounted: true;
+}>;

package/dist/dts/form/with-handlers-and-children/RhfUtilsFormProps.d.ts

@@ -9,7 +9,11 @@ export type RhfUtilsFormPropsonBeforeSubmitInvariants<TFieldValues extends SafeF
     input: TFieldValues;
     output: TTransformedValues;
     api: TApiValues;
-}, context: UseRhfUtilsFormOnSubmitContext<TFieldValues, TTransformedValues, TApiValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => MaybePromise<[keyof TFieldValues | keyof TApiValues, string, unknown][]>;
+}, context: UseRhfUtilsFormOnSubmitContext<TFieldValues, TTransformedValues, TApiValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => MaybePromise<{
+    field: keyof TFieldValues | keyof TApiValues;
+    message: string;
+    valid: boolean | undefined | null;
+}[]>;
 export type RhfUtilsFormProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues, TGetApiValues extends undefined | RhfUtilsFormPropsGetApiValues<TTransformedValues, SafeFieldValues>, TOnSubmitReturnType, TApiValues extends undefined | SafeFieldValues = TGetApiValues extends RhfUtilsFormPropsGetApiValues<TTransformedValues, infer U> ? U : undefined> = {
     getApiData?: TGetApiValues;
     /** Cancellation handler -- channeled through {@link RhfUtilsClientConfig.useCanFormBeCancelled} before propagating to `Children` component. */

package/dist/dts/form/with-handlers-and-children/_useHandleSubmit.d.ts

@@ -7,5 +7,5 @@ type Props<TFieldValues extends SafeFieldValues, TTransformedValues extends Safe
     onError: (error: unknown, event: React.BaseSyntheticEvent) => void;
     onFinally?: () => MaybePromise<unknown>;
 };
-export declare const useRhfUtilsFormHandleSubmit_Internal: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ onValid, onInvalid, onError, onFinally, }: Props<TFieldValues, TTransformedValues>) => ((event: React.FormEvent<HTMLFormElement>) => void);
+export declare const useRhfUtilsFormHandleSubmit_Internal: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ onValid, onInvalid, onError, onFinally, }: Props<TFieldValues, TTransformedValues>) => ((event: React.SubmitEvent<HTMLFormElement>) => void);
 export {};