@formality-ui/react 0.2.3 → 0.2.5

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
@@ -591,6 +593,14 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
      * (`false` for immediate, or a number for a per-field delay).
      */
     debounce?: number | false;
+    /**
+     * React Hook Form validation trigger `mode`, forwarded to `useForm({ mode })`.
+     * One of `'onChange'` (default) | `'onBlur'` | `'onSubmit'` | `'onTouched'` |
+     * `'all'`. Honored as-is — auto-save is mode-agnostic: its validity gates
+     * trigger validation of the touched fields themselves via `methods.trigger`
+     * (which ignores `mode`), so it works under any mode. See PRD §12.
+     */
+    mode?: "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
     /** Form-level validation */
     validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;
 }
@@ -642,7 +652,7 @@ interface FormRenderAPI<TFieldValues extends FieldValues = FieldValues> {
  * </Form>
  * ```
  */
-declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, validate, }: FormProps<TFieldValues>): JSX.Element;
+declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, mode, validate, }: FormProps<TFieldValues>): JSX.Element;
 
 /**
  * Field component props.

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
@@ -591,6 +593,14 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
      * (`false` for immediate, or a number for a per-field delay).
      */
     debounce?: number | false;
+    /**
+     * React Hook Form validation trigger `mode`, forwarded to `useForm({ mode })`.
+     * One of `'onChange'` (default) | `'onBlur'` | `'onSubmit'` | `'onTouched'` |
+     * `'all'`. Honored as-is — auto-save is mode-agnostic: its validity gates
+     * trigger validation of the touched fields themselves via `methods.trigger`
+     * (which ignores `mode`), so it works under any mode. See PRD §12.
+     */
+    mode?: "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
     /** Form-level validation */
     validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;
 }
@@ -642,7 +652,7 @@ interface FormRenderAPI<TFieldValues extends FieldValues = FieldValues> {
  * </Form>
  * ```
  */
-declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, validate, }: FormProps<TFieldValues>): JSX.Element;
+declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, mode, validate, }: FormProps<TFieldValues>): JSX.Element;
 
 /**
  * Field component props.

package/dist/index.js

@@ -147,6 +147,7 @@ function Form({
   record,
   autoSave = false,
   debounce: debounceMs = 1e3,
+  mode,
   validate
 }) {
   const providerConfig = useConfigContext();
@@ -164,7 +165,7 @@ function Form({
     return resolveAllInitialValues(config, mergedInputs, record ?? {});
   }, [config, mergedInputs, record]);
   const methods = useForm({
-    mode: "onChange",
+    mode: mode ?? "onChange",
     defaultValues,
     values: record
   });
@@ -404,9 +405,20 @@ function Form({
     if (!validationsComplete || executionVersionRef.current !== executionVersion) {
       return;
     }
-    for (const fieldName of changedFields) {
-      const fieldState = methods.getFieldState(fieldName);
-      if (fieldState.error) {
+    const changedArray = [...changedFields];
+    if (changedArray.length > 0) {
+      const changedValid = await methods.trigger(changedArray);
+      if (executionVersionRef.current !== executionVersion) {
+        return;
+      }
+      if (!changedValid) {
+        return;
+      }
+      const changedValidationsComplete = await waitForFieldValidation(
+        changedArray,
+        executionVersion
+      );
+      if (!changedValidationsComplete || executionVersionRef.current !== executionVersion) {
         return;
       }
     }
@@ -1086,6 +1098,40 @@ function Field({
   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,
@@ -1163,6 +1209,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,
@@ -1180,7 +1244,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;
@@ -1199,10 +1264,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 });