@paragrav/rhf-utils 0.0.27 → 0.0.30

package/dist/types/errors/root/FormRootErrors.d.ts

@@ -0,0 +1,7 @@
+import { FlatFieldErrors } from '../flat/types';
+
+type Props = React.DetailedHTMLProps<React.HTMLAttributes<HTMLUListElement>, HTMLUListElement> & {
+    errors: FlatFieldErrors;
+};
+declare const FormRootErrors: React.FC<Props>;
+export default FormRootErrors;

package/dist/types/errors/root/consts.d.ts

@@ -0,0 +1 @@
+export declare const FormErrorPathRoot = "root";

package/dist/types/errors/root/getRootFlatFieldErrors.d.ts

@@ -0,0 +1,8 @@
+import { FlatFieldErrors } from '../flat/types';
+import { FieldErrors } from 'react-hook-form';
+
+/**
+ * Pending.
+ */
+declare const getRootFlatFieldErrors: (errors: FieldErrors) => FlatFieldErrors;
+export default getRootFlatFieldErrors;

package/dist/types/errors/root/isFormErrorPathRoot.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Determine if an error path is root. (e.g., `root` or `root.nested`)
+ * @param path Flat path. (e.g., 'root.nested')
+ */
+declare const isFormErrorPathRoot: (path: string) => boolean;
+export default isFormErrorPathRoot;

package/dist/types/errors/root/useRootFormFieldErrorsMemo.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Root field errors from form.
+ * These are typically displayed at the bottom of the form.
+ */
+declare const useRootFormFieldErrorsMemo: () => import('../flat/types').FlatFieldErrors;
+export default useRootFormFieldErrorsMemo;

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

@@ -4,5 +4,5 @@
  *
  * `console.debug()` is unlikely to trigger any automated console capture reporting.
  */
-declare const useFormErrorConsoleDebug: (condition: boolean) => void;
+declare const useFormErrorConsoleDebug: (enabled?: boolean) => void;
 export default useFormErrorConsoleDebug;

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

@@ -0,0 +1,7 @@
+import { FieldErrors } from 'react-hook-form';
+
+/**
+ * Create memoized value from form errors.
+ */
+declare const useFormErrorsMemo: <TReturn>(callback: (errors: FieldErrors) => TReturn) => TReturn;
+export default useFormErrorsMemo;

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

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

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

