8x8 Oxygen - Date Time Range Selector

Instalation

$ yarn add @8x8/oxygen-date-time-range-selector

$ npm install @8x8/oxygen-date-time-range-selector

Usage

Full component - Dropdown + Range Picker

import DateTimeRangeSelector, {
  predefinedRanges,
  Styled,
  DateTimeRangeSelectorPredefinedList,
} from '@8x8/oxygen-date-time-range-selector';

<DateTimeRangeSelector
  predefinedRanges={predefinedRanges}
  predefinedRange={predefinedRange}
  dateTimeRange={dateTimeRange}
  size="large"
  placeholder="Date Range Time Selector"
  clearButtonLabel="Clear"
  finishButtonLabel="Ok"
  dateFormat="MM/dd/yyyy"
  timeFormat="hh:mm a"
  isDisabled={false}
  onRangeChange={onRangeChange}
  onOpen={onOpen}
  onClose={onClose}
/>

Range Picker only

import {
  DateTimeRangePicker,
  predefinedRanges,
} from '@8x8/oxygen-date-time-range-selector';

<DateTimeRangePicker
  endTimeErrorMessage={'Invalid Range'}
  startTimeLabel={'From'}
  endTimeLabel={'To'}
  customPredefinedRangeLabel={'Custom Range'}
  predefinedRanges={predefinedRanges}
  toLabel={'To'}
  fromLabel={'From'}
  dateFormat="MM/dd/yyyy"
  timeFormat="hh:mm a"
  onRangeChange={onRangeChange}
/>

Predefined ranges

// default predefinedRanges
// using date-fns to generate startDate and endDate
// to change the displayed text, clone and modify the `displayName` for each item in the list
const predefinedRanges = [
  {
    id: 'TODAY',
    displayName: 'Today',
    dateTimeRange: () => {
      const today = {
        startDate: startOfToday(),
        endDate: endOfToday(),
      };

      return today;
    },
  },
  {
    id: 'LAST_HOUR',
    displayName: 'Last Hour',
    dateTimeRange: () => {
      const now = new Date();
      const lastHour = {
        startDate: subHours(now, 1),
        endDate: now,
      };

      return lastHour;
    },
  },
  {
    id: 'YESTERDAY',
    displayName: 'Yesterday',
    dateTimeRange: () => {
      const yesterday = {
        startDate: startOfYesterday(),
        endDate: endOfYesterday(),
      };

      return yesterday;
    },
  },
  {
    id: 'LAST_X_DAYS',
    displayName: 'Last X Days',
    selectedDisplayName: ['Last', 'Days'],
    dateTimeRange: x => {
      const now = new Date();
      const lastXDays = {
        startDate: startOfDay(subDays(now, x || 1)),
        endDate: endOfToday(),
      };

      return lastXDays;
    },
    hasArgument: true,
  },
  {
    id: 'THIS_WEEK',
    displayName: 'This Week',
    dateTimeRange: () => {
      const now = new Date();
      const thisWeek = {
        startDate: startOfWeek(now, { weekStartsOn: 1 }), // Monday = 1
        endDate: endOfToday(),
      };

      return thisWeek;
    },
  },
  {
    id: 'THIS_MONTH',
    displayName: 'This Month',
    dateTimeRange: () => {
      const now = new Date();
      const thisMonth = {
        startDate: startOfMonth(now),
        endDate: endOfToday(),
      };

      return thisMonth;
    },
  },
  {
    id: 'LAST_MONTH',
    displayName: 'Last Month',
    dateTimeRange: () => {
      const now = new Date();
      const lastMonth = {
        startDate: subMonths(startOfMonth(now), 1),
        endDate: endOfMonth(subMonths(now, 1)),
      };

      return lastMonth;
    },
  },
  {
    id: 'LAST_X_MONTHS',
    displayName: 'Last X Months',
    selectedDisplayName: ['Last', 'Months'],
    dateTimeRange: x => {
      const now = new Date();
      const lastXMonths = {
        startDate: startOfDay(subMonths(now, x || 1)),
        endDate: endOfToday(),
      };

      return lastXMonths;
    },
    hasArgument: true,
  },
  {
    id: 'THIS_YEAR',
    displayName: 'This Year',
    dateTimeRange: () => {
      const now = new Date();
      const thisYear = {
        startDate: startOfYear(now),
        endDate: endOfToday(),
      };

      return thisYear;
    },
  },
  {
    id: 'LAST_YEAR',
    displayName: 'Last Year',
    dateTimeRange: () => {
      const now = new Date();
      const lastYear = {
        startDate: subYears(startOfYear(now), 1),
        endDate: endOfYear(subYears(now, 1)),
      };

      return lastYear;
    },
  },
];

