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

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
 
@@ -113,7 +146,11 @@ This component is an updated version of [`DateInput`](/#DateInput) that's easier
   render(<Example />)
   ```
 
-### With custom validation
+### 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.
+
+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
 ---
@@ -163,3 +200,101 @@ 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,
+    })
+  }
+
+  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 />)
+```

package/src/DateInput2/index.tsx

@@ -44,16 +44,55 @@ import type { DateInput2Props } from './props'
 import type { FormMessage } from '@instructure/ui-form-field'
 import type { Moment } from '@instructure/ui-i18n'
 
-function parseDate(dateString: string): string {
+/*
+ * 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: string, timezone: string): string {
+  // 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 empty string if not a valid date
-  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: string,
+  locale: string,
+  timezone: string
+) {
+  return new Date(dateString).toLocaleDateString(locale, {
+    month: 'long',
+    year: 'numeric',
+    day: 'numeric',
+    timeZone: timezone
+  })
 }
 
 /**
 ---
 category: components
 ---
+
+@module experimental
 **/
 const DateInput2 = ({
   renderLabel,
@@ -73,31 +112,52 @@ const DateInput2 = ({
   locale,
   timezone,
   placeholder,
+  formatDate = defaultDateFormatter,
+  // margin, TODO enable this prop
   ...rest
 }: DateInput2Props) => {
-  const [selectedDate, setSelectedDate] = useState<string>('')
+  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 [inputValue, setInputValue] = useState<string>(
+    value ? formatDate(value, getLocale(), getTimezone()) : ''
+  )
   const [inputMessages, setInputMessages] = useState<FormMessage[]>(
     messages || []
   )
   const [showPopover, setShowPopover] = useState<boolean>(false)
-  const localeContext = useContext(ApplyLocaleContext)
-
-  useEffect(() => {
-    // when `value` is changed, validation runs again and removes the error message if validation passes
-    // but it's NOT adding error message if validation fails for better UX
-    validateInput(true)
-  }, [value])
 
   useEffect(() => {
     setInputMessages(messages || [])
   }, [messages])
 
-  const handleInputChange = (e: SyntheticEvent, value: string) => {
-    onChange?.(e, value)
-    // blur event formats the input which should trigger parsing
-    if (e.type !== 'blur') {
-      setSelectedDate(parseDate(value))
-    }
+  useEffect(() => {
+    validateInput(true)
+  }, [inputValue])
+
+  const handleInputChange = (e: SyntheticEvent, newValue: string) => {
+    setInputValue(newValue)
+    const parsedInput = timezoneDateToUtc(newValue, getTimezone())
+    onChange?.(e, parsedInput, newValue)
   }
 
   const handleDateSelected = (
@@ -105,22 +165,17 @@ const DateInput2 = ({
     _momentDate: Moment,
     e: SyntheticEvent
   ) => {
-    const formattedDate = new Date(dateString).toLocaleDateString(getLocale(), {
-      month: 'long',
-      year: 'numeric',
-      day: 'numeric',
-      timeZone: getTimezone()
-    })
-    handleInputChange(e, formattedDate)
-    setSelectedDate(dateString)
+    const formattedDate = formatDate(dateString, getLocale(), getTimezone())
+    setInputValue(formattedDate)
     setShowPopover(false)
+    onChange?.(e, dateString, formattedDate)
     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): boolean => {
     // don't validate empty input
-    if (!value || parseDate(value) || selectedDate) {
+    if (!inputValue || timezoneDateToUtc(inputValue, getTimezone()) || value) {
       setInputMessages(messages || [])
       return true
     }
@@ -141,51 +196,28 @@ 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: SyntheticEvent) => {
-    const isInputValid = validateInput(false)
-    if (isInputValid && selectedDate) {
-      const formattedDate = new Date(selectedDate).toLocaleDateString(
-        getLocale(),
-        {
-          month: 'long',
-          year: 'numeric',
-          day: 'numeric',
-          timeZone: getTimezone()
-        }
-      )
-      handleInputChange(e, formattedDate)
+    if (value) {
+      const formattedDate = formatDate(value, getLocale(), getTimezone())
+      if (formattedDate !== inputValue) {
+        setInputValue(formattedDate)
+        onChange?.(e, value, formattedDate)
+      }
     }
-    onRequestValidateDate?.(value, isInputValid)
+    validateInput(false)
+    onRequestValidateDate?.(value, !!value)
     onBlur?.(e)
   }
 
   return (
     <TextInput
       {...passthroughProps(rest)}
+      // margin={'large'} TODO add this prop to TextInput
       renderLabel={renderLabel}
       onChange={handleInputChange}
       onBlur={handleBlur}
       isRequired={isRequired}
-      value={value}
+      value={inputValue}
       placeholder={placeholder}
       width={width}
       size={size}
@@ -217,10 +249,10 @@ const DateInput2 = ({
           <Calendar
             withYearPicker={withYearPicker}
             onDateSelected={handleDateSelected}
-            selectedDate={selectedDate}
-            visibleMonth={selectedDate}
-            locale={locale}
-            timezone={timezone}
+            selectedDate={value}
+            visibleMonth={value}
+            locale={getLocale()}
+            timezone={getTimezone()}
             role="listbox"
             renderNextMonthButton={
               <IconButton

package/src/DateInput2/props.ts

@@ -28,7 +28,11 @@ import type { SyntheticEvent, InputHTMLAttributes } from 'react'
 import { controllable } from '@instructure/ui-prop-types'
 import { FormPropTypes } from '@instructure/ui-form-field'
 import type { FormMessage } from '@instructure/ui-form-field'
-import type { OtherHTMLAttributes, Renderable, PropValidators } from '@instructure/shared-types'
+import type {
+  OtherHTMLAttributes,
+  Renderable,
+  PropValidators
+} from '@instructure/shared-types'
 
 type DateInput2OwnProps = {
   /**
@@ -41,9 +45,9 @@ type DateInput2OwnProps = {
     nextMonthButton: string
   }
   /**
-   * Specifies the input value.
+   * Specifies the input value *before* formatting. The `formatDate` will be applied to it before displaying. Should be a valid, parsable date.
    */
-  value?: string // TODO: controllable(PropTypes.string)
+  value?: string
   /**
    * Specifies the input size.
    */
@@ -56,7 +60,11 @@ type DateInput2OwnProps = {
   /**
    * Callback fired when the input changes.
    */
-  onChange?: (event: React.SyntheticEvent, value: string) => void
+  onChange?: (
+    event: React.SyntheticEvent,
+    isoDateString: string,
+    formattedValue: string
+  ) => void
   /**
    * Callback executed when the input fires a blur event.
    */
@@ -91,21 +99,12 @@ type DateInput2OwnProps = {
    */
   messages?: FormMessage[]
   /**
-   * Callback fired requesting the calendar be shown.
-   */
-  onRequestShowCalendar?: (event: SyntheticEvent) => void
-  /**
-   * Callback fired requesting the calendar be hidden.
-   */
-  onRequestHideCalendar?: (event: SyntheticEvent) => void
-  /**
-   * Callback fired when the input is blurred. Feedback should be provided
-   * to the user when this function is called if the selected date or input
-   * value is invalid. The component has an internal check whether the date can
-   * be parsed to a valid date.
+   * Callback fired when the input is blurred or a date is selected from the calendar.
+   * Feedback should be provided to the user when this function is called if the selected date or input
+   * value is invalid. The component has an internal check whether the date can be parsed to a valid date.
    */
   onRequestValidateDate?: (
-    value?: string,
+    isoDateString?: string,
     internalValidationPassed?: boolean
   ) => void | FormMessage[]
   /**
@@ -157,6 +156,18 @@ type DateInput2OwnProps = {
     startYear: number
     endYear: number
   }
+
+  /**
+   * Formatting function for how the date should be displayed inside the input field. It will be applied if the user clicks on a date in the date picker of after blur event from the input field.
+   */
+  formatDate?: (isoDate: string, locale: string, timezone: string) => string
+
+  /**
+   * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,
+   * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via
+   * familiar CSS-like shorthand. For example: `margin="small auto large"`.
+   */
+  // margin?: Spacing TODO enable this prop
 }
 
 type PropKeys = keyof DateInput2OwnProps
@@ -180,8 +191,6 @@ const propTypes: PropValidators<PropKeys> = {
   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,
@@ -189,7 +198,8 @@ const propTypes: PropValidators<PropKeys> = {
   ]),
   locale: PropTypes.string,
   timezone: PropTypes.string,
-  withYearPicker: PropTypes.object
+  withYearPicker: PropTypes.object,
+  formatDate: PropTypes.func
 }
 
 export type { DateInput2Props }