@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Calendar/TimedEvent.tsx

@@ -0,0 +1,247 @@
+import { type CSSProperties, type KeyboardEvent, type MouseEvent, type PointerEvent } from 'react';
+import clsx from 'clsx';
+import { useLocale } from '../../i18n/useLocale';
+import { formatTime } from '../../calendar';
+import { Tooltip } from '../Tooltip';
+import { resolveEventColor } from './eventColor';
+import { formatEventDuration } from './utils';
+import type { DragMode, DragPreview } from './useEventDrag';
+import type { CalendarEvent, CalendarView, RenderEvent, TimedEventBlock } from './types';
+import styles from './TimedEvent.module.scss';
+
+export interface TimedEventProps {
+  /** Placed block produced by `layoutEventsForHourGrid`. */
+  block: TimedEventBlock;
+  /** Pixel height per hour row (matches the hour-grid scaffold). */
+  hourRowHeight: number;
+  /** Which view is rendering this chip (`'week'` or `'day'`). Passed to `renderEvent` for branching. */
+  view?: CalendarView;
+  /** Optional custom inner content. When set, replaces the default time + title spans. */
+  renderEvent?: RenderEvent;
+  /** Fires when the chip is clicked; receives the `CalendarEvent` and the raw click. */
+  onClick?: (event: CalendarEvent, e: MouseEvent<HTMLButtonElement>) => void;
+  /** The live drag placement for THIS block, when it is the one being dragged. */
+  preview?: DragPreview | null;
+  /** Whether the grid accepts move gestures (`onEventMove` is wired). */
+  canMove?: boolean;
+  /** Whether the grid accepts resize gestures (`onEventResize` is wired). */
+  canResize?: boolean;
+  /** Starts a pointer drag. Called from `pointerdown` on the block or its resize handle. */
+  onDragStart?: (block: TimedEventBlock, mode: DragMode, e: PointerEvent) => void;
+  /** Keyboard equivalent of a drag — whole snap steps, and whole columns for a move. */
+  onNudge?: (
+    block: TimedEventBlock,
+    delta: { mode: DragMode; steps: number; columns?: number },
+  ) => void;
+  /** `id` of the visually-hidden element describing the keyboard drag shortcuts. */
+  dragHintId?: string;
+}
+
+/**
+ * Internal: a single timed-event block, absolutely positioned inside an
+ * hour-grid day column. Tone-styled, wrapped in a Tooltip so the full
+ * "time range + title" is reachable even when the chip is short.
+ *
+ * @remarks
+ * **When NOT to use:** Do not render `TimedEvent` directly in application code —
+ * it is an internal building block consumed by `HourGrid`. Use `Calendar` (or
+ * `WeekView`/`DayView`) from the design system and pass events via the `events` prop.
+ */
+const MIN_BLOCK_HEIGHT_PX = 20;
+/** Percent of the day column each cascade lane is offset to the right. */
+const LANE_OFFSET_PERCENT = 10;
+/** Z-index used for the hovered / focused block — sits above any lane. */
+const HOVER_Z_INDEX = 100;
+
+export function TimedEvent({
+  block,
+  hourRowHeight,
+  view = 'week',
+  renderEvent,
+  onClick,
+  preview = null,
+  canMove = false,
+  canResize = false,
+  onDragStart,
+  onNudge,
+  dragHintId,
+}: TimedEventProps) {
+  const locale = useLocale();
+  const { toneClass, hasStripe, style: colorStyle } = resolveEventColor(block.event);
+  const isDragging = preview !== null;
+
+  // While a drag is in flight the block renders at the proposed placement,
+  // not at the one its `events` entry describes — that only changes if and
+  // when the consumer commits the drop.
+  const startMinutes = preview ? preview.startMinutes : block.startMinutes;
+  const endMinutes = preview ? preview.endMinutes : block.endMinutes;
+
+  const top = (startMinutes / 60) * hourRowHeight;
+  const rawHeight = ((endMinutes - startMinutes) / 60) * hourRowHeight;
+  const height = Math.max(rawHeight, MIN_BLOCK_HEIGHT_PX);
+  // Google-Calendar-style cascade: each lane shifts right by a small,
+  // constant step but every block still extends to the column's right edge.
+  // Higher lanes overlay earlier ones via z-index, so later events
+  // partially cover the one beneath them while keeping the predecessor's
+  // left edge visible. On hover, the block lifts to full width and on top
+  // — see `:hover` rules in TimedEvent.module.scss.
+  //
+  // A dragging block leaves the cascade entirely: full width, top of the
+  // stack, so it reads as lifted off the grid.
+  const leftPercent = isDragging ? 0 : LANE_OFFSET_PERCENT * block.lane;
+  const zIndex = isDragging ? HOVER_Z_INDEX : block.lane + 1;
+
+  // While dragging, the time label must describe the PROPOSED placement, not
+  // the one the event still has. For a snap-to-15 gesture the label is the
+  // feedback — a block that visibly slides to 11:00 while still reading
+  // "9:00 – 10:00" is telling the user the wrong thing at the moment they
+  // decide whether to release.
+  const displayStart = preview ? preview.startsAt : block.event.startsAt;
+  const displayEnd = preview ? preview.endsAt : block.event.endsAt;
+
+  const startLabel = formatTime(displayStart, locale);
+  const endLabel = displayEnd ? formatTime(displayEnd, locale) : null;
+
+  // For zero-duration events the start and end times are the same (or there's
+  // no endsAt) — collapse to a single time label rather than "9:30 AM – 9:30 AM".
+  const isZeroDuration = !endLabel || endLabel === startLabel;
+  const timeLabel = isZeroDuration ? startLabel : `${startLabel} – ${endLabel}`;
+
+  const duration = formatEventDuration(displayStart, displayEnd);
+  const tooltipContent = (
+    <span className={styles.tooltipBody}>
+      <span className={styles.tooltipTime}>
+        {timeLabel} · {duration}
+      </span>
+      <span className={styles.tooltipTitle}>{block.event.title}</span>
+    </span>
+  );
+
+  const handleClick = (e: MouseEvent<HTMLButtonElement>) => {
+    e.stopPropagation();
+    onClick?.(block.event, e);
+  };
+
+  const handlePointerDown = (e: PointerEvent<HTMLButtonElement>) => {
+    if (!canMove) return;
+    onDragStart?.(block, 'move', e);
+  };
+
+  const handleHandlePointerDown = (e: PointerEvent<HTMLSpanElement>) => {
+    if (!canResize) return;
+    onDragStart?.(block, 'resize', e);
+  };
+
+  // Keyboard equivalent of the pointer gesture, so rescheduling isn't
+  // mouse-only. Alt is the modifier throughout: bare arrows stay free for
+  // the browser's own scrolling, and Alt+Arrow is not claimed by the grid.
+  const handleKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+    if (!e.altKey || !onNudge) return;
+    if (e.ctrlKey || e.metaKey) return;
+    const resize = e.shiftKey;
+    if (resize && !canResize) return;
+    if (!resize && !canMove) return;
+
+    switch (e.key) {
+      case 'ArrowUp':
+        e.preventDefault();
+        e.stopPropagation();
+        onNudge(block, { mode: resize ? 'resize' : 'move', steps: -1 });
+        break;
+      case 'ArrowDown':
+        e.preventDefault();
+        e.stopPropagation();
+        onNudge(block, { mode: resize ? 'resize' : 'move', steps: 1 });
+        break;
+      case 'ArrowLeft':
+        // Column changes are a move concept only — there is nothing to
+        // resize sideways.
+        if (resize) return;
+        e.preventDefault();
+        e.stopPropagation();
+        onNudge(block, { mode: 'move', steps: 0, columns: -1 });
+        break;
+      case 'ArrowRight':
+        if (resize) return;
+        e.preventDefault();
+        e.stopPropagation();
+        onNudge(block, { mode: 'move', steps: 0, columns: 1 });
+        break;
+      default:
+        break;
+    }
+  };
+
+  // Short events use a single-line row layout (time + title side-by-side)
+  // so the start time stays visible even on min-height blocks. Tall events
+  // stack time above title in a column for more breathing room.
+  const isShort = height < MIN_BLOCK_HEIGHT_PX + 10;
+
+  const customContent = renderEvent
+    ? renderEvent(block.event, {
+        view,
+        asAllDay: false,
+        timeLabel,
+        duration,
+      })
+    : null;
+
+  const draggable = canMove || canResize;
+
+  return (
+    <Tooltip content={tooltipContent}>
+      <button
+        type="button"
+        className={clsx(
+          styles.block,
+          toneClass && styles[toneClass],
+          colorStyle && styles.colored,
+          hasStripe && styles.striped,
+          isShort && styles.short,
+          canMove && styles.movable,
+          isDragging && styles.dragging,
+          preview?.invalid && styles.invalidDrop,
+        )}
+        style={
+          {
+            ...colorStyle,
+            top,
+            height,
+            '--cal-block-left': `${leftPercent}%`,
+            '--cal-block-width': `${100 - leftPercent}%`,
+            '--cal-block-z': zIndex,
+            '--cal-block-z-hover': HOVER_Z_INDEX,
+          } as CSSProperties
+        }
+        // `aria-grabbed` is deprecated in ARIA 1.1 and unsupported in practice;
+        // the drag capability is announced through the description instead.
+        aria-describedby={draggable ? dragHintId : undefined}
+        data-dragging={isDragging || undefined}
+        onClick={handleClick}
+        onPointerDown={handlePointerDown}
+        onKeyDown={draggable ? handleKeyDown : undefined}
+      >
+        {customContent !== null ? (
+          customContent
+        ) : (
+          <>
+            <span className={styles.time}>{timeLabel}</span>
+            <span className={styles.title}>{block.event.title}</span>
+          </>
+        )}
+        {canResize && (
+          // A span, not a nested <button> (illegal inside the block button).
+          // Keyboard users reach the same capability through Alt+Shift+Arrow
+          // on the block itself, so the handle is purely a pointer affordance.
+          <span
+            role="presentation"
+            aria-hidden="true"
+            className={styles.resizeHandle}
+            onPointerDown={handleHandlePointerDown}
+            onClick={(e) => e.stopPropagation()}
+          />
+        )}
+      </button>
+    </Tooltip>
+  );
+}

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

