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

package/lib/DateInput2/props.js

@@ -36,7 +36,6 @@ const propTypes = exports.propTypes = {
   renderLabel: _propTypes.default.oneOfType([_propTypes.default.node, _propTypes.default.func]).isRequired,
   screenReaderLabels: _propTypes.default.object.isRequired,
   value: (0, _controllable.controllable)(_propTypes.default.string),
-  size: _propTypes.default.oneOf(['small', 'medium', 'large']),
   placeholder: _propTypes.default.string,
   onChange: _propTypes.default.func,
   onBlur: _propTypes.default.func,
@@ -45,10 +44,10 @@ const propTypes = exports.propTypes = {
   isInline: _propTypes.default.bool,
   width: _propTypes.default.string,
   messages: _propTypes.default.arrayOf(_FormPropTypes.FormPropTypes.message),
-  onRequestValidateDate: _propTypes.default.func,
   invalidDateErrorMessage: _propTypes.default.oneOfType([_propTypes.default.func, _propTypes.default.string]),
   locale: _propTypes.default.string,
   timezone: _propTypes.default.string,
   withYearPicker: _propTypes.default.object,
-  formatDate: _propTypes.default.func
+  dateFormat: _propTypes.default.oneOfType([_propTypes.default.string, _propTypes.default.object]),
+  onRequestValidateDate: _propTypes.default.func
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-date-input",
-  "version": "9.6.1-snapshot-2",
+  "version": "9.7.0",
   "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.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",
+    "@instructure/ui-axe-check": "9.7.0",
+    "@instructure/ui-babel-preset": "9.7.0",
+    "@instructure/ui-buttons": "9.7.0",
+    "@instructure/ui-scripts": "9.7.0",
+    "@instructure/ui-test-utils": "9.7.0",
     "@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.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",
+    "@instructure/emotion": "9.7.0",
+    "@instructure/shared-types": "9.7.0",
+    "@instructure/ui-calendar": "9.7.0",
+    "@instructure/ui-form-field": "9.7.0",
+    "@instructure/ui-i18n": "9.7.0",
+    "@instructure/ui-icons": "9.7.0",
+    "@instructure/ui-popover": "9.7.0",
+    "@instructure/ui-position": "9.7.0",
+    "@instructure/ui-prop-types": "9.7.0",
+    "@instructure/ui-react-utils": "9.7.0",
+    "@instructure/ui-selectable": "9.7.0",
+    "@instructure/ui-testable": "9.7.0",
+    "@instructure/ui-text-input": "9.7.0",
+    "@instructure/ui-utils": "9.7.0",
     "moment-timezone": "^0.5.45",
     "prop-types": "^15.8.1"
   },

package/src/DateInput/README.md

@@ -2,7 +2,7 @@
 describes: DateInput
 ---
 
-> **Important:** You can now use are updated version [`DateInput2`](/#DateInput2) which is easier to configure for developers, has a better UX, better accessibility features and a year picker. We recommend using that instead of `DateInput` which will be deprecated in the future.
+> *Note:* you can now try the updated (but still experimental) [`DateInput2`](/#DateInput2) which is easier to configure for developers, has a better UX, better accessibility features and a year picker. We recommend using that instead of `DateInput` which will be deprecated in the future.
 
 The `DateInput` component provides a visual interface for inputting date data.
 

package/src/DateInput2/README.md

@@ -2,16 +2,13 @@
 describes: DateInput2
 ---
 
-`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.
+> *Warning*: `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 API changes.
 
 ### Minimal config
 
 - ```js
   class Example extends React.Component {
-    initialDate = '2024-09-09T14:00:00.000Z'
-    state = { dateString: this.initialDate, inputValue: '' }
+    state = { inputValue: '', dateString: '' }
 
     render() {
       return (
@@ -23,17 +20,17 @@ describes: DateInput2
               nextMonthButton: 'Next month',
               prevMonthButton: 'Previous month'
             }}
-            value={this.state.dateString}
+            value={this.state.inputValue}
             width="20rem"
-            onChange={(e, dateString, inputValue) => {
+            onChange={(e, inputValue, dateString) => {
               this.setState({ dateString, inputValue })
             }}
             invalidDateErrorMessage="Invalid date"
           />
           <p>
-            UTC Date String: <code>{this.state.dateString}</code>
-            <br />
             Input Value: <code>{this.state.inputValue}</code>
+            <br />
+            UTC Date String: <code>{this.state.dateString}</code>
           </p>
         </div>
       )
@@ -45,72 +42,160 @@ describes: DateInput2
 
 - ```js
   const Example = () => {
-    const [dateString, setDateString] = useState('')
     const [inputValue, setInputValue] = useState('')
+    const [dateString, setDateString] = useState('')
     return (
       <div>
-        <DateInput2
-          renderLabel="Choose a date"
-          screenReaderLabels={{
-            calendarIcon: 'Calendar',
-            nextMonthButton: 'Next month',
-            prevMonthButton: 'Previous month'
-          }}
-          value={dateString}
-          width="20rem"
-          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>
+          <DateInput2
+            renderLabel="Choose a date"
+            screenReaderLabels={{
+              calendarIcon: 'Calendar',
+              nextMonthButton: 'Next month',
+              prevMonthButton: 'Previous month'
+            }}
+            value={inputValue}
+            width="20rem"
+            onChange={(e, inputValue, dateString) => {
+              setInputValue(inputValue)
+              setDateString(dateString)
+            }}
+            invalidDateErrorMessage="Invalid date"
+          />
+          <p>
+            Input Value: <code>{inputValue}</code>
+            <br />
+            UTC Date String: <code>{dateString}</code>
+          </p>
+        </div>
     )
   }
 
   render(<Example />)
   ```
 
-### Timezones and UTC
+### Parsing and formatting dates
 
-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.
+When typing in a date manually (instead of using the included picker), the component tries to parse the date as you type it in. By default parsing is based on the user's locale which determines the order of day, month and year (e.g.: a user with US locale will have MONTH/DAY/YEAR order, and someone with GB locale will have DAY/MONTH/YEAR order).
 
-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.
+Any of the following separators can be used when typing a date: `,`, `-`, `.`, `/` or a whitespace however on blur the date will be formatted according to the locale and separators will be changed and leading zeros also adjusted.
 
-### Parsing dates
+If you want different parsing and formatting then the current locale you can use the `dateFormat` prop which accepts either a string with a name of a different locale (so you can use US date format even if the user is France) or a parser and formatter functions.
 
-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.
+The default parser also has a limitation of not working with years before `1000` and after `9999`. These values are invalid by default but not with custom parsers.
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [value, setValue] = useState('')
+  const [value2, setValue2] = useState('')
+  const [value3, setValue3] = useState('')
+
+  return (
+    <div>
+      <p>US locale with default format:</p>
+      <DateInput2
+        renderLabel="Choose a date"
+        screenReaderLabels={{
+          calendarIcon: 'Calendar',
+          nextMonthButton: 'Next month',
+          prevMonthButton: 'Previous month'
+        }}
+        width="20rem"
+        value={value}
+        locale="en-us"
+        onChange={(e, value) => setValue(value)}
+      />
+      <p>US locale with german date format:</p>
+      <DateInput2
+        renderLabel="Choose a date"
+        screenReaderLabels={{
+          calendarIcon: 'Calendar',
+          nextMonthButton: 'Next month',
+          prevMonthButton: 'Previous month'
+        }}
+        width="20rem"
+        value={value2}
+        locale="en-us"
+        dateFormat="de-de"
+        onChange={(e, value) => setValue2(value)}
+      />
+      <p>US locale with ISO date format:</p>
+      <DateInput2
+        renderLabel="Choose a date"
+        screenReaderLabels={{
+          calendarIcon: 'Calendar',
+          nextMonthButton: 'Next month',
+          prevMonthButton: 'Previous month'
+        }}
+        width="20rem"
+        value={value3}
+        locale="en-us"
+        dateFormat={{
+          parser: (input) => {
+            // split input on '.', whitespace, '/', ',' or '-' using regex: /[.\s/.-]+/
+            // the '+' allows splitting on consecutive delimiters
+            const [year, month, day] = input.split(/[,.\s/.-]+/)
+            const newDate = new Date(year, month-1, day)
+            return isNaN(newDate) ? '' : newDate
+          },
+          formatter: (date) => {
+            // vanilla js formatter but you could use a date library instead
+            const year = date.getFullYear()
+            // month is zero indexed so add 1
+            const month = `${date.getMonth() + 1}`.padStart(2, '0')
+            const day = `${date.getDate()}`.padStart(2, '0')
+            return `${year}-${month}-${day}`
+          }
+        }}
+        onChange={(e, value) => setValue3(value)}
+      />
+    </div>
+  )
+}
+
+render(<Example />)
+```
+
+### Timezones
+
+In the examples above you can see that the `onChange` callback also return a UTC date string. This means it is timezone adjusted. If the timezone is not set via the `timezone` prop, it is calculated/assumed from the user's machine. 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 (summertime).
 
 ### With year picker
 
 - ```js
   class Example extends React.Component {
-    state = { value: '' }
+    state = { inputValue: '', dateString: '' }
 
     render() {
       return (
-        <DateInput2
-          renderLabel="Choose a date"
-          screenReaderLabels={{
-            calendarIcon: 'Calendar',
-            nextMonthButton: 'Next month',
-            prevMonthButton: 'Previous month'
-          }}
-          width="20rem"
-          value={this.state.value}
-          onChange={(e, value) => this.setState({ value })}
-          invalidDateErrorMessage="Invalid date"
-          withYearPicker={{
-            screenReaderLabel: 'Year picker',
-            startYear: 1900,
-            endYear: 2024
-          }}
-        />
+        <div>
+          <DateInput2
+            renderLabel="Choose a date"
+            screenReaderLabels={{
+              calendarIcon: 'Calendar',
+              nextMonthButton: 'Next month',
+              prevMonthButton: 'Previous month'
+            }}
+            value={this.state.inputValue}
+            width="20rem"
+            onChange={(e, inputValue, dateString) => {
+              this.setState({ dateString, inputValue })
+            }}
+            invalidDateErrorMessage="Invalid date"
+            withYearPicker={{
+              screenReaderLabel: 'Year picker',
+              startYear: 1900,
+              endYear: 2024
+            }}
+          />
+          <p>
+            Input Value: <code>{this.state.inputValue}</code>
+            <br />
+            UTC Date String: <code>{this.state.dateString}</code>
+          </p>
+        </div>
       )
     }
   }
@@ -120,26 +205,36 @@ When typing a date in the input field instead of using the included picker, the
 
 - ```js
   const Example = () => {
-    const [value, setValue] = useState('')
-
+    const [inputValue, setInputValue] = useState('')
+    const [dateString, setDateString] = useState('')
     return (
-      <DateInput2
-        renderLabel="Choose a date"
-        screenReaderLabels={{
-          calendarIcon: 'Calendar',
-          nextMonthButton: 'Next month',
-          prevMonthButton: 'Previous month'
-        }}
-        width="20rem"
-        value={value}
-        onChange={(e, value) => setValue(value)}
-        invalidDateErrorMessage="Invalid date"
-        withYearPicker={{
-          screenReaderLabel: 'Year picker',
-          startYear: 1900,
-          endYear: 2024
-        }}
-      />
+      <div>
+          <DateInput2
+            renderLabel="Choose a date"
+            screenReaderLabels={{
+              calendarIcon: 'Calendar',
+              nextMonthButton: 'Next month',
+              prevMonthButton: 'Previous month'
+            }}
+            value={inputValue}
+            width="20rem"
+            onChange={(e, inputValue, dateString) => {
+              setInputValue(inputValue)
+              setDateString(dateString)
+            }}
+            invalidDateErrorMessage="Invalid date"
+            withYearPicker={{
+              screenReaderLabel: 'Year picker',
+              startYear: 1900,
+              endYear: 2024
+            }}
+          />
+          <p>
+            Input Value: <code>{inputValue}</code>
+            <br />
+            UTC Date String: <code>{dateString}</code>
+          </p>
+        </div>
     )
   }
 
@@ -148,9 +243,9 @@ When typing a date in the input field instead of using the included picker, the
 
 ### Date validation
 
-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.
+By default `DateInput2` only does date validation if the `invalidDateErrorMessage` prop is provided. Validation is triggered on the blur event of the input field. Invalid dates are determined current locale.
 
-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:
+If you want to do more complex validation (e.g. only allow a subset of dates) you can use the `onRequestValidateDate` and `messages` props.
 
 ```js
 ---
@@ -158,18 +253,24 @@ type: example
 ---
 const Example = () => {
   const [value, setValue] = useState('')
+  const [dateString, setDateString] = useState('')
   const [messages, setMessages] = useState([])
 
-  const handleDateValidation = (dateString, isValidDate) => {
-    if (!isValidDate) {
+  const handleDateValidation = (e, inputValue, utcIsoDate) => {
+    // utcIsoDate will be an empty string if the input cannot be parsed as a date
+
+    const date = new Date(utcIsoDate)
+
+    // don't validate empty input
+    if (!utcIsoDate && inputValue.length > 0) {
       setMessages([{
         type: 'error',
         text: 'This is not a valid date'
       }])
-    } else if (new Date(dateString) < new Date('January 1, 1900')) {
+    } else if (date < new Date('1990-01-01')) {
       setMessages([{
         type: 'error',
-        text: 'Use date after January 1, 1900'
+        text: 'Select date after January 1, 1990'
       }])
     } else {
       setMessages([])
@@ -178,7 +279,7 @@ const Example = () => {
 
   return (
     <DateInput2
-      renderLabel="Choose a date after January 1, 1900"
+      renderLabel="Choose a date after January 1, 1990"
       screenReaderLabels={{
         calendarIcon: 'Calendar',
         nextMonthButton: 'Next month',
@@ -201,100 +302,6 @@ const Example = () => {
 render(<Example />)
 ```
 
-### Date formatting
-
-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
----
-type: example
----
-const Example = () => {
-  const [value1, setValue1] = useState('')
-  const [value2, setValue2] = useState('')
-  const [value3, setValue3] = useState('')
-
-  const shortDateFormatFn = (dateString, locale, timezone) => {
-    return new Date(dateString).toLocaleDateString(locale, {
-      month: 'numeric',
-      year: 'numeric',
-      day: 'numeric',
-      timeZone: timezone,
-    })
-  }
+### Date format hint
 
-  const isoDateFormatFn = (dateString, locale, timezone) => {
-    // this is a simple way to get ISO8601 date in a specific timezone but should not be used in production
-    // please use a proper date library instead like date-fns, luxon or dayjs
-    const localeDate = new Date(dateString).toLocaleDateString('sv', {
-      month: 'numeric',
-      year: 'numeric',
-      day: 'numeric',
-      timeZone: timezone,
-    })
-
-    return localeDate
-  }
-
-  return (
-    <div style={{display: 'flex', flexDirection: 'column', gap: '1.5rem'}}>
-        <DateInput2
-          renderLabel="Default format"
-          screenReaderLabels={{
-            calendarIcon: 'Calendar',
-            nextMonthButton: 'Next month',
-            prevMonthButton: 'Previous month'
-          }}
-          isInline
-          width="20rem"
-          value={value1}
-          onChange={(e, value) => setValue1(value)}
-          withYearPicker={{
-            screenReaderLabel: 'Year picker',
-            startYear: 1900,
-            endYear: 2024
-          }}
-        />
-        <DateInput2
-          renderLabel="Short format in current locale"
-          screenReaderLabels={{
-            calendarIcon: 'Calendar',
-            nextMonthButton: 'Next month',
-            prevMonthButton: 'Previous month'
-          }}
-          isInline
-          width="20rem"
-          value={value2}
-          onChange={(e, value) => setValue2(value)}
-          formatDate={shortDateFormatFn}
-          withYearPicker={{
-            screenReaderLabel: 'Year picker',
-            startYear: 1900,
-            endYear: 2024
-          }}
-        />
-        <DateInput2
-          renderLabel="ISO8601"
-          screenReaderLabels={{
-            calendarIcon: 'Calendar',
-            nextMonthButton: 'Next month',
-            prevMonthButton: 'Previous month'
-          }}
-          isInline
-          width="20rem"
-          value={value3}
-          onChange={(e, value) => setValue3(value)}
-          formatDate={isoDateFormatFn}
-          withYearPicker={{
-            screenReaderLabel: 'Year picker',
-            startYear: 1900,
-            endYear: 2024
-          }}
-        />
-    </div>
-  )
-}
-
-render(<Example />)
-```
+If the `placeholder` property is undefined it will display a hint for the date format (like `DD/MM/YYYY`). Usually it is recommended to leave it as it is for a better user experience.