feat(calendar): add custom cell content to Calendar

.changeset/popular-seals-appear.md

@@ -0,0 +1,5 @@
+---
+"@nextui-org/calendar": minor
+---
+
+Added the `renderCellContent` prop to the `Calendar` and `RangeCalendar` components, allowing developers to specify custom content for each calendar cell. Updated the existing tests and added new test cases to cover the custom cell content functionality.

.changeset/tame-students-tan.md

@@ -0,0 +1,28 @@
+---
+"@nextui-org/calendar": major
+---
+
+### Changes
+- Added support for customizing calendar cells.
+  - You can now use `children` to customize the content of calendar cells.
+  - The default structure of calendar cells has been updated to improve flexibility.
+
+### Breaking Changes
+- **WHAT**: The following changes might affect existing implementations:
+  1. Style class names have been renamed (e.g., `cellButton` → `cellHeader`).
+  2. The internal structure of calendar cells has changed, which may cause existing styles to no longer apply.
+- **WHY**: These changes were made to provide better flexibility and support for modern styling and customization.
+- **HOW**:
+  1. If you are using custom styles, update the class names to the new ones.
+  2. Use `children` to customize the content of calendar cells.
+  3. Refer to the example below for implementation:
+
+```jsx
+<Calendar>
+  {(date) => (
+    <div style={{ backgroundColor: "lightblue" }}>
+      <span>{date.day}</span>
+    </div>
+  )}
+</Calendar>
+```

apps/docs/content/components/calendar/custom-cell-content.raw.jsx

@@ -0,0 +1,50 @@
+import React from "react";
+import {
+  Calendar,
+  CalendarCellContent,
+  CalendarCellHeader,
+  CalendarCellBody,
+} from "@nextui-org/react";
+
+export default function App() {
+  return (
+    <Calendar calendarWidth={400}>
+      {(date) => (
+        <CalendarCellContent>
+          <CalendarCellHeader />
+          <CalendarCellBody>
+            <div className="flex flex-col w-full text-tiny gap-0.5 px-0.5">
+              {date.day % 7 === 0 && (
+                <span
+                  aria-label="Calendar event"
+                  className="bg-red-500/20 w-full rounded-md px-1 text-red-400 line-clamp-1"
+                  role="status"
+                >
+                  MTG
+                </span>
+              )}
+              {date.day % 5 === 0 && (
+                <span
+                  aria-label="calendar event"
+                  className="bg-green-500/20 w-full rounded-md px-1 text-green-400 line-clamp-1"
+                  role="status"
+                >
+                  MTG
+                </span>
+              )}
+              {date.day % 3 === 0 && (
+                <span
+                  aria-label="calendar event"
+                  className="bg-yellow-500/20 w-full rounded-md px-1 text-yellow-400 line-clamp-1"
+                  role="status"
+                >
+                  MTG
+                </span>
+              )}
+            </div>
+          </CalendarCellBody>
+        </CalendarCellContent>
+      )}
+    </Calendar>
+  );
+}

apps/docs/content/components/calendar/custom-cell-content.tsx

@@ -0,0 +1,9 @@
+import App from "./custom-cell-content.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/components/calendar/index.ts

@@ -12,6 +12,7 @@ import internationalCalendars from "./international-calendars";
 import visibleMonths from "./visible-months";
 import pageBehaviour from "./page-behaviour";
 import presets from "./presets";
