dash: Add beforeStartTooltip to <Calendar /> (#42105)

This adds a new `beforeStartTooltip` prop to `<Calendar />` that can be used to add a tooltip to buttons that are disabled. The implementation is done by customizing components of react-day-picker v9. I added a test to verify that the implementation behaves correctly.

GitOrigin-RevId: 9e4e57d09dee22950ca3b9a56d3501c3152d7542

Author: Nicolapps

npm-packages/dashboard-common/src/elements/Calendar.stories.tsx

@@ -30,6 +30,11 @@ export const RestrictedRange: Story = {
       before: rangeStart,
       after: rangeEnd,
     },
+    beforeStartTooltip: (
+      <>
+        This is <em>too early</em>!
+      </>
+    ),
   },
 };
 

npm-packages/dashboard-common/src/elements/Calendar.test.tsx

@@ -0,0 +1,117 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Calendar, CalendarProps } from "./Calendar";
+
+describe("Calendar", () => {
+  describe("beforeStartTooltip", () => {
+    const MESSAGE = "Cannot select dates before start";
+
+    const currentMonth = new Date(2025, 5); // June 2025
+    const minDate = new Date(2025, 5, 10);
+    const maxDate = new Date(2025, 5, 20);
+
+    const calendarProps = {
+      mode: "single",
+      selected: new Date(2025, 5, 15),
+      defaultMonth: currentMonth,
+      startMonth: minDate,
+      endMonth: maxDate,
+      disabled: { before: minDate, after: maxDate },
+      beforeStartTooltip: MESSAGE,
+      onSelect: () => {},
+    } satisfies Partial<CalendarProps>;
+
+    describe("on day buttons", () => {
+      it("should show tooltip on dates before the start of allowed dates", async () => {
+        const user = userEvent.setup();
+
+        render(<Calendar {...calendarProps} />);
+
+        const day9Button = screen.getByRole("button", {
+          name: "Monday, June 9th, 2025",
+        });
+
+        expect(day9Button).toBeDisabled();
+
+        await user.hover(day9Button);
+
+        expect(
+          screen.getByRole("tooltip", {
+            name: MESSAGE,
+          }),
+        ).toBeInTheDocument();
+      });
+
+      it("should show tooltip on dates in the range of allowed dates", async () => {
+        const user = userEvent.setup();
+
+        render(<Calendar {...calendarProps} />);
+
+        const day10Button = screen.getByRole("button", {
+          name: "Tuesday, June 10th, 2025",
+        });
+
+        expect(day10Button).toBeEnabled();
+
+        await user.hover(day10Button);
+
+        expect(screen.queryByText(MESSAGE)).not.toBeInTheDocument();
+      });
+
+      it("should not show tooltip on dates after the end of allowed dates", async () => {
+        const user = userEvent.setup();
+
+        render(<Calendar {...calendarProps} />);
+
+        const day21Button = screen.getByRole("button", {
+          name: "Saturday, June 21st, 2025",
+        });
+
+        expect(day21Button).toBeDisabled();
+
+        await user.hover(day21Button);
+        expect(screen.queryByText(MESSAGE)).not.toBeInTheDocument();
+      });
+    });
+
+    describe("on previous month button", () => {
+      it("should show a tooltip on the previous month button", async () => {
+        const user = userEvent.setup();
+
+        render(<Calendar {...calendarProps} />);
+
+        const prevButton = screen.getByRole("button", {
+          name: "Go to the Previous Month",
+        });
+        expect(prevButton).toHaveAttribute("aria-disabled", "true");
+
+        // Hover over the disabled button - should show tooltip
+        await user.hover(prevButton);
+
+        expect(
+          screen.getByRole("tooltip", {
+            name: MESSAGE,
+          }),
+        ).toBeInTheDocument();
+      });
+
+      it("should not show the tooltip on the next month button", async () => {
+        const user = userEvent.setup();
+
+        render(<Calendar {...calendarProps} />);
+
+        const nextButton = screen.getByRole("button", {
+          name: "Go to the Next Month",
+        });
+        expect(nextButton).toHaveAttribute("aria-disabled", "true");
+
+        await user.hover(nextButton);
+        expect(
+          screen.queryByRole("tooltip", {
+            name: MESSAGE,
+          }),
+        ).not.toBeInTheDocument();
+      });
+    });
+  });
+});

npm-packages/dashboard-common/src/elements/Calendar.tsx

@@ -1,19 +1,29 @@
 "use client";
 
 import * as React from "react";
+import { ChevronLeftIcon, ChevronRightIcon } from "@radix-ui/react-icons";
 import {
-  ChevronLeftIcon,
-  ChevronRightIcon,
-  ChevronUpIcon,
-  ChevronDownIcon,
-} from "@radix-ui/react-icons";
-import { ChevronProps, ClassNames, DayPicker } from "react-day-picker";
+  ClassNames,
+  DayButton,
+  DayButtonProps,
+  DayPicker,
+  DayProps,
+  NextMonthButtonProps,
+  PreviousMonthButtonProps,
+} from "react-day-picker";
 
 import { cn } from "@ui/cn";
