@instructure/ui-date-input 9.6.0 → 9.6.1-pr-snapshot-1726659472372

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-date-input",
-  "version": "9.6.0",
+  "version": "9.6.1-pr-snapshot-1726659472372",
   "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-pr-snapshot-1726659472372",
+    "@instructure/ui-babel-preset": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-buttons": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-scripts": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-test-utils": "9.6.1-pr-snapshot-1726659472372",
     "@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-pr-snapshot-1726659472372",
+    "@instructure/shared-types": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-calendar": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-form-field": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-i18n": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-icons": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-popover": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-position": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-prop-types": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-react-utils": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-selectable": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-testable": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-text-input": "9.6.1-pr-snapshot-1726659472372",
+    "@instructure/ui-utils": "9.6.1-pr-snapshot-1726659472372",
     "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,28 +2,37 @@
 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.
+> *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 {
-    state = { value: '' }
+    state = { inputValue: '', dateString: '' }
 
     render() {
       return (
-        <DateInput2
-          renderLabel="Choose a date"
-          screenReaderLabels={{
-            calendarIcon: 'Calendar',
-            nextMonthButton: 'Next month',
-            prevMonthButton: 'Previous month'
-          }}
-          value={this.state.value}
-          width="20rem"
-          onChange={(e, value) => this.setState({ value })}
-          invalidDateErrorMessage="Invalid date"
-        />
+        <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"
+          />
+          <p>
+            Input Value: <code>{this.state.inputValue}</code>
+            <br />
+            UTC Date String: <code>{this.state.dateString}</code>
+          </p>
+        </div>
       )
     }
   }
@@ -33,8 +42,58 @@ This component is an updated version of [`DateInput`](/#DateInput) that's easier
 
 - ```js
   const Example = () => {
-    const [value, setValue] = 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={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 />)
+  ```
+
+### Parsing and formatting dates
+
+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).
+
+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.
+
+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.
+
+The default parser also have a limitation of excluding 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('')
+
+  return (
+    <div>
+      <p>US locale with german date format:</p>
       <DateInput2
         renderLabel="Choose a date"
         screenReaderLabels={{
@@ -42,42 +101,87 @@ This component is an updated version of [`DateInput`](/#DateInput) that's easier
           nextMonthButton: 'Next month',
           prevMonthButton: 'Previous month'
         }}
-        value={value}
         width="20rem"
+        value={value}
+        locale="en-us"
+        dateFormat="de-de"
         onChange={(e, value) => setValue(value)}
-        invalidDateErrorMessage="Invalid date"
       />
-    )
-  }
+      <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={value2}
+        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) => setValue2(value)}
+      />
+    </div>
+  )
+}
 
-  render(<Example />)
-  ```
+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>
       )
     }
   }
@@ -87,26 +191,36 @@ This component is an updated version of [`DateInput`](/#DateInput) that's easier
 
 - ```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>
     )
   }
 
@@ -115,9 +229,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. Validation is triggered on the blur event of the input field. Invalid dates are determined based on [parsing](/#DateInput2/#Parsing%20and%20formatting%20dates).
 
-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 `onBlur` and `messages` props.
 
 ```js
 ---
@@ -125,18 +239,22 @@ 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) => {
+    const date = new Date(utcIsoDate)
+    console.log(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([])
@@ -145,7 +263,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',
@@ -167,101 +285,3 @@ const Example = () => {
 
 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.
-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,
-    })
-  }
-
-  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 />)
-```