@@ -0,0 +1,3 @@
+.switcher {
+  display: flex;
+}

package/src/components/Calendar/ViewSwitcher.tsx

@@ -0,0 +1,47 @@
+import { useMemo } from 'react';
+import { Tabs } from '../Tabs';
+import type { CalendarView } from './types';
+import styles from './ViewSwitcher.module.scss';
+
+export interface ViewSwitcherProps {
+  view: CalendarView;
+  onViewChange: (view: CalendarView) => void;
+  monthLabel: string;
+  weekLabel: string;
+  dayLabel: string;
+  agendaLabel: string;
+}
+
+/**
+ * Internal: segmented control for switching between month / week / day /
+ * agenda views. Uses the design system's `<Tabs>` for ARIA + keyboard
+ * navigation.
+ *
+ * @remarks
+ * **When NOT to use:** Do not render `ViewSwitcher` directly. It is composed
+ * by the `Calendar` shell. Use `<Calendar view ... onViewChange ...>`.
+ */
+export function ViewSwitcher({
+  view,
+  onViewChange,
+  monthLabel,
+  weekLabel,
+  dayLabel,
+  agendaLabel,
+}: ViewSwitcherProps) {
+  const items = useMemo(
+    () => [
+      { id: 'month', label: monthLabel },
+      { id: 'week', label: weekLabel },
+      { id: 'day', label: dayLabel },
+      { id: 'agenda', label: agendaLabel },
+    ],
+    [monthLabel, weekLabel, dayLabel, agendaLabel],
+  );
+
+  return (
+    <div className={styles.switcher}>
+      <Tabs activeId={view} onChange={(id) => onViewChange(id as CalendarView)} items={items} />
+    </div>
+  );
+}

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