@@ -0,0 +1,21 @@
+import { FormBaseProps } from './FormBase';
+import { LazyDevToolProps } from '../devtool/LazyDevTool';
+import { FieldValues, SubmitErrorHandler, UseFormReturn } from 'react-hook-form';
+import { default as React } from 'react';
+
+export type FormProps<TFieldValues extends FieldValues, TTransformedValues extends FieldValues> = Omit<FormBaseProps, 'onSubmit'> & {
+    isDev: boolean;
+    formRef: React.RefObject<HTMLFormElement>;
+    onSubmit: (values: TTransformedValues, context: UseFormReturn<TFieldValues, unknown, TTransformedValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => unknown | Promise<unknown>;
+    /** Submit error handler. (Only for errors not of instance `FormError`, which are handled internally.) */
+    onSubmitError?: (error: unknown, values: TTransformedValues, context: UseFormReturn<TFieldValues, unknown, TTransformedValues>, event: React.BaseSyntheticEvent<SubmitEvent>) => void;
+    /** Submit handler when form is invalid. */
+    onSubmitInvalid?: SubmitErrorHandler<TFieldValues>;
+    options?: {
+        disableEmptyRootError?: boolean;
+        devTool?: LazyDevToolProps | 'disabled';
+    };
+    className?: string;
+};
+declare function Form<TFieldValues extends FieldValues, TTransformedValues extends FieldValues>({ isDev, formRef, onSubmit, onSubmitError, onSubmitInvalid, options, children, ...props }: FormProps<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+export default Form;

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

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+
+export type FormBaseProps = React.PropsWithoutRef<JSX.IntrinsicElements['form']> & {
+    antiCsrfToken?: string;
+};
+declare const _default: (props: Omit<React.DetailedHTMLProps<React.FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>, "ref"> & {
+    antiCsrfToken?: string | undefined;
+} & React.RefAttributes<HTMLFormElement>) => React.ReactNode;
+export default _default;

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

@@ -0,0 +1,6 @@
+import { FieldPath, FieldValues } from 'react-hook-form';
+
+export declare class FormError<TFieldValues extends FieldValues> extends Error {
+    errors: Partial<Record<FieldPath<TFieldValues> | `root.${string}`, string>>;
+    constructor(errors: Partial<Record<FieldPath<TFieldValues> | `root.${string}`, string>>, message?: string);
+}

package/dist/types/form/context/FormProvider.d.ts

@@ -0,0 +1,13 @@
+import { FormUtilsContextProviderProps } from './utils/FormUtilsContextProvider';
+import { FormProps } from '../Form';
+import { FieldValues, UseFormReturn } from 'react-hook-form';
+
+type Props<TFieldValues extends FieldValues, // input values
+TTransformedValues extends FieldValues> = React.PropsWithChildren<{
+    ctx: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
+} & {
+    form: FormProps<TFieldValues, TTransformedValues>;
+    utils?: FormUtilsContextProviderProps;
+}>;
+declare function FormProvider<TFieldValues extends FieldValues, TTransformedValues extends FieldValues>({ ctx, form, utils, children }: Props<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+export default FormProvider;

package/dist/types/form/context/parent/FormParentContextProvider.d.ts

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

package/dist/types/form/context/parent/index.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="react" />
+export type FormParentContext = {
+    isBusy: boolean;
+    setIsBusy: (isBusy: boolean) => void;
+};
+export declare const _useFormParentContext: () => FormParentContext | undefined, _FormParentContextProvider: import('react').Provider<FormParentContext | undefined>;

package/dist/types/form/context/parent/useAsFormParentState.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Connect specific form state as parent context.
+ *
+ * Requires usage of provider.
+ */
+declare const useAsFormParentState: () => void;
+export default useAsFormParentState;

package/dist/types/form/context/parent/useFormParentIsBusy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Get parent form state, if exists.
+ *
+ * Context provider not required. (`undefined` value in this case.)
+ */
+declare const useFormParentIsBusy: () => boolean | undefined;
+export default useFormParentIsBusy;

package/dist/types/form/context/utils/FormUtilsContextProvider.d.ts

@@ -0,0 +1,12 @@
+import { FormProps } from '../../Form';
+import { FieldValues } from 'react-hook-form';
+
+export type FormUtilsContextProviderProps = {
+    /** Callback after successful submit, and form reset. */
+    onSubmitSuccessfulAndReset?: () => void;
+};
+type Props<TFieldValues extends FieldValues, TTransformedValues extends FieldValues> = React.PropsWithChildren<{
+    formProps: FormProps<TFieldValues, TTransformedValues>;
+} & FormUtilsContextProviderProps>;
+declare function FormUtilsContextProvider<TFieldValues extends FieldValues, TTransformedValues extends FieldValues>({ formProps, onSubmitSuccessfulAndReset, children, }: Props<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+export default FormUtilsContextProvider;

package/dist/types/form/context/utils/useFormUtilsContext.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="react" />
+export type FormUtilsContext = {
+    formRef: React.RefObject<HTMLFormElement>;
+    /** Callback to trigger submit manually -- e.g., on change. */
+    requestSubmit: HTMLFormElement['requestSubmit'];
+};
+declare const useFormUtilsContext: () => FormUtilsContext, _FormUtilsContextProvider: import('react').Provider<FormUtilsContext | undefined>;
+export default useFormUtilsContext;
+export { _FormUtilsContextProvider };

package/dist/types/form/search/FormSearch.d.ts

@@ -0,0 +1,32 @@
+import { FormBaseProps } from '../FormBase';
+import { z } from 'zod';
+import { default as React } from 'react';
+
+declare const _default: <TSchema extends z.ZodTypeAny, TSchemaOutput extends z.output<TSchema> = z.output<TSchema>>(props: Omit<FormBaseProps, "children" | "onSubmit"> & {
+    /**
+     * Search params schema.
+     *
+     * Make sure all properties are marked as `optional().catch(undefiend)` to avoid errors from parsing.
+     */
+    schema: TSchema;
+    /** Current search params. */
+    search: NoInfer<TSchemaOutput>;
+    Fields: React.FC<{
+        search: TSchemaOutput;
+        isSubmitting: boolean;
+    }>;
+    /**
+     * Callback to handle form submission.
+     * @param search New search params.
+     * @param data Sanitized form data.
+     * @param event Form submit event.
+     */
+    onSubmit?: ((search: TSchemaOutput, data: TSchemaOutput, event: React.FormEvent<HTMLFormElement>) => unknown) | undefined;
+    /**
+     * Error handler.
+     *
+     * Obviates need for consumer `try/catch`.
+     */
+    onSubmitError?: ((error: unknown, search: TSchemaOutput, data: TSchemaOutput, event: React.FormEvent<HTMLFormElement>) => void) | undefined;
+} & React.RefAttributes<HTMLFormElement>) => React.ReactNode;
+export default _default;

package/dist/types/form/search/FormSearchHiddenInputs.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { Stringifiable } from 'query-string';
+
+/**
+ * Generate hidden inputs from the current search query string.
+ * This allows form to not require JS.
+ */
+declare const FormSearchHiddenInputs: React.FC<{
+    search: Record<string, Stringifiable>;
+    /** Keys to ignore. i.e., they have inputs. */
+    include: string[];
+}>;
+export default FormSearchHiddenInputs;

package/dist/types/form/search/getNewSearchParams.d.ts

@@ -0,0 +1,2 @@
+declare const getNewSearchParams: <TSearchParams extends Record<string, unknown>>(current: TSearchParams | undefined, update: TSearchParams) => TSearchParams;
+export default getNewSearchParams;

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

@@ -0,0 +1,28 @@
+import { FormProps } from './Form';
+import { FormUtilsContextProviderProps } from './context/utils/FormUtilsContextProvider';
+import { FieldValues, UseFormProps as RhfUseFormProps } from 'react-hook-form';
+import { default as React } from 'react';
+
+export type UseFormProps<TFieldValues extends FieldValues, TTransformedValues extends FieldValues> = {
+    rhf: RhfUseFormProps<TFieldValues>;
+    props: FormProps<TFieldValues, TTransformedValues>;
+    utils?: FormUtilsContextProviderProps;
+};
+export type UseFormReturn = ReturnType<typeof useForm>;
+/**
+ * Base Rhf Form hook. Use `Form` in `index.ts` for most cases.
+ * Use this if you need to separate form components.
+ * e.g., a form for table row due to `form` being considered invalid HTML around `tr` tags.
+ * With this hook, you can wrap the `tr` tag with `form.Provider` and use `form.Form` inside
+ * one of the cells. Other components can be outside form while referring to form by its id via `form` attribute.
+ * see https://caniuse.com/?search=form%20attribute
+ * @returns Form provider and form.
+ */
+export declare const useForm: <TFieldValues extends FieldValues, TTransformedValues extends FieldValues>({ rhf, props, utils, }: UseFormProps<TFieldValues, TTransformedValues>) => {
+    Provider: React.FC<{
+        children?: React.ReactNode;
+    }>;
+    Form: React.FC<{
+        children?: React.ReactNode;
+    }>;
+};

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

@@ -0,0 +1,2 @@
+declare const useFormIsBusy: () => boolean;
+export default useFormIsBusy;

package/dist/types/main.d.ts

@@ -1,17 +1,22 @@
 export { default as LazyDevTool } from './devtool/LazyDevTool';
+export { default as useFormErrorsFlatContext } from './errors/context';
+export { default as FormErrorsFlatContextProvider } from './errors/context/provider';
 export { default as FormErrorMessage } from './errors/message/FormErrorMessage';
 export { default as FormErrorMessageByPath } from './errors/message/FormErrorMessageByPath';
 export { default as FormNonFieldErrorMarker } from './errors/nonfield/FormNonFieldErrorMarker';
-export { default as FormNonFieldErrorMarkerHtmlAttribute } from './errors/nonfield/FormNonFieldErrorMarker.utils';
+export { default as FormNonFieldErrorMarkerHtmlAttribute } from './errors/nonfield/FormNonFieldErrorMarkerHtmlAttribute';
 export { default as useFormHasOrphanAndNoFieldErrors } from './errors/orphan/useFormHasOrphanAndNoFieldErrors';
-export { default as useOrphanFormErrors } from './errors/orphan/useOrphanFormErrors';
-export { default as useOrphanFormErrorsToConsoleError } from './errors/orphan/useOrphanFormErrorsToConsoleError';
-export { default as useRootFormFieldErrors } from './errors/root/useRootFormFieldErrors';
+export { default as useOrphanFormErrorsMemo } from './errors/orphan/useOrphanFormErrorsMemo';
+export { default as useOrphanFormErrorsToConsole } from './errors/orphan/useOrphanFormErrorsToConsole';
+export { default as useRootFormFieldErrorsMemo } from './errors/root/useRootFormFieldErrorsMemo';
 export { default as useFormErrorConsoleDebug } from './errors/useFormErrorConsoleDebug';
 export { default as useFormErrorsEffect } from './errors/useFormErrorsEffect';
 export { default as useFormErrorsIfAny } from './errors/useFormErrorsIfAny';
-export { default as useFormErrorsOnChange } from './errors/useFormErrorsOnChange';
+export { default as useFormErrorsMemo } from './errors/useFormErrorsMemo';
 export { default as useFormRequestSubmit } from './errors/useFormRequestSubmit';
+export { default as FormParentContextProvider } from './form/context/parent/FormParentContextProvider';
+export { default as useAsFormParentState } from './form/context/parent/useAsFormParentState';
+export { default as useFormParentIsBusy } from './form/context/parent/useFormParentIsBusy';
 export { default as useFormOnSubmitSuccessful } from './submit/useFormOnSubmitSuccessful';
 export { default as useFormOnSubmitSuccessfulAndReset } from './submit/useFormOnSubmitSuccessfulAndReset';
 export { default as useResetFormAfterSubmitSuccessful } from './submit/useResetFormOnSubmitSuccessful';

package/dist/types/submit/useResetFormOnSubmitSuccessful.d.ts

@@ -8,5 +8,5 @@ type Options = {
  * See `Rules` section: https://react-hook-form.com/api/useform/reset/
  * Specifically: "- It's recommended to reset inside useEffect after submission."
  */
-declare const useResetFormAfterSubmitSuccessful: (options?: Options) => void;
+declare const useResetFormAfterSubmitSuccessful: ({ enabled, ...options }: Options) => void;
 export default useResetFormAfterSubmitSuccessful;

package/dist/types/utils/createContext.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+
+/**
+ * Create a strongly-typed context that throws error if no provider is found.
+ * @returns A tuple with a function to get the context and the context provider.
+ */
+declare function createContext<T = unknown>(): readonly [() => T | undefined, () => T & ({} | null), React.Provider<T | undefined>];
+export default createContext;

package/dist/types/utils/createRequiredContext.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+
+/**
+ * Create a strongly-typed context that throws error if no provider is found.
+ * @returns A tuple with a function to get the context and the context provider.
+ */
+declare function createRequiredContext<T = unknown>(): readonly [() => T & ({} | null), React.Provider<T | undefined>];
+export default createRequiredContext;

package/dist/types/utils/fixedForwardRef.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+
+/**
+ * @see https://www.totaltypescript.com/forwardref-with-generic-components
+ */
+declare function fixedForwardRef<T, P = object>(render: (props: P, ref: React.Ref<T>) => React.ReactNode): (props: P & React.RefAttributes<T>) => React.ReactNode;
+export default fixedForwardRef;

package/dist/types/utils/useImperativeForwardedRef.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+
+/**
+ * Create a ref and point forwarded ref to it.
+ *
+ * Use case: forwarded refs are optional, but sometimes you need the ref.
+ *
+ * @param forwardedRef Forwarded `ref` prop.
+ */
+declare const useImperativeForwardedRef: <TRef>(forwardedRef: React.ForwardedRef<TRef> | undefined) => React.RefObject<TRef>;
+export default useImperativeForwardedRef;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@paragrav/rhf-utils",
   "author": "paragrav.dev",
   "license": "MIT",
-  "version": "0.0.27",
+  "version": "0.0.30",
   "description": "Integration utilities for react-hook-form.",
   "type": "module",
   "sideEffects": false,
@@ -71,6 +71,18 @@
       "default": "./dist/esm/errors/root/useRootFormFieldErrors.mjs",
       "types": "./dist/types/errors/root/useRootFormFieldErrors.d.ts"
     },
+    "./form/context/parent/FormParentContextProvider": {
+      "default": "./dist/esm/form/context/parent/FormParentContextProvider.mjs",
+      "types": "./dist/types/form/context/parent/FormParentContextProvider.d.ts"
+    },
+    "./form/context/parent/useAsFormParentState": {
+      "default": "./dist/esm/form/context/parent/useAsFormParentState.mjs",
+      "types": "./dist/types/form/context/parent/useAsFormParentState.d.ts"
+    },
+    "./form/context/parent/useFormParentIsBusy": {
+      "default": "./dist/esm/form/context/parent/useFormParentIsBusy.mjs",
+      "types": "./dist/types/form/context/parent/useFormParentIsBusy.d.ts"
+    },
     "./submit/useFormOnSubmitSuccessful": {
       "default": "./dist/esm/submit/useFormOnSubmitSuccessful.mjs",
       "types": "./dist/types/submit/useFormOnSubmitSuccessful.d.ts"
@@ -99,6 +111,7 @@
   },
   "peerDependencies": {
     "flat": "^6",
+    "query-string": "^9",
     "react": "^18",
     "react-hook-form": "^7"
   },
@@ -109,6 +122,7 @@
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/node": "^18.19.26",
     "@types/react": "^18.2.69",
+    "@types/react-dom": "^18.2.23",
     "@typescript-eslint/eslint-plugin": "^7.3.1",
     "@typescript-eslint/parser": "^7.3.1",
     "@vitejs/plugin-react": "^4.2.1",
@@ -145,9 +159,13 @@
   },
   "homepage": "https://github.com/paragrav/rhf-utils",
   "keywords": [
-    "react-hook-form",
-    "zod",
+    "integration",
     "form",
-    "react"
+    "forms",
+    "react",
+    "react-hook-form",
+    "utilities",
+    "utils",
+    "zod"
   ]
 }

package/dist/esm/errors/getFlatFieldErrors.mjs

@@ -1,22 +0,0 @@
-import { get as f } from "react-hook-form";
-import n from "./flattenFieldErrors.mjs";
-const p = (t) => {
-  const a = n(t), c = Object.keys(a);
-  return Object.fromEntries(
-    c.reduce(
-      (e, o) => {
-        const r = o.replace(d, "");
-        if (r === o)
-          return e;
-        const s = f(t, r, void 0);
-        return s && e.push([r, s]), e;
-      },
-      []
-      // entries
-    )
-  );
-}, d = /\.(?:type|message)\b$/;
-export {
-  p as default,
-  d as regexMaybeFieldErrorLeafNode
-};

package/dist/esm/errors/orphan/useOrphanFormErrors.mjs

@@ -1,14 +0,0 @@
-import "react";
-import t from "../../isEmptyObject.mjs";
-import e from "../useFormErrorsOnChange.mjs";
-import n from "./getOrphanFlatFieldErrors.mjs";
-const m = (r) => e((o) => {
-  if (t(o))
-    return {};
-  if (!r.current)
-    throw new Error();
-  return n(o, r.current);
-}), a = m;
-export {
-  a as default
-};

package/dist/esm/errors/orphan/useOrphanFormErrorsToConsoleError.mjs

@@ -1,24 +0,0 @@
-import n from "react";
-import { useFormContext as m, useFormState as a } from "react-hook-form";
-import c from "../../isEmptyObject.mjs";
-import p from "./useOrphanFormErrors.mjs";
-const u = (o, e) => {
-  const { getValues: s } = m(), { errors: t } = a(), r = p(o);
-  n.useEffect(() => {
-    if (!c(r) && (console.error(
-      "useOrphanFormErrorsToConsoleError",
-      // include debugging details
-      {
-        location: window.location,
-        values: s(),
-        // form values
-        errors: t,
-        orphans: r
-      }
-    ), e))
-      throw new Error("Orphan errors detected");
-  }, [r]);
-}, h = u;
-export {
-  h as default
-};

package/dist/esm/errors/root/useRootFormFieldErrors.mjs

@@ -1,6 +0,0 @@
-import o from "../useFormErrorsOnChange.mjs";
-import { getRootFlatFieldErrors as r } from "./utils.mjs";
-const t = () => o(r), m = t;
-export {
-  m as default
-};

package/dist/esm/errors/root/utils.mjs

@@ -1,11 +0,0 @@
-import s from "../getFlatFieldErrors.mjs";
-const t = "root", i = (r) => r === t || r.startsWith(t + "."), n = (r) => {
-  const o = s(r);
-  return Object.fromEntries(
-    Object.entries(o).filter(([e]) => i(e))
-  );
-};
-export {
-  n as getRootFlatFieldErrors,
-  i as isFormErrorPathRoot
-};

package/dist/esm/errors/useFormFieldErrors.mjs

@@ -1,13 +0,0 @@
-import t from "./getFlatFieldErrors.mjs";
-import s from "./isFieldError.mjs";
-import i from "./useFormErrorsOnChange.mjs";
-const f = () => i(l), l = (r) => {
-  const o = t(r);
-  return Object.fromEntries(
-    Object.entries(o).filter(([, e]) => s(e))
-  );
-};
-export {
-  f as default,
-  l as getFlatFieldFormErrors
-};