@paragrav/rhf-utils 0.0.138 → 0.0.140

package/README.md

@@ -22,10 +22,9 @@ Integration and utility library for [react-hook-form](https://www.react-hook-for
     - schema-typed Controller component and FormSubmitError class
 - simpler/flatter `FieldErrors` structure (`FlatFieldErrors`)
   - context groups errors into `all`, `fields`, `roots`, and `orphans` (`useFlatFieldErrorsContext`)
-  - `RhfUtilsFieldErrorMessage` for displaying error message
 - safer `FieldValues` type (`SafeFieldValues`)
 - `zod` support, including input/output types for transformations
-- ~3.6kB min+gzip (excluding [peer dependencies](#peer-dependencies))
+- ~3.2kB min+gzip core (excluding [peer dependencies](#peer-dependencies))
 
 ## Install
 
@@ -57,7 +56,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
     // RhfUtilsFormOptions (see further below)
     utils: {
       stopSubmitPropagation: true,
-      devTool: import.meta.env.DEV,
+      devTool: import.meta.env.DEV && { placement: 'top-right' },
     },
 
     // default form props
@@ -189,7 +188,7 @@ Currently, only `zod` is supported.
           <label>
             Email
             <input {...field} disabled={isSubmitting} />
-            <RhfUtilsFieldErrorMessage path={field.name} />
+            <ErrorMessage path={field.name} />
           </label>
         )}
       />
@@ -337,7 +336,7 @@ Programatically, an "orphan" is any form state error that meets ALL of the follo
 
 - non-field -- i.e., no RHF-supplied `ref` on `FieldError` object
 - non-root -- i.e., not `root` or `root.${string}` path
-- no corresponding "marker" in DOM (i.e., `FormNonFieldErrorMarker`)
+- no corresponding "marker" in DOM (i.e., `RhfUtilsNonFieldErrorMarker`)
 
 This is because:
 
@@ -345,7 +344,7 @@ This is because:
 - root errors (non-field, without `ref`s) are assumed to always be listed for display
 - all other errors must be marked as displayed to distinguish from being an orphan
 
-_See [FormNonFieldErrorMarker](#formnonfielderrormarker) section below for more information about when and why marker is needed._
+_See [RhfUtilsNonFieldErrorMarker](#rhfutilsnonfielderrormarker) section below for more information about when and why marker is needed._
 
 #### Using orphan errors
 
@@ -358,11 +357,11 @@ Detected orphans can be accessed via any of the following:
   - returns an object with list of errors grouped by `all`, `fields` (with `ref`), `roots`, `orphans` records, and includes computed booleans `hasErrors` and `hasOrphans`
 - boolean value from `useFlatFieldErrorsContextHasOnlyOrphans`
 
-### FormNonFieldErrorMarker
+### RhfUtilsNonFieldErrorMarker
 
 _If you don't need orphan detection, you can skip this section. By default, orphan detection still occurs but doesn't otherwise do anything._
 
-To get accurate orphan detection, you must use `FormNonFieldErrorMarker` when displaying any non-root non-field errors. (Example further below.)
+To get accurate orphan detection, you must use `RhfUtilsNonFieldErrorMarker` when displaying any non-root non-field errors. (Example further below.)
 
 There is little harm in including it consistently for all individual errors displayed. (DOM traversal to find marker only occurs if error is non-field AND non-root, which is not typical.)
 
@@ -372,23 +371,19 @@ A typical example is a field array with a required minimum number of items -- e.
 
 When there are zero items, the error is non-field and non-root. You would probably display this error (manually) near the field array, using something like RHF's [`ErrorMessage`](https://www.react-hook-form.com/api/useformstate/errormessage/) component.
 
-In order to NOT detect this as an orphan, it must be explicitly "marked" as displayed using `FormNonFieldErrorMarker`.
+In order to NOT detect this as an orphan, it must be explicitly "marked" as displayed using `RhfUtilsNonFieldErrorMarker`.
 
-You can incorporate `FormNonFieldErrorMarker` into your own component library, or use this library's `RhfUtilsFieldErrorMessage` to display error message to user, which includes this marker.
+You should incorporate `RhfUtilsNonFieldErrorMarker` into your own component library's error message display component.
 
 ```tsx
-<RhfUtilsFieldErrorMessage path="items" />
+<RhfUtilsNonFieldErrorMarker path="items" />
 ```
 
-Uncommon, but if you are ONLY listing a summary of all errors, without individual displays, you will need to use the marker manually.
+_If you include the marker in bulk error lists, it will defeat the purpose of the marker. Only use marker for individual errors. Therefore, if you are ONLY listing a summary of all errors, without individual displays, you will need to use the marker manually._
 
-```tsx
-<FormNonFieldErrorMarker path="items" />
-```
-
-_If you include the marker for error lists, it will defeat the purpose of the marker. Only use marker for individual errors._
+## Other Features
 
-## Form Groups
+### Form Groups _(0.65kB min+gzip)_
 
 Sometimes you need to group multiple forms together.
 
@@ -413,6 +408,22 @@ In children forms, there are two options. You can choose to consider form "busy"
 
 Both hooks return `boolean` value indicating whether parent form is busy.
 
+### TRPC.io Utils _(0.41kB min+gzip)_
+
+#### `trpcClientErrorToFormSubmitFieldErrorsSchemaTransformer`
+
+`zod`-based schema for transforming `TRPCClientErrorLike<AnyRouter>` server errors to `FormSubmitFieldErrors`.
+
+#### `makeOnSubmitTrpcClientErrorHandler`
+
+HOF to make a `onSubmitErrorUnknown` handler for TRPC.io server errors (with fallback callback for non-TRPC errors).
+
+```ts
+  onSubmitErrorUnknown: makeOnSubmitTrpcClientErrorHandler((error) => {
+    // non-trpc error
+  }),
+```
+
 ## Other
 
 ### SafeFieldValues

package/dist/esm/{utils/createContext.mjs → createContext.mjs}

@@ -12,5 +12,5 @@ function i() {
   };
 }
 export {
-  i as default
+  i as c
 };

package/dist/esm/group.mjs

@@ -0,0 +1,74 @@
+import { jsx as F } from "react/jsx-runtime";
+import t from "react";
+import { c as f } from "./createContext.mjs";
+import { useFormState as i } from "react-hook-form";
+const {
+  Provider: h,
+  useRequired: c,
+  useMaybe: u
+} = f(), v = ({ children: s }) => {
+  const [e, r] = t.useState([]), d = e.length, B = t.useCallback((o, I) => {
+    r(
+      (n) => I ? (
+        // add to array
+        [...n, o]
+      ) : (
+        // remove from array
+        n.filter((C) => C !== o)
+      )
+    );
+  }, []), [l, p] = t.useState(!1);
+  return /* @__PURE__ */ F(h, { value: {
+    children: {
+      busyCount: d,
+      busyIds: e,
+      setBusyId: B
+    },
+    parent: {
+      isBusy: l,
+      setIsBusy: p
+    }
+  }, children: s });
+}, a = (s) => {
+  const { setBusyId: e } = c().children, r = t.useId();
+  t.useEffect(() => {
+    e(r, s);
+  }, [s, r, e]), t.useEffect(() => () => {
+    e(r, !1);
+  }, []);
+}, y = () => {
+  const s = u();
+  return !!(s != null && s.parent.isBusy);
+}, T = () => (a(!0), y()), E = () => {
+  const { isSubmitting: s } = i();
+  return a(s), y();
+}, M = () => {
+  const s = u();
+  return !!(s != null && s.children.busyCount) || !!(s != null && s.parent.isBusy);
+}, G = () => {
+  const s = u();
+  return !!(s != null && s.children.busyCount);
+}, m = () => {
+  const { isSubmitting: s, isLoading: e } = i();
+  return s || e;
+}, _ = () => {
+  const s = m(), { setIsBusy: e } = c().parent;
+  return t.useEffect(() => {
+    e(s);
+  }, [e, s]), G();
+}, x = () => {
+  var r;
+  const s = m(), e = (r = u()) == null ? void 0 : r.parent.isBusy;
+  return !!(s || e);
+};
+export {
+  v as FormGroupContextProvider,
+  T as useFormGroupChildIsMountedTracker,
+  E as useFormGroupChildIsSubmittingTracker,
+  a as useFormGroupChildTracker,
+  M as useFormGroupIsAnyBusy,
+  G as useFormGroupIsChildBusy,
+  y as useFormGroupIsParentBusy,
+  _ as useFormGroupParentTracker,
+  x as useFormOrParentIsBusy
+};

package/dist/esm/main.mjs

@@ -0,0 +1,483 @@
+import { jsx as i, Fragment as B, jsxs as Z } from "react/jsx-runtime";
+import a from "react";
+import { c as E } from "./createContext.mjs";
+import { zodResolver as I } from "@hookform/resolvers/zod";
+import { useFormContext as b, Controller as L, get as z, useFormState as x, FormProvider as A, useForm as $ } from "react-hook-form";
+import { i as O, _ as H, u as g } from "./useFlatFieldErrorsContext.mjs";
+import { flatten as Q } from "flat";
+const {
+  Provider: G,
+  useMaybe: _
+} = E(), J = a.lazy(
+  () => import("@hookform/devtools").then((r) => ({
+    default: r.DevTool
+  }))
+), K = ({ enabled: r, props: t }) => {
+  if (!r) return null;
+  const { control: e } = b();
+  return /* @__PURE__ */ i(a.Suspense, { fallback: null, children: /* @__PURE__ */ i(J, { control: e, ...t }) });
+};
+class F extends Error {
+  constructor(t, e) {
+    super(e), this.errors = t;
+  }
+}
+const X = (r, t) => {
+  Object.entries(t).forEach(([e, o]) => {
+    r.setError(e, {
+      type: "FormSubmitFieldError",
+      // default
+      ...o
+    });
+  });
+}, Y = ({
+  children: r
+}) => /* @__PURE__ */ i(B, { children: r });
+function rr(r) {
+  return /* @__PURE__ */ i(L, { ...r });
+}
+function er({
+  formId: r,
+  formRef: t,
+  //
+  onSubmit: e,
+  onSubmitError: o,
+  onSubmitInvalid: s,
+  Children: n,
+  //
+  form: l,
+  utils: u
+}) {
+  const m = b(), d = _(), c = async (h) => {
+    u != null && u.stopSubmitPropagation && h.stopPropagation();
+    try {
+      await m.handleSubmit(v, s)(h);
+    } catch (f) {
+      p(f, h);
+    }
+  }, v = (h, f) => e == null ? void 0 : e(
+    h,
+    {
+      formId: r,
+      formRef: t,
+      context: m,
+      utils: u,
+      FormSubmitError: F
+    },
+    f
+  ), p = (h, f) => {
+    var y;
+    const R = h instanceof F ? (
+      // consumer can manually throw FormSubmitError (e.g., manual validation)
+      h.errors
+    ) : (
+      // if error is not FormSubmitError, consumer can provide global handler
+      (y = d == null ? void 0 : d.onSubmitErrorUnknown) == null ? void 0 : y.call(d, h)
+    );
+    R && X(m, R), o == null || o(
+      h,
+      {
+        formId: r,
+        formRef: t,
+        context: m,
+        utils: u
+      },
+      f
+    );
+  }, P = {
+    formId: r,
+    formRef: t,
+    context: m,
+    utils: u,
+    Controller: rr,
+    FormSubmitError: F
+  }, V = P, N = (d == null ? void 0 : d.FormComponent) ?? "form", q = (d == null ? void 0 : d.FormChildrenWrapper) ?? Y;
+  return /* @__PURE__ */ i(
+    N,
+    {
+      ...l,
+      ref: t,
+      onSubmit: (h) => void c(h),
+      children: /* @__PURE__ */ Z(q, { ...V, children: [
+        /* @__PURE__ */ i(
+          K,
+          {
+            enabled: !!(u != null && u.devTool),
+            props: typeof (u == null ? void 0 : u.devTool) == "object" ? u.devTool : void 0
+          }
+        ),
+        /* @__PURE__ */ i(n, { ...P })
+      ] })
+    }
+  );
+}
+const C = (r) => (t) => (
+  // re-create object from entries
+  Object.fromEntries(
+    // break down to entries
+    Object.entries(t).filter(r)
+  )
+), k = (r) => !!r.ref, tr = ([, r]) => k(r), or = C(
+  tr
+), W = "data-rhfutils-nonfield-error-marker-path", sr = (r, t) => (
+  // list of selector variants
+  [
+    // equals
+    // e.g., attr="path"
+    ["", ""],
+    [
+      // @see https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors#attrvalue_4
+      "^",
+      // only match nested (avoid match 'field' with 'field1`)
+      "."
+    ]
+  ].map(
+    ([e, o]) => nr(
+      W + e,
+      r + o
+    )
+  ).join(", ")
+), nr = (r, t) => `[role="alert"][${r}="${t}"]`, ur = (r, t) => !!t.querySelector(
+  sr(r)
+), S = "root", j = (r) => r === S || r.startsWith(S + "."), lr = (r, t, e) => (
+  // non-field
+  !k(t) && // non-root
+  !j(r) && // not marked in DOM
+  !ur(r, e)
+), ir = (r) => ([t, e]) => lr(t, e, r), dr = (r, t) => C(
+  ir(t)
+)(r), ar = ([r]) => j(r), mr = C(
+  ar
+), hr = (r) => Q(r), cr = (r) => {
+  const t = hr(r), e = Object.keys(t);
+  return Object.fromEntries(
+    e.reduce(
+      (o, s) => {
+        const n = s.replace(
+          fr,
+          ""
+        );
+        if (n === s) return o;
+        const l = z(r, n, void 0);
+        return l && o.push([n, l]), o;
+      },
+      []
+      // entries
+    )
+  );
+}, fr = /\.(?:type|message)\b$/, Fr = ({
+  formRef: r,
+  children: t
+}) => {
+  const { errors: e } = x(), o = cr(e), s = r.current ? dr(o, r.current) : {}, n = {
+    all: o,
+    fields: or(o),
+    roots: mr(o),
+    orphans: s,
+    // computed
+    hasErrors: !O(e),
+    hasOrphans: !O(s)
+  };
+  return /* @__PURE__ */ i(H, { value: n, children: t });
+}, br = (r, t, e, o = "debug") => {
+  console[o](r, { values: t, errors: e });
+}, Er = (r) => {
+  const t = b(), e = g();
+  a.useEffect(() => {
+    var n, l;
+    if (!e.hasErrors) return;
+    const o = (n = r == null ? void 0 : r.console) == null ? void 0 : n.call(r, e);
+    o && br(
+      o.message ?? U,
+      t.getValues(),
+      e,
+      o.type
+    );
+    const s = (l = r == null ? void 0 : r.throw) == null ? void 0 : l.call(r, e);
+    if (s)
+      throw new Error(typeof s == "string" ? s : U);
+  }, [e]);
+}, U = "Form errors", Cr = (r) => {
+  const t = a.useRef(!1);
+  a.useEffect(() => {
+    r && (t.current = !0);
+  }, [r]);
+  const e = () => {
+    t.current = !1;
+  };
+  return [t.current, e];
+}, vr = (r, t) => {
+  const { isSubmitSuccessful: e, isSubmitting: o } = x(), [s, n] = Cr(o);
+  a.useEffect(() => {
+    r && (o || s && (n(), r(e)));
+  }, [o]);
+}, pr = (r) => {
+  const { getValues: t, reset: e } = b();
+  vr((o) => {
+    var u;
+    if (!r) return;
+    const s = (u = r[o ? "success" : "error"]) == null ? void 0 : u.values;
+    if (!s) return;
+    const n = s === "current", l = n ? t() : void 0;
+    e(l, {
+      // keep submit stuff for tracking relevant state (e.g., `useFormOnSubmitSuccessful`)
+      keepIsSubmitSuccessful: !0,
+      keepIsSubmitted: !0,
+      keepSubmitCount: !0,
+      /**
+       * This is necessary when setting default values to current values (lest form stop updating).
+       *
+       * Technically, we are keeping values and resetting default values to same values.
+       *
+       * Steps to repro:
+       * - RhfUtilsClientConfig with resetOnSubmitted set to success values to current
+       * - remove `keepValues` prop from reset
+       * - create valid form, submit
+       * - form values should be unchanged
+       * - unexpectedly: can no longer type into input
+       */
+      keepValues: n,
+      // keep errors in the case of unsuccessful submit
+      keepErrors: !0
+    });
+  });
+}, Pr = (r) => a.useCallback(
+  (t) => {
+    if (!r.current) throw new Error();
+    Rr(r.current, t);
+  },
+  [r]
+), Rr = (r, t) => {
+  r.requestSubmit(t);
+}, yr = ({
+  onChange: r,
+  delay: t
+}) => {
+  const e = a.useRef(), o = () => {
+    e.current && (r(e.current.value), e.current = void 0);
+  }, s = () => {
+    e.current && clearTimeout(e.current.timer);
+  };
+  return a.useEffect(
+    // return timeout clearer
+    () => s,
+    []
+  ), [(l) => {
+    s(), e.current = {
+      // value being tracked
+      value: l,
+      // new timer
+      timer: setTimeout(o, t)
+    };
+  }];
+}, Or = (r, t) => {
+  const e = !(t != null && t.disabled), o = Pr(r), [s] = yr({
+    // on change value after debounce
+    onChange: () => {
+      o();
+    },
+    delay: (t == null ? void 0 : t.debounce) ?? 0
+  });
+  a.useEffect(() => {
+    if (!e) return;
+    const n = r.current;
+    if (!n) throw new Error();
+    const l = (u) => {
+      s(u);
+    };
+    return n.addEventListener("change", l), () => {
+      n.removeEventListener("change", l);
+    };
+  }, []);
+}, { Provider: Sr, useRequired: Ur } = E(), Zr = Ur, xr = ({
+  formId: r,
+  formRef: t,
+  options: e,
+  children: o
+}) => {
+  var n;
+  const s = _();
+  return Er((n = s == null ? void 0 : s.fieldErrors) == null ? void 0 : n.output), Or(t, {
+    // check for false/undefined
+    disabled: ((e == null ? void 0 : e.submitOnChange) ?? !1) === !1,
+    debounce: typeof (e == null ? void 0 : e.submitOnChange) == "number" ? e.submitOnChange : void 0
+  }), pr(e == null ? void 0 : e.resetOnSubmitted), /* @__PURE__ */ i(Sr, { value: { formId: r, formRef: t, options: e }, children: o });
+};
+function gr({
+  formId: r,
+  formRef: t,
+  rhfForm: e,
+  utils: o,
+  children: s
+}) {
+  return /* @__PURE__ */ i(A, { ...e, children: /* @__PURE__ */ i(Fr, { formRef: t, children: /* @__PURE__ */ i(
+    xr,
+    {
+      formId: r,
+      formRef: t,
+      options: o,
+      children: s
+    }
+  ) }) });
+}
+const w = ({
+  defaultValues: r,
+  onSubmit: t,
+  onSubmitError: e,
+  onSubmitInvalid: o,
+  Children: s,
+  rhf: n,
+  form: l,
+  utils: u
+}) => {
+  const m = a.useId(), d = $({
+    ...n,
+    defaultValues: r
+  }), c = a.useRef(null);
+  return {
+    id: m,
+    ref: c,
+    context: d,
+    providerProps: {
+      formId: m,
+      formRef: c,
+      rhfForm: d,
+      utils: u
+    },
+    formProps: {
+      Children: s,
+      onSubmit: t,
+      onSubmitError: e,
+      onSubmitInvalid: o,
+      formId: m,
+      formRef: c,
+      form: l,
+      utils: u
+    },
+    FormSubmitError: F
+  };
+};
+function T(r) {
+  const t = w(r);
+  return /* @__PURE__ */ i(gr, { ...t.providerProps, children: /* @__PURE__ */ i(er, { ...t.formProps }) });
+}
+const _r = (r, ...t) => (
+  // sequentially merge each set of props into defaults
+  t.reduce(
+    (e, o) => {
+      var s, n, l, u, m, d;
+      return {
+        rhf: {
+          ...e == null ? void 0 : e.rhf,
+          ...o.rhf
+        },
+        utils: {
+          ...e == null ? void 0 : e.utils,
+          ...o.utils,
+          // manual merges
+          // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- false positive
+          ...(((s = e == null ? void 0 : e.utils) == null ? void 0 : s.resetOnSubmitted) || ((n = o.utils) == null ? void 0 : n.resetOnSubmitted)) && {
+            resetOnSubmitted: {
+              ...(l = e == null ? void 0 : e.utils) == null ? void 0 : l.resetOnSubmitted,
+              ...(u = o.utils) == null ? void 0 : u.resetOnSubmitted
+            }
+          }
+        },
+        form: {
+          ...e == null ? void 0 : e.form,
+          ...o.form,
+          // manual merges
+          className: [(m = e == null ? void 0 : e.form) == null ? void 0 : m.className, (d = o.form) == null ? void 0 : d.className].filter(Boolean).join(" ") || void 0
+          // stringify (replace empty string with undefined)
+        }
+      };
+    },
+    // start with defaults
+    r
+  )
+), kr = (r) => (t) => {
+  const e = M(r, t);
+  return {
+    useForm: (o, s) => {
+      const n = e(o, s);
+      return {
+        ...w(n),
+        FormWithProviders: () => /* @__PURE__ */ i(T, { ...n })
+      };
+    },
+    FormWithProviders: Wr(r, t)
+  };
+}, M = (r, t) => function(o, s) {
+  return {
+    ...s,
+    ..._r(
+      t.defaults,
+      s,
+      {
+        rhf: {
+          resolver: r(o)
+        }
+      }
+    )
+  };
+}, Wr = (r, t) => {
+  const e = M(r, t);
+  return function({
+    schema: s,
+    children: n,
+    ...l
+  }) {
+    return /* @__PURE__ */ i(
+      T,
+      {
+        ...e(s, l),
+        children: n
+      }
+    );
+  };
+}, jr = kr(I), {
+  Provider: wr,
+  useRequired: D
+} = E(), Ir = ({
+  config: r,
+  children: t
+}) => {
+  const [e] = a.useState(r), [o] = a.useState(
+    () => jr(e ?? {})
+  );
+  return /* @__PURE__ */ i(G, { value: e, children: /* @__PURE__ */ i(wr, { value: o, children: t }) });
+};
+function Lr({
+  schema: r,
+  ...t
+}) {
+  const { FormWithProviders: e } = D();
+  return /* @__PURE__ */ i(e, { schema: r, ...t });
+}
+const zr = (r, t) => D().useForm(r, t), Ar = () => {
+  const r = g();
+  return a.useMemo(() => !r.hasErrors || !r.hasOrphans ? !1 : Object.keys(r.orphans).length === Object.keys(r.all).length, [r]);
+}, $r = ({ path: r }) => {
+  const t = {
+    [W]: r
+  };
+  return /* @__PURE__ */ i(
+    "div",
+    {
+      role: "alert",
+      "aria-hidden": "true",
+      style: { display: "none" },
+      ...t
+    }
+  );
+};
+export {
+  F as FormSubmitError,
+  Ir as RhfUtilsClientForZodContextProvider,
+  $r as RhfUtilsNonFieldErrorMarker,
+  Lr as RhfUtilsZodForm,
+  g as useFlatFieldErrorsContext,
+  Ar as useFlatFieldErrorsContextHasOnlyOrphans,
+  Zr as useRhfUtilsContext,
+  zr as useRhfUtilsZodForm
+};