@paragrav/rhf-utils 0.0.50 → 0.0.53

package/dist/types/src/form/useFormWithProviders.d.ts

@@ -0,0 +1,31 @@
+import { UseFormProps } from './useForm';
+import { FormUtilsContextProviderProps } from './context/utils/FormUtilsContextProvider';
+import { FieldValues } from 'react-hook-form';
+import { default as React } from 'react';
+
+export type UseFormWithProvidersProps<TFieldValues extends FieldValues, TTransformedValues extends FieldValues> = UseFormProps<TFieldValues, TTransformedValues> & {
+    /** {@link FormUtilsContextProviderProps} props for `FormUtilsContextProvider`. */
+    utils?: FormUtilsContextProviderProps;
+};
+export type UseFormWithProvidersReturn = ReturnType<typeof useFormWithProviders>;
+/**
+ * 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.
+ */
+declare const useFormWithProviders: <TFieldValues extends FieldValues, TTransformedValues extends FieldValues>({ rhf, form, utils, }: UseFormWithProvidersProps<TFieldValues, TTransformedValues>) => {
+    readonly Provider: React.FC<{
+        children?: React.ReactNode;
+    }>;
+    readonly id: string;
+    readonly ref: React.RefObject<HTMLFormElement>;
+    readonly context: import('react-hook-form').UseFormReturn<TFieldValues, unknown, TTransformedValues>;
+    readonly Form: React.FC<{
+        children?: React.ReactNode;
+    }>;
+};
+export default useFormWithProviders;

package/dist/types/src/form/utils/getSubmitterButtonData.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+
+/**
+ * Get [name, value] of button/input that submitted form.
+ * Useful when determining user intent
+ */
+declare const getSubmitterButtonData: (event: React.BaseSyntheticEvent) => [
+    name: string,
+    value: string
+] | undefined;
+export default getSubmitterButtonData;

package/dist/types/src/isEmptyObject.d.ts

@@ -0,0 +1,2 @@
+declare const isEmptyObject: (obj: Record<string, unknown>) => boolean;
+export default isEmptyObject;

package/dist/types/src/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/submit/error/FormSubmitError.d.ts

@@ -0,0 +1,6 @@
+import { FieldPath, FieldValues } from 'react-hook-form';
+
+export declare class FormSubmitError<TFieldValues extends FieldValues = 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/src/submit/error/handleFormSubmitError.d.ts

@@ -0,0 +1,7 @@
+import { FieldValues, UseFormReturn } from 'react-hook-form';
+
+/**
+ * Handle form submit error if {@link FormSubmitError}. Add items to RHF form errors.
+ */
+declare const handleFormSubmitError: <TFieldValues extends FieldValues, TTransformedValues extends FieldValues>(error: unknown, ctx: UseFormReturn<TFieldValues, unknown, TTransformedValues>) => void;
+export default handleFormSubmitError;

package/dist/types/src/submit/useFormOnSubmitSuccessful.d.ts

@@ -0,0 +1,2 @@
+declare const useFormOnSubmitSuccessful: (callback?: () => void) => void;
+export default useFormOnSubmitSuccessful;

package/dist/types/src/submit/useFormOnSubmitSuccessfulAndReset.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Calls a callback after a successful submit and after a form reset.
+ *
+ * Use this when your forms use a isDirty prompter for user action that would lose unsaved data.
+ * You must reset form before you can navigate away from page.
+ *
+ * Using RHF and following its rules, we are not able to get the state `isSubmitSuccessful=true` and `isDirty=false`.
+ * So, this has to keep track of previous state.
+ *
+ * SubmitSuccessfulAndReset = was `isSubmitSuccessful` and now `!isSubmitSuccessful && !isDirty`
+ */
+declare const useFormOnSubmitSuccessfulAndReset: (callback?: () => void) => void;
+export default useFormOnSubmitSuccessfulAndReset;

package/dist/types/src/submit/useResetFormOnSubmitError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Handle resetting after successful submit with no server validation errors.
+ * See `Rules` section: https://react-hook-form.com/api/useform/reset/
+ * Specifically: "- It's recommended to reset inside useEffect after submission."
+ */
+declare const useResetFormOnSubmitError: (disabled?: boolean) => void;
+export default useResetFormOnSubmitError;

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

