chore(CalendarMonth): provided explicit guidance for labeling an inli…

…ne calendar month (#8375)

* chore(CalendarMonth): provided explicit guidance for labeling an inline calendar month

* update per PR comments

* move inline accommodations into an inlineProps prop

* fix typo and address PR comments

* fix test failures

* fix tests and snapshots

packages/react-core/src/components/CalendarMonth/CalendarMonth.tsx

@@ -20,6 +20,15 @@ export enum Weekday {
   Saturday
 }
 
+export interface CalendarMonthInlineProps {
+  /** Component wrapping the calendar month when used inline. Recommended to be 'article'. */
+  component?: keyof JSX.IntrinsicElements;
+  /** Title of the calendar rendered above the inline calendar month. Recommended to be a 'title' component. */
+  title?: React.ReactNode;
+  /** Id of the accessible label of the calendar month. Recommended to map to the title. */
+  ariaLabelledby?: string;
+}
+
 /** Additional properties that extend from and can be passed to the main component. These
  * properties allow customizing the calendar formatting and aria-labels.
  */
@@ -49,6 +58,8 @@ export interface CalendarFormat {
   weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | Weekday;
   /** Accessible label for the year input. */
   yearInputAriaLabel?: string;
+  /** Props used to ensure accessibility when displaying the calendar month inline. */
+  inlineProps?: CalendarMonthInlineProps;
 }
 
 export interface CalendarProps extends CalendarFormat, Omit<React.HTMLProps<HTMLDivElement>, 'onChange'> {
@@ -133,6 +144,7 @@ export const CalendarMonth = ({
   yearInputAriaLabel = 'Select year',
   cellAriaLabel,
   isDateFocused = false,
+  inlineProps,
   ...props
 }: CalendarProps) => {
   const longMonths = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11].map(monthNum => new Date(1990, monthNum)).map(monthFormat);
@@ -232,7 +244,8 @@ export const CalendarMonth = ({
   const isHoveredDateValid = isValidated(hoveredDate);
   const monthFormatted = monthFormat(focusedDate);
   const yearFormatted = yearFormat(focusedDate);
-  return (
+
+  const calendarToRender = (
     <div className={css(styles.calendarMonth, className)} {...props}>
       <div className={styles.calendarMonthHeader}>
         <div className={css(styles.calendarMonthHeaderNavControl, styles.modifiers.prevMonth)}>
@@ -386,4 +399,16 @@ export const CalendarMonth = ({
       </table>
     </div>
   );
+
+  if (inlineProps !== undefined) {
+    const Component = (inlineProps.component ? inlineProps.component : 'article') as any;
+    return (
+      <Component {...(inlineProps.ariaLabelledby && { 'aria-labelledby': inlineProps.ariaLabelledby })}>
+        {inlineProps.title}
+        {calendarToRender}
+      </Component>
+    );
+  }
+  return calendarToRender;
 };
+CalendarMonth.displayName = 'CalendarMonth';

packages/react-core/src/components/CalendarMonth/__tests__/CalendarMonth.test.tsx

@@ -55,3 +55,12 @@ test('Next year dates have correct year in aria label', () => {
   const nextYearDate = screen.getByRole('button', { name: '1 January 2025' });
   expect(nextYearDate).toBeVisible();
 });
+
+test('InlineProps render correct wrapper component and attributes', () => {
+  render(<CalendarMonth inlineProps={{component: 'article', title: <div id="hi">Title</div>, ariaLabelledby: "hi"}} />);
+
+  const article = screen.getByRole('article');
+  expect(article).toHaveAttribute('aria-labelledby', 'hi');
+  const title = screen.getByText('Title');
+  expect(title).toBeVisible();
+});

packages/react-core/src/components/CalendarMonth/examples/CalendarMonth.md

@@ -2,7 +2,7 @@
 id: Calendar month
 section: components
 cssPrefix: pf-c-calendar-month
-propComponents: ['CalendarMonth', 'CalendarFormat']
+propComponents: ['CalendarMonth', 'CalendarFormat', 'CalendarMonthInlineProps']
 ---
 
 ## Examples

packages/react-core/src/components/CalendarMonth/examples/CalendarMonthDateRange.tsx

@@ -1,10 +1,27 @@
 import React from 'react';
-import { CalendarMonth } from '@patternfly/react-core';
+import { CalendarMonth, Title, CalendarMonthInlineProps } from '@patternfly/react-core';
 
 export const CalendarMonthDateRange: React.FunctionComponent = () => {
   const startDate = new Date(2020, 10, 11);
   const endDate = new Date(2020, 10, 24);
   const disablePreStartDates = (date: Date) => date >= startDate;
 
-  return <CalendarMonth validators={[disablePreStartDates]} date={endDate} rangeStart={startDate} />;
+  const inlineProps: CalendarMonthInlineProps = {
+    component: 'article',
+    title: (
+      <Title id="display-range" headingLevel="h4">
+        Calendar month displaying a range
+      </Title>
+    ),
+    ariaLabelledby: 'display-range'
+  };
+
+  return (
+    <CalendarMonth
+      validators={[disablePreStartDates]}
+      date={endDate}
+      rangeStart={startDate}
+      inlineProps={inlineProps}
+    />
+  );
 };

packages/react-core/src/components/CalendarMonth/examples/CalendarMonthSelectableDate.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { CalendarMonth } from '@patternfly/react-core';
+import { CalendarMonth, Title, CalendarMonthInlineProps } from '@patternfly/react-core';
 
 export const CalendarMonthSelectableDate: React.FunctionComponent = () => {
   const [date, setDate] = React.useState(new Date(2020, 10, 24));
@@ -9,10 +9,20 @@ export const CalendarMonthSelectableDate: React.FunctionComponent = () => {
     console.log(`updated month: ${newDate.getMonth()}, updated year: ${newDate.getFullYear()}`);
   };
 
+  const inlineProps: CalendarMonthInlineProps = {
+    component: 'article',
+    title: (
+      <Title headingLevel="h4" id="favorite-date">
+        Select your favorite date
+      </Title>
+    ),
+    ariaLabelledby: 'favorite-date'
+  };
+
   return (
-    <React.Fragment>
+    <>
+      <CalendarMonth date={date} onChange={setDate} onMonthChange={onMonthChange} inlineProps={inlineProps} />
       <pre>Selected date: {date.toString()}</pre>
-      <CalendarMonth date={date} onChange={setDate} onMonthChange={onMonthChange} />
-    </React.Fragment>
+    </>
   );
 };