@formality-ui/react 0.2.2 → 0.2.3

package/README.md

@@ -135,7 +135,7 @@ Form container with React Hook Form integration.
 | `record` | `Record<string, any>` | Initial values |
 | `onSubmit` | `(values) => void` | Submit handler |
 | `autoSave` | `boolean` | Enable auto-save |
-| `debounce` | `number` | Debounce delay (ms) |
+| `debounce` | `number \| false` | Auto-save debounce delay (ms); `false` submits immediately (no timer). Defaults to `1000` |
 
 **Render API:**
 | Property | Type | Description |
@@ -293,6 +293,78 @@ Enable automatic form submission on changes:
 </Form>
 ```
 
+The Form-level `debounce` prop (`number | false`, default `1000`) sets the
+default cadence for every field. `false` submits immediately on every change;
+a number delays the save until that many milliseconds elapse without a change.
+
+### Per-field debounce overrides
+
+Each input type can override the auto-save cadence via
+`InputConfig.debounce: number | false | undefined`. When unset, the field falls
+back to the Form-level `debounce` prop.
+
+```tsx
+const inputs: Record<string, InputConfig> = {
+  // switch saves IMMEDIATELY on toggle (no timer):
+  switch: { component: Switch, defaultValue: false, debounce: false },
+  // textField waits 2s after typing stops:
+  textField: { component: TextField, defaultValue: "", debounce: 2000 },
+  // select waits 0.5s:
+  select: { component: Select, defaultValue: "", debounce: 500 },
+  // numberField is unset → falls back to the Form-level `debounce` prop:
+  numberField: { component: NumberField, defaultValue: 0 },
+};
+```
+
+The routing, transcribed from `Form.tsx` (`changeField`):
+
+| `InputConfig.debounce` | Behavior                                     |
+| ---------------------- | -------------------------------------------- |
+| `false`                | Submit immediately (no debounce timer).      |
+| `<number>`             | A per-field timer at that ms interval.       |
+| `undefined`            | Fall back to the Form-level `debounce` prop. |
+
+**Coalescing by interval.** Per-field numeric timers are keyed by their **ms
+interval**, not by field name. Fields that share the same numeric debounce
+coalesce into a **single** timer; all of their pending changes accumulate in a
+shared set and are captured together when that timer fires. Fields with
+different numeric debounces each get their own timer and fire on their own
+cadence.
+
+### Flushing pending saves: `submitImmediate()`
+
+`submitImmediate()` flushes any pending auto-save **immediately** — both the
+per-field numeric timers and the Form-level timer. It is a **no-op** when
+nothing is pending (no spurious empty save), cancels any trailing timers so
+they cannot race this flush, and runs the save pipeline **exactly once**.
+
+`submitImmediate` lives on the form's context value — access it via
+[`useFormContext()`](#useformcontext), **not** the `<Form>` render-prop API:
+
+```tsx
+function SaveNowButton() {
+  const { submitImmediate } = useFormContext();
+  return <button onClick={() => submitImmediate()}>Save Now</button>;
+}
+```
+
+### The debounced submit handle (`cancel` / `flush` / `pending`)
+
+`useFormContext()` also exposes `debouncedSubmit`, a `DebouncedFunction` with
+the standard debounced-handle contract:
+
+| Member              | Behavior                                        |
+| ------------------- | ----------------------------------------------- |
+| `debouncedSubmit()` | Schedule the debounced invocation.              |
+| `.cancel()`         | Cancel any pending invocation.                  |
+| `.flush()`          | Immediately execute any pending invocation.     |
+| `.pending()`        | `true` if an invocation is currently scheduled. |
+
+`.pending()` is **reliable** — it tracks the real scheduled state on both the
+Form-level and per-field debouncers (the earlier "always returns `false`" bug
+has been fixed). For most UI needs prefer `submitImmediate()`: it covers both
+timer sources and the cancel-race, so you do not have to manage them yourself.
+
 ## Hooks
 
 ### useFormContext
@@ -309,6 +381,14 @@ function CustomComponent() {
 }
 ```
 
+Two auto-save handles are available on the context value (see
+[Auto-Save](#auto-save) for the full semantics):
+
+| Member            | Description                                                      |
+| ----------------- | ---------------------------------------------------------------- |
+| `submitImmediate` | Flush pending auto-save immediately (both timer sources).        |
+| `debouncedSubmit` | The `DebouncedFunction` handle (`cancel` / `flush` / `pending`). |
+
 ### useConditions
 
 Evaluate conditions manually:
@@ -655,6 +735,15 @@ All other code — `packages/core/**`, `packages/react/**`, and any future
 adapter with a real implementation — is in scope and must clear 90%. See
 `vitest.config.ts` for the exact configuration.
 
+## Known Issues
+
+- **`isDisabled` condition matcher (React adapter)** — conditions using the
+  `isDisabled` field-state matcher do not currently evaluate correctly in the
+  React adapter because the `fieldStates` map intentionally omits the
+  `disabled` property (to avoid circular re-render dependencies). See
+  [`KNOWN_ISSUES.md`](./KNOWN_ISSUES.md) for the symptom, root cause, and a
+  value-based workaround.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -432,22 +432,15 @@ function Form({
     await handleSubmit(values);
   }, [methods, handleSubmit, waitForFieldValidation]);
   executeAutoSaveRef.current = executeAutoSave;
-  const getOrCreateDebounced = react.useCallback(
-    (ms) => {
-      const cached = fieldDebouncersRef.current.get(ms);
-      if (cached) return cached;
-      const debouncedFn = lodashEs.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 = react.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;
   react.useEffect(() => {
     return () => {
@@ -472,13 +465,9 @@ function Form({
         }
       );
     }
-    const debouncedFn = lodashEs.debounce(() => {
+    return wrapDebounced(() => {
       executeAutoSaveRef.current?.();
     }, debounceMs);
-    return Object.assign(debouncedFn, {
-      pending: () => false
-      // lodash debounce handles this internally
-    });
   }, [debounceMs]);
   debouncedSubmitRef.current = debouncedSubmit;
   react.useEffect(() => {
@@ -487,7 +476,11 @@ function Form({
     };
   }, [debouncedSubmit]);
   const submitImmediate = react.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 = react.useMemo(() => {
     const allFields = Object.keys(config);
@@ -561,6 +554,30 @@ function Form({
     resolvedTitle
   }) : children }) }) });
 }
+function wrapDebounced(callback, ms) {
+  let isPending = false;
+  const debounced = lodashEs.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)) {
@@ -1008,18 +1025,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 = react.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 = react.useMemo(() => {
     if (hiddenProp !== void 0) return !hiddenProp;
@@ -1034,13 +1085,6 @@ 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 = react.useMemo(() => {
     return core.resolveLabel(name, fieldConfig, fieldSelectProps, restProps);
   }, [name, fieldConfig, fieldSelectProps, restProps]);