export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
  defaults: {
    // globally-relevant subset of RHF's `UseFormProps` options
    rhf: {
      mode: 'onSubmit',
    },

    // RhfUtilsFormOptions (see further below)
    utils: {
      stopSubmitPropagation: true,
      devTool: import.meta.env.DEV && { placement: 'top-right' },
    },

    // global default native form props
    form: {
      noValidate: true,
      className: 'my-form-class',
    },
  },

  // 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: (
    // RhfUtilsFormComponentProps
    {
      formProps, //       computed form props
      formId, //          unique id string
      formRef, //         ref
      context, //         rhf UseFormReturn (without proxy `formState`)
      options, //         RhfUtilsFormOptions (with any custom props)
      Controller, //      rhf controller (SafeFieldValues-typed; no schema at this level)
      FormSubmitError, // error class (SafeFieldValues-typed; no schema at this level)
      children, //        RhfUtilsZodForm's Children instance
    },
  ) => {
    useMyGlobalFormHook();

    // form-level control of your own hooks/behaviors via custom option props
    // (see "Extend RhfUtilsFormOptions" section for more info)
    useMyOptionalFormHook({
      enabled: !!options.enableMyOptionalFormHook,
    });

    return (
      <Form.Root {...formProps} ref={formRef}>
        {/* RhfUtilsZodForm.Children "outlet" (see "Component Hierarchy" section) */}
        {children}

        {/* root errors list */}
        <RootErrorsList />
      </Form.Root>
    );
  },

  // hook that returns callback to determine whether form can be cancelled
  // if `true`, `RhfUtilsZodForm.onCancel` at form-level is called (e.g., parent component hides form)
  // this allows you to handle non-navigational blocking/prompting
  // NOTE: this library is router-agnostic, so navigation blocking should happen elsewhere
  // (i.e., calling your own hook in `FormComponent`)
  useCanFormBeCancelled: () => {
    const { isDirty } = useFormState();

    // return callback to be called at event-time
    return ({ options }) =>
      !options.enableMyPrompter || // my prompter option not enabled
      !isDirty || // or rhf form state not dirty
      confirm('Are you sure you want to cancel?'); // or user confirms
  },

  // non-FormSubmitError thrown in onSubmit
  // use case: handle and transform server error data for frontend
  onSubmitErrorUnknown: (
    error, // unknown
  ) => {
    // return FormSubmitFieldErrors object to be merged to RHF context errors
    if (isMyServerError(error))
      return transformMyServerErrorToFormSubmitFieldErrors(error);
  },

  // RHF FormState.errors output for debugging
  fieldErrors: {
    // callbacks to determine when to output information about field errors
    // provided `FlatFieldErrorsContext` (all, fields, roots, orphans, hasOrphans)
    // (See "Orphan Errors" section below for more info.)
    output: {
      // determine when to console ("debug" or "error")
      console: ({ hasOrphans }) =>
        // facilitate local debugging of form validation
        (import.meta.env.DEV && { type: 'debug' }) ||
        // console error for reporting on prod
        (hasOrphans && { type: 'error' }),

      // callback to determine when to throw an error based on field errors
      throw: ({ hasOrphans }) =>
        // bring attention to orphans locally
        import.meta.env.DEV && hasOrphans,
    },
  },
};

<RhfUtilsClientConfigProvider config={rhfUtilsClientConfig}>
  {children}
</RhfUtilsClientConfigProvider>

<RhfUtilsZodFormWithProviders
  schema={z.object({
    email: z.string().min(1).email(),
    password: z.string().min(1),
    passwordConfirm: z.string().min(1),
  })}
  defaultValues={{ email: '', password: '', passwordConfirm: '' }}
  getApiData={({ email, password }) => ({ email, password })}
  // cancel handler (passed to `Children` below)
  // execution routed through `RhfUtilsClientConfig.useCanFormBeCancelled`, if provided
  onCancel={handleCancel}
  // submit handlers
  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,
    ],
  ]}
  onBeforeSubmit={({ input, output, api }, context, event) => {
    if (!isValid(input.email))
      throw new context.FormSubmitError({
        email: { message: 'Email is invalid.' },
      });
  }}
  // submit handler
  onSubmit={({ input, output, api }, context, event) => registerService(api)}
  onSubmitSuccess={(onSubmitResult, { input, output, api }, context, event) =>
    navigate('/app/' + onSubmitResult.id)
  }
  // handle error declaratively (i.e., no throw/catch)
  onSubmitError={({ error, context, event }) => {
    handleError(error);
  }}
  onSubmitFinally={() => {
    setState();
  }}
  // form-specific options/overrides (merged with defaults)
  rhf={{
    mode: 'onBlur',
  }}
  utils={{
    submitOnWatch: { debounce: 250 },
    // custom option props
    // (see "Extend RhfUtilsFormOptions" section)
    enableMyOptionalFormHook: true,
  }}
  // surfaced form element attributes
  id="my-form"
  className="my-special-form-class" // merged with global defaults
  // other form element attributes
  form={{ noValidate: true }} // merged with global defaults
  // fields
  Children={({
    // UseRhfUtilsFormChildrenProps
    formId, //          unique id string
    formRef, //         ref
    context, //         rhf UseFormReturn (without proxy `formState`)
    options, //         RhfUtilsFormOptions
    Controller, //      schema-typed rhf controller
    FormSubmitError, // schema-typed error class
    onCancel, //        wrapped cancel handler from above
  }) => (
    <>
      <Controller
        name="email" // schema-typed field name
        render={({ field, formState: { isSubmitting } }) => (
          <Stack>
            <label>
              Email
              <input {...field} disabled={isSubmitting} />
            </label>

            <ErrorMessage path={field.name} />
          </Stack>
        )}
      />

      <button type="button" onClick={onCancel}>
        Cancel
      </button>
      <button type="submit">Login</button>
    </>
  )}
