@formality-ui/react 0.2.2 → 0.2.4

package/dist/index.d.cts

@@ -202,10 +202,12 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  * `<Field>` renders your input component via React Hook Form's `<Controller>`.
  * At runtime Formality merges a `coreProps` bundle onto the component (name,
  * value, onChange, onBlur, and — as a React-special key — `ref`). The three
- * members below are the **injected-props contract**: `formState` reaches
- * templates and render-prop children; `state` (subscribed field state) and a
- * top-level `forwardRef` key are delivered at runtime by `<Field>` (see
- * "Runtime delivery" below).
+ * members below are the **injected-props contract**: `formState` always
+ * reaches templates and render-prop children, and reaches plain components
+ * that have opted into Formality state via `provideState` /
+ * `passSubscriptions`; `state` (subscribed field state) and a top-level
+ * `forwardRef` key are delivered at runtime by `<Field>` (see "Runtime
+ * delivery" below).
  *
  * **Destructure before forwarding.** Component authors MUST destructure
  * `state`, `formState`, and `forwardRef` OUT of props before spreading the

package/dist/index.d.ts

@@ -202,10 +202,12 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  * `<Field>` renders your input component via React Hook Form's `<Controller>`.
  * At runtime Formality merges a `coreProps` bundle onto the component (name,
  * value, onChange, onBlur, and — as a React-special key — `ref`). The three
- * members below are the **injected-props contract**: `formState` reaches
- * templates and render-prop children; `state` (subscribed field state) and a
- * top-level `forwardRef` key are delivered at runtime by `<Field>` (see
- * "Runtime delivery" below).
+ * members below are the **injected-props contract**: `formState` always
+ * reaches templates and render-prop children, and reaches plain components
+ * that have opted into Formality state via `provideState` /
+ * `passSubscriptions`; `state` (subscribed field state) and a top-level
+ * `forwardRef` key are delivered at runtime by `<Field>` (see "Runtime
+ * delivery" below).
  *
  * **Destructure before forwarding.** Component authors MUST destructure
  * `state`, `formState`, and `forwardRef` OUT of props before spreading the

package/dist/index.js

@@ -430,22 +430,15 @@ function Form({
     await handleSubmit(values);
   }, [methods, handleSubmit, waitForFieldValidation]);
   executeAutoSaveRef.current = executeAutoSave;
-  const getOrCreateDebounced = useCallback(
-    (ms) => {
-      const cached = fieldDebouncersRef.current.get(ms);
-      if (cached) return cached;
-      const debouncedFn = debounce(() => {
-        executeAutoSaveRef.current?.();
-      }, ms);
-      const fn = Object.assign(debouncedFn, {
-        pending: () => false
-        // lodash debounce tracks pending internally
-      });
-      fieldDebouncersRef.current.set(ms, fn);
-      return fn;
-    },
-    []
-  );
+  const getOrCreateDebounced = useCallback((ms) => {
+    const cached = fieldDebouncersRef.current.get(ms);
+    if (cached) return cached;
+    const fn = wrapDebounced(() => {
+      executeAutoSaveRef.current?.();
+    }, ms);
+    fieldDebouncersRef.current.set(ms, fn);
+    return fn;
+  }, []);
   getOrCreateDebouncedRef.current = getOrCreateDebounced;
   useEffect(() => {
     return () => {
@@ -470,13 +463,9 @@ function Form({
         }
       );
     }
-    const debouncedFn = debounce(() => {
+    return wrapDebounced(() => {
       executeAutoSaveRef.current?.();
     }, debounceMs);
-    return Object.assign(debouncedFn, {
-      pending: () => false
-      // lodash debounce handles this internally
-    });
   }, [debounceMs]);
   debouncedSubmitRef.current = debouncedSubmit;
   useEffect(() => {
@@ -485,7 +474,11 @@ function Form({
     };
   }, [debouncedSubmit]);
   const submitImmediate = useCallback(() => {
-    debouncedSubmitRef.current?.flush();
+    const anyPending = debouncedSubmitRef.current?.pending() === true || [...fieldDebouncersRef.current.values()].some((fn) => fn.pending());
+    if (!anyPending) return;
+    debouncedSubmitRef.current?.cancel();
+    fieldDebouncersRef.current.forEach((fn) => fn.cancel());
+    executeAutoSaveRef.current?.();
   }, []);
   const unusedFields = useMemo(() => {
     const allFields = Object.keys(config);
@@ -559,6 +552,30 @@ function Form({
     resolvedTitle
   }) : children }) }) });
 }