l10n

import deLocale from 'date-fns/locale/de';

<DateTimeRangeSelector
  predefinedRange={predefinedRange}
  dateTimeRange={dateTimeRange}
  placeholder="Zeitauswahl für Datumsbereich"
  clearButtonLabel="Löschen"
  finishButtonLabel="Ja"
  dateFormat="dd.MM.yyyy"
  timeFormat="hh:mm"
  onRangeChange={onRangeChange}
  locale={deLocale}
/>;

Available styled components

• DropdownContainer,
• Content,
• Footer,
• CalendarWrapper,
• CalendarContainer,
• DateTimeInputs,
• DateInput,
• TimeInput,
• EndTimeError,
• DateTimeInputContainer,
• InputContainer,
• InputIcon,
• PredefinedList,
• PredefinedListItem,
• PredefinedListInputWrapper,

Custom Close Handlers

| Name | Type | Example | Description | | --------- | ------ | ------- | ----------------------------------------------------------------- | | target | node | window | The element that is going to receive the event listener | | eventName | string | 'click' | The name of the event | | capture | bool | false | Specify weather to use capture or bubbling to propagate the event |

Example

const customCloseHandlers = [
  {
    target: document.body,
    eventName: 'ps-scroll-x',
    capture: true,
  },
];

Predefined Range

interface PredefinedRange

| Name | Type | Example | Description | | :--------------------- | :------------------------------------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | | id | string | 'YESTERDAY' | ID used to represent the predefined range | | displayName | string | 'Yesterday' | The name that will be displayed in the list of predefined ranges | | dateTimeRange | (value?: number) => { startDate: Date; endDate: Date } | () => ({ startDate, endDate }) | Function that may receive an argument and has to return an object representing the date range | | hasArgument? | boolean | undefined | Tell if the predefined range has an argument | | selectedDisplayName? | string[] | ['Last', 'Days'] | Array containing two strings. In the case of a predefined range with an argument, the strings will be on either side of the input box |

Props

DateTimeRangeSelector

interface DateTimeRangeSelectorProps

