envoc-form 4.0.1-9 → 4.2.0

package/src/DatePicker/DatePickerGroup.tsx

@@ -1,15 +1,15 @@
 import { useEffect, useState } from 'react';
-import DatePicker, { DatePickerProps } from 'react-date-picker/dist/entry.nostyle';
+import DatePicker, {
+  DatePickerProps,
+} from 'react-date-picker/dist/entry.nostyle';
 import classnames from 'classnames';
 import parseISO from 'date-fns/parseISO';
 import { InjectedFieldProps } from '../Field/InjectedFieldProps';
 import { FormDefaults } from '../FormDefaults';
 import Group, { GroupProps } from '../Group';
 
-// Docs for react-date-picker https://www.npmjs.com/package/react-date-picker
-
 export interface DatePickerGroupProps<T>
-  extends InjectedFieldProps<T | undefined>,
+  extends InjectedFieldProps<T | undefined | null>,
     Omit<
       DatePickerProps,
       keyof InjectedFieldProps<T> | 'name' | 'value' | 'className'
@@ -18,23 +18,35 @@ export interface DatePickerGroupProps<T>
   convert: (arg: Date) => T;
 }
 
+/**
+ * Field for inputting dates. Uses `<Group/>` and `<DatePicker/>`.
+ *
+ * Uses [react-date-picker](https://www.npmjs.com/package/react-date-picker)
+ */
 export default function DatePickerGroup<T>({
   input,
   meta,
   label,
   helpText,
   className,
+  required,
   disabled,
   convert,
+  maxDate = new Date(9999, 11, 31),
+  minDate = new Date(1000, 0, 1),
   ...rest
 }: DatePickerGroupProps<T>) {
   const [displayDate, setDisplayDate] = useState<Date | null>(null);
 
   useEffect(() => {
-    if (input.value != null) {
-      setDisplayDate(new Date(`${input.value}T00:00:00.000`));
-    } else {
+    if (!input.value) {
       setDisplayDate(null);
+    } else if (typeof input.value === 'string') {
+      if (input.value.indexOf('T') === -1) {
+        setDisplayDate(new Date(`${input.value}T00:00:00.000`));
+      } else {
+        setDisplayDate(new Date(input.value));
+      }
     }
   }, [setDisplayDate, input.value]);
 
@@ -48,6 +60,7 @@ export default function DatePickerGroup<T>({
         className,
         FormDefaults.cssClassPrefix + 'date-picker'
       )}
+      required={required}
       disabled={disabled}>
       <DatePicker
         {...rest}
@@ -57,6 +70,8 @@ export default function DatePickerGroup<T>({
         )}
         value={displayDate}
         onChange={handleChange}
+        maxDate={maxDate}
+        minDate={minDate}
       />
     </Group>
   );
@@ -95,6 +110,7 @@ export default function DatePickerGroup<T>({
 export function convertToTimeZoneInsensitiveISOString(date: Date): string {
   const year = new Intl.DateTimeFormat('en', { year: 'numeric' })
     .format(date)
+    .substring(0, 4)
     .padStart(4, '0');
   const month = new Intl.DateTimeFormat('en', { month: '2-digit' }).format(
     date

package/src/DatePicker/StringDateOnlyPickerGroup.tsx

@@ -1,9 +1,14 @@
-import { DatePickerHelper } from './DatePickerHelper';
 import DatePickerGroup from './DatePickerGroup';
+import { DatePickerHelper } from './DatePickerHelper';
 
 export interface StringDateOnlyPickerGroupProps
-  extends DatePickerHelper<string | undefined> {}
+  extends DatePickerHelper<string | undefined | null> {}
 
+/**
+ * Date picker input that consumes and outputs as a date only string in ISO format `YYYY-MM-DD`.
+ *
+ * Default display to the user is in `MM/DD/YYYY` format.
+ */
 export default function StringDatePickerGroup(
   props: StringDateOnlyPickerGroupProps
 ) {

package/src/DatePicker/StringDatePickerGroup.tsx

@@ -2,7 +2,13 @@ import DatePickerGroup from './DatePickerGroup';
 import { DatePickerHelper } from './DatePickerHelper';
 
 export interface StringDatePickerGroupProps
-  extends DatePickerHelper<string | undefined> {}
+  extends DatePickerHelper<string | undefined | null> {}
+
+/**
+ * Date picker input that consumes and outputs as a date only string in ISO format `YYYY-MM-DDTHH:mm:ss.sssZ` or `±YYYYYY-MM-DDTHH:mm:ss.sssZ`
+ *
+ * If you need `YYYY-MM-DD` format use `<StringDateOnlyPickerGroup/>`.
+ */
 export default function StringDatePickerGroup(
   props: StringDatePickerGroupProps
 ) {

package/src/DateTimePicker/DateTimePicker.test.tsx

@@ -0,0 +1,243 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import StringDateTimePickerGroup from './StringDateTimePickerGroup';
+import FormTestBase, { PersonDto } from '../__Tests__/FormTestBase';
+
+//hack so the datetimepicker internals don't complain about this not existing in the context of jest
+HTMLCanvasElement.prototype.getContext = () => null;
+
+describe('StringDateTimePickerGroup', () => {
+  it('renders without crashing', () => {
+    render(
+      <FormTestBase>
+        {({ Field }) => (
+          <Field
+            name="createdDateTime"
+            Component={StringDateTimePickerGroup}
+            label="Created Date Time"
+            monthPlaceholder="mm"
+            dayPlaceholder="dd"
+            yearPlaceholder="yyyy"
+            disableClock
+            maxDate={new Date('9/23/2023')}
+            minDate={new Date('6/22/2022')}
+          />
+        )}
+      </FormTestBase>
+    );
+  });
+
+  it('has matching snapshot', () => {
+    const renderResult = render(
+      <FormTestBase>
+        {({ Field }) => (
+          <Field
+            name="createdDateTime"
+            Component={StringDateTimePickerGroup}
+            label="Created Date Time"
+            monthPlaceholder="mm"
+            dayPlaceholder="dd"
+            yearPlaceholder="yyyy"
+            disableClock
+            maxDate={new Date('9/23/2023')}
+            minDate={new Date('6/22/2022')}
+          />
+        )}
+      </FormTestBase>
+    );
+    expect(renderResult.asFragment()).toMatchSnapshot();
+  });
+
+  it('does not render with initial date-only string and throws exception', () => {
+    const dateOnlyString = '2024-09-04';
+    const personDtoWithDateOnlyString: PersonDto = {
+      createdDateTime: dateOnlyString,
+    };
+
+    try {
+      render(
+        <FormTestBase initialValues={personDtoWithDateOnlyString}>
+          {({ Field }) => (
+            <Field
+              name="createdDateTime"
+              Component={StringDateTimePickerGroup}
+              label="Created Date Time"
+              monthPlaceholder="mm"
+              dayPlaceholder="dd"
+              yearPlaceholder="yyyy"
+              disableClock
+            />
+          )}
+        </FormTestBase>
+      );
+
+      fail('Expected an exception to be thrown for date-only string');
+    } catch (error: any) {
+      // Assert that the error message matches the expected message
+      expect(error.message).toEqual(
+        `Invalid "date time" value of ${dateOnlyString} provided to DateTimePickerGroup component. Please provide ISO 8601 string that includes the time zone designator. Sample strings: 2022-09-24T:08:54:12+00:00, 2022-09-24T:08:54:12Z, 2022-09-24T:08:54:12.123-05:00`
+      );
+    }
+  });
+
+  it('renders with ISO UTC date time string taking browser timezone into account', () => {
+    const isoUTCDateTimeString = '2024-04-09T21:00:24.670Z';
+    const personDtoWithDateTimeString: PersonDto = {
+      createdDateTime: isoUTCDateTimeString,
+    };
+
+    render(
+      <FormTestBase initialValues={personDtoWithDateTimeString}>
+        {({ Field }) => (
+          <Field
+            name="createdDateTime"
+            Component={StringDateTimePickerGroup}
+            label="Created Date Time"
+            monthPlaceholder="mm"
+            dayPlaceholder="dd"
+            yearPlaceholder="yyyy"
+            disableClock
+          />
+        )}
+      </FormTestBase>
+    );
+
+    const dateTimePickerInputComponent = document.querySelector(
+      'input[name="datetime"][type="datetime-local"]'
+    );
+    const utcDate = new Date(isoUTCDateTimeString);
+    const localDateTimeString =
+      convertToDateTimePickerComponentValueString(utcDate);
+
+    // Assert that no exception is thrown during rendering
+    expect(true).toBe(true);
+    // Assert the value of the component
+    expect(dateTimePickerInputComponent).toHaveValue(localDateTimeString);
+  });
+
+  it('does not render with invalid datetime ISO string and throws exception', () => {
+    const invalidISODateTimeString = '2024-04-11T01:00:00.000-5:00';
+    const personDtoWithDateOnlyString: PersonDto = {
+      createdDateTime: invalidISODateTimeString,
+    };
+
+    try {
+      render(
+        <FormTestBase initialValues={personDtoWithDateOnlyString}>
+          {({ Field }) => (
+            <Field
+              name="createdDateTime"
+              Component={StringDateTimePickerGroup}
+              label="Created Date Time"
+              monthPlaceholder="mm"
+              dayPlaceholder="dd"
+              yearPlaceholder="yyyy"
+              disableClock
+            />
+          )}
+        </FormTestBase>
+      );
+
+      fail('Expected an exception to be thrown for invalid datetime string');
+    } catch (error: any) {
+      // Assert that the error message matches the expected message
+      expect(error.message).toEqual(
+        `Invalid "date time" value of ${invalidISODateTimeString} provided to DateTimePickerGroup component. Please provide ISO 8601 string that includes the time zone designator. Sample strings: 2022-09-24T:08:54:12+00:00, 2022-09-24T:08:54:12Z, 2022-09-24T:08:54:12.123-05:00`
+      );
+    }
+  });
+
+  it('renders with ISO date time string with different offset than browser taking browser timezone into account', () => {
+    const isoDateTimeString = '2024-04-09T21:00:24.670-01:00';
+    const personDtoWithDateTimeString: PersonDto = {
+      createdDateTime: isoDateTimeString,
+    };
+
+    render(
+      <FormTestBase initialValues={personDtoWithDateTimeString}>
+        {({ Field }) => (
+          <Field
+            name="createdDateTime"
+            Component={StringDateTimePickerGroup}
+            label="Created Date Time"
+            monthPlaceholder="mm"
+            dayPlaceholder="dd"
+            yearPlaceholder="yyyy"
+            disableClock
+          />
+        )}
+      </FormTestBase>
+    );
+
+    const dateTimePickerInputComponent = document.querySelector(
+      'input[name="datetime"][type="datetime-local"]'
+    );
+    const utcDate = new Date(isoDateTimeString);
+    const localDateTimeString =
+      convertToDateTimePickerComponentValueString(utcDate);
+
+    // Assert that no exception is thrown during rendering
+    expect(true).toBe(true);
+    // Assert the value of the component
+    expect(dateTimePickerInputComponent).toHaveValue(localDateTimeString);
+  });
+
+  it('renders with ISO date time string with same offset as the browser taking browser timezone into account', () => {
+    const isoDateTimeString = '2024-04-09T21:00:24.670-05:00';
+    const personDtoWithDateTimeString: PersonDto = {
+      createdDateTime: isoDateTimeString,
+    };
+
+    render(
+      <FormTestBase initialValues={personDtoWithDateTimeString}>
+        {({ Field }) => (
+          <Field
+            name="createdDateTime"
+            Component={StringDateTimePickerGroup}
+            label="Created Date Time"
+            monthPlaceholder="mm"
+            dayPlaceholder="dd"
+            yearPlaceholder="yyyy"
+            disableClock
+          />
+        )}
+      </FormTestBase>
+    );
+
+    const dateTimePickerInputComponent = document.querySelector(
+      'input[name="datetime"][type="datetime-local"]'
+    );
+    const utcDate = new Date(isoDateTimeString);
+    const localDateTimeString =
+      convertToDateTimePickerComponentValueString(utcDate);
+
+    // Assert that no exception is thrown during rendering
+    expect(true).toBe(true);
+    // Assert the value of the component
+    expect(dateTimePickerInputComponent).toHaveValue(localDateTimeString);
+  });
+});
+
+function convertToDateTimePickerComponentValueString(date: Date): string {
+  // Format the date in the required format using `intl.DateTimeFormat`
+  const year = new Intl.DateTimeFormat('en', { year: 'numeric' })
+    .format(date)
+    .padStart(4, '0');
+
+  const month = new Intl.DateTimeFormat('en', { month: '2-digit' }).format(
+    date
+  );
+
+  const day = new Intl.DateTimeFormat('en', { day: '2-digit' }).format(date);
+
+  const hour = new Intl.DateTimeFormat('en', {
+    hour: '2-digit',
+    hourCycle: 'h23',
+  }).format(date);
+
+  const minute = new Intl.DateTimeFormat('en', { minute: '2-digit' })
+    .format(date)
+    .padStart(2, '0');
+
+  return `${year}-${month}-${day}T${hour}:${minute}`;
+}

package/src/DateTimePicker/DateTimePickerGroup.tsx

@@ -0,0 +1,116 @@
+import { useEffect, useState } from 'react';
+import { DateTimePicker, DateTimePickerProps } from 'react-datetime-picker';
+import classnames from 'classnames';
+import parseISO from 'date-fns/parseISO';
+import { InjectedFieldProps } from '../Field/InjectedFieldProps';
+import { FormDefaults } from '../FormDefaults';
+import Group, { GroupProps } from '../Group';
+
+// Represents a single date/date string, or null
+type DateTimePickerValuePiece = Date | string | null;
+// Represents either a single date/date string, a pair of dates/date strings for a range, or null
+type DateTimePickerValue =
+  | DateTimePickerValuePiece
+  | [DateTimePickerValuePiece, DateTimePickerValuePiece];
+
+export interface DateTimePickerGroupProps<T>
+  extends InjectedFieldProps<T | undefined | null>,
+    Omit<
+      DateTimePickerProps,
+      keyof InjectedFieldProps<T> | 'name' | 'value' | 'className'
+    >,
+    Omit<GroupProps, keyof InjectedFieldProps<T> | 'children'> {
+  convert: (date: Date) => T;
+}
+
+/**
+ * Field for inputting date and time. Uses `<Group/>` and `<DateTimePicker/>`.
+ *
+ * Uses [react-datetime-picker](https://www.npmjs.com/package/react-datetime-picker)
+ */
+export default function DateTimePickerGroup<T>({
+  input,
+  meta,
+  label,
+  helpText,
+  className,
+  required,
+  disabled,
+  convert,
+  ...rest
+}: DateTimePickerGroupProps<T>) {
+  const [displayDateTime, setDisplayDateTime] = useState<Date | null>(null);
+
+  useEffect(() => {
+    const inputValue = input.value;
+    if (!inputValue) {
+      setDisplayDateTime(null);
+    } else if (typeof inputValue === 'string') {
+      const parsedDateTime = convertISODateTimeStringToDate(inputValue);
+      setDisplayDateTime(parsedDateTime);
+    } else if (inputValue instanceof Date) {
+      setDisplayDateTime(inputValue);
+    }
+  }, [setDisplayDateTime, input.value]);
+
+  return (
+    <Group
+      input={input}
+      meta={meta}
+      label={label}
+      helpText={helpText}
+      className={classnames(
+        className,
+        FormDefaults.cssClassPrefix + 'date-time-picker'
+      )}
+      required={required}
+      disabled={disabled}>
+      <DateTimePicker
+        {...rest}
+        className={classnames(
+          FormDefaults.cssClassPrefix + 'date-time-picker',
+          className
+        )}
+        value={displayDateTime}
+        onChange={handleChange}
+      />
+    </Group>
+  );
+
+  function handleChange(newDateTime: DateTimePickerValue) {
+    const { onChange } = input;
+    if (onChange === null) {
+      return;
+    }
+
+    if (!newDateTime) {
+      onChange(undefined);
+      setDisplayDateTime(null);
+      return;
+    } else if (typeof newDateTime === 'string') {
+      const parsedDateTime = parseISO(newDateTime);
+      setDisplayDateTime(parsedDateTime);
+      onChange(convert(parsedDateTime));
+    } else if (newDateTime instanceof Date) {
+      setDisplayDateTime(newDateTime);
+      onChange(convert(newDateTime));
+    }
+  }
+}
+
+function convertISODateTimeStringToDate(isoDateTimeString: string) {
+  const isoDateTimeRegex =
+    /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?)([+-]\d{2}:\d{2}|Z)?$/;
+  const isValidIsoDateTimeString = isoDateTimeRegex.test(isoDateTimeString);
+  if (isValidIsoDateTimeString) {
+    return new Date(isoDateTimeString);
+  }
+
+  const errorMessage = `Invalid "date time" value of ${isoDateTimeString} provided to DateTimePickerGroup component. Please provide ISO 8601 string that includes the time zone designator. Sample strings: 2022-09-24T:08:54:12+00:00, 2022-09-24T:08:54:12Z, 2022-09-24T:08:54:12.123-05:00`;
+  if (process.env.NODE_ENV !== 'production') {
+    throw new Error(errorMessage);
+  } else {
+    console.error(errorMessage);
+  }
+  return null;
+}

package/src/DateTimePicker/DateTimePickerHelper.ts

@@ -0,0 +1,4 @@
+import { DateTimePickerGroupProps } from './DateTimePickerGroup';
+
+export interface DateTimePickerHelper<T>
+  extends Omit<DateTimePickerGroupProps<T>, 'convert'> {}

package/src/DateTimePicker/StringDateTimePickerGroup.tsx

@@ -0,0 +1,61 @@
+import DateTimePickerGroup from './DateTimePickerGroup';
+import { DateTimePickerHelper } from './DateTimePickerHelper';
+
+export interface StringDateTimePickerGroupProps
+  extends DateTimePickerHelper<string | undefined | null> {}
+
+/**
+ * Date Time picker input that consumes JS Date object and outputs as a date time offset string in ISO format `YYYY-MM-DDTHH:mm:ss.sss±hh:mm`.
+ *
+ * Default display to the user is in `MM/DD/YYYY HH:mm:ss AM/PM` format.
+ */
+export default function StringDateTimePickerGroup(
+  props: StringDateTimePickerGroupProps
+) {
+  return <DateTimePickerGroup {...props} convert={convertToISOString} />;
+}
+
+function convertToISOString(date: Date): string {
+  // Get the offset in minutes
+  const offsetMinutes = date.getTimezoneOffset();
+
+  // Calculate the offset in hours and minutes
+  const offsetHours = Math.floor(Math.abs(offsetMinutes) / 60);
+  const offsetMinutesPart = Math.abs(offsetMinutes) % 60;
+
+  // Format the offset in the required format (+/-hh:mm)
+  const offsetString =
+    (offsetMinutes >= 0 ? '-' : '+') +
+    String(offsetHours).padStart(2, '0') +
+    ':' +
+    String(offsetMinutesPart).padStart(2, '0');
+
+  // Format the date in the required format using `intl.DateTimeFormat`
+  const year = new Intl.DateTimeFormat('en', { year: 'numeric' })
+    .format(date)
+    .padStart(4, '0');
+
+  const month = new Intl.DateTimeFormat('en', { month: '2-digit' }).format(
+    date
+  );
+
+  const day = new Intl.DateTimeFormat('en', { day: '2-digit' }).format(date);
+
+  const hour = new Intl.DateTimeFormat('en', {
+    hour: '2-digit',
+    hourCycle: 'h23',
+  }).format(date);
+
+  const minute = new Intl.DateTimeFormat('en', { minute: '2-digit' })
+    .format(date)
+    .padStart(2, '0');
+
+  const second = new Intl.DateTimeFormat('en', {
+    second: '2-digit',
+    fractionalSecondDigits: 3,
+  })
+    .format(date)
+    .padStart(6, '0');
+
+  return `${year}-${month}-${day}T${hour}:${minute}:${second}${offsetString}`;
+}