@instructure/ui-calendar 11.6.0 → 11.6.1-snapshot-129

package/src/Calendar/{Day → v1/Day}/props.ts

@@ -29,7 +29,7 @@ import type {
 } from '@instructure/shared-types'
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
 import { KeyboardEvent, MouseEvent } from 'react'
-import type { ViewProps } from '@instructure/ui-view'
+import type { ViewProps } from '@instructure/ui-view/v11_6'
 import { Renderable } from '@instructure/shared-types'
 
 type CalendarDayOwnProps = {

package/src/Calendar/{index.tsx → v1/index.tsx}

@@ -24,7 +24,7 @@
 
 import { Children, Component, ReactElement, MouseEvent } from 'react'
 
-import { View } from '@instructure/ui-view'
+import { View } from '@instructure/ui-view/v11_6'
 import {
   safeCloneElement,
   callRenderProp,
@@ -35,7 +35,7 @@ import { createChainedFunction } from '@instructure/ui-utils'
 import { logError as error } from '@instructure/console'
 import { AccessibleContent } from '@instructure/ui-a11y-content'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 
 import { Locale, DateTime, ApplyLocaleContext } from '@instructure/ui-i18n'
 import type { Moment } from '@instructure/ui-i18n'
@@ -49,13 +49,13 @@ import { allowedProps } from './props'
 import type { CalendarProps, CalendarState } from './props'
 import { Renderable } from '@instructure/shared-types'
 
-import { IconButton } from '@instructure/ui-buttons'
+import { IconButton } from '@instructure/ui-buttons/v11_6'
 import {
   IconArrowOpenStartSolid,
   IconArrowOpenEndSolid
 } from '@instructure/ui-icons'
 
-import { SimpleSelect } from '@instructure/ui-simple-select'
+import { SimpleSelect } from '@instructure/ui-simple-select/v11_6'
 
 /**
 ---

package/src/Calendar/v2/Day/index.tsx

@@ -0,0 +1,176 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Component, MouseEvent, KeyboardEvent } from 'react'
+
+import { View } from '@instructure/ui-view/latest'
+import type { ViewProps } from '@instructure/ui-view/latest'
+import { AccessibleContent } from '@instructure/ui-a11y-content'
+import {
+  omitProps,
+  callRenderProp,
+  getElementType
+} from '@instructure/ui-react-utils'
+
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { CalendarDayProps, CalendarDayStyleProps } from './props'
+
+/**
+---
+parent: Calendar
+id: Calendar.Day
+---
+ **/
+@withStyle(generateStyle)
+class Day extends Component<CalendarDayProps> {
+  static readonly componentId = 'Calendar.Day'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    interaction: 'enabled',
+    isSelected: false,
+    isToday: false,
+    isOutsideMonth: false
+  } as const
+
+  ref: Element | null = null
+
+  componentDidMount() {
+    this.props.makeStyles?.(this.makeStylesVariables)
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.(this.makeStylesVariables)
+  }
+
+  get makeStylesVariables(): CalendarDayStyleProps {
+    return { isDisabled: this.isDisabled }
+  }
+
+  get isDisabled() {
+    const { interaction } = this.props
+    return interaction === 'disabled'
+  }
+
+  get elementType() {
+    const { as } = this.props
+    return as || getElementType(Day, this.props)
+  }
+
+  shouldApplyAriaSelected() {
+    const { role } = this.props
+    return !!role && ['option', 'gridcell'].indexOf(role) > -1
+  }
+
+  handleClick = (event: MouseEvent<ViewProps & Element>) => {
+    const { onClick, date } = this.props
+    if (typeof onClick === 'function') {
+      onClick(event, { date })
+    }
+  }
+
+  handleKeyDown = (event: KeyboardEvent<ViewProps & Element>) => {
+    const { onKeyDown, date } = this.props
+    if (typeof onKeyDown === 'function') {
+      onKeyDown(event, { date })
+    }
+  }
+
+  handleElementRef = (el: Element | null) => {
+    const { elementRef } = this.props
+    this.ref = el
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  render() {
+    const {
+      children,
+      label,
+      interaction,
+      isOutsideMonth,
+      isSelected,
+      isToday,
+      onClick,
+      onKeyDown,
+      as,
+      styles,
+      ...props
+    } = this.props
+
+    const { elementType, isDisabled } = this
+
+    const passthroughProps = View.omitViewProps(
+      omitProps(props, Day.allowedProps),
+      Day
+    )
+
+    return (
+      <View
+        {...passthroughProps}
+        as={elementType}
+        css={styles?.calendarDay}
+        display="inline-block"
+        margin="xxx-small"
+        borderWidth="none"
+        borderColor="transparent"
+        background="transparent"
+        cursor={
+          elementType === 'button' || elementType === 'a'
+            ? isDisabled
+              ? 'not-allowed'
+              : 'pointer'
+            : 'auto'
+        }
+        disabled={isDisabled}
+        aria-current={isToday ? 'date' : undefined}
+        aria-selected={
+          this.shouldApplyAriaSelected()
+            ? isSelected
+              ? 'true'
+              : 'false'
+            : undefined
+        }
+        onClick={onClick && this.handleClick}
+        onKeyDown={onKeyDown && this.handleKeyDown}
+        elementRef={this.handleElementRef}
+        data-cid="Calendar.Day"
+      >
+        <span css={styles?.day}>
+          <AccessibleContent alt={label}>
+            {callRenderProp(children)}
+          </AccessibleContent>
+        </span>
+      </View>
+    )
+  }
+}
+
+export default Day
+export { Day }

package/src/Calendar/v2/Day/props.ts

@@ -0,0 +1,126 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type {
+  AsElementType,
+  CalendarDayTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import { KeyboardEvent, MouseEvent } from 'react'
+import type { ViewProps } from '@instructure/ui-view/latest'
+import { Renderable } from '@instructure/shared-types'
+
+type CalendarDayOwnProps = {
+  /**
+   * The rendered representation of the corresponding date.
+   */
+  children?: Renderable
+  /**
+   * An ISO 8601 formatted string representing the date corresponding to
+   * this `<Calendar.Day />`
+   */
+  date: string
+  /**
+   * Accessible label to provide more context for the date to assistive
+   * technologies. This should consist of more than just a numerical date value.
+   * It should also include the month and the year. Ex. instead of just `1`,
+   * provide `1 August 2019`.
+   */
+  label: string
+  /**
+   * Is the `<Calendar.Day />` disabled
+   */
+  interaction?: 'enabled' | 'disabled'
+  /**
+   * Is the `<Calendar.Day />` selected
+   */
+  isSelected?: boolean
+  /**
+   * Is the `<Calendar.Day />` today
+   */
+  isToday?: boolean
+  /**
+   * Is the `<Calendar.Day />` located outside the current rendered month
+   */
+  isOutsideMonth?: boolean
+  /**
+   * Callback fired on click.
+   * @param {Object} event - the click event
+   * @param {Object} data - additional data
+   * @param data.date - the date of the corresponding `<Calendar.Day />`
+   */
+  onClick?: (
+    event: MouseEvent<ViewProps & Element>,
+    date: { date: string }
+  ) => void
+  /**
+   * Callback fired on key down.
+   * @param {Object} event - the key down event
+   * @param {Object} data - additional data
+   * @param data.date - the date of the corresponding `<Calendar.Day />`
+   */
+  onKeyDown?: (
+    event: KeyboardEvent<ViewProps & Element>,
+    data: { date: string }
+  ) => void
+  /**
+   * A ref function for the underlying DOM element.
+   */
+  elementRef?: (element: Element | null) => void
+  /**
+   * the element type to render as
+   */
+  as?: AsElementType
+}
+
+type CalendarDayStyleProps = {
+  isDisabled: boolean
+}
+
+type PropKeys = keyof CalendarDayOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type CalendarDayProps = CalendarDayOwnProps &
+  WithStyleProps<CalendarDayTheme, CalendarDayStyle> &
+  OtherHTMLAttributes<CalendarDayOwnProps>
+
+type CalendarDayStyle = ComponentStyle<'calendarDay' | 'day'>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'date',
+  'label',
+  'interaction',
+  'isSelected',
+  'isToday',
+  'isOutsideMonth',
+  'onClick',
+  'onKeyDown',
+  'elementRef',
+  'as'
+]
+
+export type { CalendarDayProps, CalendarDayStyleProps, CalendarDayStyle }
+export { allowedProps }

package/src/Calendar/v2/Day/styles.ts

@@ -0,0 +1,96 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { NewComponentTypes, SharedTokens } from '@instructure/ui-themes'
+import type {
+  CalendarDayProps,
+  CalendarDayStyleProps,
+  CalendarDayStyle
+} from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} state the state of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['CalendarDay'],
+  props: CalendarDayProps,
+  _sharedTokens: SharedTokens,
+  state: CalendarDayStyleProps
+): CalendarDayStyle => {
+  const { isOutsideMonth, isSelected, isToday } = props
+  const { isDisabled } = state
+
+  return {
+    calendarDay: {
+      label: 'calendarDay',
+      padding: 0
+    },
+
+    day: {
+      label: 'calendarDay__day',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      background: componentTheme.background,
+      color: componentTheme.color,
+      fontSize: componentTheme.fontSize,
+      textDecoration: 'none',
+      lineHeight: 1,
+      height: componentTheme.height,
+      minWidth: componentTheme.minWidth,
+      border: 'none',
+      margin: 0,
+
+      ...(isOutsideMonth && {
+        color: componentTheme.outsideMonthColor
+      }),
+
+      ...(isSelected && {
+        background: componentTheme.selectedBackground,
+        borderRadius: componentTheme.selectedBorderRadius,
+        color: componentTheme.selectedColor
+      }),
+
+      ...(isToday &&
+        !isSelected && {
+          background: componentTheme.todayBackground,
+          borderRadius: componentTheme.todayBorderRadius,
+          color: componentTheme.todayColor
+        }),
+
+      ...(isDisabled && {
+        opacity: 0.5
+      })
+    }
+  }
+}
+
+export default generateStyle

