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

package/CHANGELOG.md

@@ -3,12 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [9.6.1-pr-snapshot-1726659472372](https://github.com/instructure/instructure-ui/compare/v9.6.0...v9.6.1-pr-snapshot-1726659472372) (2024-09-18)
+# [9.7.0](https://github.com/instructure/instructure-ui/compare/v9.6.0...v9.7.0) (2024-09-23)
 
 
 ### Features
 
-* **ui-date-input:** improve DateInput2 api, extend docs ([27bc27f](https://github.com/instructure/instructure-ui/commit/27bc27f8a5e18cf3cabee8b5ea18f75629728ab6))
+* **ui-date-input:** improve DateInput2 api, extend docs ([f369604](https://github.com/instructure/instructure-ui/commit/f3696040d59f9baf9b9a27070e6fbc3d458e4495))
 
 
 

package/es/DateInput2/index.js

@@ -46,7 +46,7 @@ function parseLocaleDate(dateString = '', locale, timeZone) {
 
   // Split string on '.', whitespace, '/', ',' or '-' using regex: /[.\s/.-]+/.
   // The '+' allows splitting on consecutive delimiters.
-  // `.filter(Boolean)` is needed because some locales have a delimeter at the end (e.g.: "hu-hu")
+  // `.filter(Boolean)` is needed because some locales have a delimeter at the end (e.g.: hungarian dates are formatted as `2024. 09. 19.`)
   const splitDate = dateString.split(/[,.\s/.-]+/).filter(Boolean);
 
   // create a locale formatted new date to later extract the order and delimeter information
@@ -66,13 +66,17 @@ function parseLocaleDate(dateString = '', locale, timeZone) {
     }
   });
 
-  // sensible year limitations
+  // sensible limitations
   if (!year || !month || !day || year < 1000 || year > 9999) return null;
 
   // create utc date from year, month (zero indexed) and day
   const date = new Date(Date.UTC(year, month - 1, day));
+  if (date.getMonth() !== month - 1 || date.getDate() !== day) {
+    // Check if the Date object adjusts the values. If it does, the input is invalid.
+    return null;
+  }
 
-  // Format date string in the provided timezone
+  // Format date string in the provided timezone. The locale here is irrelevant, we only care about how to time is adjusted for the timezone.
   const parts = new Intl.DateTimeFormat('en-US', {
     timeZone,
     year: 'numeric',
@@ -97,9 +101,9 @@ function parseLocaleDate(dateString = '', locale, timeZone) {
 
   // Calculate time difference for timezone offset
   const timeDiff = new Date(dateInTimezone + 'Z').getTime() - date.getTime();
-  const newTime = new Date(date.getTime() - timeDiff);
+  const utcTime = new Date(date.getTime() - timeDiff);
   // Return the UTC Date corresponding to the time in the specified timezone
-  return newTime;
+  return utcTime;
 }
 
 /**
@@ -158,7 +162,10 @@ const DateInput2 = ({
     showPopover = _useState4[0],
     setShowPopover = _useState4[1];
   useEffect(() => {
-    setInputMessages(messages || []);
+    // don't set input messages if there is an error set already
+    if (!inputMessages) {
+      setInputMessages(messages || []);
+    }
   }, [messages]);
   useEffect(() => {
     const _parseDate = parseDate(value),
@@ -196,6 +203,21 @@ const DateInput2 = ({
       numberingSystem: 'latn'
     });
   };
+  const getDateFromatHint = () => {
+    const exampleDate = new Date('2024-09-01');
+    const formattedDate = formatDate(exampleDate);
+
+    // Create a regular expression to find the exact match of the number
+    const regex = n => {
+      return new RegExp(`(?<!\\d)0*${n}(?!\\d)`, 'g');
+    };
+
+    // Replace the matched number with the same number of dashes
+    const year = `${exampleDate.getFullYear()}`;
+    const month = `${exampleDate.getMonth() + 1}`;
+    const day = `${exampleDate.getDate()}`;
+    return formattedDate.replace(regex(year), match => 'Y'.repeat(match.length)).replace(regex(month), match => 'M'.repeat(match.length)).replace(regex(day), match => 'D'.repeat(match.length));
+  };
   const handleInputChange = (e, newValue) => {
     const _parseDate3 = parseDate(newValue),
       _parseDate4 = _slicedToArray(_parseDate3, 2),
@@ -234,7 +256,7 @@ const DateInput2 = ({
     onBlur: handleBlur,
     isRequired: isRequired,
     value: value,
-    placeholder: placeholder,
+    placeholder: placeholder !== null && placeholder !== void 0 ? placeholder : getDateFromatHint(),
     width: width,
     display: isInline ? 'inline-block' : 'block',
     messages: inputMessages,

package/lib/DateInput2/index.js

@@ -55,7 +55,7 @@ function parseLocaleDate(dateString = '', locale, timeZone) {
 
   // Split string on '.', whitespace, '/', ',' or '-' using regex: /[.\s/.-]+/.
   // The '+' allows splitting on consecutive delimiters.
-  // `.filter(Boolean)` is needed because some locales have a delimeter at the end (e.g.: "hu-hu")
+  // `.filter(Boolean)` is needed because some locales have a delimeter at the end (e.g.: hungarian dates are formatted as `2024. 09. 19.`)
   const splitDate = dateString.split(/[,.\s/.-]+/).filter(Boolean);
 
   // create a locale formatted new date to later extract the order and delimeter information
@@ -75,13 +75,17 @@ function parseLocaleDate(dateString = '', locale, timeZone) {
     }
   });
 
-  // sensible year limitations
+  // sensible limitations
   if (!year || !month || !day || year < 1000 || year > 9999) return null;
 
   // create utc date from year, month (zero indexed) and day
   const date = new Date(Date.UTC(year, month - 1, day));
+  if (date.getMonth() !== month - 1 || date.getDate() !== day) {
+    // Check if the Date object adjusts the values. If it does, the input is invalid.
+    return null;
+  }
 
-  // Format date string in the provided timezone
+  // Format date string in the provided timezone. The locale here is irrelevant, we only care about how to time is adjusted for the timezone.
   const parts = new Intl.DateTimeFormat('en-US', {
     timeZone,
     year: 'numeric',
@@ -106,9 +110,9 @@ function parseLocaleDate(dateString = '', locale, timeZone) {
 
   // Calculate time difference for timezone offset
   const timeDiff = new Date(dateInTimezone + 'Z').getTime() - date.getTime();
-  const newTime = new Date(date.getTime() - timeDiff);
+  const utcTime = new Date(date.getTime() - timeDiff);
   // Return the UTC Date corresponding to the time in the specified timezone
-  return newTime;
+  return utcTime;
 }
 
 /**
@@ -167,7 +171,10 @@ const DateInput2 = ({
     showPopover = _useState4[0],
     setShowPopover = _useState4[1];
   (0, _react.useEffect)(() => {
-    setInputMessages(messages || []);
+    // don't set input messages if there is an error set already
+    if (!inputMessages) {
+      setInputMessages(messages || []);
+    }
   }, [messages]);
   (0, _react.useEffect)(() => {
     const _parseDate = parseDate(value),
@@ -205,6 +212,21 @@ const DateInput2 = ({
       numberingSystem: 'latn'
     });
   };
+  const getDateFromatHint = () => {
+    const exampleDate = new Date('2024-09-01');
+    const formattedDate = formatDate(exampleDate);
+
+    // Create a regular expression to find the exact match of the number
+    const regex = n => {
+      return new RegExp(`(?<!\\d)0*${n}(?!\\d)`, 'g');
+    };
+
+    // Replace the matched number with the same number of dashes
+    const year = `${exampleDate.getFullYear()}`;
+    const month = `${exampleDate.getMonth() + 1}`;
+    const day = `${exampleDate.getDate()}`;
+    return formattedDate.replace(regex(year), match => 'Y'.repeat(match.length)).replace(regex(month), match => 'M'.repeat(match.length)).replace(regex(day), match => 'D'.repeat(match.length));
+  };
   const handleInputChange = (e, newValue) => {
     const _parseDate3 = parseDate(newValue),
       _parseDate4 = (0, _slicedToArray2.default)(_parseDate3, 2),
@@ -243,7 +265,7 @@ const DateInput2 = ({
     onBlur: handleBlur,
     isRequired: isRequired,
     value: value,
-    placeholder: placeholder,
+    placeholder: placeholder !== null && placeholder !== void 0 ? placeholder : getDateFromatHint(),
     width: width,
     display: isInline ? 'inline-block' : 'block',
     messages: inputMessages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-date-input",
-  "version": "9.6.1-pr-snapshot-1726659472372",
+  "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-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",
+    "@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-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",
+    "@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/DateInput2/README.md

@@ -81,7 +81,7 @@ Any of the following separators can be used when typing a date: `,`, `-`, `.`, `
 
 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.
+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
 ---
@@ -90,10 +90,11 @@ type: example
 const Example = () => {
   const [value, setValue] = useState('')
   const [value2, setValue2] = useState('')
+  const [value3, setValue3] = useState('')
 
   return (
     <div>
-      <p>US locale with german date format:</p>
+      <p>US locale with default format:</p>
       <DateInput2
         renderLabel="Choose a date"
         screenReaderLabels={{
@@ -104,10 +105,9 @@ const Example = () => {
         width="20rem"
         value={value}
         locale="en-us"
-        dateFormat="de-de"
         onChange={(e, value) => setValue(value)}
       />
-      <p>US locale with ISO date format:</p>
+      <p>US locale with german date format:</p>
       <DateInput2
         renderLabel="Choose a date"
         screenReaderLabels={{
@@ -118,6 +118,20 @@ const Example = () => {
         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/.-]+/
@@ -135,7 +149,7 @@ const Example = () => {
             return `${year}-${month}-${day}`
           }
         }}
-        onChange={(e, value) => setValue2(value)}
+        onChange={(e, value) => setValue3(value)}
       />
     </div>
   )
@@ -229,9 +243,9 @@ In the examples above you can see that the `onChange` callback also return a UTC
 
 ### 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).
+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 `onBlur` and `messages` props.
+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
 ---
@@ -243,8 +257,10 @@ const Example = () => {
   const [messages, setMessages] = useState([])
 
   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)
-    console.log(utcIsoDate)
+
     // don't validate empty input
     if (!utcIsoDate && inputValue.length > 0) {
       setMessages([{
@@ -285,3 +301,7 @@ const Example = () => {
 
 render(<Example />)
 ```
+
+### Date format hint
+
+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.

package/src/DateInput2/index.tsx

@@ -55,7 +55,7 @@ function parseLocaleDate(dateString: string = '', locale: string, timeZone: stri
 
   // Split string on '.', whitespace, '/', ',' or '-' using regex: /[.\s/.-]+/.
   // The '+' allows splitting on consecutive delimiters.
-  // `.filter(Boolean)` is needed because some locales have a delimeter at the end (e.g.: "hu-hu")
+  // `.filter(Boolean)` is needed because some locales have a delimeter at the end (e.g.: hungarian dates are formatted as `2024. 09. 19.`)
   const splitDate = dateString.split(/[,.\s/.-]+/).filter(Boolean)
 
   // create a locale formatted new date to later extract the order and delimeter information
@@ -76,13 +76,18 @@ function parseLocaleDate(dateString: string = '', locale: string, timeZone: stri
     }
   })
 
-  // sensible year limitations
+  // sensible limitations
   if (!year || !month || !day || year < 1000 || year > 9999) return null
 
   // create utc date from year, month (zero indexed) and day
   const date = new Date(Date.UTC(year, month - 1, day))
 
-  // Format date string in the provided timezone
+  if (date.getMonth() !== month - 1 || date.getDate() !== day) {
+    // Check if the Date object adjusts the values. If it does, the input is invalid.
+    return null
+  }
+
+  // Format date string in the provided timezone. The locale here is irrelevant, we only care about how to time is adjusted for the timezone.
   const parts = new Intl.DateTimeFormat('en-US', {
       timeZone,
       year: 'numeric',
@@ -109,9 +114,9 @@ function parseLocaleDate(dateString: string = '', locale: string, timeZone: stri
 
   // Calculate time difference for timezone offset
   const timeDiff = new Date(dateInTimezone + 'Z').getTime() - date.getTime()
-  const newTime = new Date(date.getTime() - timeDiff)
+  const utcTime = new Date(date.getTime() - timeDiff)
   // Return the UTC Date corresponding to the time in the specified timezone
-  return newTime
+  return utcTime
 }
 
 /**
@@ -170,7 +175,10 @@ const DateInput2 = ({
   const [showPopover, setShowPopover] = useState<boolean>(false)
 
   useEffect(() => {
-    setInputMessages(messages || [])
+    // don't set input messages if there is an error set already
+    if (!inputMessages) {
+      setInputMessages(messages || [])
+    }
   }, [messages])
 
   useEffect(() => {
@@ -206,6 +214,25 @@ const DateInput2 = ({
     return date.toLocaleDateString(typeof dateFormat === 'string' ? dateFormat : getLocale(), {timeZone: getTimezone(), calendar: 'gregory', numberingSystem: 'latn'})
   }
 
+  const getDateFromatHint = () => {
+    const exampleDate = new Date('2024-09-01')
+    const formattedDate = formatDate(exampleDate)
+
+    // Create a regular expression to find the exact match of the number
+    const regex = (n: string) => {
+      return new RegExp(`(?<!\\d)0*${n}(?!\\d)`, 'g')
+    }
+
+    // Replace the matched number with the same number of dashes
+    const year = `${exampleDate.getFullYear()}`
+    const month = `${exampleDate.getMonth() + 1}`
+    const day = `${exampleDate.getDate()}`
+    return formattedDate
+      .replace(regex(year), (match) => 'Y'.repeat(match.length))
+      .replace(regex(month), (match) => 'M'.repeat(match.length))
+      .replace(regex(day), (match) => 'D'.repeat(match.length))
+  }
+
   const handleInputChange = (e: SyntheticEvent, newValue: string) => {
     const [, utcIsoDate] = parseDate(newValue)
     onChange?.(e, newValue, utcIsoDate)
@@ -251,7 +278,7 @@ const DateInput2 = ({
       onBlur={handleBlur}
       isRequired={isRequired}
       value={value}
-      placeholder={placeholder}
+      placeholder={placeholder ?? getDateFromatHint()}
       width={width}
       display={isInline ? 'inline-block' : 'block'}
       messages={inputMessages}

package/src/DateInput2/props.ts

@@ -45,12 +45,11 @@ type DateInput2OwnProps = {
     nextMonthButton: string
   }
   /**
-   * Specifies the input value *before* formatting. The `formatDate` will be applied to it before displaying. Should be a valid, parsable date.
+   * Specifies the input value.
    */
   value?: string
   /**
-   * Html placeholder text to display when the input has no value. This should
-   * be hint text, not a label replacement.
+   * Placeholder text for the input field. If it's left undefined it will display a hint for the date format (like `DD/MM/YYYY`).
    */
   placeholder?: string
   /**
@@ -58,7 +57,7 @@ type DateInput2OwnProps = {
    */
   onChange?: (
     event: React.SyntheticEvent,
-    value: string,
+    inputValue: string,
     utcDateString: string
   ) => void
   /**
@@ -121,7 +120,7 @@ type DateInput2OwnProps = {
    * This property can also be set via a context property and if both are set
    * then the component property takes precedence over the context property.
    *
-   * The web browser's timezone will be used if no value is set via a component
+   * The system timezone will be used if no value is set via a component
    * property or a context property.
    **/
   timezone?: string
@@ -147,7 +146,7 @@ type DateInput2OwnProps = {
   * By default the date format is determined by the locale but can be changed via this prop to an alternate locale (passing it in as a string) or a custom parser and formatter (both as functions)
   */
   dateFormat?: {
-    parser: (input: string) => Date
+    parser: (input: string) => Date | null
     formatter: (date: Date) => string
   } | string