@@ -0,0 +1,12 @@
+import { KeepStateOptions } from 'react-hook-form';
+
+type Options = {
+    enabled?: boolean;
+} & KeepStateOptions;
+/**
+ * Handle resetting after successful submit with no server validation errors.
+ * See `Rules` section: https://react-hook-form.com/api/useform/reset/
+ * Specifically: "- It's recommended to reset inside useEffect after submission."
+ */
+declare const useResetFormAfterSubmitSuccessful: ({ enabled, ...options }: Options) => void;
+export default useResetFormAfterSubmitSuccessful;

package/dist/types/src/submit/useSubmitFormOnChange.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+
+declare const useSubmitFormOnChange: (formRef: React.RefObject<HTMLFormElement>, disabled?: boolean) => void;
+export default useSubmitFormOnChange;

package/dist/types/src/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/src/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/src/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>) => React.RefObject<TRef>;
+export default useImperativeForwardedRef;

package/dist/types/src/utils/useThrowAsyncError.d.ts

@@ -0,0 +1,5 @@
+/**
+ * React cannot handle async errors in event handlers or useEffects.
+ */
+declare const useThrowAsyncError: () => (error: unknown) => void;
+export default useThrowAsyncError;

package/dist/types/src/utils/useToggle.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+
+declare const useToggle: (defaultValue?: boolean) => [boolean, React.DispatchWithoutAction];
+export default useToggle;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@paragrav/rhf-utils",
   "author": "paragrav.dev",
   "license": "MIT",
-  "version": "0.0.50",
+  "version": "0.0.53",
   "description": "Integration utilities for react-hook-form.",
   "type": "module",
   "sideEffects": false,
@@ -10,6 +10,12 @@
     "dist"
   ],
   "module": "./dist/esm/exports.mjs",
+  "imports": {
+    "#is-development": {
+      "development": "./src/env-conditions/development.ts",
+      "default": "./src/env-conditions/production.ts"
+    }
+  },
   "exports": {
     ".": {
       "default": "./dist/esm/exports.mjs",
@@ -107,10 +113,18 @@
       "default": "./dist/esm/form/context/group/useFormGroupParentTracker.mjs",
       "types": "./dist/types/form/context/group/useFormGroupParentTracker.d.ts"
     },
+    "./form/context/group/useFormOrParentIsBusy": {
+      "default": "./dist/esm/form/context/group/useFormOrParentIsBusy.mjs",
+      "types": "./dist/types/form/context/group/useFormOrParentIsBusy.d.ts"
+    },
     "./form/context/group/useFormGroupChildIsSubmittingTracker": {
       "default": "./dist/esm/form/context/group/useFormGroupChildIsSubmittingTracker.mjs",
       "types": "./dist/types/form/context/group/useFormGroupChildIsSubmittingTracker.d.ts"
     },
+    "./form/context/group/useFormGroupChildTracker": {
+      "default": "./dist/esm/form/context/group/useFormGroupChildTracker.mjs",
+      "types": "./dist/types/form/context/group/useFormGroupChildTracker.d.ts"
+    },
     "./form/context/group/useFormGroupChildIsMountedTracker": {
       "default": "./dist/esm/form/context/group/useFormGroupChildIsMountedTracker.mjs",
       "types": "./dist/types/form/context/group/useFormGroupChildIsMountedTracker.d.ts"
@@ -159,12 +173,12 @@
   "scripts": {
     "build": "npm install && npm run validate && vite build",
     "build:dev": "vite build --config vite.config.dev.ts",
-    "dev": "vite",
+    "dev": "vite --config vite.config.dev.ts",
     "lint": "eslint --ignore-path ./.gitignore --ext ts,tsx --report-unused-disable-directives --max-warnings 0 .",
     "preinstall": "npx only-allow npm",
     "prepare": "husky",
     "prepublishOnly": "npm run build",
-    "preview": "vite preview",
+    "preview": "vite preview --config vite.config.dev.ts",
     "test": "vitest",
     "test:ct": "playwright test -c playwright-ct.config.ts",
     "test:ct:ui": "playwright test -c playwright-ct.config.ts --ui",