@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Calendar/Calendar.tokens.scss

@@ -0,0 +1,262 @@
+// Calendar.tokens.scss — Component-scoped tokens for <Calendar> and all of its sibling views (Month/Week/Day/Agenda + DayCell/EventChip/TimedEvent/HourGrid/AllDayBand/ViewSwitcher). Defaults preserve byte-identical output. Cross-component composition with DatePicker is intentional — each component owns its tokens.
+:root {
+  // ── Root + header ────────────────────────────────────────────────────────
+  --calendar-gap: var(--space-3);
+  --calendar-header-gap: var(--space-3);
+  --calendar-title-font-size: var(--font-size-lg);
+  --calendar-title-font-weight: var(--font-weight-semibold);
+  --calendar-title-fg: var(--color-fg);
+
+  // ── Shared surface (borders + radius + view background) ──────────────────
+  --calendar-border-color: var(--color-border);
+  --calendar-radius: var(--radius-md);
+  --calendar-bg: var(--color-bg);
+  --calendar-bg-subtle: var(--color-bg-subtle);
+  --calendar-bg-muted: var(--color-bg-muted);
+  --calendar-accent: var(--color-accent);
+  --calendar-accent-bg-subtle: var(--color-accent-bg-subtle);
+  --calendar-fg: var(--color-fg);
+  --calendar-fg-muted: var(--color-fg-muted);
+
+  // ── Weekday header (Month) ───────────────────────────────────────────────
+  --calendar-weekday-padding: var(--space-2);
+  --calendar-weekday-font-size: var(--font-size-xs);
+  --calendar-weekday-font-weight: var(--font-weight-medium);
+  --calendar-weekday-fg: var(--color-fg-muted);
+  --calendar-weekday-letter-spacing: var(--letter-spacing-caps);
+
+  // ── Month grid day cell ──────────────────────────────────────────────────
+  --calendar-day-cell-min-height: var(--size-calendar-day-cell-min-height);
+  --calendar-day-cell-today-ring-width: var(--border-width-emphasis);
+
+  // ── DayCell (number) ─────────────────────────────────────────────────────
+  --calendar-day-cell-padding: var(--space-2);
+  --calendar-day-cell-opacity-other-month: var(--opacity-disabled);
+  --calendar-day-cell-number-font-size: var(--font-size-sm);
+  --calendar-day-cell-number-font-weight: var(--font-weight-medium);
+  --calendar-day-cell-number-fg: var(--color-fg);
+  --calendar-day-cell-today-fg: var(--color-accent);
+  --calendar-day-cell-today-font-weight: var(--font-weight-bold);
+
+  // ── Month bar slot + "more" chip ─────────────────────────────────────────
+  --calendar-bar-slot-padding: var(--space-1);
+  --calendar-more-chip-wrapper-padding: var(--space-1) var(--space-2);
+  --calendar-more-chip-padding: var(--space-1) var(--space-2);
+  --calendar-more-chip-radius: var(--radius-sm);
+  --calendar-more-chip-font-size: var(--font-size-xs);
+  --calendar-more-chip-fg: var(--color-fg-muted);
+  --calendar-more-chip-bg-hover: var(--color-bg-subtle);
+  --calendar-more-chip-fg-hover: var(--color-fg);
+
+  // ── EventChip ────────────────────────────────────────────────────────────
+  --calendar-event-chip-gap: var(--space-1);
+  --calendar-event-chip-padding-x: var(--space-2);
+  --calendar-event-chip-height: var(--space-5);
+  --calendar-event-chip-radius: var(--radius-sm);
+  --calendar-event-chip-font-size: var(--font-size-xs);
+  --calendar-event-chip-font-weight: var(--font-weight-medium);
+  --calendar-event-chip-transition-filter: var(--transition-fast);
+  --calendar-event-chip-transition-bg: var(--transition-fast);
+  --calendar-event-chip-time-opacity: var(--opacity-muted);
+
+  // EventChip — tone fills (non-allDay)
+  --calendar-event-chip-bg-neutral: var(--color-bg-subtle);
+  --calendar-event-chip-fg-neutral: var(--color-fg);
+  --calendar-event-chip-border-color-neutral: var(--color-border-strong);
+  --calendar-event-chip-bg-accent: var(--color-accent-bg-subtle);
+  --calendar-event-chip-fg-accent: var(--color-accent);
+  --calendar-event-chip-bg-success: var(--color-success-bg-subtle);
+  --calendar-event-chip-fg-success: var(--color-success);
+  --calendar-event-chip-bg-warning: var(--color-warning-bg-subtle);
+
+  // warning uses --color-warning-strong, not --color-warning, which measures
+  // @contrast --color-warning on --color-bg = 2.14:1 light
+  // @contrast --color-warning-strong on --color-bg = 5.95:1 light
+  // @contrast --color-warning-fg on --color-warning-strong = 10.57:1 dark
+  // @contrast --color-warning on --color-warning-bg-subtle = 2.01:1 light
+  // @contrast --color-warning-strong on --color-warning-bg-subtle = 5.61:1 light
+  // @contrast --color-warning-fg on --color-warning = 6.60:1 light
+  // @contrast --color-warning-fg on --color-warning-strong = 2.37:1 light
+  // 2.01:1 on the light tint (and 2.14:1 as a dot on --color-bg), below WCAG AA
+  // for text and below 1.4.11's 3:1 for a graphical object. The strong variant
+  // clears both. Dark is unaffected — the two resolve to the same value there.
+  --calendar-event-chip-fg-warning: var(--color-warning-strong);
+  --calendar-event-chip-bg-danger: var(--color-danger-bg-subtle);
+  --calendar-event-chip-fg-danger: var(--color-danger);
+
+  // EventChip — allDay tone fills
+  --calendar-event-chip-all-day-bg-neutral: var(--color-fg);
+  --calendar-event-chip-all-day-fg-neutral: var(--color-bg);
+  --calendar-event-chip-all-day-bg-accent: var(--color-accent);
+  --calendar-event-chip-all-day-fg-accent: var(--color-accent-fg);
+  --calendar-event-chip-all-day-bg-success: var(--color-success);
+  --calendar-event-chip-all-day-fg-success: var(--color-success-fg);
+
+  // Keeps the AMBER fill. The failing pair here was white-on-amber (2.14:1), and
+  // the fix belongs on the text: --color-warning-fg is now a dark ink, giving
+  // 6.60:1. Darkening the FILL also passed (5.95:1) but read as chocolate brown
+  // — on a solid chip the hue IS the caution signal, so this keeps it. warning
+  // is the only tone whose all-day pair failed; accent/success/danger are all
+  // dark enough for white text at 5.11-6.82:1 in LIGHT. (Dark pairs these fills
+  // with a dark fg instead, at 5.83-8.16:1 — the figures above are light-theme
+  // only, which the rest of this block assumes but never said.) (Was 4.55-6.82 until #484 raised
+  // danger and success; nothing measures 4.55 any more.)
+  --calendar-event-chip-all-day-bg-warning: var(--color-warning);
+
+  // --color-warning-fg is calibrated against --color-warning (6.60:1) and ONLY
+  // that: on --color-warning-strong it measures 2.37:1 in light. (Dark is
+  // unaffected — the two warning tokens resolve to the same value there, and
+  // the pair measures 10.57:1.) Pairing the two
+  // 'warning' tokens looks right and is not — keep this fg with the amber fill
+  // above.
+  --calendar-event-chip-all-day-fg-warning: var(--color-warning-fg);
+  --calendar-event-chip-all-day-bg-danger: var(--color-danger);
+  --calendar-event-chip-all-day-fg-danger: var(--color-danger-fg);
+
+  // ── Per-event palette color (CalendarEvent.color) ────────────────────────
+  // The palette bg/fg pair and the resolved tone colour are injected INLINE by
+  // resolveEventColor(), the same shape EntityChip/IconTile/PillMenu use —
+  // there is deliberately no token per palette colour here. This is the only
+  // declared token for the feature: the geometry. The three colour properties
+  // (`-color-bg`, `-color-fg`, `-stripe-color`) have no declared default, so a
+  // `.colored`/`.striped` class applied without its inline style paints
+  // nothing rather than something wrong.
+  --calendar-event-color-stripe-width: var(--border-width-strong);
+
+  // One stripe scale for all three surfaces: the chip, the timed block and the
+  // agenda row already resolved the four non-neutral tones to identical values,
+  // so a per-surface prefix bought nothing and split the one place this needs
+  // to be correct. `neutral` is absent on purpose — it is the default state and
+  // never draws a stripe.
+  // warning does NOT use --color-warning. The bare amber measures
+  // 1.52–2.01:1 against all 30 palette backgrounds in light theme — below the
+  // 3:1 WCAG 1.4.11 bar for a graphical object, and unreadable as a 3px band on
+  // a tint. --color-warning-strong clears 3:1 against all 30 (min 4.25 — no `:1`, because a minimum over 30
+  // backgrounds is not a pair any single @contrast annotation can compute).
+  --calendar-event-stripe-accent: var(--color-accent);
+  --calendar-event-stripe-success: var(--color-success);
+  --calendar-event-stripe-warning: var(--color-warning-strong);
+  --calendar-event-stripe-danger: var(--color-danger);
+
+  // EventChip — tooltip
+  --calendar-event-tooltip-gap: var(--space-1);
+  --calendar-event-tooltip-time-font-size: var(--font-size-xs);
+  --calendar-event-tooltip-time-font-weight: var(--font-weight-regular);
+  --calendar-event-tooltip-time-fg: var(--color-bg-subtle);
+  --calendar-event-tooltip-title-font-size: var(--font-size-sm);
+  --calendar-event-tooltip-title-font-weight: var(--font-weight-medium);
+  --calendar-event-tooltip-title-fg: var(--color-bg);
+
+  // ── TimedEvent (HourGrid block) ──────────────────────────────────────────
+  --calendar-timed-event-gap: var(--space-1);
+  --calendar-timed-event-padding: var(--space-1) var(--space-2);
+  --calendar-timed-event-radius: var(--radius-sm);
+  --calendar-timed-event-font-size: var(--font-size-xs);
+  --calendar-timed-event-font-weight: var(--font-weight-medium);
+  --calendar-timed-event-transition-position: var(--transition-base);
+  --calendar-timed-event-transition-filter: var(--transition-fast);
+  --calendar-timed-event-transition-bg: var(--transition-fast);
+  --calendar-timed-event-time-font-size: var(--font-size-xs);
+  --calendar-timed-event-time-font-weight: var(--font-weight-regular);
+  --calendar-timed-event-time-opacity: var(--opacity-muted);
+
+  // TimedEvent — tone fills
+  --calendar-timed-event-bg-neutral: var(--color-bg-subtle);
+  --calendar-timed-event-fg-neutral: var(--color-fg);
+  --calendar-timed-event-border-color-neutral: var(--color-border-strong);
+  --calendar-timed-event-bg-accent: var(--color-accent-bg-subtle);
+  --calendar-timed-event-fg-accent: var(--color-accent);
+  --calendar-timed-event-bg-success: var(--color-success-bg-subtle);
+  --calendar-timed-event-fg-success: var(--color-success);
+  --calendar-timed-event-bg-warning: var(--color-warning-bg-subtle);
+
+  // See the chip note above — same pair, same failure.
+  --calendar-timed-event-fg-warning: var(--color-warning-strong);
+  --calendar-timed-event-bg-danger: var(--color-danger-bg-subtle);
+  --calendar-timed-event-fg-danger: var(--color-danger);
+
+  // ── HourGrid (Week/Day chrome) ───────────────────────────────────────────
+  --calendar-hour-grid-bg: var(--color-bg);
+  --calendar-hour-corner-bg: var(--color-bg-subtle);
+  --calendar-hour-column-header-padding: var(--space-2);
+  --calendar-hour-column-header-bg: var(--color-bg-subtle);
+  --calendar-hour-column-header-font-size: var(--font-size-xs);
+  --calendar-hour-column-header-font-weight: var(--font-weight-medium);
+  --calendar-hour-column-header-fg: var(--color-fg);
+  --calendar-hour-column-header-bg-weekend: var(--color-bg-muted);
+  --calendar-hour-column-header-bg-today: var(--color-accent-bg-subtle);
+  --calendar-hour-column-header-fg-today: var(--color-accent);
+  --calendar-hour-label-padding: var(--space-1) var(--space-2);
+  --calendar-hour-label-font-size: var(--font-size-xs);
+  --calendar-hour-label-fg: var(--color-fg-muted);
+  --calendar-hour-label-bg: var(--color-bg-subtle);
+  --calendar-hour-day-column-bg-weekend: var(--color-bg-muted);
+  --calendar-hour-separator-bg: var(--color-border);
+
+  // Availability underlay (HourGrid background bands). `unavailable` shades
+  // closed/blocked time; `available` lightly tints bookable time so a free
+  // slot reads differently from a closed one.
+  --calendar-background-band-bg-unavailable: var(--color-bg-muted);
+  --calendar-background-band-bg-available: var(--color-success-bg-subtle);
+  --calendar-background-band-opacity: var(--opacity-muted);
+
+  // Drag-to-reschedule
+  --calendar-drag-block-opacity: var(--opacity-muted);
+  --calendar-drag-block-shadow: var(--shadow-lg);
+  --calendar-drag-invalid-outline: var(--color-danger);
+  --calendar-drag-invalid-outline-width: var(--border-width-emphasis);
+  --calendar-resize-handle-height: var(--space-2);
+  --calendar-resize-handle-bg-hover: var(--color-border-strong);
+  --calendar-now-line-height: var(--border-width-emphasis);
+  --calendar-now-line-bg: var(--color-danger);
+
+  // ── AllDayBand ───────────────────────────────────────────────────────────
+  --calendar-all-day-band-gap: var(--space-1);
+  --calendar-all-day-band-padding-y: var(--space-1);
+  --calendar-all-day-band-bg: var(--color-bg);
+  --calendar-all-day-band-bar-slot-padding-x: var(--space-1);
+
+  // ── AgendaView ───────────────────────────────────────────────────────────
+  --calendar-agenda-padding-y: var(--space-3);
+  --calendar-agenda-empty-padding: var(--space-6);
+  --calendar-agenda-empty-font-size: var(--font-size-sm);
+  --calendar-agenda-empty-fg: var(--color-fg-muted);
+  --calendar-agenda-day-group-gap: var(--space-2);
+  --calendar-agenda-day-group-padding-bottom: var(--space-2);
+  --calendar-agenda-day-header-padding: var(--space-2) var(--space-3);
+  --calendar-agenda-day-header-bg: var(--color-bg-subtle);
+  --calendar-agenda-day-header-font-size: var(--font-size-md);
+  --calendar-agenda-day-header-font-weight: var(--font-weight-medium);
+  --calendar-agenda-day-header-fg: var(--color-fg);
+  --calendar-agenda-day-header-bg-today: var(--color-accent-bg-subtle);
+  --calendar-agenda-day-header-border-today: var(--color-accent);
+  --calendar-agenda-day-header-fg-today: var(--color-accent);
+  --calendar-agenda-rows-gap: var(--space-1);
+  --calendar-agenda-rows-padding-left: var(--space-3);
+  --calendar-agenda-row-gutter-width: var(--size-calendar-agenda-gutter);
+  --calendar-agenda-row-gap: var(--space-2);
+  --calendar-agenda-row-padding: var(--space-2) var(--space-3);
+  --calendar-agenda-row-radius: var(--radius-sm);
+  --calendar-agenda-row-font-size: var(--font-size-sm);
+  --calendar-agenda-row-fg: var(--color-fg);
+  --calendar-agenda-row-bg-hover: var(--color-bg-subtle);
+  --calendar-agenda-row-transition-bg: var(--transition-fast);
+  --calendar-agenda-time-font-size: var(--font-size-sm);
+  --calendar-agenda-time-fg: var(--color-fg-muted);
+  --calendar-agenda-all-day-font-weight: var(--font-weight-medium);
+  --calendar-agenda-all-day-fg: var(--color-fg);
+  --calendar-agenda-tone-dot-size: var(--space-2);
+  --calendar-agenda-tone-dot-radius: var(--radius-full);
+  --calendar-agenda-body-gap: var(--space-2);
+  --calendar-agenda-title-font-weight: var(--font-weight-medium);
+  --calendar-agenda-title-fg: var(--color-fg);
+  --calendar-agenda-tone-neutral: var(--color-border-strong);
+  --calendar-agenda-tone-accent: var(--color-accent);
+  --calendar-agenda-tone-success: var(--color-success);
+
+  // The agenda tone dot is a graphical object on --color-bg: 2.14:1 -> 5.95:1
+  // in light. (Dark is unaffected — the two warning tokens are the same value
+  // there.)
+  --calendar-agenda-tone-warning: var(--color-warning-strong);
+  --calendar-agenda-tone-danger: var(--color-danger);
+}