@@ -0,0 +1,10 @@
+@use './Calendar.tokens';
+
+.weekView {
+  display: flex;
+  flex-direction: column;
+  border: var(--border-width) solid var(--calendar-border-color);
+  border-radius: var(--calendar-radius);
+  overflow: hidden;
+  background: var(--calendar-bg);
+}

package/src/components/Calendar/WeekView.tsx

@@ -0,0 +1,137 @@
+import { useMemo } from 'react';
+import { useWeek } from '../../calendar/useWeek';
+import { useLocale } from '../../i18n/useLocale';
+import { formatWeekdayShort } from '../../calendar/formatters';
+import { AllDayBand } from './AllDayBand';
+import { HourGrid, HOUR_GUTTER_WIDTH, type HourGridColumn } from './HourGrid';
+import { layoutBackgroundIntervals, layoutEventsForHourGrid } from './utils';
+import type {
+  CalendarBackgroundInterval,
+  CalendarDropCandidate,
+  CalendarDropResult,
+  CalendarEvent,
+  CalendarEventMove,
+  CalendarEventResize,
+  RenderEvent,
+} from './types';
+import styles from './WeekView.module.scss';
+
+export interface WeekViewProps {
+  /** Navigation cursor — any date in the target week works. */
+  cursor: Date;
+  /** Events to display across the week. */
+  events: readonly CalendarEvent[];
+  /** Inclusive start, exclusive end of the visible hour range. */
+  hourRange: readonly [number, number];
+  /** Pixel height per hour row. */
+  hourRowHeight: number;
+  /** Override locale (otherwise reads `useLocale()`). */
+  locale?: string;
+  /** Override locale-derived first day of week (0=Sun..6=Sat). */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /**
+   * Availability underlay bands. `resourceId` is ignored (week view has no
+   * resource columns), but each interval is still clipped to the column dates
+   * it covers — one interval per day to shade a whole week.
+   */
+  backgroundIntervals?: readonly CalendarBackgroundInterval[];
+  /** Fires when a timed-event block or all-day chip is clicked. */
+  onEventClick?: (event: CalendarEvent) => void;
+  /** Fires when empty hour-grid space inside a day column is clicked, with that column's date. */
+  onDayClick?: (date: Date) => void;
+  /** Enables drag-to-move (across days as well as within one). */
+  onEventMove?: (event: CalendarEvent, next: CalendarEventMove) => CalendarDropResult;
+  /** Enables drag-to-resize. */
+  onEventResize?: (event: CalendarEvent, next: CalendarEventResize) => CalendarDropResult;
+  /** Live veto during a drag. */
+  canDropEvent?: (event: CalendarEvent, next: CalendarDropCandidate) => boolean;
+  /** Snap granularity for drags, in minutes. */
+  dragSnapMinutes?: number;
+  /** Optional custom event renderer (see `RenderEvent`). */
+  renderEvent?: RenderEvent;
+  /** Override the "now" clock for the now-line. For tests; defaults to `new Date()`. */
+  now?: Date;
+}
+
+/**
+ * Internal: 7-day hour grid. Shows the week containing `cursor`, with an
+ * AllDayBand above and an HourGrid below.
+ *
+ * @remarks
+ * **When NOT to use:** Do not render `WeekView` directly in application code —
+ * use the `Calendar` shell component, which owns view state and navigation
+ * and dispatches into `WeekView` when `view === 'week'`.
+ */
+export function WeekView({
+  cursor,
+  events,
+  hourRange,
+  hourRowHeight,
+  locale: localeOverride,
+  weekStartsOn,
+  backgroundIntervals,
+  onEventClick,
+  onDayClick,
+  onEventMove,
+  onEventResize,
+  canDropEvent,
+  dragSnapMinutes,
+  renderEvent,
+  now,
+}: WeekViewProps) {
+  const contextLocale = useLocale();
+  const locale = localeOverride ?? contextLocale;
+  const week = useWeek(cursor, { locale, weekStartsOn });
+
+  const columns: HourGridColumn[] = useMemo(
+    () => week.days.map((d) => ({ date: d.date, key: d.key, isWeekend: d.isWeekend })),
+    [week.days],
+  );
+
+  const layout = useMemo(
+    () => layoutEventsForHourGrid(events, columns, hourRange),
+    [events, columns, hourRange],
+  );
+
+  const backgroundBlocks = useMemo(
+    () => layoutBackgroundIntervals(backgroundIntervals ?? [], columns, hourRange),
+    [backgroundIntervals, columns, hourRange],
+  );
+
+  const headers = week.days.map((d) => (
+    <span>
+      {formatWeekdayShort(d.date, locale)} <strong>{d.dayOfMonth}</strong>
+    </span>
+  ));
+
+  return (
+    <div className={styles.weekView}>
+      <AllDayBand
+        bars={layout.allDayBars}
+        columnCount={7}
+        gutterWidth={HOUR_GUTTER_WIDTH}
+        view="week"
+        renderEvent={renderEvent}
+        onEventClick={onEventClick}
+      />
+      <HourGrid
+        columns={columns}
+        columnHeaders={headers}
+        hourRange={hourRange}
+        hourRowHeight={hourRowHeight}
+        timedBlocks={layout.timedBlocks}
+        backgroundBlocks={backgroundBlocks}
+        view="week"
+        renderEvent={renderEvent}
+        onEventClick={onEventClick}
+        onDayClick={onDayClick}
+        onEventMove={onEventMove}
+        onEventResize={onEventResize}
+        canDropEvent={canDropEvent}
+        dragSnapMinutes={dragSnapMinutes}
+        now={now}
+        ariaLabel={week.weekLabel}
+      />
+    </div>
+  );
+}

