@super-calendar/dom 2.1.5 → 2.2.0

package/src/DateRangePicker.tsx

@@ -0,0 +1,360 @@
+import { format } from "date-fns";
+import {
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from "react";
+import {
+  type DateRange,
+  type DateSelectionConstraints,
+  nextDateRange,
+  type WeekStartsOn,
+} from "@super-calendar/core";
+import { MonthList, type MonthListSlot } from "./MonthList";
+import { createSlots, type SlotStyleProps } from "./slots";
+import { type DomCalendarTheme, mergeDomTheme } from "./theme";
+
+/** Styleable chrome of the pickers (the calendar's own slots forward through too). */
+export type DatePickerSlot = "trigger" | "popover" | "footer" | "clear";
+
+interface PickerBaseProps
+  extends DateSelectionConstraints, SlotStyleProps<DatePickerSlot | MonthListSlot> {
+  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
+  weekStartsOn?: WeekStartsOn;
+  /** Height of the popover calendar viewport in px (default 320). */
+  height?: number;
+  /** Placeholder shown on the trigger when nothing is selected. */
+  placeholder?: string;
+  /** Disable the whole field. */
+  disabled?: boolean;
+  /** Theme overrides for the calendar. */
+  theme?: Partial<DomCalendarTheme>;
+  /** Class applied to the root element. */
+  className?: string;
+  /** Inline styles applied to the root element. */
+  style?: CSSProperties;
+}
+
+const triggerDefault: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  gap: 8,
+  minWidth: 220,
+  padding: "8px 12px",
+  borderRadius: 8,
+  cursor: "pointer",
+  font: "inherit",
+  textAlign: "left",
+};
+
+const popoverDefault: CSSProperties = {
+  position: "absolute",
+  zIndex: 20,
+  marginTop: 6,
+  overflow: "hidden",
+  borderRadius: 12,
+  minWidth: 300,
+};
+
+/**
+ * The shared popover shell: a trigger button and a calendar panel that closes on
+ * outside-click and Escape, and returns focus to the trigger. `renderCalendar`
+ * gets a close callback so a single-date pick can dismiss immediately.
+ */
+function usePopover() {
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const onDown = (e: MouseEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        setOpen(false);
+        triggerRef.current?.focus();
+      }
+    };
+    document.addEventListener("mousedown", onDown);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("mousedown", onDown);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [open]);
+
+  return { open, setOpen, rootRef, triggerRef };
+}
+
+interface ShellProps {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  rootRef: React.RefObject<HTMLDivElement | null>;
+  triggerRef: React.RefObject<HTMLButtonElement | null>;
+  theme: DomCalendarTheme;
+  slot: ReturnType<typeof createSlots<DatePickerSlot | MonthListSlot>>;
+  label: string;
+  hasValue: boolean;
+  placeholder: string;
+  disabled?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel: string;
+  children: ReactNode;
+}
+
+function PickerShell({
+  open,
+  setOpen,
+  rootRef,
+  triggerRef,
+  theme,
+  slot,
+  label,
+  hasValue,
+  placeholder,
+  disabled,
+  className,
+  style,
+  ariaLabel,
+  children,
+}: ShellProps): ReactElement {
+  const dialogId = useId();
+  return (
+    <div
+      ref={rootRef}
+      className={className}
+      style={{
+        position: "relative",
+        display: "inline-block",
+        fontFamily: theme.fontFamily,
+        ...style,
+      }}
+    >
+      <button
+        ref={triggerRef}
+        type="button"
+        disabled={disabled}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-controls={open ? dialogId : undefined}
+        onClick={() => setOpen(!open)}
+        {...slot("trigger", {
+          base: triggerDefault,
+          themed: {
+            border: `1px solid ${theme.gridLine}`,
+            background: theme.eventBackground,
+            color: hasValue ? theme.text : theme.textMuted,
+            opacity: disabled ? 0.5 : 1,
+          },
+        })}
+      >
+        <span>{hasValue ? label : placeholder}</span>
+        <span aria-hidden>▾</span>
+      </button>
+      {open ? (
+        <div
+          id={dialogId}
+          role="dialog"
+          aria-label={ariaLabel}
+          {...slot("popover", {
+            base: popoverDefault,
+            themed: { background: theme.eventBackground, border: `1px solid ${theme.gridLine}` },
+          })}
+        >
+          {children}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/** Props for {@link DatePicker}. */
+export interface DatePickerProps extends PickerBaseProps {
+  /** The selected day, or `null`. */
+  value: Date | null;
+  /** Called with the day the user picks. */
+  onChange: (date: Date) => void;
+  /** Format the trigger label. Default: `d MMM yyyy`. */
+  formatLabel?: (date: Date) => string;
+}
+
+/**
+ * A single-date input with a popover calendar. Controlled via `value` / `onChange`.
+ * Composed from {@link MonthList}; forward calendar slots (e.g. `dayBadge`) through
+ * `classNames` to restyle the popover.
+ *
+ * @example
+ * ```tsx
+ * const [value, setValue] = useState<Date | null>(null);
+ * <DatePicker value={value} onChange={setValue} />
+ * ```
+ */
+export function DatePicker({
+  value,
+  onChange,
+  formatLabel = (d) => format(d, "d MMM yyyy"),
+  weekStartsOn = 0,
+  height = 320,
+  placeholder = "Select a date",
+  disabled,
+  theme: themeOverrides,
+  className,
+  style,
+  classNames,
+  styles,
+  minDate,
+  maxDate,
+  isDateDisabled,
+}: DatePickerProps): ReactElement {
+  const theme = mergeDomTheme(themeOverrides);
+  const slot = createSlots<DatePickerSlot | MonthListSlot>({ classNames, styles });
+  const { open, setOpen, rootRef, triggerRef } = usePopover();
+
+  return (
+    <PickerShell
+      open={open}
+      setOpen={setOpen}
+      rootRef={rootRef}
+      triggerRef={triggerRef}
+      theme={theme}
+      slot={slot}
+      label={value ? formatLabel(value) : ""}
+      hasValue={!!value}
+      placeholder={placeholder}
+      disabled={disabled}
+      className={className}
+      style={style}
+      ariaLabel="Choose a date"
+    >
+      <MonthList
+        date={value ?? new Date()}
+        weekStartsOn={weekStartsOn}
+        selectedDates={value ? [value] : []}
+        minDate={minDate}
+        maxDate={maxDate}
+        isDateDisabled={isDateDisabled}
+        onPressDay={(day) => {
+          onChange(day);
+          setOpen(false);
+          triggerRef.current?.focus();
+        }}
+        height={height}
+        classNames={classNames}
+        styles={styles}
+      />
+    </PickerShell>
+  );
+}
+
+/** Props for {@link DateRangePicker}. */
+export interface DateRangePickerProps extends PickerBaseProps {
+  /** The selected range, or `null`. `end` is `null` while only the start is picked. */
+  value: DateRange | null;
+  /** Called with the next range on each pick (start-only, then complete). */
+  onChange: (range: DateRange | null) => void;
+  /** Format the trigger label. Default: `d MMM – d MMM yyyy`. */
+  formatLabel?: (range: DateRange) => string;
+}
+
+function defaultRangeLabel(range: DateRange): string {
+  const start = format(range.start, "d MMM yyyy");
+  return range.end ? `${start} – ${format(range.end, "d MMM yyyy")}` : `${start} – …`;
+}
+
+/**
+ * A date-range input with a popover calendar. Controlled via `value` / `onChange`;
+ * each pick advances the range through {@link nextDateRange} (start, then end), and
+ * the popover closes once both ends are set.
+ *
+ * @example
+ * ```tsx
+ * const [range, setRange] = useState<DateRange | null>(null);
+ * <DateRangePicker value={range} onChange={setRange} />
+ * ```
+ */
+export function DateRangePicker({
+  value,
+  onChange,
+  formatLabel = defaultRangeLabel,
+  weekStartsOn = 0,
+  height = 320,
+  placeholder = "Select dates",
+  disabled,
+  theme: themeOverrides,
+  className,
+  style,
+  classNames,
+  styles,
+  minDate,
+  maxDate,
+  isDateDisabled,
+}: DateRangePickerProps): ReactElement {
+  const theme = mergeDomTheme(themeOverrides);
+  const slot = createSlots<DatePickerSlot | MonthListSlot>({ classNames, styles });
+  const { open, setOpen, rootRef, triggerRef } = usePopover();
+  const constraints: DateSelectionConstraints = { minDate, maxDate, isDateDisabled };
+
+  return (
+    <PickerShell
+      open={open}
+      setOpen={setOpen}
+      rootRef={rootRef}
+      triggerRef={triggerRef}
+      theme={theme}
+      slot={slot}
+      label={value ? formatLabel(value) : ""}
+      hasValue={!!value}
+      placeholder={placeholder}
+      disabled={disabled}
+      className={className}
+      style={style}
+      ariaLabel="Choose a date range"
+    >
+      <MonthList
+        date={value?.start ?? new Date()}
+        weekStartsOn={weekStartsOn}
+        selectedRange={value ?? undefined}
+        minDate={minDate}
+        maxDate={maxDate}
+        isDateDisabled={isDateDisabled}
+        onPressDay={(day) => {
+          const next = nextDateRange(value, day, constraints);
+          onChange(next);
+          // Close once a full range is set.
+          if (next?.end) {
+            setOpen(false);
+            triggerRef.current?.focus();
+          }
+        }}
+        height={height}
+        classNames={classNames}
+        styles={styles}
+      />
+      <div
+        {...slot("footer", {
+          base: { display: "flex", justifyContent: "flex-end", padding: "8px 10px" },
+          themed: { borderTop: `1px solid ${theme.gridLine}` },
+        })}
+      >
+        <button
+          type="button"
+          onClick={() => onChange(null)}
+          {...slot("clear", {
+            base: { border: "none", background: "transparent", cursor: "pointer", font: "inherit" },
+            themed: { color: theme.textMuted },
+          })}
+        >
+          Clear
+        </button>
+      </div>
+    </PickerShell>
+  );
+}

package/src/MonthList.tsx

@@ -7,14 +7,25 @@ import {
   compareDayEvents,
   type DateRange,
   type DateSelectionConstraints,
+  type EventAccessibilityLabeler,
   groupEventsByDay,
+  type WeekdayFormat,
   type WeekStartsOn,
 } from "@super-calendar/core";
-import { type DomMonthEvent, MonthView } from "./MonthView";
+import { type DomMonthEvent, MonthView, type MonthViewSlot } from "./MonthView";
+import { createSlots, type SlotStyleProps } from "./slots";
 import { type DomCalendarTheme, mergeDomTheme } from "./theme";
 
+/**
+ * Styleable parts of {@link MonthList}. The shared weekday header uses `weekdays`
+ * / `weekday`; every other slot is forwarded to each month's {@link MonthView}
+ * (e.g. `title`, `day`, `chip`). See {@link MonthViewSlot}.
+ */
+export type MonthListSlot = MonthViewSlot;
+
 /** Props for {@link MonthList}. */
-export interface MonthListProps<T = unknown> extends DateSelectionConstraints {
+export interface MonthListProps<T = unknown>
+  extends DateSelectionConstraints, SlotStyleProps<MonthListSlot> {
   /** Anchor month; the list spans `pastMonths` before to `futureMonths` after. */
   date: Date;
   /** Months to render before the anchor (default 1). */
@@ -23,10 +34,18 @@ export interface MonthListProps<T = unknown> extends DateSelectionConstraints {
   futureMonths?: number;
   /** First day of the week. Sunday = 0 (default) ... Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
+  /** Weekday header label width: `narrow` ("M"), `short` ("Mon", default), or `long` ("Monday"). */
+  weekdayFormat?: WeekdayFormat;
   /** Events to render as chips in each day cell (calendar layout when provided). */
   events?: CalendarEvent<T>[];
   /** Custom chip renderer; falls back to the built-in titled chip. */
   renderEvent?: DomMonthEvent<T>;
+  /**
+   * Override the screen-reader label for each event chip. Receives the event and a
+   * `{ mode: "month", isAllDay, ampm: false }` context; return the full text to
+   * announce. Defaults to the event title and day (e.g. "Standup, 15 July").
+   */
+  eventAccessibilityLabel?: EventAccessibilityLabeler<T>;
   /** Max chips shown per day before a "+N more" row (default 3). */
   maxVisibleEventCount?: number;
   /** Template for the overflow row; `{moreCount}` is replaced. */
@@ -70,9 +89,11 @@ export function MonthList<T = unknown>({
   date,
   pastMonths = 1,
   futureMonths = 12,
+  weekdayFormat = "short",
   weekStartsOn = 0,
   events,
   renderEvent,
+  eventAccessibilityLabel,
   maxVisibleEventCount,
   moreLabel,
   onPressEvent,
@@ -90,8 +111,11 @@ export function MonthList<T = unknown>({
   onPressDay,
   className,
   style,
+  classNames,
+  styles,
 }: MonthListProps<T>): ReactElement {
   const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
+  const slot = createSlots<MonthListSlot>({ classNames, styles });
 
   const months = useMemo(() => {
     const first = startOfMonth(addMonths(date, -pastMonths));
@@ -102,8 +126,8 @@ export function MonthList<T = unknown>({
   // The weekday header only depends on the week start and locale, not the
   // rendered month window.
   const weekdays = useMemo(
-    () => buildMonthGrid(date, { weekStartsOn, locale }).weekdays,
-    [date, weekStartsOn, locale],
+    () => buildMonthGrid(date, { weekStartsOn, weekdayFormat, locale }).weekdays,
+    [date, weekStartsOn, weekdayFormat, locale],
   );
 
   // Build the day→events index once for the whole list rather than per month.
@@ -128,17 +152,22 @@ export function MonthList<T = unknown>({
       style={{ fontFamily: theme.fontFamily, color: theme.text, ...style }}
     >
       <div
-        style={{
-          display: "grid",
-          gridTemplateColumns: "repeat(7, minmax(0, 1fr))",
-          borderBottom: `1px solid ${theme.gridLine}`,
-          padding: "8px 0",
-        }}
+        {...slot("weekdays", {
+          base: { display: "grid", gridTemplateColumns: "repeat(7, minmax(0, 1fr))" },
+          themed: { borderBottom: `1px solid ${theme.gridLine}`, padding: "8px 0" },
+        })}
       >
         {weekdays.map((wd) => (
           <span
             key={wd.label}
-            style={{ textAlign: "center", fontSize: 12, fontWeight: 600, color: theme.textMuted }}
+            {...slot("weekday", {
+              themed: {
+                textAlign: "center",
+                fontSize: 12,
+                fontWeight: 600,
+                color: theme.textMuted,
+              },
+            })}
           >
             {wd.label}
           </span>
@@ -161,6 +190,7 @@ export function MonthList<T = unknown>({
             events={events}
             eventsByDay={eventsByDay}
             renderEvent={renderEvent}
+            eventAccessibilityLabel={eventAccessibilityLabel}
             maxVisibleEventCount={maxVisibleEventCount}
             moreLabel={moreLabel}
             onPressEvent={onPressEvent}
@@ -177,6 +207,8 @@ export function MonthList<T = unknown>({
             isDateDisabled={isDateDisabled}
             keyboardDayNavigation={keyboardDayNavigation}
             onPressDay={onPressDay}
+            classNames={classNames}
+            styles={styles}
           />
         )}
       />