@lotics/ui 46.14.1 → 47.1.0

package/src/calendar/context.ts

@@ -0,0 +1,47 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { CalendarEvent, CalendarViewLabels, CalendarViewMode, Weekday } from "./types";
+
+/**
+ * What every calendar part reads.
+ *
+ * Events are held as `CalendarEvent<unknown>` and the press/render callbacks are
+ * keyed by event **id**, not by the typed event. That is what lets the root be
+ * generic over the consumer's row type while the parts stay plain: the root
+ * closes over its own typed array and resolves the id back before calling out,
+ * so no part ever has to launder a type it does not know.
+ */
+export interface CalendarContextValue {
+  events: CalendarEvent<unknown>[];
+  /** The anchor date; which days are in view is each part's own business. */
+  date: Date;
+  setDate: (date: Date) => void;
+  view: CalendarViewMode;
+  setView: (view: CalendarViewMode) => void;
+  /** Which modes the toolbar offers. */
+  views: CalendarViewMode[];
+  weekStartsOn: Weekday;
+  locale?: string;
+  labels: CalendarViewLabels;
+  /** What the calendar treats as "now" — the today badge, the red line, and the
+   *  hour a grid opens at. Supplied rather than read from the clock so a
+   *  workspace in another zone can hand over ITS wall clock, and so a test can
+   *  pin a day. */
+  now: Date;
+  /** Default visible window of a day in the time grid, in minutes from midnight.
+   *  A viewport, never a filter — an event outside it still widens the grid. */
+  dayStartMinutes: number;
+  dayEndMinutes: number;
+  onEventPress?: (id: string) => void;
+  onSlotPress?: (start: Date, end: Date) => void;
+  renderEvent?: (event: CalendarEvent<unknown>) => ReactNode;
+}
+
+const CalendarContext = createContext<CalendarContextValue | null>(null);
+
+export const CalendarProvider = CalendarContext.Provider;
+
+export function useCalendar(): CalendarContextValue {
+  const ctx = useContext(CalendarContext);
+  if (!ctx) throw new Error("Calendar parts must be used within a CalendarView");
+  return ctx;
+}

package/src/calendar/dates.ts