package/src/components/Calendar/eventColor.ts

@@ -0,0 +1,60 @@
+import type { CSSProperties } from 'react';
+import { paletteTokens } from '../../palette';
+import type { CalendarEvent, CalendarEventTone } from './types';
+
+/**
+ * Internal: resolves a `CalendarEvent`'s two colour axes into the CSS custom
+ * properties the chip / block / agenda-row stylesheets read.
+ *
+ * The axes are deliberately NOT in competition, so there is no precedence rule
+ * to remember:
+ * - `color` (category identity) wins the surface. This helper only hands out
+ *   the palette's `bg`/`fg` pair; each stylesheet decides how to spend them,
+ *   and they do NOT spend them alike — the chip and the timed block take a
+ *   tinted background with the saturated colour for text and border, while the
+ *   agenda row is never filled and spends `fg` on its leading dot alone.
+ * - `tone` (semantic state) moves to a band on the left edge, drawn only when
+ *   it is something other than the `'neutral'` default. A state therefore
+ *   survives being given a category colour instead of being overridden by it.
+ *
+ * With no `color` the event keeps its original behaviour exactly: the tone
+ * class paints the whole surface and no stripe is drawn. That is what makes
+ * this additive for every existing consumer.
+ *
+ * Lives in one place because three surfaces render events (`EventChip`,
+ * `TimedEvent`, `AgendaView`) and a rule duplicated three ways drifts.
+ */
+export interface ResolvedEventColor {
+  /** Tone class to apply, or `undefined` when `color` has taken the surface. */
+  toneClass: CalendarEventTone | undefined;
+  /** True when a leading-edge stripe should be drawn for the semantic tone. */
+  hasStripe: boolean;
+  /** Inline custom properties, or `undefined` when the event has no `color`. */
+  style: CSSProperties | undefined;
+}
+
+/** @param event - the event being rendered. */
+export function resolveEventColor(event: CalendarEvent): ResolvedEventColor {
+  const tone: CalendarEventTone = event.tone ?? 'neutral';
+
+  if (!event.color) {
+    return { toneClass: tone, hasStripe: false, style: undefined };
+  }
+
+  const { bg, fg } = paletteTokens(event.color);
+  // A neutral tone carries no state worth a stripe — it IS the default — so a
+  // category-coloured event with no explicit state stays a clean single colour.
+  const hasStripe = tone !== 'neutral';
+
+  return {
+    toneClass: undefined,
+    hasStripe,
+    style: {
+      '--calendar-event-color-bg': bg,
+      '--calendar-event-color-fg': fg,
+      ...(hasStripe
+        ? { '--calendar-event-stripe-color': `var(--calendar-event-stripe-${tone})` }
+        : null),
+    } as CSSProperties,
+  };
+}

package/src/components/Calendar/index.ts

@@ -0,0 +1,18 @@
+export { Calendar } from './Calendar';
+export type { CalendarProps } from './Calendar';
+export type {
+  CalendarBackgroundInterval,
+  CalendarBackgroundTone,
+  CalendarDropCandidate,
+  CalendarDropResult,
+  CalendarEvent,
+  CalendarEventMove,
+  CalendarEventResize,
+  CalendarEventTone,
+  CalendarResource,
+  CalendarView,
+  EventBar,
+  MonthLayout,
+  RenderEvent,
+  RenderEventContext,
+} from './types';