package/src/components/Calendar/Calendar.tsx

@@ -0,0 +1,370 @@
+import { forwardRef, useCallback, useState, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import { Button } from '../Button';
+import { Cluster } from '../Cluster';
+import { addDays, addMonths, addWeeks, startOfWeek } from '../../calendar/dateMath';
+import { useMonth } from '../../calendar/useMonth';
+import { useWeek } from '../../calendar/useWeek';
+import { useDay } from '../../calendar/useDay';
+import { useAgenda } from '../../calendar/useAgenda';
+import { useLocale } from '../../i18n/useLocale';
+import { LocaleProvider } from '../../i18n/LocaleProvider';
+import { useTranslation } from '../../i18n/useTranslation';
+import { getFirstDayOfWeek } from '../../calendar/weekInfo';
+import { MonthView } from './MonthView';
+import { WeekView } from './WeekView';
+import { DayView } from './DayView';
+import { AgendaView } from './AgendaView';
+import { ViewSwitcher } from './ViewSwitcher';
+import type {
+  CalendarBackgroundInterval,
+  CalendarDropCandidate,
+  CalendarDropResult,
+  CalendarEvent,
+  CalendarEventMove,
+  CalendarEventResize,
+  CalendarResource,
+  CalendarView,
+  RenderEvent,
+} from './types';
+import styles from './Calendar.module.scss';
+
+export interface CalendarProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'defaultValue'
+> {
+  /** Events to display. */
+  events?: readonly CalendarEvent[];
+  /** Active view (controlled). Pair with `onViewChange`. */
+  view?: CalendarView;
+  /** Initial view (uncontrolled). Defaults to `'month'`. */
+  defaultView?: CalendarView;
+  /** Fires when the user clicks the view switcher. */
+  onViewChange?: (view: CalendarView) => void;
+  /** Navigation cursor (controlled). */
+  value?: Date;
+  /** Initial cursor (uncontrolled). Defaults to `new Date()`. */
+  defaultValue?: Date;
+  /** Fires on prev/next/today/keyboard navigation. */
+  onChange?: (date: Date) => void;
+  /**
+   * Fires when the user clicks a day cell's empty space.
+   * - Month view: empty space in a day cell, the "+N more" overflow chip, or
+   *   keyboard activation (Enter/Space) on a focused cell.
+   * - Week/Day view: empty hour-grid space inside that day's column —
+   *   **mouse click only**. There is no keyboard equivalent in v3; consumers
+   *   needing keyboard activation in week/day should surface their detail UI
+   *   through the focusable event chips (which fire `onEventClick`).
+   */
+  onDayClick?: (date: Date) => void;
+  /** Fires when the user clicks an event chip. */
+  onEventClick?: (event: CalendarEvent) => void;
+  /** Override locale. Defaults to `useLocale()`. */
+  locale?: string;
+  /** Override locale-derived first day of week. */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /** Lane cap per week (month view). Default 3. Events beyond it collapse into a "+N more" chip; clicking it fires `onDayClick(date)`. */
+  maxLanesPerWeek?: number;
+  /**
+   * Hour range shown in week/day views (inclusive start, exclusive end).
+   * Defaults to `[7, 19]` (7am–7pm). Hours outside this range are NOT
+   * rendered (no row in the grid).
+   */
+  hourRange?: [number, number];
+  /** Pixel height per hour row in week/day views. Default 48. */
+  hourRowHeight?: number;
+  /**
+   * Split `view="day"` into one column per bookable subject — practitioner,
+   * chair, room, bay — all sharing a single time axis and a single scroll
+   * container. This is the "resource day view" of scheduling products.
+   *
+   * Events are routed by `CalendarEvent.resourceId`. A timed event whose
+   * `resourceId` matches nothing (or is absent) lands in a trailing
+   * "unassigned" column, which is only rendered when such an event exists.
+   * All-day events without a `resourceId` are day-wide and span every column.
+   *
+   * Ignored by month, week and agenda views — those have their own column
+   * meaning.
+   *
+   * Don't approximate it with N side-by-side `<Calendar view="day">` in a
+   * `Split`: each brings its own header, gutter and scroll, so they drift.
+   */
+  resources?: readonly CalendarResource[];
+  /**
+   * Availability underlay for week/day views: non-interactive bands painted
+   * behind the events, distinguishing "closed" from "open and free". "Open
+   * and busy" already reads from the event blocks themselves.
+   *
+   * An interval list rather than a weekly-hours object, because working
+   * hours vary by day (a lunch break), by date (a holiday, a short day) and
+   * by column (per-practitioner shifts). Bands take no part in the event
+   * collision cascade and never intercept clicks — `onDayClick` still fires
+   * through them.
+   *
+   * Every interval is clipped to each column's own date, so a week view needs
+   * one interval per day rather than one that all seven columns share.
+   */
+  backgroundIntervals?: readonly CalendarBackgroundInterval[];
+  /**
+   * Enables drag-to-reschedule in week/day views. Called on drop with the
+   * proposed placement; the event's duration is preserved.
+   *
+   * **Nothing moves until you commit it.** `events` stays the source of
+   * truth — apply the change to your own state to make it stick. To refuse a
+   * drop (the server rejects overlaps, out-of-hours bookings, …) return
+   * `false`, or a promise that resolves `false` or rejects: the block snaps
+   * back and the preview is discarded. Prefer `canDropEvent` for rules you
+   * can evaluate synchronously — it refuses the drop *during* the drag, so
+   * the user sees it before releasing.
+   *
+   * Omit to keep today's read-only behaviour.
+   */
+  onEventMove?: (event: CalendarEvent, next: CalendarEventMove) => CalendarDropResult;
+  /**
+   * Enables drag-to-resize in week/day views (a handle on the block's bottom
+   * edge). `startsAt` is unchanged; only `endsAt` moves. Same commit and
+   * rejection semantics as `onEventMove`.
+   */
+  onEventResize?: (event: CalendarEvent, next: CalendarEventResize) => CalendarDropResult;
+  /**
+   * Synchronous veto, evaluated continuously while dragging. Return `false`
+   * and the placement renders as a refused drop and is never proposed to
+   * `onEventMove` / `onEventResize`. Use for rules you can check locally
+   * (opening hours, overlaps within the loaded event set); use the handler's
+   * own return value for rules only the server can settle.
+   *
+   * `next.mode` says which gesture is being judged, and narrows the payload:
+   * `'move'` carries the target `resourceId`, `'resize'` cannot change the
+   * column so it doesn't. Rules like "shortening is always fine, relocating
+   * needs approval" are otherwise inexpressible — the predicate fires while
+   * the pointer is still at the origin, where both gestures report the
+   * event's own start.
+   *
+   * Note that `backgroundIntervals` does NOT gate drops. Shading a slot
+   * closed is presentation; enforcing it is this predicate's job. Derive both
+   * from one source so they cannot drift.
+   */
+  canDropEvent?: (event: CalendarEvent, next: CalendarDropCandidate) => boolean;
+  /**
+   * Snap granularity for drags, in minutes. Default 15 — a drag lands on a
+   * quarter-hour boundary rather than an arbitrary pixel offset. Also the
+   * step size for the keyboard equivalent (Alt + arrow keys).
+   *
+   * Values below 1 (including 0 and negatives) are treated as 1 minute.
+   */
+  dragSnapMinutes?: number;
+  /**
+   * Optional custom renderer for the inner content of every event chip
+   * across views (month chips, week/day timed blocks, all-day band chips).
+   * The returned ReactNode replaces the default `<time> · <title>` markup
+   * inside the chip's button wrapper — the wrapper still handles tone
+   * background, click, tooltip, and (for timed blocks) absolute positioning.
+   *
+   * To override colors, return content with inline styling that fills the
+   * wrapper (e.g., `position: absolute; inset: 0; background: <color>`).
+   *
+   * The `ctx` argument carries view-aware metadata: `view`, `asAllDay`,
+   * `continuesLeft`/`continuesRight` (multi-day), `timeLabel`, `duration`.
+   */
+  renderEvent?: RenderEvent;
+}
+
+/**
+ * Month / week / day / agenda calendar.
+ * @see docs/components/Calendar.md
+ */
+export const Calendar = forwardRef<HTMLDivElement, CalendarProps>(function Calendar(
+  {
+    events = [],
+    view: viewProp,
+    defaultView,
+    onViewChange,
+    value,
+    defaultValue,
+    onChange,
+    onDayClick,
+    onEventClick,
+    locale,
+    weekStartsOn,
+    maxLanesPerWeek = 3,
+    hourRange = [7, 19],
+    hourRowHeight = 48,
+    resources,
+    backgroundIntervals,
+    onEventMove,
+    onEventResize,
+    canDropEvent,
+    dragSnapMinutes = 15,
+    renderEvent,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const [uncontrolled, setUncontrolled] = useState<Date>(() => defaultValue ?? new Date());
+  const cursor = value ?? uncontrolled;
+  const [uncontrolledView, setUncontrolledView] = useState<CalendarView>(
+    () => defaultView ?? 'month',
+  );
+  const view = viewProp ?? uncontrolledView;
+
+  const handleChange = useCallback(
+    (next: Date) => {
+      if (value === undefined) setUncontrolled(next);
+      onChange?.(next);
+    },
+    [value, onChange],
+  );
+
+  const handleViewChange = useCallback(
+    (next: CalendarView) => {
+      if (viewProp === undefined) setUncontrolledView(next);
+      onViewChange?.(next);
+    },
+    [viewProp, onViewChange],
+  );
+
+  const contextLocale = useLocale();
+  const resolvedWeekStartsOn = weekStartsOn ?? getFirstDayOfWeek(locale ?? contextLocale);
+
+  const grid = useMonth(cursor, { locale, weekStartsOn });
+  const week = useWeek(cursor, { locale, weekStartsOn });
+  const day = useDay(cursor, { locale });
+  // Agenda window mirrors the cursor's current week (Sun-Sat or Mon-Sun
+  // depending on locale). Prev/Next on agenda steps a week, same as week view.
+  const agendaFrom = startOfWeek(cursor, resolvedWeekStartsOn);
+  const agendaTo = addDays(agendaFrom, 6);
+  const agenda = useAgenda(agendaFrom, agendaTo, { locale, weekStartsOn });
+
+  // Prev/Next step matches the active view: a month in month view, a week in
+  // week or agenda view, a day in day view. Without this, multi-day events
+  // that span several weeks aren't reachable in week/day view — each click
+  // would skip over them.
+  const stepBy =
+    view === 'month'
+      ? (d: Date, n: number) => addMonths(d, n)
+      : view === 'day'
+        ? (d: Date, n: number) => addDays(d, n)
+        : (d: Date, n: number) => addWeeks(d, n);
+  const goPrev = () => handleChange(stepBy(cursor, -1));
+  const goNext = () => handleChange(stepBy(cursor, 1));
+  const goToday = () => handleChange(new Date());
+
+  // View-aware title + prev/next aria-labels. Each view's label/range
+  // formatter is locale-aware (Intl-driven inside the hooks).
+  const titleLabel =
+    view === 'month'
+      ? grid.monthLabel
+      : view === 'week'
+        ? week.weekLabel
+        : view === 'day'
+          ? day.dayLabel
+          : agenda.rangeLabel;
+  const prevLabel =
+    view === 'month'
+      ? t('calendar.previousMonth')
+      : view === 'week'
+        ? t('calendar.previousWeek')
+        : view === 'day'
+          ? t('calendar.previousDay')
+          : t('calendar.previousAgenda');
+  const nextLabel =
+    view === 'month'
+      ? t('calendar.nextMonth')
+      : view === 'week'
+        ? t('calendar.nextWeek')
+        : view === 'day'
+          ? t('calendar.nextDay')
+          : t('calendar.nextAgenda');
+
+  const body: ReactNode = (
+    <div ref={ref} className={clsx(styles.calendar, className)} {...rest}>
+      <header className={styles.header}>
+        <h2 className={styles.title}>{titleLabel}</h2>
+        <Cluster gap="sm" align="center">
+          <Cluster gap="xs" align="center">
+            <Button size="xs" variant="ghost" iconOnly aria-label={prevLabel} onClick={goPrev}>
+              <ChevronLeft size={14} />
+            </Button>
+            <Button size="sm" variant="secondary" onClick={goToday}>
+              {t('calendar.today')}
+            </Button>
+            <Button size="xs" variant="ghost" iconOnly aria-label={nextLabel} onClick={goNext}>
+              <ChevronRight size={14} />
+            </Button>
+          </Cluster>
+          <ViewSwitcher
+            view={view}
+            onViewChange={handleViewChange}
+            monthLabel={t('calendar.viewMonth')}
+            weekLabel={t('calendar.viewWeek')}
+            dayLabel={t('calendar.viewDay')}
+            agendaLabel={t('calendar.viewAgenda')}
+          />
+        </Cluster>
+      </header>
+      {view === 'month' && (
+        <MonthView
+          grid={grid}
+          events={events}
+          maxLanesPerWeek={maxLanesPerWeek}
+          cursor={cursor}
+          onChange={handleChange}
+          onDayClick={onDayClick}
+          onEventClick={onEventClick}
+          renderEvent={renderEvent}
+        />
+      )}
+      {view === 'week' && (
+        <WeekView
+          cursor={cursor}
+          events={events}
+          hourRange={hourRange}
+          hourRowHeight={hourRowHeight}
+          locale={locale}
+          weekStartsOn={weekStartsOn}
+          backgroundIntervals={backgroundIntervals}
+          onEventClick={onEventClick}
+          onDayClick={onDayClick}
+          onEventMove={onEventMove}
+          onEventResize={onEventResize}
+          canDropEvent={canDropEvent}
+          dragSnapMinutes={dragSnapMinutes}
+          renderEvent={renderEvent}
+        />
+      )}
+      {view === 'day' && (
+        <DayView
+          cursor={cursor}
+          events={events}
+          hourRange={hourRange}
+          hourRowHeight={hourRowHeight}
+          locale={locale}
+          resources={resources}
+          backgroundIntervals={backgroundIntervals}
+          onEventClick={onEventClick}
+          onDayClick={onDayClick}
+          onEventMove={onEventMove}
+          onEventResize={onEventResize}
+          canDropEvent={canDropEvent}
+          dragSnapMinutes={dragSnapMinutes}
+          renderEvent={renderEvent}
+        />
+      )}
+      {view === 'agenda' && (
+        <AgendaView
+          days={agenda.days}
+          rangeLabel={agenda.rangeLabel}
+          events={events}
+          locale={locale}
+          onEventClick={onEventClick}
+          renderEvent={renderEvent}
+        />
+      )}
+    </div>
+  );
+
+  return locale !== undefined ? <LocaleProvider locale={locale}>{body}</LocaleProvider> : body;
+});

package/src/components/Calendar/DayCell.module.scss

@@ -0,0 +1,30 @@
+@use '../../styles/mixins' as *;
+@use './Calendar.tokens';
+
+.cell {
+  padding: var(--calendar-day-cell-padding);
+  cursor: pointer;
+  outline: none;
+
+  // INSET: the month grid clips, and the first column's cell is flush with its left
+  // edge, so an outset ring loses that band (#505).
+  &:focus-visible {
+    @include focus-ring($offset: calc(-1 * var(--ring-offset)));
+  }
+}
+
+.otherMonth .dayNumber {
+  opacity: var(--calendar-day-cell-opacity-other-month);
+}
+
+.dayNumber {
+  font-size: var(--calendar-day-cell-number-font-size);
+  font-weight: var(--calendar-day-cell-number-font-weight);
+  color: var(--calendar-day-cell-number-fg);
+  line-height: 1;
+}
+
+.todayNumber {
+  color: var(--calendar-day-cell-today-fg);
+  font-weight: var(--calendar-day-cell-today-font-weight);
+}