package/src/Calendar/v2/README.md

@@ -0,0 +1,255 @@
+---
+describes: Calendar
+---
+
+The `Calendar` component provides a visual interface for date data.
+
+### Default config
+
+For ease of use in most situations, the `Calendar` component provides a default
+configuration. The default configuration can be overridden by providing props
+to the `Calendar` component.
+
+```js
+---
+type: example
+---
+<Calendar/>
+```
+
+### Default config with additional props
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [selectedDate, setSelectedDate] = useState('')
+    const [visibleMonth, setVisibleMonth] = useState('2025-05')
+
+    return (
+      <Calendar
+        visibleMonth={visibleMonth}
+        currentDate="2023-12-15"
+        disabledDates={['2023-12-22', '2023-12-12', '2023-12-11']}
+        selectedDate={selectedDate}
+        onRequestRenderNextMonth={(_e, requestedMonth) =>
+          setVisibleMonth(requestedMonth)
+        }
+        onRequestRenderPrevMonth={(_e, requestedMonth) =>
+          setVisibleMonth(requestedMonth)
+        }
+        onDateSelected={(date) => {
+          setSelectedDate(date)
+        }}
+      />
+    )
+  }
+  render(<Example />)
+```
+
+### With year picker
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [selectedDate, setSelectedDate] = useState('')
+    const [visibleMonth, setVisibleMonth] = useState('2024-02')
+
+    return (
+      <Calendar
+        visibleMonth={visibleMonth}
+        currentDate="2024-02-29"
+        disabledDates={['2023-12-22', '2023-12-12', '2023-12-11']}
+        selectedDate={selectedDate}
+        onRequestRenderNextMonth={(_e, requestedMonth) =>
+          setVisibleMonth(requestedMonth)
+        }
+        onRequestRenderPrevMonth={(_e, requestedMonth) =>
+          setVisibleMonth(requestedMonth)
+        }
+        onDateSelected={(date) => {
+          setSelectedDate(date)
+        }}
+        withYearPicker={{
+          screenReaderLabel: 'Year picker',
+          startYear: 1999,
+          endYear: 2024,
+          maxHeight: '200px'
+        }}
+      />
+    )
+  }
+  render(<Example />)
+```
+
+### Composing a Calendar in your Application
+
+By design, the `Calendar` component does not dictate which date libraries or
+formats you use in your application. The following example demonstrates how a
+basic `Calendar` might be created using utilities from
+[Moment.js](https://momentjs.com/docs/#/parsing/).
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [renderedDate, setRenderedDate] = useState(
+      parseDate('2019-08-02').toISOString()
+    )
+
+    const todayDate = parseDate('2019-08-16').toISOString()
+    const generateMonth = () => {
+      const date = parseDate(renderedDate).startOf('month').startOf('week')
+
+      return Array.apply(null, Array(Calendar.DAY_COUNT)).map(() => {
+        const currentDate = date.clone()
+        date.add({ days: 1 })
+
+        // This workaround is needed because moment's `.add({days: 1})` function has a bug that happens when the date added lands perfectly onto the DST cutoff,
+        // in these cases adding 1 day results in 23 hours added instead,
+        // so `moment.tz('2024-09-07T00:00:00', 'America/Santiago').add({days: 1})` results
+        // in "Sat Sep 07 2024 23:00:00 GMT-0400" instead of "Sun Sep 08 2024 00:00:00 GMT-0400".
+        // which would cause duplicate dates in the calendar.
+        // More info on the bug: https://github.com/moment/moment/issues/4743
+        // Please note that this causes one hour of time difference in the affected timezones/dates and to
+        // fully solve this bug we need to change to something like luxon which handles this properly
+        if (currentDate.clone().format('HH') === '23') {
+          return currentDate.clone().add({ hours: 1 })
+        }
+
+        return currentDate.clone()
+      })
+    }
+
+    const renderWeekdayLabels = () => {
+      const date = parseDate(renderedDate).startOf('week')
+
+      return Array.apply(null, Array(7)).map(() => {
+        const currentDate = date.clone()
+        date.add(1, 'day')
+
+        return (
+          <AccessibleContent alt={currentDate.format('dddd')}>
+            {currentDate.format('dd')}
+          </AccessibleContent>
+        )
+      })
+    }
+
+    const handleRenderNextMonth = (event) => {
+      modifyRenderedMonth(1)
+    }
+
+    const handleRenderPrevMonth = (event) => {
+      modifyRenderedMonth(-1)
+    }
+
+    const modifyRenderedMonth = (step) => {
+      const date = parseDate(renderedDate)
+      date.add(step, 'month')
+      setRenderedDate(date.toISOString())
+    }
+
+    const renderDay = (date) => {
+      return (
+        <Calendar.Day
+          key={date.toISOString()}
+          date={date.toISOString()}
+          isOutsideMonth={!date.isSame(renderedDate, 'month')}
+          isToday={date.isSame(todayDate, 'day')}
+          label={`${date.format('D')} ${date.format('MMMM')} ${date.format(
+            'YYYY'
+          )}`}
+        >
+          {date.format('D')}
+        </Calendar.Day>
+      )
+    }
+
+    const date = parseDate(renderedDate)
+
+    const buttonProps = (type = 'prev') => ({
+      size: 'small',
+      withBackground: false,
+      withBorder: false,
+      renderIcon:
+        type === 'prev' ? (
+          <ChevronLeftInstUIIcon color="baseColor" />
+        ) : (
+          <ChevronRightInstUIIcon color="baseColor" />
+        ),
+      screenReaderLabel: type === 'prev' ? 'Previous month' : 'Next month'
+    })
+
+    return (
+      <Calendar
+        renderPrevMonthButton={<IconButton {...buttonProps('prev')} />}
+        renderNextMonthButton={<IconButton {...buttonProps('next')} />}
+        renderNavigationLabel={
+          <span>
+            <div>{date.format('MMMM')}</div>
+            <div>{date.format('YYYY')}</div>
+          </span>
+        }
+        renderWeekdayLabels={renderWeekdayLabels()}
+        onRequestRenderNextMonth={handleRenderNextMonth}
+        onRequestRenderPrevMonth={handleRenderPrevMonth}
+      >
+        {generateMonth().map((date) => renderDay(date))}
+      </Calendar>
+    )
+  }
+
+  const locale = 'en-us'
+  const timezone = 'America/Denver'
+
+  const parseDate = (dateStr) => {
+    return moment.tz(dateStr, [moment.ISO_8601], locale, timezone)
+  }
+
+  render(<Example />)
+```
+
+#### Some dates to keep track of
+
+- `todayDate` - the date that represents today
+- `renderedDate` - the date that the user is viewing as they navigate the `Calendar`
+
+#### Generating a month
+
+We generate a month based on the `renderedDate` value. The `Calendar` always
+displays 6 weeks or 42 days (42 is defined as a constant `Calendar.DAY_COUNT`),
+so we pad our month values with days from the previous and next month if
+necessary. The complete implementation can be seen in the `generateMonth` function
+in our example.
+
+#### Rendering days
+
+Using the month data, we can now map it to children of type `Calendar.Day`.
+As we render each day, if it is outside the current month we can set the
+`isOutsideMonth` prop. We can also set the `isToday` prop if it is the current
+date. For accessibility, it is recommended that you provide more information to
+each `Calendar.Day` using the label prop. This label will help screen readers to
+have important context as the `Calendar` is navigated. It should include the day,
+month, and the year (Ex. instead of `1` we would provide `1 August 2019`).
+
+#### Rendering weekday labels
+
+`Calendar` requires you to provide an array of 7 labels that correspond to each
+day of the week via the `renderWeekdayLabels` prop. The visible portion of the
+label should be abbreviated (no longer than three characters). Note that screen
+readers will read this content preceding each date as the `Calendar` is navigated.
+Consider using [AccessibleContent](AccessibleContent) with the `alt` prop
+containing the full day name for assistive technologies and the children containing
+the abbreviation. ex. `[<AccessibleContent alt="Sunday">Sun</AccessibleContent>, ...]`
+
+#### Rendering next and previous month buttons
+
+The `renderNextMonthButton` and `renderPrevMonthButton` can be supplied using the
+[IconButton](IconButton) component with the `size` prop set to
+`small`, the `withBackground` and `withBorder` props both set to `false`, and the `renderIcon` prop set to `ChevronLeftInstUIIcon` or
+`ChevronRightInstUIIcon`.