/>

const Children: RhfUtilsUseZodFormChildrenFC<
  typeof schema,
  { onEvent: () => void } // other props (if required)
> = ({ ... }) => {};

// or

function Children({ ... }: RhfUtilsUseZodFormChildrenProps<
  typeof schema,
  { onEvent: () => void } // other props (if required)
>) {}

<RhfUtilsZodFormWithProviders
  Children={(rhfUtilsZodFormChildrenProps) => (
    <Children
      {...rhfUtilsZodFormChildrenProps}
      props={{ onEvent: handleEvent }}
    />
  )}
/>

<ReactHookForm.FormProvider>             // standard rhf provider
  <RhfUtilsProviders>                    // rhf utils internal providers
    <RhfUtilsClientConfig.FormComponent> // from global config (if provided)
      <RhfUtilsZodForm.Children />       // form instance component prop
    </RhfUtilsClientConfig.FormComponent>
  <RhfUtilsProviders>
</ReactHookForm.FormProvider>

<aside>
  <RhfUtilsZodFormProviders>
    <main>
      <RhfUtilsZodForm id="my-form" />
    </main>

    <footer>
      <SubmitButton form="my-form">

      <MyFormErrorsViaProviders>
    </footer>
  </RhfUtilsZodFormProviders>
</aside>

<RhfUtilsZodFormWithProviders
  onBeforeSubmit={async ({ input, output, api }, { FormSubmitError }) => {
    if (!isValid(data))
      throw new FormSubmitError({
        'street.address': { message: 'Street address invalid.' },
      });
  }}
/>

import '@paragrav/rhf-utils';

declare module '@paragrav/rhf-utils' {
  export interface Register {
    RhfUtilsFormOptions: {
      /** Custom props for your custom options/hooks/behaviors. */
      enableMyPrompter?: boolean;
      enableMyOptionalFormHook?: boolean;
      configMyOptionalFormHook?: MyCustomFormHookConfig;
    };
  }
}

<FormStateRelayContextProvider> // relay provider
  <ReactHookForm.FormProvider>  // rhf provider
    <FormStateRelayPusher />    // push form state
  <ReactHookForm.FormProvider>

  <WatchOutsideFormContext />   // watch form state
</FormStateRelayContextProvider>;

function WatchOutsideFormContext() {
  const formStateRelayWatch = useFormStateRelayWatchOnlyOrThrow(); // FormStateRelayed (for single relay watch)
}

// when watching a single form, original RHF FormState with generally-typed SafeFieldValues
type FormStateRelayed = FormState<SafeFieldValues>;

function ParentForm() {
  const childrenFormState = useFormStateRelayWatchGroup('children'); // FormStateRelayedAggregated

  return (
    <ReactHookForm.FormProvider>
      <FormStateRelayPusher formId="parent" /> // pusher
      <input type="submit" disabled={childrenFormState.isDirty} />
    </ReactHookForm.FormProvider>
  );
}

function ChildForm() {
  const parentFormState = useFormStateRelayWatchId('parent'); // FormStateRelayed

  return (
    <ReactHookForm.FormProvider>
      <FormStateRelayPusher group="children" /> // pusher
      <input type="submit" disabled={parentFormState.isSubmitting} />
    </ReactHookForm.FormProvider>
  );
}

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']
};

<FormStateRelayContextProvider>
  <ParentForm />
  <ChildForm />
  <Child2Form />
</FormStateRelayContextProvider>

<RhfUtilsNonFieldErrorMarker path="items" />