+import { Tooltip } from "@ui/Tooltip";
 
-export type CalendarProps = React.ComponentProps<typeof DayPicker>;
+export type BaseProps = React.ComponentProps<typeof DayPicker>;
+export type CalendarProps = BaseProps & {
+  beforeStartTooltip?: React.ReactNode;
+};
 
-export function Calendar({ ...props }: CalendarProps) {
+export function Calendar({
+  beforeStartTooltip,
+  ...calendarProps
+}: CalendarProps) {
   return (
     <DayPicker
       classNames={
@@ -55,24 +65,81 @@ export function Calendar({ ...props }: CalendarProps) {
         } satisfies Partial<ClassNames>
       }
       components={{
-        Chevron: function CustomChevron({ orientation }: ChevronProps) {
-          if (orientation === "left") {
-            return <ChevronLeftIcon className="size-4" />;
-          }
-          if (orientation === "right") {
-            return <ChevronRightIcon className="size-4" />;
-          }
-          if (orientation === "up") {
-            return <ChevronUpIcon className="size-4" />;
-          }
-          if (orientation === "down") {
-            return <ChevronDownIcon className="size-4" />;
-          }
-          orientation satisfies undefined;
-          return <span />;
+        PreviousMonthButton: function CustomPreviousMonthButton({
+          children: _,
+          ...buttonProps
+        }: PreviousMonthButtonProps) {
+          return (
+            <Tooltip
+              tip={buttonProps["aria-disabled"] === true && beforeStartTooltip}
+              wrapsButton
+            >
+              {/* eslint-disable-next-line react/forbid-elements, react/button-has-type -- Component managed by react-day-picker */}
+              <button {...buttonProps}>
+                <ChevronLeftIcon className="size-4" />
+              </button>
+            </Tooltip>
+          );
+        },
+
+        NextMonthButton: function CustomPreviousMonthButton({
+          children: _,
+          ...buttonProps
+        }: NextMonthButtonProps) {
+          return (
+            // eslint-disable-next-line react/forbid-elements, react/button-has-type -- Component managed by react-day-picker
+            <button {...buttonProps}>
+              <ChevronRightIcon className="size-4" />
+            </button>
+          );
+        },
+
+        // Modify `DayButton` to forward ref so that we can wrap it in a tooltip
+        DayButton: React.forwardRef<HTMLButtonElement, DayButtonProps>(
+          function CalendarDayButton(
+            { day: _, modifiers, ...buttonProps },
+            ref,
+          ) {
+            const localRef = React.useRef<HTMLButtonElement>(null);
+            React.useImperativeHandle(ref, () => localRef.current!);
+
+            React.useEffect(() => {
+              if (modifiers.focused) localRef.current?.focus();
+            }, [modifiers.focused]);
+
+            // eslint-disable-next-line react/forbid-elements, react/button-has-type -- Component managed by react-day-picker
+            return <button ref={localRef} {...buttonProps} />;
+          },
+        ) as typeof DayButton, // need `as` here since `DayButton` isn’t
+
+        // Modify `Day` to wrap the children in a tooltip when necessary
+        Day: function CalendarDay({
+          day,
+          modifiers,
+          children,
+          ...tdProps
+        }: DayProps) {
+          return (
+            <td {...tdProps}>
+              <Tooltip
+                tip={
+                  beforeStartTooltip &&
+                  modifiers.disabled &&
+                  typeof calendarProps.disabled === "object" &&
+                  "before" in calendarProps.disabled &&
+                  day.date < calendarProps.disabled.before
+                    ? beforeStartTooltip
+                    : undefined
+                }
+                wrapsButton
+              >
+                {children}
+              </Tooltip>
+            </td>
+          );
         },
       }}
-      {...props}
+      {...calendarProps}
     />
   );
 }

npm-packages/dashboard-common/src/elements/DateRangePicker.stories.tsx

@@ -22,5 +22,10 @@ export const RestrictedRange: Story = {
   args: {
     minDate: new Date(Date.now() - 4 * 7 * 24 * 60 * 60 * 1000),
     maxDate: new Date(Date.now() + 4 * 7 * 24 * 60 * 60 * 1000),
+    beforeMinDateTooltip: (
+      <>
+        This is <em>too early</em>!
+      </>
+    ),
   },
 };

npm-packages/dashboard-common/src/elements/DateRangePicker.tsx

@@ -21,6 +21,7 @@ export type DateRangeShortcut = {
 export function DateRangePicker({
   minDate,
   maxDate,
+  beforeMinDateTooltip,
   date,
   setDate,
   shortcuts,
@@ -31,6 +32,7 @@ export function DateRangePicker({
 }: {
   minDate?: Date;
   maxDate?: Date;
+  beforeMinDateTooltip?: React.ReactNode;
   date: {
     from?: Date;
     to?: Date;
@@ -156,6 +158,7 @@ export function DateRangePicker({
             startMonth={minDate}
             endMonth={maxDate}
             disabled={disabledFromRange({ minDate, maxDate })}
+            beforeStartTooltip={beforeMinDateTooltip}
             defaultMonth={from || new Date()}
             selected={selectedRange}
             onSelect={(d) => {