@super-calendar/dom 2.1.4 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-calendar/dom",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "Virtualized month / week / day calendar and date picker for react-dom. No React Native, no react-native-web.",
   "keywords": [
     "calendar",
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@super-calendar/core": "2.1.4"
+    "@super-calendar/core": "2.2.0"
   },
   "peerDependencies": {
     "@legendapp/list": ">=3",

package/src/Agenda.tsx

@@ -1,10 +1,17 @@
 import { LegendList } from "@legendapp/list/react";
 import { format, isSameDay, type Locale, startOfDay } from "date-fns";
 import { type ComponentType, type CSSProperties, type ReactElement, useMemo } from "react";
-import type { CalendarEvent } from "@super-calendar/core";
+import type { CalendarEvent, EventAccessibilityLabeler } from "@super-calendar/core";
 import { eventTimeLabel, getIsToday, isAllDayEvent } from "@super-calendar/core";
+import { createSlots, type ResolvedSlot, type SlotStyleProps } from "./slots";
 import { type DomCalendarTheme, mergeDomTheme } from "./theme";
 
+/**
+ * Styleable parts of {@link Agenda}. Pass a class or inline style per slot via the
+ * `classNames` / `styles` props.
+ */
+export type AgendaSlot = "dayHeader" | "eventRow" | "event" | "empty";
+
 /** Props passed to a custom agenda (schedule) event renderer. */
 export interface DomAgendaEventArgs<T = unknown> {
   /** The event to render. */
@@ -23,7 +30,7 @@ export interface DomAgendaEventArgs<T = unknown> {
 export type DomAgendaEvent<T = unknown> = ComponentType<DomAgendaEventArgs<T>>;
 
 /** Props for {@link Agenda}. */
-export interface AgendaProps<T = unknown> {
+export interface AgendaProps<T = unknown> extends SlotStyleProps<AgendaSlot> {
   /** Events to list. The consumer controls which (and therefore the date range). */
   events: CalendarEvent<T>[];
   /** date-fns locale for the day headers and time labels. */
@@ -38,6 +45,12 @@ export interface AgendaProps<T = unknown> {
   height?: number | string;
   /** Replace the built-in event row. */
   renderEvent?: DomAgendaEvent<T>;
+  /**
+   * Override the screen-reader label for each event row. Receives the event and a
+   * `{ mode: "schedule", isAllDay, ampm }` context; return the full text to
+   * announce. Defaults to the row's own text content.
+   */
+  eventAccessibilityLabel?: EventAccessibilityLabeler<T>;
   /** Tap an event row. */
   onPressEvent?: (event: CalendarEvent<T>) => void;
   /** Tap a day's header. */
@@ -56,8 +69,8 @@ function DefaultAgendaRow<T>({
   event,
   isAllDay,
   ampm = false,
-  theme,
-}: DomAgendaEventArgs<T> & { theme: DomCalendarTheme }) {
+  cardProps,
+}: DomAgendaEventArgs<T> & { cardProps: ResolvedSlot }) {
   const time =
     eventTimeLabel({
       mode: "schedule",
@@ -70,14 +83,7 @@ function DefaultAgendaRow<T>({
   // A filled card with the title on top and the time below, matching the native
   // schedule row.
   return (
-    <div
-      style={{
-        padding: "6px 10px",
-        borderRadius: 8,
-        background: theme.eventBackground,
-        color: theme.eventText,
-      }}
-    >
+    <div {...cardProps}>
       <div style={{ fontWeight: 600, fontSize: 14 }}>{event.title}</div>
       {time ? <div style={{ fontSize: 13, opacity: 0.75 }}>{time}</div> : null}
     </div>
@@ -103,12 +109,16 @@ export function Agenda<T = unknown>({
   theme: themeOverrides,
   height = 480,
   renderEvent,
+  eventAccessibilityLabel,
   onPressEvent,
   onPressDay,
   className,
   style,
+  classNames,
+  styles,
 }: AgendaProps<T>): ReactElement {
   const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
+  const slot = createSlots<AgendaSlot>({ classNames, styles });
   const Renderer = renderEvent;
 
   const rows = useMemo<Row<T>[]>(() => {
@@ -143,24 +153,26 @@ export function Agenda<T = unknown>({
               : getIsToday(item.date);
             const label = format(item.date, "EEEE, d LLLL", locale ? { locale } : undefined);
             const color = highlighted ? theme.todayBackground : theme.textMuted;
+            const headerProps = slot("dayHeader", {
+              base: onPressDay
+                ? {
+                    display: "block",
+                    width: "100%",
+                    border: "none",
+                    background: "transparent",
+                    cursor: "pointer",
+                    font: "inherit",
+                    textAlign: "left",
+                  }
+                : { display: "block", width: "100%" },
+              themed: { padding: "12px 12px 4px", fontSize: 13, fontWeight: 600, color },
+            });
             return onPressDay ? (
-              <button
-                type="button"
-                onClick={() => onPressDay(item.date)}
-                style={{
-                  ...headerStyle,
-                  color,
-                  border: "none",
-                  background: "transparent",
-                  cursor: "pointer",
-                  font: "inherit",
-                  textAlign: "left",
-                }}
-              >
+              <button type="button" onClick={() => onPressDay(item.date)} {...headerProps}>
                 {label}
               </button>
             ) : (
-              <div style={{ ...headerStyle, color }}>{label}</div>
+              <div {...headerProps}>{label}</div>
             );
           }
           const event = item.event;
@@ -171,33 +183,52 @@ export function Agenda<T = unknown>({
             <button
               type="button"
               onClick={onPress}
-              style={{
-                display: "block",
-                width: "100%",
-                textAlign: "left",
-                border: "none",
-                background: "transparent",
-                cursor: "pointer",
-                font: "inherit",
-                padding: "2px 12px",
-              }}
+              aria-label={
+                eventAccessibilityLabel
+                  ? eventAccessibilityLabel(event, { mode: "schedule", isAllDay, ampm })
+                  : undefined
+              }
+              {...slot("eventRow", {
+                base: {
+                  display: "block",
+                  width: "100%",
+                  textAlign: "left",
+                  border: "none",
+                  background: "transparent",
+                  cursor: "pointer",
+                  font: "inherit",
+                },
+                themed: { padding: "2px 12px" },
+              })}
             >
-              {Renderer ? <Renderer {...args} /> : <DefaultAgendaRow {...args} theme={theme} />}
+              {Renderer ? (
+                <Renderer {...args} />
+              ) : (
+                <DefaultAgendaRow
+                  {...args}
+                  cardProps={slot("event", {
+                    themed: {
+                      padding: "6px 10px",
+                      borderRadius: 8,
+                      background: theme.eventBackground,
+                      color: theme.eventText,
+                    },
+                  })}
+                />
+              )}
             </button>
           );
         }}
       />
       {rows.length === 0 ? (
-        <div style={{ padding: "16px 12px", color: theme.textMuted, fontSize: 14 }}>No events</div>
+        <div
+          {...slot("empty", {
+            themed: { padding: "16px 12px", color: theme.textMuted, fontSize: 14 },
+          })}
+        >
+          No events
+        </div>
       ) : null}
     </div>
   );
 }
-
-const headerStyle: CSSProperties = {
-  display: "block",
-  width: "100%",
-  padding: "12px 12px 4px",
-  fontSize: 13,
-  fontWeight: 600,
-};

package/src/Calendar.tsx

@@ -5,16 +5,27 @@ import type {
   CalendarEvent,
   DateRange,
   DateSelectionConstraints,
+  EventAccessibilityLabeler,
   TimeGridMode,
+  WeekdayFormat,
   WeekStartsOn,
 } from "@super-calendar/core";
-import { Agenda, type DomAgendaEvent } from "./Agenda";
-import { type DomMonthEvent, MonthView } from "./MonthView";
-import { type DomRenderEvent, TimeGrid } from "./TimeGrid";
+import { Agenda, type AgendaSlot, type DomAgendaEvent } from "./Agenda";
+import { type DomMonthEvent, MonthView, type MonthViewSlot } from "./MonthView";
+import type { SlotStyleProps } from "./slots";
+import { type DomRenderEvent, TimeGrid, type TimeGridSlot } from "./TimeGrid";
 import type { DomCalendarTheme } from "./theme";
 
+/**
+ * Styleable parts across every view {@link Calendar} can render. Only the slots
+ * for the active `mode` apply; the rest are ignored. See {@link MonthViewSlot},
+ * {@link TimeGridSlot}, and {@link AgendaSlot}.
+ */
+export type CalendarSlot = MonthViewSlot | TimeGridSlot | AgendaSlot;
+
 /** Props for {@link Calendar}. */
-export interface CalendarProps<T = unknown> extends DateSelectionConstraints {
+export interface CalendarProps<T = unknown>
+  extends DateSelectionConstraints, SlotStyleProps<CalendarSlot> {
   /**
    * The view to render (default "week"). `month` renders a month grid, `schedule`
    * a day-grouped agenda list, and the others a time grid.
@@ -41,6 +52,12 @@ export interface CalendarProps<T = unknown> extends DateSelectionConstraints {
 
   /** Tap an event (both layouts). */
   onPressEvent?: (event: CalendarEvent<T>) => void;
+  /**
+   * Override the screen-reader label for each event. Receives the event and a
+   * `{ mode, isAllDay, ampm }` context; return the full text to announce. Defaults
+   * to each view's built-in label.
+   */
+  eventAccessibilityLabel?: EventAccessibilityLabeler<T>;
 
   // --- Time-grid modes (week / day / 3days / custom) ---
   /** 12-hour AM/PM time labels (default false). */
@@ -81,6 +98,8 @@ export interface CalendarProps<T = unknown> extends DateSelectionConstraints {
   moreLabel?: string;
   /** Render neighbouring months' days in the leading/trailing cells (default true). */
   showAdjacentMonths?: boolean;
+  /** Weekday header label width: `narrow` ("M"), `short` ("Mon", default), or `long` ("Monday"). */
+  weekdayFormat?: WeekdayFormat;
   /** Fill the cell with the range background instead of the pill band. */
   fillCellOnSelection?: boolean;
   /** Selected span. */
@@ -128,6 +147,7 @@ export function Calendar<T = unknown>({
   className,
   style,
   onPressEvent,
+  eventAccessibilityLabel,
   // time grid
   ampm,
   hourHeight,
@@ -148,6 +168,7 @@ export function Calendar<T = unknown>({
   maxVisibleEventCount,
   moreLabel,
   showAdjacentMonths,
+  weekdayFormat,
   fillCellOnSelection,
   selectedRange,
   selectedDates,
@@ -160,6 +181,9 @@ export function Calendar<T = unknown>({
   renderMonthEvent,
   // schedule
   renderScheduleEvent,
+  // styling
+  classNames,
+  styles,
 }: CalendarProps<T>): ReactElement {
   if (mode === "schedule") {
     return (
@@ -172,7 +196,10 @@ export function Calendar<T = unknown>({
         activeDate={date}
         className={className}
         style={style}
+        classNames={classNames}
+        styles={styles}
         renderEvent={renderScheduleEvent}
+        eventAccessibilityLabel={eventAccessibilityLabel}
         onPressEvent={onPressEvent}
         onPressDay={onPressDay}
       />
@@ -185,10 +212,13 @@ export function Calendar<T = unknown>({
         date={date}
         events={events ?? []}
         weekStartsOn={weekStartsOn}
+        weekdayFormat={weekdayFormat}
         locale={locale}
         theme={theme}
         className={className}
         style={style}
+        classNames={classNames}
+        styles={styles}
         maxVisibleEventCount={maxVisibleEventCount}
         moreLabel={moreLabel}
         showAdjacentMonths={showAdjacentMonths}
@@ -200,9 +230,11 @@ export function Calendar<T = unknown>({
         isDateDisabled={isDateDisabled}
         keyboardDayNavigation={keyboardDayNavigation}
         onPressDay={onPressDay}
+        onCreateEvent={onCreateEvent}
         onPressEvent={onPressEvent}
         onPressMore={onPressMore}
         renderEvent={renderMonthEvent}
+        eventAccessibilityLabel={eventAccessibilityLabel}
       />
     );
   }
@@ -213,12 +245,15 @@ export function Calendar<T = unknown>({
       mode={mode}
       events={events}
       weekStartsOn={weekStartsOn}
+      weekdayFormat={weekdayFormat}
       numberOfDays={numberOfDays}
       locale={locale}
       theme={theme}
       height={height}
       className={className}
       style={style}
+      classNames={classNames}
+      styles={styles}
       ampm={ampm}
       hourHeight={hourHeight}
       scrollOffsetMinutes={scrollOffsetMinutes}
@@ -234,6 +269,7 @@ export function Calendar<T = unknown>({
       onDragEvent={onDragEvent}
       onPressDateHeader={onPressDateHeader}
       renderEvent={renderTimeEvent}
+      eventAccessibilityLabel={eventAccessibilityLabel}
       hourComponent={hourComponent}
     />
   );