@instructure/ui-date-input 9.6.0 → 9.6.1-snapshot-2

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [9.6.1-snapshot-2](https://github.com/instructure/instructure-ui/compare/v9.6.0...v9.6.1-snapshot-2) (2024-09-06)
+
+
+### Features
+
+* **ui-date-input:** improve DateInput2 api, extend docs ([42c83a2](https://github.com/instructure/instructure-ui/commit/42c83a240434dd52233c482292caa556babb5c3a))
+
+
+
+
+
 # [9.6.0](https://github.com/instructure/instructure-ui/compare/v9.5.2...v9.6.0) (2024-08-14)
 
 

package/es/DateInput2/index.js

@@ -35,9 +35,37 @@ import { passthroughProps } from '@instructure/ui-react-utils';
 import { ApplyLocaleContext, Locale } from '@instructure/ui-i18n';
 import { jsx } from '@instructure/emotion';
 import { propTypes } from './props';
-function parseDate(dateString) {
+/*
+ * Tries parsing a date in a given timezone, if it's not possible, returns an empty string
+ * If parsing is successful an ISO formatted datetime string is returned in UTC timezone
+ */
+function timezoneDateToUtc(dateString, timezone) {
+  // Don't try to parse short dateString, they are incomplete
+  if (dateString.length < 10) {
+    return '';
+  }
+
+  // Create a Date object from the input date string
   const date = new Date(dateString);
-  return isNaN(date.getTime()) ? '' : date.toISOString();
+
+  // Check if the date is valid
+  if (isNaN(date.getTime())) {
+    return '';
+  }
+
+  // snippet from https://stackoverflow.com/a/57842203
+  // but it might need to be improved:
+  // "This produces incorrect datetimes for several hours surrounding daylight saving times if the
+  // computer running the code is in a zone that doesn't obey the same daylight saving shifts as the target zone."
+  const utcDate = new Date(date.toLocaleString('en-US', {
+    timeZone: 'UTC'
+  }));
+  const tzDate = new Date(date.toLocaleString('en-US', {
+    timeZone: timezone
+  }));
+  const offset = utcDate.getTime() - tzDate.getTime();
+  const newDate = new Date(date.getTime() + offset);
+  return newDate.toISOString();
 }
 function defaultDateFormatter(dateString, locale, timezone) {
   return new Date(dateString).toLocaleDateString(locale, {
@@ -52,6 +80,8 @@ function defaultDateFormatter(dateString, locale, timezone) {
 ---
 category: components
 ---
+
+@module experimental
 **/
 const DateInput2 = ({
   renderLabel,
@@ -75,10 +105,29 @@ const DateInput2 = ({
   // margin, TODO enable this prop
   ...rest
 }) => {
-  const _useState = useState(''),
+  const localeContext = useContext(ApplyLocaleContext);
+  const getLocale = () => {
+    if (locale) {
+      return locale;
+    } else if (localeContext.locale) {
+      return localeContext.locale;
+    }
+    // default to the system's locale
+    return Locale.browserLocale();
+  };
+  const getTimezone = () => {
+    if (timezone) {
+      return timezone;
+    } else if (localeContext.timezone) {
+      return localeContext.timezone;
+    }
+    // default to the system's timezone
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  };
+  const _useState = useState(value ? formatDate(value, getLocale(), getTimezone()) : ''),
     _useState2 = _slicedToArray(_useState, 2),
-    selectedDate = _useState2[0],
-    setSelectedDate = _useState2[1];
+    inputValue = _useState2[0],
+    setInputValue = _useState2[1];
   const _useState3 = useState(messages || []),
     _useState4 = _slicedToArray(_useState3, 2),
     inputMessages = _useState4[0],
@@ -87,38 +136,29 @@ const DateInput2 = ({
     _useState6 = _slicedToArray(_useState5, 2),
     showPopover = _useState6[0],
     setShowPopover = _useState6[1];
-  const localeContext = useContext(ApplyLocaleContext);
-  useEffect(() => {
-    // when `value` is changed, validation removes the error message if passes
-    // but it's NOT adding error message if validation fails for better UX
-    validateInput(true);
-  }, [value]);
   useEffect(() => {
     setInputMessages(messages || []);
   }, [messages]);
   useEffect(() => {
-    setSelectedDate(parseDate(value || ''));
-  }, []);
-  const handleInputChange = (e, newValue, parsedDate = '') => {
-    // blur event formats the input which shouldn't trigger parsing
-    if (e.type !== 'blur') {
-      setSelectedDate(parseDate(newValue));
-    }
-    onChange === null || onChange === void 0 ? void 0 : onChange(e, newValue, parsedDate);
+    validateInput(true);
+  }, [inputValue]);
+  const handleInputChange = (e, newValue) => {
+    setInputValue(newValue);
+    const parsedInput = timezoneDateToUtc(newValue, getTimezone());
+    onChange === null || onChange === void 0 ? void 0 : onChange(e, parsedInput, newValue);
   };
   const handleDateSelected = (dateString, _momentDate, e) => {
     const formattedDate = formatDate(dateString, getLocale(), getTimezone());
-    const parsedDate = parseDate(dateString);
-    setSelectedDate(parsedDate);
-    handleInputChange(e, formattedDate, parsedDate);
+    setInputValue(formattedDate);
     setShowPopover(false);
+    onChange === null || onChange === void 0 ? void 0 : onChange(e, dateString, formattedDate);
     onRequestValidateDate === null || onRequestValidateDate === void 0 ? void 0 : onRequestValidateDate(dateString, true);
   };
 
   // onlyRemoveError is used to remove the error msg immediately when the user inputs a valid date (and don't wait for blur event)
   const validateInput = (onlyRemoveError = false) => {
     // don't validate empty input
-    if (!value || parseDate(value) || selectedDate) {
+    if (!inputValue || timezoneDateToUtc(inputValue, getTimezone()) || value) {
       setInputMessages(messages || []);
       return true;
     }
@@ -131,30 +171,16 @@ const DateInput2 = ({
     }
     return false;
   };
-  const getLocale = () => {
-    if (locale) {
-      return locale;
-    } else if (localeContext.locale) {
-      return localeContext.locale;
-    }
-    return Locale.browserLocale();
-  };
-  const getTimezone = () => {
-    if (timezone) {
-      return timezone;
-    } else if (localeContext.timezone) {
-      return localeContext.timezone;
-    }
-    // default to the system's timezone
-    return Intl.DateTimeFormat().resolvedOptions().timeZone;
-  };
   const handleBlur = e => {
-    const isInputValid = validateInput(false);
-    if (isInputValid && selectedDate) {
-      const formattedDate = formatDate(selectedDate, getLocale(), getTimezone());
-      handleInputChange(e, formattedDate, selectedDate);
+    if (value) {
+      const formattedDate = formatDate(value, getLocale(), getTimezone());
+      if (formattedDate !== inputValue) {
+        setInputValue(formattedDate);
+        onChange === null || onChange === void 0 ? void 0 : onChange(e, value, formattedDate);
+      }
     }
-    onRequestValidateDate === null || onRequestValidateDate === void 0 ? void 0 : onRequestValidateDate(value, isInputValid);
+    validateInput(false);
+    onRequestValidateDate === null || onRequestValidateDate === void 0 ? void 0 : onRequestValidateDate(value, !!value);
     onBlur === null || onBlur === void 0 ? void 0 : onBlur(e);
   };
   return jsx(TextInput, Object.assign({}, passthroughProps(rest), {
@@ -163,7 +189,7 @@ const DateInput2 = ({
     onChange: handleInputChange,
     onBlur: handleBlur,
     isRequired: isRequired,
-    value: value,
+    value: inputValue,
     placeholder: placeholder,
     width: width,
     size: size,
@@ -189,8 +215,8 @@ const DateInput2 = ({
     }, jsx(Calendar, {
       withYearPicker: withYearPicker,
       onDateSelected: handleDateSelected,
-      selectedDate: selectedDate,
-      visibleMonth: selectedDate,
+      selectedDate: value,
+      visibleMonth: value,
       locale: getLocale(),
       timezone: getTimezone(),
       role: "listbox",

package/es/DateInput2/props.js

@@ -38,8 +38,6 @@ const propTypes = {
   isInline: PropTypes.bool,
   width: PropTypes.string,
   messages: PropTypes.arrayOf(FormPropTypes.message),
-  onRequestShowCalendar: PropTypes.func,
-  onRequestHideCalendar: PropTypes.func,
   onRequestValidateDate: PropTypes.func,
   invalidDateErrorMessage: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
   locale: PropTypes.string,

package/lib/DateInput2/index.js

@@ -44,9 +44,37 @@ var _IconCalendarMonthLin, _IconArrowOpenEndSoli, _IconArrowOpenStartSo;
  * SOFTWARE.
  */
 /** @jsx jsx */
-function parseDate(dateString) {
+/*
+ * Tries parsing a date in a given timezone, if it's not possible, returns an empty string
+ * If parsing is successful an ISO formatted datetime string is returned in UTC timezone
+ */
+function timezoneDateToUtc(dateString, timezone) {
+  // Don't try to parse short dateString, they are incomplete
+  if (dateString.length < 10) {
+    return '';
+  }
+
+  // Create a Date object from the input date string
   const date = new Date(dateString);
-  return isNaN(date.getTime()) ? '' : date.toISOString();
+
+  // Check if the date is valid
+  if (isNaN(date.getTime())) {
+    return '';
+  }
+
+  // snippet from https://stackoverflow.com/a/57842203
+  // but it might need to be improved:
+  // "This produces incorrect datetimes for several hours surrounding daylight saving times if the
+  // computer running the code is in a zone that doesn't obey the same daylight saving shifts as the target zone."
+  const utcDate = new Date(date.toLocaleString('en-US', {
+    timeZone: 'UTC'
+  }));
+  const tzDate = new Date(date.toLocaleString('en-US', {
+    timeZone: timezone
+  }));
+  const offset = utcDate.getTime() - tzDate.getTime();
+  const newDate = new Date(date.getTime() + offset);
+  return newDate.toISOString();
 }
 function defaultDateFormatter(dateString, locale, timezone) {
   return new Date(dateString).toLocaleDateString(locale, {
@@ -61,6 +89,8 @@ function defaultDateFormatter(dateString, locale, timezone) {
 ---
 category: components
 ---
+
+@module experimental
 **/
 const DateInput2 = ({
   renderLabel,
@@ -84,10 +114,29 @@ const DateInput2 = ({
   // margin, TODO enable this prop
   ...rest
 }) => {
-  const _useState = (0, _react.useState)(''),
+  const localeContext = (0, _react.useContext)(_ApplyLocaleContext.ApplyLocaleContext);
+  const getLocale = () => {
+    if (locale) {
+      return locale;
+    } else if (localeContext.locale) {
+      return localeContext.locale;
+    }
+    // default to the system's locale
+    return _Locale.Locale.browserLocale();
+  };
+  const getTimezone = () => {
+    if (timezone) {
+      return timezone;
+    } else if (localeContext.timezone) {
+      return localeContext.timezone;
+    }
+    // default to the system's timezone
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  };
+  const _useState = (0, _react.useState)(value ? formatDate(value, getLocale(), getTimezone()) : ''),
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
-    selectedDate = _useState2[0],
-    setSelectedDate = _useState2[1];
+    inputValue = _useState2[0],
+    setInputValue = _useState2[1];
   const _useState3 = (0, _react.useState)(messages || []),
     _useState4 = (0, _slicedToArray2.default)(_useState3, 2),
     inputMessages = _useState4[0],
@@ -96,38 +145,29 @@ const DateInput2 = ({
     _useState6 = (0, _slicedToArray2.default)(_useState5, 2),
     showPopover = _useState6[0],
     setShowPopover = _useState6[1];
-  const localeContext = (0, _react.useContext)(_ApplyLocaleContext.ApplyLocaleContext);
-  (0, _react.useEffect)(() => {
-    // when `value` is changed, validation removes the error message if passes
-    // but it's NOT adding error message if validation fails for better UX
-    validateInput(true);
-  }, [value]);
   (0, _react.useEffect)(() => {
     setInputMessages(messages || []);
   }, [messages]);
   (0, _react.useEffect)(() => {
-    setSelectedDate(parseDate(value || ''));
-  }, []);
-  const handleInputChange = (e, newValue, parsedDate = '') => {
-    // blur event formats the input which shouldn't trigger parsing
-    if (e.type !== 'blur') {
-      setSelectedDate(parseDate(newValue));
-    }
-    onChange === null || onChange === void 0 ? void 0 : onChange(e, newValue, parsedDate);
+    validateInput(true);
+  }, [inputValue]);
+  const handleInputChange = (e, newValue) => {
+    setInputValue(newValue);
+    const parsedInput = timezoneDateToUtc(newValue, getTimezone());
+    onChange === null || onChange === void 0 ? void 0 : onChange(e, parsedInput, newValue);
   };
   const handleDateSelected = (dateString, _momentDate, e) => {
     const formattedDate = formatDate(dateString, getLocale(), getTimezone());
-    const parsedDate = parseDate(dateString);
-    setSelectedDate(parsedDate);
-    handleInputChange(e, formattedDate, parsedDate);
+    setInputValue(formattedDate);
     setShowPopover(false);
+    onChange === null || onChange === void 0 ? void 0 : onChange(e, dateString, formattedDate);
     onRequestValidateDate === null || onRequestValidateDate === void 0 ? void 0 : onRequestValidateDate(dateString, true);
   };
 
   // onlyRemoveError is used to remove the error msg immediately when the user inputs a valid date (and don't wait for blur event)
   const validateInput = (onlyRemoveError = false) => {
     // don't validate empty input
-    if (!value || parseDate(value) || selectedDate) {
+    if (!inputValue || timezoneDateToUtc(inputValue, getTimezone()) || value) {
       setInputMessages(messages || []);
       return true;
     }
@@ -140,30 +180,16 @@ const DateInput2 = ({
     }
     return false;
   };
-  const getLocale = () => {
-    if (locale) {
-      return locale;
-    } else if (localeContext.locale) {
-      return localeContext.locale;
-    }
-    return _Locale.Locale.browserLocale();
-  };
-  const getTimezone = () => {
-    if (timezone) {
-      return timezone;
-    } else if (localeContext.timezone) {
-      return localeContext.timezone;
-    }
-    // default to the system's timezone
-    return Intl.DateTimeFormat().resolvedOptions().timeZone;
-  };
   const handleBlur = e => {
-    const isInputValid = validateInput(false);
-    if (isInputValid && selectedDate) {
-      const formattedDate = formatDate(selectedDate, getLocale(), getTimezone());
-      handleInputChange(e, formattedDate, selectedDate);
+    if (value) {
+      const formattedDate = formatDate(value, getLocale(), getTimezone());
+      if (formattedDate !== inputValue) {
+        setInputValue(formattedDate);
+        onChange === null || onChange === void 0 ? void 0 : onChange(e, value, formattedDate);
+      }
     }
-    onRequestValidateDate === null || onRequestValidateDate === void 0 ? void 0 : onRequestValidateDate(value, isInputValid);
+    validateInput(false);
+    onRequestValidateDate === null || onRequestValidateDate === void 0 ? void 0 : onRequestValidateDate(value, !!value);
     onBlur === null || onBlur === void 0 ? void 0 : onBlur(e);
   };
   return (0, _emotion.jsx)(_TextInput.TextInput, Object.assign({}, (0, _passthroughProps.passthroughProps)(rest), {
@@ -172,7 +198,7 @@ const DateInput2 = ({
     onChange: handleInputChange,
     onBlur: handleBlur,
     isRequired: isRequired,
-    value: value,
+    value: inputValue,
     placeholder: placeholder,
     width: width,
     size: size,
@@ -198,8 +224,8 @@ const DateInput2 = ({
     }, (0, _emotion.jsx)(_Calendar.Calendar, {
       withYearPicker: withYearPicker,
       onDateSelected: handleDateSelected,
-      selectedDate: selectedDate,
-      visibleMonth: selectedDate,
+      selectedDate: value,
+      visibleMonth: value,
       locale: getLocale(),
       timezone: getTimezone(),
       role: "listbox",

package/lib/DateInput2/props.js

@@ -45,8 +45,6 @@ const propTypes = exports.propTypes = {
   isInline: _propTypes.default.bool,
   width: _propTypes.default.string,
   messages: _propTypes.default.arrayOf(_FormPropTypes.FormPropTypes.message),
-  onRequestShowCalendar: _propTypes.default.func,
-  onRequestHideCalendar: _propTypes.default.func,
   onRequestValidateDate: _propTypes.default.func,
   invalidDateErrorMessage: _propTypes.default.oneOfType([_propTypes.default.func, _propTypes.default.string]),
   locale: _propTypes.default.string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-date-input",
-  "version": "9.6.0",
+  "version": "9.6.1-snapshot-2",
   "description": "A UI component library made by Instructure Inc.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@instructure/ui-axe-check": "9.6.0",
-    "@instructure/ui-babel-preset": "9.6.0",
-    "@instructure/ui-buttons": "9.6.0",
-    "@instructure/ui-scripts": "9.6.0",
-    "@instructure/ui-test-utils": "9.6.0",
+    "@instructure/ui-axe-check": "9.6.1-snapshot-2",
+    "@instructure/ui-babel-preset": "9.6.1-snapshot-2",
+    "@instructure/ui-buttons": "9.6.1-snapshot-2",
+    "@instructure/ui-scripts": "9.6.1-snapshot-2",
+    "@instructure/ui-test-utils": "9.6.1-snapshot-2",
     "@testing-library/jest-dom": "^6.4.6",
     "@testing-library/react": "^15.0.7",
     "@testing-library/user-event": "^14.5.2",
@@ -35,20 +35,20 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.24.5",
-    "@instructure/emotion": "9.6.0",
-    "@instructure/shared-types": "9.6.0",
-    "@instructure/ui-calendar": "9.6.0",
-    "@instructure/ui-form-field": "9.6.0",
-    "@instructure/ui-i18n": "9.6.0",
-    "@instructure/ui-icons": "9.6.0",
-    "@instructure/ui-popover": "9.6.0",
-    "@instructure/ui-position": "9.6.0",
-    "@instructure/ui-prop-types": "9.6.0",
-    "@instructure/ui-react-utils": "9.6.0",
-    "@instructure/ui-selectable": "9.6.0",
-    "@instructure/ui-testable": "9.6.0",
-    "@instructure/ui-text-input": "9.6.0",
-    "@instructure/ui-utils": "9.6.0",
+    "@instructure/emotion": "9.6.1-snapshot-2",
+    "@instructure/shared-types": "9.6.1-snapshot-2",
+    "@instructure/ui-calendar": "9.6.1-snapshot-2",
+    "@instructure/ui-form-field": "9.6.1-snapshot-2",
+    "@instructure/ui-i18n": "9.6.1-snapshot-2",
+    "@instructure/ui-icons": "9.6.1-snapshot-2",
+    "@instructure/ui-popover": "9.6.1-snapshot-2",
+    "@instructure/ui-position": "9.6.1-snapshot-2",
+    "@instructure/ui-prop-types": "9.6.1-snapshot-2",
+    "@instructure/ui-react-utils": "9.6.1-snapshot-2",
+    "@instructure/ui-selectable": "9.6.1-snapshot-2",
+    "@instructure/ui-testable": "9.6.1-snapshot-2",
+    "@instructure/ui-text-input": "9.6.1-snapshot-2",
+    "@instructure/ui-utils": "9.6.1-snapshot-2",
     "moment-timezone": "^0.5.45",
     "prop-types": "^15.8.1"
   },

package/src/DateInput2/README.md

@@ -2,16 +2,53 @@
 describes: DateInput2
 ---
 
-This component is an updated version of [`DateInput`](/#DateInput) that's easier to configure for developers, has a better UX, better accessibility features and a year picker. We recommend using this instead of `DateInput` which will be deprecated in the future.
+`DateInput2` is an experimental upgrade to the existing [`DateInput`](/#DateInput) component, offering easier configuration, better UX, improved accessibility, and a year picker. While it addresses key limitations of `DateInput`, it's still in the experimental phase, with some missing unit tests and potential (though unlikely) API changes.
+
+`DateInput` will be deprecated in the future, but for now, developers can start using `DateInput2` and provide feedback.
 
 ### Minimal config
 
 - ```js
   class Example extends React.Component {
-    state = { value: '' }
+    initialDate = '2024-09-09T14:00:00.000Z'
+    state = { dateString: this.initialDate, inputValue: '' }
 
     render() {
       return (
+        <div>
+          <DateInput2
+            renderLabel="Choose a date"
+            screenReaderLabels={{
+              calendarIcon: 'Calendar',
+              nextMonthButton: 'Next month',
+              prevMonthButton: 'Previous month'
+            }}
+            value={this.state.dateString}
+            width="20rem"
+            onChange={(e, dateString, inputValue) => {
+              this.setState({ dateString, inputValue })
+            }}
+            invalidDateErrorMessage="Invalid date"
+          />
+          <p>
+            UTC Date String: <code>{this.state.dateString}</code>
+            <br />
+            Input Value: <code>{this.state.inputValue}</code>
+          </p>
+        </div>
+      )
+    }
+  }
+
+  render(<Example />)
+  ```
+
+- ```js
+  const Example = () => {
+    const [dateString, setDateString] = useState('')
+    const [inputValue, setInputValue] = useState('')
+    return (
+      <div>
         <DateInput2
           renderLabel="Choose a date"
           screenReaderLabels={{
@@ -19,39 +56,35 @@ This component is an updated version of [`DateInput`](/#DateInput) that's easier
             nextMonthButton: 'Next month',
             prevMonthButton: 'Previous month'
           }}
-          value={this.state.value}
+          value={dateString}
           width="20rem"
-          onChange={(e, value) => this.setState({ value })}
+          onChange={(e, newDateString, newInputValue) => {
+            setDateString(newDateString)
+            setInputValue(newInputValue)
+          }}
           invalidDateErrorMessage="Invalid date"
         />
-      )
-    }
+        <p>
+          UTC Date String: <code>{dateString}</code>
+          <br />
+          Input Value: <code>{inputValue}</code>
+        </p>
+      </div>
+    )
   }
 
   render(<Example />)
   ```
 
-- ```js
-  const Example = () => {
-    const [value, setValue] = useState('')
-    return (
-      <DateInput2
-        renderLabel="Choose a date"
-        screenReaderLabels={{
-          calendarIcon: 'Calendar',
-          nextMonthButton: 'Next month',
-          prevMonthButton: 'Previous month'
-        }}
-        value={value}
-        width="20rem"
-        onChange={(e, value) => setValue(value)}
-        invalidDateErrorMessage="Invalid date"
-      />
-    )
-  }
+### Timezones and UTC
 
-  render(<Example />)
-  ```
+In the example above you can see that the date is set via the `value` prop and returned from the `onChange` callback. This date is expected to be in UTC timezone. So if a user chooses September 10th 2024 with the timezone 'Europe/Budapest', the `onChange` function will return `2024-09-09T22:00:00.000Z` because Budapest is two hours ahead of UTC.
+
+Altought it would be nice to use the date picker without timezones and leave the time out alltogether but unfortunately you cannot decouple time from dates since the timezone determines when a day ends and another starts. In certain cases this changes the month or even the year. This can affect how you store and load dates from your database: if you want to set a saved date and that date is already timezone adjusted, you have to set it to utc with your date library of choice.
+
+### Parsing dates
+
+When typing a date in the input field instead of using the included picker, the component tries to parse the date as you type it in. To prevent premature parsing (e.g. interpreting `2024` as `2024-01-01T00:00:00.000Z`) parsing only turns on after 10 character. Typed in dates are expected to be in [Date Time String Format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format). Any other format are implementation dependant and might differ browser by browser.
 
 ### With year picker
 
@@ -115,9 +148,9 @@ This component is an updated version of [`DateInput`](/#DateInput) that's easier
 
 ### Date validation
 
-By default `DateInput2` only does date validation if the `invalidDateErrorMessage` prop is provided. This uses the browser's `Date` object to try an parse the user provided date and displays the error message if it fails. Validation is only triggered on the blur event of the input field.
+By default `DateInput2` only does date validation if the `invalidDateErrorMessage` prop is provided. This uses the browser's `Date` object to try and parse the user provided date and displays the error message if it fails. Validation is triggered on the blur event of the input field.
 
-If you want to do a more complex validation than the above (e.g. only allow a subset of dates) you can use the `onRequestValidateDate` prop to pass a validation function. This function will run on blur or on selecting the date from the picker. The result of the internal validation will be passed to this function. Then you have to set the error messages accordingly. Check the following example for more details:
+If you want to do a more complex validation than the above (e.g. only allow a subset of dates) you can use the `onRequestValidateDate` prop to pass a validation function. This function will run on blur or on selecting a date from the picker. The result of the internal validation will be passed to this function. Then you have to set the error messages accordingly. Check the following example for more details:
 
 ```js
 ---
@@ -170,7 +203,7 @@ render(<Example />)
 
 ### Date formatting
 
-The display format of the dates can be set via the `formatDate` property. It will be applied if the user clicks on a date in the date picker of after blur event from the input field.
+The display format of the date value can be set via the `formatDate` property. It will be applied if the user clicks on a date in the date picker or after the blur event from the input field.
 Something to pay attention to is that the date string passed back in the callback function **is in UTC timezone**.
 
 ```js