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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-date-input",
-  "version": "9.5.2",
+  "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.5.2",
-    "@instructure/ui-babel-preset": "9.5.2",
-    "@instructure/ui-buttons": "9.5.2",
-    "@instructure/ui-scripts": "9.5.2",
-    "@instructure/ui-test-utils": "9.5.2",
+    "@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.5.2",
-    "@instructure/shared-types": "9.5.2",
-    "@instructure/ui-calendar": "9.5.2",
-    "@instructure/ui-form-field": "9.5.2",
-    "@instructure/ui-i18n": "9.5.2",
-    "@instructure/ui-icons": "9.5.2",
-    "@instructure/ui-popover": "9.5.2",
-    "@instructure/ui-position": "9.5.2",
-    "@instructure/ui-prop-types": "9.5.2",
-    "@instructure/ui-react-utils": "9.5.2",
-    "@instructure/ui-selectable": "9.5.2",
-    "@instructure/ui-testable": "9.5.2",
-    "@instructure/ui-text-input": "9.5.2",
-    "@instructure/ui-utils": "9.5.2",
+    "@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,33 +191,47 @@ 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>
     )
   }
 
   render(<Example />)
   ```
 
-### With custom validation
+### Date validation
+
+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 `onBlur` and `messages` props.
 
 ```js
 ---
@@ -121,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([])
@@ -141,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',