@@ -32,7 +32,11 @@ export function endOfMonth(d: Date): Date {
 }
 
 export function addMonths(d: Date, n: number): Date {
-  return new Date(d.getFullYear(), d.getMonth() + n, d.getDate());
+  // Clamp the day so 31 Jan + 1 month is 28/29 Feb, not 2/3 March. Stepping a
+  // month at a time through a 31-day month otherwise skips February entirely.
+  const target = new Date(d.getFullYear(), d.getMonth() + n, 1);
+  const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+  return new Date(target.getFullYear(), target.getMonth(), Math.min(d.getDate(), lastDay));
 }
 
 export function isSameDay(a: Date, b: Date): boolean {
@@ -60,16 +64,37 @@ export function minutesSinceMidnight(d: Date): number {
   return d.getHours() * 60 + d.getMinutes();
 }
 
-/** The day columns a view spans: 7 for week, 1 for day, the 6-week grid for month. */
+/**
+ * How many week rows this month actually needs (4–6).
+ *
+ * The grid used to be a hardcoded 42 days "for a stable grid height", which buys
+ * a stable height at the price of a whole empty row in most months — June 2026
+ * rendered five weeks of dates and a sixth row of greyed-out July, eating ~17%
+ * of the calendar's height to show nothing. A month grid should be as tall as
+ * the month is; the row height absorbs the difference.
+ */
+export function weekRowsInMonth(date: Date, weekStartsOn: Weekday = 1): number {
+  const gridStart = startOfWeek(startOfMonth(date), weekStartsOn);
+  const last = endOfMonth(date);
+  return Math.ceil((dayDiff(gridStart, last) + 1) / 7);
+}
+
+/** The day columns a view spans: 7 for week, 1 for day, whole weeks for month/agenda. */
 export function daysInView(mode: CalendarViewMode, date: Date, weekStartsOn: Weekday = 1): Date[] {
   if (mode === "day") return [startOfDay(date)];
   if (mode === "week") {
     const start = startOfWeek(date, weekStartsOn);
     return Array.from({ length: 7 }, (_, i) => addDays(start, i));
   }
-  // month: full weeks covering the month → always 6 rows for a stable grid height.
+  if (mode === "agenda") {
+    // The agenda lists the month it is pointed at, so prev/next mean the same
+    // thing it does in month view and the toolbar title stays honest.
+    const start = startOfMonth(date);
+    const days = endOfMonth(date).getDate();
+    return Array.from({ length: days }, (_, i) => addDays(start, i));
+  }
   const gridStart = startOfWeek(startOfMonth(date), weekStartsOn);
-  return Array.from({ length: 42 }, (_, i) => addDays(gridStart, i));
+  return Array.from({ length: weekRowsInMonth(date, weekStartsOn) * 7 }, (_, i) => addDays(gridStart, i));
 }
 
 // ─── Localized labels (Intl, browser/workspace locale) ──────────────────────
@@ -87,9 +112,14 @@ export function hourLabel(hour: number): string {
   return `${String(hour).padStart(2, "0")}:00`;
 }
 
-/** Header title: "March 2026" (month) or the week/day range. */
+/** Agenda day heading: "Thu 12 March". */
+export function dayHeading(d: Date, locale?: string): string {
+  return new Intl.DateTimeFormat(locale, { weekday: "short", day: "numeric", month: "long" }).format(d);
+}
+
+/** Header title: "March 2026" (month/agenda) or the week/day range. */
 export function viewTitle(mode: CalendarViewMode, date: Date, weekStartsOn: Weekday, locale?: string): string {
-  if (mode === "month") {
+  if (mode === "month" || mode === "agenda") {
     return new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }).format(date);
   }
   if (mode === "day") {

package/src/calendar/event_chip.tsx

@@ -0,0 +1,141 @@
+import type { ReactNode } from "react";
+import { View, StyleSheet, type StyleProp, type ViewStyle } from "react-native";
+import { Text } from "../text";
+import { colors, type ColorName } from "../colors";
+import { proportionalRadius } from "../control_surface";
+import { FocusRingPressable } from "../focus_ring_pressable";
+import { formatTime } from "./dates";
+import type { CalendarEvent } from "./types";
+
+const DEFAULT_COLOR: ColorName = "teal";
+
+/**
+ * The ground and ink one event colour resolves to.
+ *
+ * **A wash with matching ink, never a saturated fill with white on it.** The
+ * pairing is `Badge`'s tonal one — the palette's own light ground and dark ink
+ * of a single family — so a calendar reads as the same product as everything
+ * beside it, and a month with a dozen colours in it stays a surface you can
+ * look at. A `solid()` bar per event turns the grid into a paint chart, which
+ * is what "the colours are ugly" actually names.
+ *
+ * The dot is the one place the solid shade still belongs: it is 6px, it carries
+ * identity rather than area, and it needs the contrast.
+ */
+function chipColors(name: ColorName): { ground: string; hovered: string; ink: string; dot: string } {
+  const hue = colors[name];
+  // `hovered` is the SAME ground one rung deeper, never a different colour:
+  // what has to change is only "this responds to me", and the chip must still
+  // read as the event it was a moment ago.
+  return { ground: hue[100], hovered: hue[200], ink: hue[900], dot: hue[500] };
+}
+
+/**
+ * The three ways an event is drawn.
+ *
+ * - `banner` — a bar. A thing that occupies whole DAYS: an all-day marker, a
+ *   multi-day campaign. Reads as continuous across day boundaries.
+ * - `dot`    — a coloured dot beside plain text. A timed event inside a month
+ *   cell, where a filled bar per meeting turns the month into a colour chart
+ *   and the dates stop being findable.
+ * - `block`  — a body sized to its duration, for the time grid, where vertical
+ *   extent carries the meaning.
+ *
+ * **None of them draws a border.** A washed body already states its own edge;
+ * a rule on top of it is the same edge asserted twice, on a surface that is
+ * already full of grid lines. (`board.tsx` states the same law for its cards.)
+ */
+export type EventChipVariant = "banner" | "dot" | "block";
+
+export interface EventChipProps {
+  event: CalendarEvent<unknown>;
+  variant: EventChipVariant;
+  onPress?: () => void;
+  /** Replaces the chip's contents; the press target and geometry stay ours. */
+  render?: (event: CalendarEvent<unknown>) => ReactNode;
+  /** Show the start time before the title (month cells, where there is no rail). */
+  showTime?: boolean;
+  locale?: string;
+  style?: StyleProp<ViewStyle>;
+  /** Below this the block drops its second line rather than clipping it. */
+  compact?: boolean;
+  /** The chip's rendered height, so its corners stay proportionate to it — a
+   *  fixed radius turns a 20px lane chip into a pill and barely marks a tall
+   *  block. */
+  height: number;
+}
+
+export function EventChip(props: EventChipProps) {
+  const { event, variant, onPress, render, showTime, locale, style, compact, height } = props;
+  const { ground, hovered, ink, dot } = chipColors(event.color ?? DEFAULT_COLOR);
+  const radius = proportionalRadius(height);
+
+  const label = showTime ? `${formatTime(event.start, locale)} ${event.title}` : event.title;
+
+  return (
+    <FocusRingPressable
+      onPress={onPress}
+      accessibilityRole={onPress ? "button" : undefined}
+      accessibilityLabel={accessibleName(event, locale)}
+      style={[styles.press, style]}
+    >
+      {({ hovered: over }) => {
+        // Nothing lights up without a handler, so a read-only calendar never
+        // advertises a press that does nothing.
+        const lit = !!onPress && over;
+        return render ? (
+          render(event)
+        ) : variant === "banner" ? (
+          <View style={[styles.banner, { backgroundColor: lit ? hovered : ground, borderRadius: radius }]}>
+            <Text size="xs" weight="medium" numberOfLines={1} style={{ color: ink }}>
+              {event.title}
+            </Text>
+          </View>
+        ) : variant === "dot" ? (
+          // The dot row has no ground of its own, so its hover is a NEUTRAL
+          // wash: the row is mostly plain text, and tinting it with the event's
+          // own hue would read as the event changing state rather than as the
+          // pointer being over it.
+          <View style={[styles.dotRow, lit ? { backgroundColor: colors.zinc[100], borderRadius: radius } : null]}>
+            <View style={[styles.dot, { backgroundColor: dot }]} />
+            <Text size="xs" numberOfLines={1} style={styles.dotLabel}>
+              {label}
+            </Text>
+          </View>
+        ) : (
+          <View style={[styles.block, { backgroundColor: lit ? hovered : ground, borderRadius: radius }]}>
+            <Text size="xs" weight="medium" numberOfLines={1} style={{ color: ink }}>
+              {event.title}
+            </Text>
+            {!compact ? (
+              <Text size="xs" numberOfLines={1} style={{ color: ink, opacity: 0.7 }}>
+                {event.meta ?? formatTime(event.start, locale)}
+              </Text>
+            ) : null}
+          </View>
+        );
+      }}
+    </FocusRingPressable>
+  );
+}
+
+/** What a screen reader hears: the title, then when it is — never a bare title,
+ *  which in a grid of forty of them says nothing about which one this is. */
+export function accessibleName(event: CalendarEvent<unknown>, locale?: string): string {
+  if (event.allDay) return event.title;
+  const start = formatTime(event.start, locale);
+  const end = event.end ? formatTime(event.end, locale) : null;
+  return end ? `${event.title}, ${start}–${end}` : `${event.title}, ${start}`;
+}
+
+const styles = StyleSheet.create({
+  press: { minWidth: 0 },
+  banner: { flex: 1, justifyContent: "center", paddingHorizontal: 8, minWidth: 0 },
+  dotRow: { flex: 1, flexDirection: "row", alignItems: "center", gap: 6, paddingHorizontal: 4, minWidth: 0 },
+  dot: { width: 6, height: 6, borderRadius: 3, flexShrink: 0 },
+  // `flexShrink: 1` + `minWidth: 0` on the label, not just the row: React Native
+  // defaults flexShrink to 0, so without it the title holds its full width and
+  // pushes the dot out of the cell instead of ellipsing.
+  dotLabel: { color: colors.zinc[700], flexShrink: 1, minWidth: 0 },
+  block: { flex: 1, paddingHorizontal: 8, paddingVertical: 2, overflow: "hidden", minWidth: 0 },
+});

package/src/calendar/index.ts

@@ -1,19 +1,42 @@
-export { CalendarView } from "./calendar_view";
+export { CalendarView, CalendarBody } from "./calendar_view";
 export type { CalendarViewProps } from "./calendar_view";
-export { TimeGridView } from "./time_grid_view";
-export type { TimeGridViewProps } from "./time_grid_view";
-export { MonthView } from "./month_view";
-export type { MonthViewProps } from "./month_view";
-export { layoutDayColumns, packEventLanes } from "./layout";
+export { CalendarToolbar } from "./calendar_toolbar";
+export type { CalendarToolbarProps } from "./calendar_toolbar";
+export { CalendarMonth } from "./month_view";
+export { CalendarWeek, CalendarDay, gridWindow } from "./time_grid_view";
+export { CalendarAgenda } from "./agenda_view";
+export { EventChip } from "./event_chip";
+export type { EventChipProps, EventChipVariant } from "./event_chip";
+export { useCalendar } from "./context";
+export type { CalendarContextValue } from "./context";
+export {
+  layoutDayColumns,
+  packEventLanes,
+  compareEvents,
+  fitLanes,
+  initialScrollMinutes,
+  isBanner,
+} from "./layout";
 export type { LaneBar } from "./layout";
-export { DEFAULT_CALENDAR_LABELS } from "./types";
-export type { CalendarEvent, CalendarViewMode, Weekday, EventColumn, CalendarLabels } from "./types";
+export { expandRepeats, occurrenceDays, occurrenceId, sourceEventId } from "./repeat";
+export type { RepeatRule } from "./repeat";
+export { DEFAULT_CALENDAR_VIEW_LABELS } from "./types";
+export type {
+  CalendarEvent,
+  CalendarViewMode,
+  Weekday,
+  EventColumn,
+  CalendarViewLabels,
+} from "./types";
 export {
   addDays,
   addMonths,
   startOfWeek,
   startOfMonth,
+  endOfMonth,
   daysInView,
+  weekRowsInMonth,
+  dayHeading,
   isSameDay,
   isToday,
   viewTitle,

package/src/calendar/layout.ts

@@ -1,4 +1,4 @@
-import { dayDiff } from "./dates";
+import { dayDiff, minutesSinceMidnight, startOfDay } from "./dates";
 import type { CalendarEvent, EventColumn } from "./types";
 
 /** A horizontal banner placement: which day column it starts on, how many days
@@ -11,38 +11,112 @@ export interface LaneBar<T = unknown> {
   lane: number;
 }
 
+/** True for an event that occupies whole days rather than a slot in one. */
+export function isBanner<T>(event: CalendarEvent<T>): boolean {
+  if (event.allDay) return true;
+  return event.end ? dayDiff(event.start, event.end) > 0 : false;
+}
+
+/**
+ * The order events take within a day, and the order lanes are handed out.
+ *
+ * Banners lead — a bar that runs Monday to Friday must sit ABOVE the meetings
+ * inside those days, or it gets a different lane every week row and stops
+ * reading as one continuous thing. Longest first among them, so the widest bar
+ * anchors the top lane. Timed events then follow in clock order, which is the
+ * rule the previous version was missing entirely: it sorted by day only, so a
+ * day's events appeared in whatever order the consumer's array happened to be
+ * in — 16:00 above 09:00 as often as not.
+ */
+export function compareEvents<T>(a: CalendarEvent<T>, b: CalendarEvent<T>): number {
+  const ab = isBanner(a);
+  const bb = isBanner(b);
+  if (ab !== bb) return ab ? -1 : 1;
+  const byDay = startOfDay(a.start).getTime() - startOfDay(b.start).getTime();
+  if (byDay !== 0) return byDay;
+  if (ab) {
+    const len = (e: CalendarEvent<T>) => (e.end ? dayDiff(e.start, e.end) : 0);
+    const byLen = len(b) - len(a);
+    if (byLen !== 0) return byLen;
+  } else {
+    const byTime = minutesSinceMidnight(a.start) - minutesSinceMidnight(b.start);
+    if (byTime !== 0) return byTime;
+  }
+  // Ties break on id so the layout is deterministic across renders.
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
 /**
  * Pack day-spanning events into horizontal lanes across a `numDays` window
  * starting at `rangeStart`. Greedy first-fit: an event takes the topmost lane
  * whose last bar ends before this event starts, else a new lane. Multi-day
  * events become wide bars; single-day events are span-1 bars. Deterministic.
+ *
+ * Pure over the list it is handed, which is what keeps a per-resource split
+ * (one call per group, rendered as sub-columns) a caller-side concern rather
+ * than a second code path in here.
  */
 export function packEventLanes<T>(
   events: CalendarEvent<T>[],
   rangeStart: Date,
   numDays: number,
 ): { bars: LaneBar<T>[]; lanes: number } {
-  const items = events
+  const items = [...events]
+    .sort(compareEvents)
     .map((event) => ({
       event,
       startCol: Math.max(0, dayDiff(rangeStart, event.start)),
       endCol: Math.min(numDays - 1, dayDiff(rangeStart, event.end ?? event.start)),
     }))
-    .filter((it) => it.endCol >= 0 && it.startCol <= numDays - 1 && it.endCol >= it.startCol)
-    .sort((a, b) => a.startCol - b.startCol || b.endCol - a.endCol);
+    .filter((it) => it.endCol >= 0 && it.startCol <= numDays - 1 && it.endCol >= it.startCol);
 
-  const laneEnds: number[] = [];
+  // Occupancy per lane is a set of COLUMNS, not a single "last end column".
+  // With one end per lane, a bar late in the week blocks that lane for every
+  // day BEFORE it too — a Saturday holiday banner took lane 0 across the whole
+  // row and pushed Monday's first meeting down a lane, which on a short row is
+  // the difference between seeing it and reading "+2 more".
+  const laneCols: boolean[][] = [];
+  const free = (lane: boolean[], from: number, to: number) => {
+    for (let c = from; c <= to; c++) if (lane[c]) return false;
+    return true;
+  };
   const bars = items.map((it) => {
-    let lane = laneEnds.findIndex((end) => end < it.startCol);
+    let lane = laneCols.findIndex((cols) => free(cols, it.startCol, it.endCol));
     if (lane === -1) {
-      lane = laneEnds.length;
-      laneEnds.push(it.endCol);
-    } else {
-      laneEnds[lane] = it.endCol;
+      lane = laneCols.length;
+      laneCols.push(Array.from({ length: numDays }, () => false));
     }
+    for (let c = it.startCol; c <= it.endCol; c++) laneCols[lane][c] = true;
     return { event: it.event, startCol: it.startCol, span: it.endCol - it.startCol + 1, lane };
   });
-  return { bars, lanes: laneEnds.length };
+  return { bars, lanes: laneCols.length };
+}
+
+/**
+ * How many event lanes fit in a measured week row, and whether the row must
+ * give one back to the "+N more" chip.
+ *
+ * The lane cap used to be the constant 3 while the row itself was `flex: 1` —
+ * so a tall calendar wasted the space it had and a short one drew three lanes
+ * into a 20px row, straight over the next week's dates. A cap has to be a
+ * function of the height actually measured.
+ */
+export function fitLanes(
+  availableHeight: number,
+  laneHeight: number,
+  laneGap: number,
+  neededLanes: number,
+  overflowChipHeight: number,
+): { visibleLanes: number; overflows: boolean } {
+  const per = laneHeight + laneGap;
+  // The last lane needs no trailing gap, so the gap is added back before
+  // dividing — without it a row that fits exactly N lanes reports N-1.
+  const fit = (h: number) => Math.max(0, Math.floor((h + laneGap) / per));
+  if (neededLanes <= fit(availableHeight)) return { visibleLanes: neededLanes, overflows: false };
+  // Overflowing costs the row the chip's height, NOT a whole lane: the chip is
+  // one line of small text, and charging it a full lane threw away an event
+  // that had room to be shown.
+  return { visibleLanes: fit(availableHeight - overflowChipHeight), overflows: true };
 }
 
 const MINUTES_PER_DAY = 1440;
@@ -54,6 +128,34 @@ function minutesInto(day: Date, t: Date): number {
   return ms / 60000;
 }
 
+/**
+ * The minute window a time grid should open on.
+ *
+ * The previous rule was "an hour before now", unconditionally — so navigating to
+ * any week whose events sit outside the current wall-clock hour opened on an
+ * empty grid. A week of 09:00 meetings, viewed at 13:00, looked like a week with
+ * nothing in it. What a reader wants is the content: the earliest event in view,
+ * and only when there is none does the clock (or the configured day start) decide.
+ */
+export function initialScrollMinutes(
+  events: { start: Date }[],
+  daysInRange: Date[],
+  now: Date,
+  dayStartMinutes: number,
+): number {
+  let earliest: number | null = null;
+  for (const e of events) {
+    const inRange = daysInRange.some((d) => startOfDay(e.start).getTime() === d.getTime());
+    if (!inRange) continue;
+    const m = minutesSinceMidnight(e.start);
+    if (earliest === null || m < earliest) earliest = m;
+  }
+  if (earliest !== null) return Math.max(0, earliest - 30);
+  const todayInRange = daysInRange.some((d) => startOfDay(now).getTime() === d.getTime());
+  if (todayInRange) return Math.max(0, minutesSinceMidnight(now) - 60);
+  return dayStartMinutes;
+}
+
 /**
  * Position timed events for a single grid day into side-by-side columns.
  *