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

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

@@ -20,6 +20,15 @@ export enum Weekday {
   Saturday
 }
 
+export interface InlineCalendarProps {
+  /** Component wrapping the calendar month when used inline. Recommended to be 'article'. */
+  wrapperComponent?: 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. */
+  ariaLabeledby?: 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;
+  /** */
+  inlineProps?: InlineCalendarProps;
 }
 
 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.wrapperComponent ? inlineProps.wrapperComponent : 'article') as any;
+    return (
+      <Component {...(inlineProps.ariaLabeledby && { 'aria-labeledby': inlineProps.ariaLabeledby })}>
+        {inlineProps.title}
+        {calendarToRender}
+      </Component>
+    );
+  }
+  return calendarToRender;
 };
+CalendarMonth.displayName = 'CalendarMonth';

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

@@ -55,3 +55,11 @@ 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', () => {
+  const { asFragment } = render(
+    <CalendarMonth inlineProps={{wrapperComponent: 'article', title: <div id="hi">Title</div>, ariaLabeledby: "hi"}} />
+  );
+
+  expect(asFragment()).toMatchSnapshot();
+});