@conform-to/react 1.7.2 → 1.8.1

package/README.md

@@ -7,7 +7,7 @@
  ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
 ```
 
-Version 1.7.2 / License MIT / Copyright (c) 2024 Edmund Hung
+Version 1.8.1 / License MIT / Copyright (c) 2024 Edmund Hung
 
 A type-safe form validation library utilizing web fundamentals to progressively enhance HTML Forms with full support for server frameworks like Remix and Next.js.
 

package/dist/future/context.d.ts

@@ -0,0 +1,15 @@
+export declare const FormContext: import("react").Context<{
+    observer: {
+        onFieldUpdate(callback: (event: {
+            type: "input" | "reset" | "mutation";
+            target: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+        }) => void): () => void;
+        onFormUpdate(callback: (event: {
+            type: "submit" | "input" | "reset" | "mutation";
+            target: HTMLFormElement;
+            submitter?: HTMLInputElement | HTMLButtonElement | null;
+        }) => void): () => void;
+        dispose(): void;
+    };
+}>;
+//# sourceMappingURL=context.d.ts.map

package/dist/future/context.js

@@ -0,0 +1,12 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var react = require('react');
+var dom = require('@conform-to/dom');
+
+var FormContext = /*#__PURE__*/react.createContext({
+  observer: dom.unstable_createGlobalFormsObserver()
+});
+
+exports.FormContext = FormContext;

package/dist/future/context.mjs

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+import { unstable_createGlobalFormsObserver } from '@conform-to/dom';
+
+var FormContext = /*#__PURE__*/createContext({
+  observer: unstable_createGlobalFormsObserver()
+});
+
+export { FormContext };

package/dist/future/hooks.d.ts

@@ -1,15 +1,4 @@
-export declare const formObserver: {
-    onFieldUpdate(callback: (event: {
-        type: "input" | "reset" | "mutation";
-        target: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
-    }) => void): () => void;
-    onFormUpdate(callback: (event: {
-        type: "submit" | "input" | "reset" | "mutation";
-        target: HTMLFormElement;
-        submitter?: HTMLInputElement | HTMLButtonElement | null;
-    }) => void): () => void;
-    dispose(): void;
-};
+import { type FormRef } from './util';
 export type Control = {
     /**
      * Current value of the base input. Undefined if the registered input
@@ -40,7 +29,7 @@ export type Control = {
      * both [change](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) and
      * [input](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) events.
      */
-    change(value: string | string[] | boolean | File | File[] | FileList): void;
+    change(value: string | string[] | boolean | File | File[] | FileList | null): void;
     /**
      * Emits [blur](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event) and
      * [focusout](https://developer.mozilla.org/en-US/docs/Web/API/Element/focusout_event) events.
@@ -87,4 +76,29 @@ export declare function useControl(options?: {
      */
     onFocus?: () => void;
 }): Control;
+type Selector<FormValue, Result> = (formData: FormValue | null, lastResult: Result | undefined) => Result;
+type UseFormDataOptions = {
+    /**
+     * Set to `true` to preserve file inputs and receive a `FormData` object in the selector.
+     * If omitted or `false`, the selector receives a `URLSearchParams` object, where all values are coerced to strings.
+     */
+    acceptFiles?: boolean;
+};
+/**
+ * A React hook that lets you subscribe to the current `FormData` of a form and derive a custom value from it.
+ * The selector runs whenever the form's structure or data changes, and the hook re-renders only when the result is deeply different.
+ *
+ * @see https://conform.guide/api/react/future/useFormData
+ * @example
+ * ```ts
+ * const value = useFormData(formRef, formData => formData?.get('fieldName').toString() ?? '');
+ * ```
+ */
+export declare function useFormData<Value = any>(formRef: FormRef, select: Selector<FormData, Value>, options: UseFormDataOptions & {
+    acceptFiles: true;
+}): Value;
+export declare function useFormData<Value = any>(formRef: FormRef, select: Selector<URLSearchParams, Value>, options?: UseFormDataOptions & {
+    acceptFiles?: boolean;
+}): Value;
+export {};
 //# sourceMappingURL=hooks.d.ts.map

package/dist/future/hooks.js

@@ -5,8 +5,8 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var dom = require('@conform-to/dom');
 var react = require('react');
 var util = require('./util.js');
+var context = require('./context.js');
 
-var formObserver = dom.unstable_createGlobalFormsObserver();
 /**
  * A React hook that lets you sync the state of an input and dispatch native form events from it.
  * This is useful when emulating native input behavior — typically by rendering a hidden base input
@@ -18,6 +18,9 @@ var formObserver = dom.unstable_createGlobalFormsObserver();
  * ```
  */
 function useControl(options) {
+  var {
+    observer
+  } = react.useContext(context.FormContext);
   var inputRef = react.useRef(null);
   var eventDispatched = react.useRef({});
   var defaultSnapshot = util.getDefaultSnapshot(options === null || options === void 0 ? void 0 : options.defaultValue, options === null || options === void 0 ? void 0 : options.defaultChecked, options === null || options === void 0 ? void 0 : options.value);
@@ -30,12 +33,12 @@ function useControl(options) {
   // This is necessary to ensure that input is re-registered
   // if the onFocus handler changes
   var shouldHandleFocus = typeof (options === null || options === void 0 ? void 0 : options.onFocus) === 'function';
-  var snapshot = react.useSyncExternalStore(react.useCallback(callback => formObserver.onFieldUpdate(event => {
+  var snapshot = react.useSyncExternalStore(react.useCallback(callback => observer.onFieldUpdate(event => {
     var input = event.target;
     if (Array.isArray(inputRef.current) ? inputRef.current.some(item => item === input) : inputRef.current === input) {
       callback();
     }
-  }), []), () => {
+  }), [observer]), () => {
     var input = inputRef.current;
     var prev = snapshotRef.current;
     var next = !input ? defaultSnapshot : Array.isArray(input) ? {
@@ -175,5 +178,54 @@ function useControl(options) {
   };
 }
 
-exports.formObserver = formObserver;
+/**
+ * A React hook that lets you subscribe to the current `FormData` of a form and derive a custom value from it.
+ * The selector runs whenever the form's structure or data changes, and the hook re-renders only when the result is deeply different.
+ *
+ * @see https://conform.guide/api/react/future/useFormData
+ * @example
+ * ```ts
+ * const value = useFormData(formRef, formData => formData?.get('fieldName').toString() ?? '');
+ * ```
+ */
+
+function useFormData(formRef, select, options) {
+  var {
+    observer
+  } = react.useContext(context.FormContext);
+  var valueRef = react.useRef();
+  var formDataRef = react.useRef(null);
+  var value = react.useSyncExternalStore(react.useCallback(callback => {
+    var formElement = util.getFormElement(formRef);
+    if (formElement) {
+      var _formData = dom.getFormData(formElement);
+      formDataRef.current = options !== null && options !== void 0 && options.acceptFiles ? _formData : new URLSearchParams(Array.from(_formData).map(_ref => {
+        var [key, value] = _ref;
+        return [key, value.toString()];
+      }));
+    }
+    var unsubscribe = observer.onFormUpdate(event => {
+      if (event.target === util.getFormElement(formRef)) {
+        var _formData2 = dom.getFormData(event.target, event.submitter);
+        formDataRef.current = options !== null && options !== void 0 && options.acceptFiles ? _formData2 : new URLSearchParams(Array.from(_formData2).map(_ref2 => {
+          var [key, value] = _ref2;
+          return [key, value.toString()];
+        }));
+        callback();
+      }
+    });
+    return unsubscribe;
+  }, [observer, formRef, options === null || options === void 0 ? void 0 : options.acceptFiles]), () => {
+    // @ts-expect-error FIXME
+    var result = select(formDataRef.current, valueRef.current);
+    if (typeof valueRef.current !== 'undefined' && dom.unstable_deepEqual(result, valueRef.current)) {
+      return valueRef.current;
+    }
+    valueRef.current = result;
+    return result;
+  }, () => select(null, undefined));
+  return value;
+}
+
 exports.useControl = useControl;
+exports.useFormData = useFormData;

package/dist/future/hooks.mjs

@@ -1,8 +1,8 @@
-import { unstable_createGlobalFormsObserver, unstable_deepEqual, isFieldElement, unstable_change, unstable_focus, unstable_blur } from '@conform-to/dom';
-import { useRef, useEffect, useSyncExternalStore, useCallback } from 'react';
-import { getDefaultSnapshot, getRadioGroupValue, getCheckboxGroupValue, getInputSnapshot, focusable, initializeField } from './util.mjs';
+import { unstable_deepEqual, isFieldElement, unstable_change, unstable_focus, unstable_blur, getFormData } from '@conform-to/dom';
+import { useContext, useRef, useEffect, useSyncExternalStore, useCallback } from 'react';
+import { getDefaultSnapshot, getRadioGroupValue, getCheckboxGroupValue, getInputSnapshot, focusable, initializeField, getFormElement } from './util.mjs';
+import { FormContext } from './context.mjs';
 
-var formObserver = unstable_createGlobalFormsObserver();
 /**
  * A React hook that lets you sync the state of an input and dispatch native form events from it.
  * This is useful when emulating native input behavior — typically by rendering a hidden base input
@@ -14,6 +14,9 @@ var formObserver = unstable_createGlobalFormsObserver();
  * ```
  */
 function useControl(options) {
+  var {
+    observer
+  } = useContext(FormContext);
   var inputRef = useRef(null);
   var eventDispatched = useRef({});
   var defaultSnapshot = getDefaultSnapshot(options === null || options === void 0 ? void 0 : options.defaultValue, options === null || options === void 0 ? void 0 : options.defaultChecked, options === null || options === void 0 ? void 0 : options.value);
@@ -26,12 +29,12 @@ function useControl(options) {
   // This is necessary to ensure that input is re-registered
   // if the onFocus handler changes
   var shouldHandleFocus = typeof (options === null || options === void 0 ? void 0 : options.onFocus) === 'function';
-  var snapshot = useSyncExternalStore(useCallback(callback => formObserver.onFieldUpdate(event => {
+  var snapshot = useSyncExternalStore(useCallback(callback => observer.onFieldUpdate(event => {
     var input = event.target;
     if (Array.isArray(inputRef.current) ? inputRef.current.some(item => item === input) : inputRef.current === input) {
       callback();
     }
-  }), []), () => {
+  }), [observer]), () => {
     var input = inputRef.current;
     var prev = snapshotRef.current;
     var next = !input ? defaultSnapshot : Array.isArray(input) ? {
@@ -171,4 +174,53 @@ function useControl(options) {
   };
 }
 
-export { formObserver, useControl };
+/**
+ * A React hook that lets you subscribe to the current `FormData` of a form and derive a custom value from it.
+ * The selector runs whenever the form's structure or data changes, and the hook re-renders only when the result is deeply different.
+ *
+ * @see https://conform.guide/api/react/future/useFormData
+ * @example
+ * ```ts
+ * const value = useFormData(formRef, formData => formData?.get('fieldName').toString() ?? '');
+ * ```
+ */
+
+function useFormData(formRef, select, options) {
+  var {
+    observer
+  } = useContext(FormContext);
+  var valueRef = useRef();
+  var formDataRef = useRef(null);
+  var value = useSyncExternalStore(useCallback(callback => {
+    var formElement = getFormElement(formRef);
+    if (formElement) {
+      var _formData = getFormData(formElement);
+      formDataRef.current = options !== null && options !== void 0 && options.acceptFiles ? _formData : new URLSearchParams(Array.from(_formData).map(_ref => {
+        var [key, value] = _ref;
+        return [key, value.toString()];
+      }));
+    }
+    var unsubscribe = observer.onFormUpdate(event => {
+      if (event.target === getFormElement(formRef)) {
+        var _formData2 = getFormData(event.target, event.submitter);
+        formDataRef.current = options !== null && options !== void 0 && options.acceptFiles ? _formData2 : new URLSearchParams(Array.from(_formData2).map(_ref2 => {
+          var [key, value] = _ref2;
+          return [key, value.toString()];
+        }));
+        callback();
+      }
+    });
+    return unsubscribe;
+  }, [observer, formRef, options === null || options === void 0 ? void 0 : options.acceptFiles]), () => {
+    // @ts-expect-error FIXME
+    var result = select(formDataRef.current, valueRef.current);
+    if (typeof valueRef.current !== 'undefined' && unstable_deepEqual(result, valueRef.current)) {
+      return valueRef.current;
+    }
+    valueRef.current = result;
+    return result;
+  }, () => select(null, undefined));
+  return value;
+}
+
+export { useControl, useFormData };

package/dist/future/index.d.ts

@@ -1,2 +1,4 @@
-export { useControl } from './hooks';
+export { unstable_isDirty as isDirty } from '@conform-to/dom';
+export { useControl, useFormData } from './hooks';
+export type { Control } from './hooks';
 //# sourceMappingURL=index.d.ts.map

package/dist/future/index.js

@@ -2,8 +2,14 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var dom = require('@conform-to/dom');
 var hooks = require('./hooks.js');
 
 
 
+Object.defineProperty(exports, 'isDirty', {
+	enumerable: true,
+	get: function () { return dom.unstable_isDirty; }
+});
 exports.useControl = hooks.useControl;
+exports.useFormData = hooks.useFormData;

package/dist/future/index.mjs

@@ -1 +1,2 @@
-export { useControl } from './hooks.mjs';
+export { unstable_isDirty as isDirty } from '@conform-to/dom';
+export { useControl, useFormData } from './hooks.mjs';

package/dist/future/util.d.ts

@@ -1,3 +1,5 @@
+export type FormRef = React.RefObject<HTMLFormElement | HTMLFieldSetElement | HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLButtonElement | null> | string;
+export declare function getFormElement(formRef: FormRef | undefined): HTMLFormElement | null;
 export declare function focusable(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
 export declare function initializeField(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, options: {
     defaultValue?: string | string[] | File | File[] | null;

package/dist/future/util.js

@@ -4,6 +4,17 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var dom = require('@conform-to/dom');
 
+function getFormElement(formRef) {
+  var _element$form;
+  if (typeof formRef === 'string') {
+    return document.forms.namedItem(formRef);
+  }
+  var element = formRef === null || formRef === void 0 ? void 0 : formRef.current;
+  if (element instanceof HTMLFormElement) {
+    return element;
+  }
+  return (_element$form = element === null || element === void 0 ? void 0 : element.form) !== null && _element$form !== void 0 ? _element$form : null;
+}
 function focusable(element) {
   if (!element.hidden && element.type !== 'hidden') {
     return;
@@ -130,6 +141,7 @@ function getDefaultSnapshot(defaultValue, defaultChecked, value) {
 exports.focusable = focusable;
 exports.getCheckboxGroupValue = getCheckboxGroupValue;
 exports.getDefaultSnapshot = getDefaultSnapshot;
+exports.getFormElement = getFormElement;
 exports.getInputSnapshot = getInputSnapshot;
 exports.getRadioGroupValue = getRadioGroupValue;
 exports.initializeField = initializeField;

package/dist/future/util.mjs

@@ -1,5 +1,16 @@
 import { unstable_updateField, isGlobalInstance } from '@conform-to/dom';
 
+function getFormElement(formRef) {
+  var _element$form;
+  if (typeof formRef === 'string') {
+    return document.forms.namedItem(formRef);
+  }
+  var element = formRef === null || formRef === void 0 ? void 0 : formRef.current;
+  if (element instanceof HTMLFormElement) {
+    return element;
+  }
+  return (_element$form = element === null || element === void 0 ? void 0 : element.form) !== null && _element$form !== void 0 ? _element$form : null;
+}
 function focusable(element) {
   if (!element.hidden && element.type !== 'hidden') {
     return;
@@ -123,4 +134,4 @@ function getDefaultSnapshot(defaultValue, defaultChecked, value) {
   return {};
 }
 
-export { focusable, getCheckboxGroupValue, getDefaultSnapshot, getInputSnapshot, getRadioGroupValue, initializeField };
+export { focusable, getCheckboxGroupValue, getDefaultSnapshot, getFormElement, getInputSnapshot, getRadioGroupValue, initializeField };

package/package.json

@@ -3,7 +3,7 @@
   "description": "Conform view adapter for react",
   "homepage": "https://conform.guide",
   "license": "MIT",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -41,7 +41,7 @@
     "url": "https://github.com/edmundhung/conform/issues"
   },
   "dependencies": {
-    "@conform-to/dom": "1.7.2"
+    "@conform-to/dom": "1.8.1"
   },
   "devDependencies": {
     "@babel/core": "^7.17.8",