+import customCellContent from "./custom-cell-content";
 
 export const calendarContent = {
   usage,
@@ -28,4 +29,5 @@ export const calendarContent = {
   visibleMonths,
   pageBehaviour,
   presets,
+  customCellContent,
 };

apps/docs/content/components/range-calendar/custom-cell-content.raw.jsx

@@ -0,0 +1,49 @@
+import {
+  RangeCalendar,
+  CalendarCellContent,
+  CalendarCellHeader,
+  CalendarCellBody,
+} from "@nextui-org/react";
+
+export default function App() {
+  return (
+    <RangeCalendar calendarWidth={400}>
+      {(date) => (
+        <CalendarCellContent>
+          <CalendarCellHeader />
+          <CalendarCellBody>
+            <div className="flex flex-col w-full text-tiny gap-0.5 px-0.5">
+              {date.day % 7 === 0 && (
+                <span
+                  aria-label="calendar event"
+                  className="bg-red-500/20 w-full rounded-md px-1 text-red-400 line-clamp-1"
+                  role="status"
+                >
+                  MTG
+                </span>
+              )}
+              {date.day % 5 === 0 && (
+                <span
+                  aria-label="calendar event"
+                  className="bg-green-500/20 w-full rounded-md px-1 text-green-400 line-clamp-1"
+                  role="status"
+                >
+                  MTG
+                </span>
+              )}
+              {date.day % 3 === 0 && (
+                <span
+                  aria-label="calendar event"
+                  className="bg-yellow-500/20 w-full rounded-md px-1 text-yellow-400 line-clamp-1"
+                  role="status"
+                >
+                  MTG
+                </span>
+              )}
+            </div>
+          </CalendarCellBody>
+        </CalendarCellContent>
+      )}
+    </RangeCalendar>
+  );
+}

apps/docs/content/components/range-calendar/custom-cell-content.tsx

@@ -0,0 +1,9 @@
+import App from "./custom-cell-content.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/components/range-calendar/index.ts

@@ -12,6 +12,7 @@ import internationalCalendars from "./international-calendars";
 import visibleMonths from "./visible-months";
 import pageBehaviour from "./page-behaviour";
 import presets from "./presets";
+import customCellContent from "./custom-cell-content";
 import withMonthAndYearPicker from "./with-month-and-year-picker";
 
 export const rangeCalendarContent = {
@@ -29,5 +30,6 @@ export const rangeCalendarContent = {
   visibleMonths,
   pageBehaviour,
   presets,
+  customCellContent,
   withMonthAndYearPicker,
 };

apps/docs/content/docs/components/calendar.mdx

@@ -129,6 +129,20 @@ Here's the example to customize `topContent` and `bottomContent` to have some pr
 
 <CodeDemo title="Presets" files={calendarContent.presets} />
 
+### Custom Cell Content
+
+The Calendar component supports customizing the cell content in two ways:
+
+<CodeDemo title="Custom Cell" files={calendarContent.customCellContent} />
+
+The Calendar provides three components for cell customization:
+
+- `CalendarCellContent`: The wrapper component for the cell content
+- `CalendarCellHeader`: The interactive header element that handles selection
+- `CalendarCellBody`: Additional content container below the button
+
+These components inherit all calendar states (selected, disabled, etc.) and maintain proper accessibility.
+
 ## Slots
 
 - **base**: Calendar wrapper, it handles alignment, placement, and general appearance.
@@ -146,6 +160,10 @@ Here's the example to customize `topContent` and `bottomContent` to have some pr
 - **gridBodyRow**: The date grid body row element (e.g. `<tr>`).
 - **cell**: The date grid cell element (e.g. `<td>`).
 - **cellButton**: The button element within the cell.
+- **cellContent**: The wrapper for custom cell content.
+- **cellHeaderWrapper**: The wrapper for the cell header content.
+- **cellHeader**: The header element within the cell that handles selection.
+- **cellBody**: The container for additional cell content.
 - **pickerWrapper**: The wrapper for the picker
 - **pickerMonthList**: The month list picker.
 - **pickerYearList**: The year list picker.

apps/docs/content/docs/components/range-calendar.mdx

@@ -13,6 +13,7 @@ A range calendar consists of a grouping element containing one or more date grid
 
 ---
 
+
 <CarbonAd/>
 
 ## Installation
@@ -32,8 +33,8 @@ A range calendar consists of a grouping element containing one or more date grid
 
 <ImportTabs
   commands={{
-    main: 'import {RangeCalendar} from "@nextui-org/react";',
-    individual: 'import {RangeCalendar} from "@nextui-org/calendar";',
+    main: 'import {RangeCalendar, CalendarCellContent, CalendarCellHeader, CalendarCellBody} from "@nextui-org/react";',
+    individual: 'import {RangeCalendar, CalendarCellContent, CalendarCellHeader, CalendarCellBody} from "@nextui-org/calendar";',
   }}
 />
 
@@ -45,6 +46,56 @@ Date values are provided using objects in the [@internationalized/date](https://
 
 <CodeDemo title="Usage" files={rangeCalendarContent.usage} />
 
+### Custom Cell Content
+
+The Calendar component supports customizing the cell content in two ways:
+
+1. Using a render function:
+```tsx
+<RangeCalendar>
+  {(date, cellState) => (
+    <CalendarCellContent>
+      <CalendarCellHeader>
+        <span 
+          className={
+            getDayOfWeek(date, locale) === 0 
+              ? "text-red-500" 
+              : "text-default-500"
+          }
+        >
+          {date.day}
+        </span>
+      </CalendarCellHeader>
+    </CalendarCellContent>
+  )}
+</RangeCalendar>
+```
+
+2. Using component composition:
+```tsx
+<RangeCalendar>
+  <CalendarCellContent>
+    <CalendarCellHeader />
+    <CalendarCellBody>
+      <div className="flex flex-col w-full gap-0.5 justify-center items-center p-0.5">
+        <span className="bg-red-600 h-1 w-full rounded-full" />
+        <span className="bg-green-600 h-1 w-full rounded-full" />
+        <span className="bg-yellow-600 h-1 w-full rounded-full" />
+      </div>
+    </CalendarCellBody>
+  </CalendarCellContent>
+</RangeCalendar>
+```
+
+The calendar provides three components for cell customization:
+- `CalendarCellContent`: Wrapper component for the entire cell content
+- `CalendarCellHeader`: Interactive button element that handles selection
+- `CalendarCellBody`: Container for additional content below the button
+
+These components inherit all calendar states (selected, disabled, etc.) and maintain proper accessibility.
+
+<CodeDemo title="Custom Cell Content" files={rangeCalendarContent.customCellContent} />
+
 ### Disabled
 
 The `isDisabled` boolean prop makes the Calendar disabled. Cells cannot be focused or selected.
@@ -137,6 +188,21 @@ Here's the example to customize `topContent` and `bottomContent` to have some pr
 
 <CodeDemo title="Presets" files={rangeCalendarContent.presets} />
 
+### Custom Cell Content
+
+The Calendar component supports customizing the cell content in two ways:
+
+<CodeDemo title="Custom Cell" files={rangeCalendarContent.customCellContent} />
+
+The Calendar provides three components for cell customization:
+
+- `CalendarCellContent`: The wrapper component for the cell content
+- `CalendarCellHeader`: The interactive header element that handles selection
+- `CalendarCellBody`: Additional content container below the button
+
+These components inherit all calendar states (selected, disabled, etc.) and maintain proper accessibility.
+
+
 ## Slots
 
 - **base**: Calendar wrapper, it handles alignment, placement, and general appearance.
@@ -154,6 +220,10 @@ Here's the example to customize `topContent` and `bottomContent` to have some pr
 - **gridBodyRow**: The date grid body row element (e.g. `<tr>`).
 - **cell**: The date grid cell element (e.g. `<td>`).
 - **cellButton**: The button element within the cell.
+- **cellContent**: The wrapper for custom cell content.
+- **cellHeaderWrapper**: The wrapper for the cell header content.
+- **cellHeader**: The header element within the cell that handles selection.
+- **cellBody**: The container for additional cell content.
 - **pickerWrapper**: The wrapper for the picker
 - **pickerMonthList**: The month list picker.
 - **pickerYearList**: The year list picker.

packages/components/calendar/__tests__/calendar.test.tsx

@@ -464,4 +464,25 @@ describe("Calendar", () => {
       expect(year).toHaveAttribute("data-value", "2567");
     });
   });
+
+  describe("Custom cell content", () => {
+    it("should render custom content in the calendar cells", () => {
+      const wrapper = render(
+        <Calendar defaultValue={new CalendarDate(2024, 3, 31)}>
+          {(date) => (
+            <div>
+              {date.day}
+              <span>*</span>
+            </div>
+          )}
+        </Calendar>,
+      );
+
+      const gridCells = wrapper.getAllByRole("gridcell");
+      const customContentCell = gridCells.find((cell) => cell.textContent === "31*");
+
+      expect(customContentCell).not.toBeNull();
+      expect(customContentCell).toHaveTextContent("31*");
+    });
+  });
 });

packages/components/calendar/__tests__/range-calendar.test.tsx

@@ -748,4 +748,30 @@ describe("RangeCalendar", () => {
       expect(end).toEqual(new CalendarDate(2019, 6, 25));
     });
   });
+
+  describe("Custom cell content", () => {
+    it("should render custom content in the range calendar cells", () => {
+      const wrapper = render(
+        <RangeCalendar
+          defaultValue={{start: new CalendarDate(2024, 6, 25), end: new CalendarDate(2024, 6, 26)}}
+        >
+          {(date) => (
+            <div>
+              {date.day}
+              <span>*</span>
+            </div>
+          )}
+        </RangeCalendar>,
+      );
+
+      const gridCells = wrapper.getAllByRole("gridcell");
+      const customContentCellA = gridCells.find((cell) => cell.textContent === "25*");
+      const customContentCellB = gridCells.find((cell) => cell.textContent === "26*");
+
+      expect(customContentCellA).not.toBeNull();
+      expect(customContentCellA).toHaveTextContent("25*");
+      expect(customContentCellB).not.toBeNull();
+      expect(customContentCellB).toHaveTextContent("26*");
+    });
+  });
 });