| Name | Type | Default | Description | | :---------------------------- | :------------------------------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | clearButtonLabel? | string | 'Clear' | The value of the clear button | | customCloseHandlers? | CloseHandler[] | [] | Array containing events that should trigger the hiding of the date time range | | customPredefinedRangeLabel? | string | 'Custom' | The value of the "Custom" predefined list label | | dateFormat? | string | 'MM/dd/yyyy' | The way that dates are formatted. The complete list of values can be found: https://date-fns.org/v2.28.0/docs/format | | dateTimeRange? | { startDate: Date; endDate: Date } | undefined | The selected date range | | endTimeErrorMessage? | string | 'Cannot be before start time' | The value of the error message that appears when end time is before start time | | endTimeLabel? | string | 'End Time' | The value of the "End Time" time selector label | | finishButtonLabel? | string | 'Finish' | The value of the finish button | | fromLabel? | string | 'From' | The value of the "From" input label | | hasError? | boolean | false | Tell when the input box has error | | hasIntraday? | boolean | false | Specifies if the Intraday range toggle is visible | | headerRenderer? | (props: DateTimeRangeSelectorProps) => React.ReactNode | undefined | Function for rendering a custom calendar header | | hidePredefinedRanges? | boolean | false | Specifies if the predefined ranges component should be displayed | | hideTime? | boolean | false | Specifies if the top time selector component should be displayed | | iconLeft? | React.ElementType | null | Add icon on the left side of the input | | id? | string | undefined | Define id attribute for input element | | inputIcon? | React.ReactNode | undefined | Replaces the default input icon; a component passed here receives reverse (true while the picker is open). If the value is null, no icon will be displayed on the right side of the input box | | inputRenderer? | (props: InputRendererProps) => React.ReactNode | undefined | Function for rendering a custom input | | intraday? | { startTime: TimeValue; endTime: TimeValue } | undefined | The selected intraday range, applied to every day in the date range when the Intraday toggle is enabled | | intradayLabel? | string | undefined | The label displayed in front of the Intraday Range toggle button | | intradayTooltipText? | string | undefined | The tooltip text shown on the Intraday Range info icon | | isDisabled? | boolean | false | Tell when input box is disabled | | locale? | Locale | undefined | Defines the locale options and strings (e.g. day or month names) used to format date values. Works with locale definitions from date-fns: https://date-fns.org/v2.28.0/docs/I18n en is the built-in, default language, doesn't require any setup | | onClose? | () => void | noop | Callback executed after the dropdown with date and time range selector becomes hidden | | onOpen? | () => void | noop | Callback executed after the dropdown with date and time range selector becomes visible | | onRangeChange? | (changes: object) => void | noop | Callback executed when either the finish button or clear button is pressed | | otherCalendarProps? | Partial<CalendarProps> | {} | Object with properties to be passed to the calendar component. See Calendar documentation | | placeholder? | string | 'Select Date Range' | The default value of the input box | | predefinedRange? | { id: string; value?: number } | { id: 'CUSTOM' } | The currently selected predefined range represented by 'id' and 'value' if it has an argument, otherwise value should be undefined | | predefinedRanges? | PredefinedRange[] | defaultPredefinedRanges | Array of predefined range objects. Predefined ranges are shown in the left side list. They can represent a fixed range (ex. yesterday, last month) or can have an argument to calculate a relative range (ex. last x days, last x months) | | size? | 'large' \| 'small' | 'large' | The size of the input box | | startTimeLabel? | string | 'Start Time' | The value of the "Start Time" time selector label | | testId? | string | 'DATE_TIME_RANGE_SELECTOR' | Test ID DOM attribute value | | theme? | Partial<DateTimeRangeSelectorTheme> | undefined | Overrides applied on top of the light or dark settings resolved by OxygenProvider | | timeFormat? | string | 'hh:mm a' | The way that times are formatted. The complete list of values can be found: https://date-fns.org/v2.28.0/docs/format | | toLabel? | string | 'To' | The value of the "To" input label |

DateTimeRangeSelectorPredefinedList

interface DateTimeRangeSelectorPredefinedListProps

| Name | Type | Default | Description | | :---------------------------- | :------------------------------------------------ | :---------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | | ranges | PredefinedRange[] | Required | Available predefined ranges. See above docs about predefinedRanges array | | selectedRange | { id: string; value?: number } | Required | The selected (active) range. Should contain the id of the range, and the value, if applies (for example for "Last X Days" range) | | customPredefinedRangeLabel? | string | undefined | Custom label for the custom range option | | hideCustomRange? | boolean | false | Render without 'Custom' range | | onRangeSelect? | (range: { id: string; value?: number }) => void | undefined | Callback function for range selection and value change (for "Last X ..." range types) | | testId? | string | 'DATE_TIME_RANGE_SELECTOR_DROPDOWN_PREDEFINED_LIST' | Test ID DOM attribute value | | theme? | Partial<Theme> | undefined | Theme object for DateTimeRangeSelector, mandatory to send since it's an internal component |