@atlaskit/form 9.0.12 → 9.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/form
 
+## 9.1.0
+
+### Minor Changes
+
+- [#83175](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/83175) [`03e4aaa5a468`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/03e4aaa5a468) - Adds ability to subscribe to form state using the useFormState hook. This can be helpful in situations such as forms with conditional fields, or for previewing a form response. [Read the docs here.](https://atlassian.design/components/form/examples#listening-to-form-state-with-useformstate)
+
 ## 9.0.12
 
 ### Patch Changes

package/dist/cjs/form.js

@@ -25,6 +25,9 @@ var FormContext = exports.FormContext = /*#__PURE__*/(0, _react.createContext)({
   },
   getCurrentValue: function getCurrentValue() {
     return undefined;
+  },
+  subscribe: function subscribe() {
+    return function () {};
   }
 });
 
@@ -134,9 +137,10 @@ function Form(props) {
   var FormContextValue = (0, _react.useMemo)(function () {
     return {
       registerField: registerField,
-      getCurrentValue: getCurrentValue
+      getCurrentValue: getCurrentValue,
+      subscribe: form.subscribe
     };
-  }, [registerField, getCurrentValue]);
+  }, [registerField, getCurrentValue, form.subscribe]);
   return /*#__PURE__*/_react.default.createElement(FormContext.Provider, {
     value: FormContextValue
   }, /*#__PURE__*/_react.default.createElement(IsDisabledContext.Provider, {

package/dist/cjs/index.js

@@ -88,6 +88,12 @@ Object.defineProperty(exports, "default", {
     return _form.default;
   }
 });
+Object.defineProperty(exports, "useFormState", {
+  enumerable: true,
+  get: function get() {
+    return _useFormState.useFormState;
+  }
+});
 var _form = _interopRequireDefault(require("./form"));
 var _formHeader = _interopRequireDefault(require("./form-header"));
 var _formFooter = _interopRequireDefault(require("./form-footer"));
@@ -98,4 +104,5 @@ var _rangeField = _interopRequireDefault(require("./range-field"));
 var _label = require("./label");
 var _messages = require("./messages");
 var _fieldset = _interopRequireDefault(require("./fieldset"));
-var _requiredAsterisk = _interopRequireDefault(require("./required-asterisk"));
+var _requiredAsterisk = _interopRequireDefault(require("./required-asterisk"));
+var _useFormState = require("./use-form-state");

package/dist/cjs/use-form-state.js

@@ -0,0 +1,76 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useFormState = void 0;
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _react = require("react");
+var _form = require("./form");
+// Constantized to avoid a new object reference built every call
+var defaultSubscriptionConfig = {
+  values: true
+};
+
+/**
+ * Build a simple hash for a given subscription object for use in a `useMemo` dependencies array.
+ * This is because `{ values: true } !== { values: true }`, but `'values:true|' === 'values:true|'`
+ *
+ * @example { values: true, dirty: false } => 'values:true|dirty:false|'
+ */
+var getSubscriptionHash = function getSubscriptionHash(subscriptionConfig) {
+  var hash = '';
+  for (var key in subscriptionConfig) {
+    if (subscriptionConfig.hasOwnProperty(key)) {
+      hash += "".concat(key, ":").concat(subscriptionConfig[key], "|");
+    }
+  }
+  return hash;
+};
+
+/**
+ * A hook to return a recent form state for use within the `<Form>` as it requires context access.
+ * This is useful for previewing form state, or for building custom fields that need to react to form state.
+ *
+ * This should not be used as a way to persist form state into another form state, use `onSubmit` for proper form handling.
+ *
+ * @note On the initial render, this should be `undefined` as our form has not provided any state.
+ */
+var useFormState = exports.useFormState = function useFormState() {
+  var subscriptionConfig = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : defaultSubscriptionConfig;
+  var _useContext = (0, _react.useContext)(_form.FormContext),
+    subscribe = _useContext.subscribe;
+  var _useState = (0, _react.useState)(),
+    _useState2 = (0, _slicedToArray2.default)(_useState, 2),
+    state = _useState2[0],
+    setState = _useState2[1];
+
+  /**
+   * A hash for us to shallow compare the subscriptionConfig object to react to shallow changes, but avoid referential changes.
+   * We avoid computing the hash if the subscription config has referential equality altogether.
+   */
+  var subscriptionConfigHash = (0, _react.useMemo)(function () {
+    return getSubscriptionHash(subscriptionConfig);
+  }, [subscriptionConfig]);
+
+  /**
+   * Return a memoized version of the subscription config to only react to shallow changes, not referential changes.
+   * Eg. calling `useFormState({ values: true })` twice will result in two different objects by reference, but not by shallow comparison.
+   * This will ensure we don't re-subscribe to the form state when the subscription config is the same.
+   */
+  var config = (0, _react.useMemo)(function () {
+    return subscriptionConfig;
+  },
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally controlled with a hash to have an explicit shallow comparison
+  [subscriptionConfigHash]);
+  (0, _react.useEffect)(function () {
+    var unsubscribe = subscribe(function (formState) {
+      setState(formState);
+    }, config);
+    return function () {
+      return unsubscribe();
+    };
+  }, [subscribe, config]);
+  return state;
+};

package/dist/es2019/form.js

@@ -11,7 +11,10 @@ export const FormContext = /*#__PURE__*/createContext({
   registerField: function () {
     return () => {};
   },
-  getCurrentValue: () => undefined
+  getCurrentValue: () => undefined,
+  subscribe: function () {
+    return () => {};
+  }
 });
 
 /**
@@ -112,9 +115,10 @@ export default function Form(props) {
   const FormContextValue = useMemo(() => {
     return {
       registerField,
-      getCurrentValue
+      getCurrentValue,
+      subscribe: form.subscribe
     };
-  }, [registerField, getCurrentValue]);
+  }, [registerField, getCurrentValue, form.subscribe]);
   return /*#__PURE__*/React.createElement(FormContext.Provider, {
     value: FormContextValue
   }, /*#__PURE__*/React.createElement(IsDisabledContext.Provider, {

package/dist/es2019/index.js

@@ -9,4 +9,6 @@ export { Label, Legend } from './label';
 export { HelperMessage, ErrorMessage, ValidMessage } from './messages';
 export { default as Fieldset } from './fieldset';
 export { default as RequiredAsterisk } from './required-asterisk';
-// eslint-disable-next-line import/no-unresolved
+// eslint-disable-next-line import/no-unresolved
+
+export { useFormState } from './use-form-state';

package/dist/es2019/use-form-state.js

@@ -0,0 +1,60 @@
+import { useContext, useEffect, useMemo, useState } from 'react';
+import { FormContext } from './form';
+
+// Constantized to avoid a new object reference built every call
+const defaultSubscriptionConfig = {
+  values: true
+};
+
+/**
+ * Build a simple hash for a given subscription object for use in a `useMemo` dependencies array.
+ * This is because `{ values: true } !== { values: true }`, but `'values:true|' === 'values:true|'`
+ *
+ * @example { values: true, dirty: false } => 'values:true|dirty:false|'
+ */
+const getSubscriptionHash = subscriptionConfig => {
+  let hash = '';
+  for (const key in subscriptionConfig) {
+    if (subscriptionConfig.hasOwnProperty(key)) {
+      hash += `${key}:${subscriptionConfig[key]}|`;
+    }
+  }
+  return hash;
+};
+
+/**
+ * A hook to return a recent form state for use within the `<Form>` as it requires context access.
+ * This is useful for previewing form state, or for building custom fields that need to react to form state.
+ *
+ * This should not be used as a way to persist form state into another form state, use `onSubmit` for proper form handling.
+ *
+ * @note On the initial render, this should be `undefined` as our form has not provided any state.
+ */
+export const useFormState = (subscriptionConfig = defaultSubscriptionConfig) => {
+  const {
+    subscribe
+  } = useContext(FormContext);
+  const [state, setState] = useState();
+
+  /**
+   * A hash for us to shallow compare the subscriptionConfig object to react to shallow changes, but avoid referential changes.
+   * We avoid computing the hash if the subscription config has referential equality altogether.
+   */
+  const subscriptionConfigHash = useMemo(() => getSubscriptionHash(subscriptionConfig), [subscriptionConfig]);
+
+  /**
+   * Return a memoized version of the subscription config to only react to shallow changes, not referential changes.
+   * Eg. calling `useFormState({ values: true })` twice will result in two different objects by reference, but not by shallow comparison.
+   * This will ensure we don't re-subscribe to the form state when the subscription config is the same.
+   */
+  const config = useMemo(() => subscriptionConfig,
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally controlled with a hash to have an explicit shallow comparison
+  [subscriptionConfigHash]);
+  useEffect(() => {
+    const unsubscribe = subscribe(formState => {
+      setState(formState);
+    }, config);
+    return () => unsubscribe();
+  }, [subscribe, config]);
+  return state;
+};

package/dist/esm/form.js

@@ -14,6 +14,9 @@ export var FormContext = /*#__PURE__*/createContext({
   },
   getCurrentValue: function getCurrentValue() {
     return undefined;
+  },
+  subscribe: function subscribe() {
+    return function () {};
   }
 });
 
@@ -123,9 +126,10 @@ export default function Form(props) {
   var FormContextValue = useMemo(function () {
     return {
       registerField: registerField,
-      getCurrentValue: getCurrentValue
+      getCurrentValue: getCurrentValue,
+      subscribe: form.subscribe
     };
-  }, [registerField, getCurrentValue]);
+  }, [registerField, getCurrentValue, form.subscribe]);
   return /*#__PURE__*/React.createElement(FormContext.Provider, {
     value: FormContextValue
   }, /*#__PURE__*/React.createElement(IsDisabledContext.Provider, {

package/dist/esm/index.js

@@ -9,4 +9,6 @@ export { Label, Legend } from './label';
 export { HelperMessage, ErrorMessage, ValidMessage } from './messages';
 export { default as Fieldset } from './fieldset';
 export { default as RequiredAsterisk } from './required-asterisk';
-// eslint-disable-next-line import/no-unresolved
+// eslint-disable-next-line import/no-unresolved
+
+export { useFormState } from './use-form-state';

package/dist/esm/use-form-state.js

@@ -0,0 +1,70 @@
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+import { useContext, useEffect, useMemo, useState } from 'react';
+import { FormContext } from './form';
+
+// Constantized to avoid a new object reference built every call
+var defaultSubscriptionConfig = {
+  values: true
+};
+
+/**
+ * Build a simple hash for a given subscription object for use in a `useMemo` dependencies array.
+ * This is because `{ values: true } !== { values: true }`, but `'values:true|' === 'values:true|'`
+ *
+ * @example { values: true, dirty: false } => 'values:true|dirty:false|'
+ */
+var getSubscriptionHash = function getSubscriptionHash(subscriptionConfig) {
+  var hash = '';
+  for (var key in subscriptionConfig) {
+    if (subscriptionConfig.hasOwnProperty(key)) {
+      hash += "".concat(key, ":").concat(subscriptionConfig[key], "|");
+    }
+  }
+  return hash;
+};
+
+/**
+ * A hook to return a recent form state for use within the `<Form>` as it requires context access.
+ * This is useful for previewing form state, or for building custom fields that need to react to form state.
+ *
+ * This should not be used as a way to persist form state into another form state, use `onSubmit` for proper form handling.
+ *
+ * @note On the initial render, this should be `undefined` as our form has not provided any state.
+ */
+export var useFormState = function useFormState() {
+  var subscriptionConfig = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : defaultSubscriptionConfig;
+  var _useContext = useContext(FormContext),
+    subscribe = _useContext.subscribe;
+  var _useState = useState(),
+    _useState2 = _slicedToArray(_useState, 2),
+    state = _useState2[0],
+    setState = _useState2[1];
+
+  /**
+   * A hash for us to shallow compare the subscriptionConfig object to react to shallow changes, but avoid referential changes.
+   * We avoid computing the hash if the subscription config has referential equality altogether.
+   */
+  var subscriptionConfigHash = useMemo(function () {
+    return getSubscriptionHash(subscriptionConfig);
+  }, [subscriptionConfig]);
+
+  /**
+   * Return a memoized version of the subscription config to only react to shallow changes, not referential changes.
+   * Eg. calling `useFormState({ values: true })` twice will result in two different objects by reference, but not by shallow comparison.
+   * This will ensure we don't re-subscribe to the form state when the subscription config is the same.
+   */
+  var config = useMemo(function () {
+    return subscriptionConfig;
+  },
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally controlled with a hash to have an explicit shallow comparison
+  [subscriptionConfigHash]);
+  useEffect(function () {
+    var unsubscribe = subscribe(function (formState) {
+      setState(formState);
+    }, config);
+    return function () {
+      return unsubscribe();
+    };
+  }, [subscribe, config]);
+  return state;
+};

package/dist/types/form.d.ts

@@ -1,5 +1,5 @@
 import React, { ReactNode } from 'react';
-import { FieldConfig, FieldSubscriber, FieldSubscription, FormState, Unsubscribe } from 'final-form';
+import { FieldConfig, FieldSubscriber, FieldSubscription, FormApi, FormState, Unsubscribe } from 'final-form';
 import { OnSubmitHandler } from './types';
 type DefaultValue<FieldValue> = (value?: FieldValue) => FieldValue;
 type RegisterField = <FieldValue>(name: string, defaultValue: FieldValue | DefaultValue<FieldValue>, subscriber: FieldSubscriber<FieldValue>, subscription: FieldSubscription, config: FieldConfig<FieldValue>) => Unsubscribe;
@@ -12,6 +12,7 @@ type GetCurrentValue = <FormValues>(name: string) => FormValues[keyof FormValues
 export declare const FormContext: React.Context<{
     registerField: RegisterField;
     getCurrentValue: GetCurrentValue;
+    subscribe: FormApi['subscribe'];
 }>;
 /**
  * __Is disabled context__

package/dist/types/index.d.ts

@@ -15,3 +15,4 @@ export { HelperMessage, ErrorMessage, ValidMessage } from './messages';
 export { default as Fieldset } from './fieldset';
 export { default as RequiredAsterisk } from './required-asterisk';
 export type { OnSubmitHandler, FormApi } from './types';
+export { useFormState } from './use-form-state';

package/dist/types/use-form-state.d.ts

@@ -0,0 +1,10 @@
+import { FormState, FormSubscription } from 'final-form';
+/**
+ * A hook to return a recent form state for use within the `<Form>` as it requires context access.
+ * This is useful for previewing form state, or for building custom fields that need to react to form state.
+ *
+ * This should not be used as a way to persist form state into another form state, use `onSubmit` for proper form handling.
+ *
+ * @note On the initial render, this should be `undefined` as our form has not provided any state.
+ */
+export declare const useFormState: <FormValues extends Record<string, any>>(subscriptionConfig?: FormSubscription) => FormState<FormValues> | undefined;

package/dist/types-ts4.5/form.d.ts

@@ -1,5 +1,5 @@
 import React, { ReactNode } from 'react';
-import { FieldConfig, FieldSubscriber, FieldSubscription, FormState, Unsubscribe } from 'final-form';
+import { FieldConfig, FieldSubscriber, FieldSubscription, FormApi, FormState, Unsubscribe } from 'final-form';
 import { OnSubmitHandler } from './types';
 type DefaultValue<FieldValue> = (value?: FieldValue) => FieldValue;
 type RegisterField = <FieldValue>(name: string, defaultValue: FieldValue | DefaultValue<FieldValue>, subscriber: FieldSubscriber<FieldValue>, subscription: FieldSubscription, config: FieldConfig<FieldValue>) => Unsubscribe;
@@ -12,6 +12,7 @@ type GetCurrentValue = <FormValues>(name: string) => FormValues[keyof FormValues
 export declare const FormContext: React.Context<{
     registerField: RegisterField;
     getCurrentValue: GetCurrentValue;
+    subscribe: FormApi['subscribe'];
 }>;
 /**
  * __Is disabled context__

package/dist/types-ts4.5/index.d.ts

@@ -15,3 +15,4 @@ export { HelperMessage, ErrorMessage, ValidMessage } from './messages';
 export { default as Fieldset } from './fieldset';
 export { default as RequiredAsterisk } from './required-asterisk';
 export type { OnSubmitHandler, FormApi } from './types';
+export { useFormState } from './use-form-state';

package/dist/types-ts4.5/use-form-state.d.ts

@@ -0,0 +1,10 @@
+import { FormState, FormSubscription } from 'final-form';
+/**
+ * A hook to return a recent form state for use within the `<Form>` as it requires context access.
+ * This is useful for previewing form state, or for building custom fields that need to react to form state.
+ *
+ * This should not be used as a way to persist form state into another form state, use `onSubmit` for proper form handling.
+ *
+ * @note On the initial render, this should be `undefined` as our form has not provided any state.
+ */
+export declare const useFormState: <FormValues extends Record<string, any>>(subscriptionConfig?: FormSubscription) => FormState<FormValues> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/form",
-  "version": "9.0.12",
+  "version": "9.1.0",
   "description": "A form allows users to input information.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
@@ -46,6 +46,7 @@
     "@af/accessibility-testing": "*",
     "@af/integration-testing": "*",
     "@af/visual-regression": "*",
+    "@atlaskit/banner": "^12.1.22",
     "@atlaskit/button": "^17.7.0",
     "@atlaskit/checkbox": "^13.1.0",
     "@atlaskit/ds-lib": "^2.2.0",
@@ -56,6 +57,7 @@
     "@atlaskit/visual-regression": "*",
     "@atlassian/atlassian-frontend-prettier-config-1.0.1": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.1",
     "@testing-library/react": "^12.1.5",
+    "@testing-library/react-hooks": "^8.0.1",
     "@testing-library/user-event": "^14.4.3",
     "@types/final-form-focus": "^1.1.1",
     "jest-in-case": "^1.0.2",