+function wrapDebounced(callback, ms) {
+  let isPending = false;
+  const debounced = debounce(() => {
+    isPending = false;
+    callback();
+  }, ms);
+  return Object.assign(
+    () => {
+      isPending = true;
+      debounced();
+    },
+    {
+      cancel: () => {
+        isPending = false;
+        debounced.cancel();
+      },
+      flush: () => {
+        isPending = false;
+        debounced.flush();
+      },
+      pending: () => isPending
+    }
+  );
+}
 function transformValuesForSubmit(values, config, inputs) {
   const result = {};
   for (const [name, value] of Object.entries(values)) {
@@ -1006,18 +1023,52 @@ function Field({
       }
     }
   }, [effectiveSetValue.hasCondition, effectiveSetValue.value, name]);
+  const { providerSelectProps, formSelectProps, fieldSelectProps } = usePropsEvaluation({
+    selectProps: fieldConfig.selectProps,
+    formDefaultFieldProps: formConfig.selectDefaultFieldProps,
+    providerDefaultFieldProps: providerConfig.selectDefaultFieldProps,
+    subscribesTo: fieldConfig.subscribesTo,
+    fieldName: name
+  });
   const isDisabled = useMemo(() => {
     if (disabledProp !== void 0) return disabledProp;
     if (fieldConfig.disabled !== void 0) return fieldConfig.disabled;
     if (conditionResult.hasDisabledCondition)
       return conditionResult.disabled ?? false;
     if (groupContext.state.isDisabled) return true;
+    const propsLayers = [
+      fieldSelectProps,
+      // layer 2: field-level selectProps
+      formSelectProps,
+      // layer 5: form-level selectDefaultFieldProps
+      providerSelectProps,
+      // layer 7: provider-level selectDefaultFieldProps
+      inputConfig.props,
+      // layer 4: input config props
+      fieldConfig.props,
+      // layer 3: field config props
+      formConfig.defaultFieldProps,
+      // layer 6: form-level defaultFieldProps
+      providerConfig.defaultFieldProps
+      // layer 8: provider-level defaultFieldProps
+    ];
+    for (const layer of propsLayers) {
+      const layerDisabled = layer?.disabled;
+      if (layerDisabled !== void 0) return Boolean(layerDisabled);
+    }
     return false;
   }, [
     disabledProp,
     fieldConfig.disabled,
+    fieldConfig.props,
     conditionResult,
-    groupContext.state.isDisabled
+    groupContext.state.isDisabled,
+    fieldSelectProps,
+    formSelectProps,
+    providerSelectProps,
+    inputConfig.props,
+    formConfig.defaultFieldProps,
+    providerConfig.defaultFieldProps
   ]);
   const isVisible = useMemo(() => {
     if (hiddenProp !== void 0) return !hiddenProp;
@@ -1032,16 +1083,43 @@ function Field({
     conditionResult,
     groupContext.state.isVisible
   ]);
-  const { providerSelectProps, formSelectProps, fieldSelectProps } = usePropsEvaluation({
-    selectProps: fieldConfig.selectProps,
-    formDefaultFieldProps: formConfig.selectDefaultFieldProps,
-    providerDefaultFieldProps: providerConfig.selectDefaultFieldProps,
-    subscribesTo: fieldConfig.subscribesTo,
-    fieldName: name
-  });
   const label = useMemo(() => {
     return resolveLabel(name, fieldConfig, fieldSelectProps, restProps);
   }, [name, fieldConfig, fieldSelectProps, restProps]);
+  const passSubscriptionsEnabled = fieldConfig.passSubscriptions === true;
+  const provideStateEnabled = fieldConfig.provideState === true;
+  const subscribedWatchNames = useMemo(
+    () => passSubscriptionsEnabled && allSubscriptions.length > 0 ? allSubscriptions : [],
+    [passSubscriptionsEnabled, allSubscriptions]
+  );
+  const subscribedValues = useWatch({
+    control: methods.control,
+    name: subscribedWatchNames.length > 0 ? subscribedWatchNames : []
+  });
+  const subscribedState = useMemo(() => {
+    if (!passSubscriptionsEnabled || subscribedWatchNames.length === 0) {
+      return void 0;
+    }
+    const result = {};
+    const values = Array.isArray(subscribedValues) ? subscribedValues : [subscribedValues];
+    subscribedWatchNames.forEach((fieldName, i) => {
+      const fs = methods.getFieldState(fieldName);
+      result[fieldName] = makeProxyState({
+        value: values[i],
+        isTouched: fs.isTouched,
+        isDirty: fs.isDirty,
+        isValidating: fs.isValidating,
+        error: fs.error,
+        invalid: fs.invalid
+      });
+    });
+    return result;
+  }, [
+    passSubscriptionsEnabled,
+    subscribedWatchNames,
+    subscribedValues,
+    methods
+  ]);
   const validationRules = useMemo(() => {
     return {
       ...fieldConfig.rules,
@@ -1119,6 +1197,24 @@ function Field({
           inputConfig.formatter,
           providerConfig.formatters
         );
+        const stateInjection = {};
+        if (provideStateEnabled) {
+          stateInjection[providerConfig.defaultSubscriptionPropName] = makeProxyState({
+            value: field.value,
+            isTouched: fieldState.isTouched,
+            isDirty: fieldState.isDirty,
+            isValidating: fieldState.isValidating,
+            error: fieldState.error,
+            invalid: fieldState.invalid
+          });
+        }
+        if (passSubscriptionsEnabled && subscribedState) {
+          const subsPropName = fieldConfig.passSubscriptionsAs ?? providerConfig.defaultSubscriptionPropName;
+          stateInjection[subsPropName] = subscribedState;
+        }
+        if (provideStateEnabled || passSubscriptionsEnabled) {
+          stateInjection.formState = formState;
+        }
         const finalProps = mergeFieldProps({
           providerDefaultFieldProps: providerConfig.defaultFieldProps,
           providerSelectDefaultFieldProps: providerSelectProps,
@@ -1136,7 +1232,8 @@ function Field({
             [inputConfig.inputFieldProp ?? "value"]: formattedValue,
             onChange: handleChange(field.onChange),
             onBlur: field.onBlur,
-            forwardRef: field.ref
+            forwardRef: field.ref,
+            ...stateInjection
           }
         });
         const Component = inputConfig.component;
@@ -1155,10 +1252,22 @@ function Field({
             }
           );
         } else if (isHostComponent) {
-          const { forwardRef: hostRef, ...restHostProps } = finalProps;
+          const subsPropName = fieldConfig.passSubscriptionsAs ?? providerConfig.defaultSubscriptionPropName;
+          const strippedHostProps = {};
+          const nonDomKeys = /* @__PURE__ */ new Set([
+            "forwardRef",
+            "formState",
+            "state",
+            subsPropName
+          ]);
+          for (const [key, value] of Object.entries(finalProps)) {
+            if (!nonDomKeys.has(key)) {
+              strippedHostProps[key] = value;
+            }
+          }
           renderedField = createElement(inputConfig.component, {
-            ...restHostProps,
-            ref: hostRef
+            ...strippedHostProps,
+            ref: finalProps.forwardRef
           });
         } else {
           renderedField = /* @__PURE__ */ jsx(Component, { ...finalProps });