@lotics/ui 46.14.1 → 47.0.0

package/src/calendar/calendar_toolbar.tsx

@@ -0,0 +1,84 @@
+import type { ReactNode } from "react";
+import { View, StyleSheet } from "react-native";
+import { Text } from "../text";
+import { Button } from "../button";
+import { IconButton } from "../icon_button";
+import { SegmentedControl, type SegmentOption } from "../segmented_control";
+import { useCalendar } from "./context";
+import { addDays, addMonths, startOfDay, viewTitle } from "./dates";
+import type { CalendarViewMode } from "./types";
+
+/**
+ * The toolbar's height when it does not wrap — what the root has to subtract
+ * before asking whether the GRID still fits. It wraps only at widths that are
+ * already compact, where the answer is the agenda either way.
+ */
+export const CALENDAR_TOOLBAR_HEIGHT = 57;
+
+export interface CalendarToolbarProps {
+  /** Extra controls, rendered after the view switch — filters, an add action. */
+  children?: ReactNode;
+}
+
+/**
+ * Prev / today / next, the range title, and the view switch.
+ *
+ * **Optional on purpose.** Mounting `CalendarView` with children means the app
+ * supplies its own chrome, because a Lotics screen already has a header band and
+ * a calendar that welds one on produces two stacked bands. The switch is the
+ * kit's `SegmentedControl` rather than three hand-rolled pills — a mutually
+ * exclusive choice among a few peers is exactly what that control is.
+ */
+export function CalendarToolbar(props: CalendarToolbarProps) {
+  const { date, setDate, view, setView, views, weekStartsOn, locale, labels } = useCalendar();
+
+  const step = (dir: number) => {
+    if (view === "month" || view === "agenda") setDate(addMonths(date, dir));
+    else setDate(addDays(date, dir * (view === "week" ? 7 : 1)));
+  };
+
+  const options: SegmentOption<CalendarViewMode>[] = views.map((v) => ({ label: labels[v], value: v }));
+
+  return (
+    <View style={styles.toolbar}>
+      <View style={styles.navGroup}>
+        <IconButton icon="chevron-left" size="md" accessibilityLabel={labels.previous} onPress={() => step(-1)} />
+        <Button color="secondary" title={labels.today} onPress={() => setDate(startOfDay(new Date()))} />
+        <IconButton icon="chevron-right" size="md" accessibilityLabel={labels.next} onPress={() => step(1)} />
+      </View>
+
+      <Text size="lg" weight="semibold" numberOfLines={1} style={styles.title}>
+        {viewTitle(view, date, weekStartsOn, locale)}
+      </Text>
+
+      <View style={styles.trailing}>
+        {props.children}
+        {options.length > 1 ? (
+          <SegmentedControl<CalendarViewMode>
+            accessibilityLabel={labels.month}
+            options={options}
+            value={view}
+            onValueChange={setView}
+          />
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  toolbar: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    gap: 12,
+    flexWrap: "wrap",
+  },
+  navGroup: { flexDirection: "row", alignItems: "center", gap: 6 },
+  // The title takes the slack and ellipses; the two control groups hold their
+  // size, so a long month name never squeezes the buttons out of the band.
+  title: { flexGrow: 1, flexShrink: 1, minWidth: 0, textAlign: "center" },
+  trailing: { flexDirection: "row", alignItems: "center", gap: 8, flexShrink: 0 },
+});

package/src/calendar/calendar_view.tsx

@@ -1,131 +1,224 @@
-import { useState } from "react";
-import { View, StyleSheet } from "react-native";
-import { Text } from "../text";
+import { useMemo, useState, type ReactNode } from "react";
+import { View, StyleSheet, type LayoutChangeEvent } from "react-native";
 import { colors } from "../colors";
-import { FocusRingPressable } from "../focus_ring_pressable";
-import { MonthView } from "./month_view";
-import { TimeGridView } from "./time_grid_view";
-import { addDays, addMonths, viewTitle } from "./dates";
-import { DEFAULT_CALENDAR_LABELS } from "./types";
-import type { CalendarEvent, CalendarLabels, CalendarViewMode, Weekday } from "./types";
+import { useLoticsLocale } from "../locale";
+import { CalendarProvider, useCalendar, type CalendarContextValue } from "./context";
+import { CalendarToolbar, CALENDAR_TOOLBAR_HEIGHT } from "./calendar_toolbar";
+import { CalendarMonth, MIN_MONTH_HEIGHT } from "./month_view";
+import { CalendarWeek, CalendarDay } from "./time_grid_view";
+import { CalendarAgenda } from "./agenda_view";
+import { daysInView, startOfDay } from "./dates";
+import { expandRepeats, sourceEventId } from "./repeat";
+import type { CalendarEvent, CalendarViewLabels, CalendarViewMode, Weekday } from "./types";
 
-const VIEW_ORDER: CalendarViewMode[] = ["month", "week", "day"];
+/** Below this width the month/week grids stop being readable and the agenda
+ *  takes over. Seven columns need ~110px each to hold a real title; under that
+ *  the grid can only say WHICH days have something. */
+const DEFAULT_COMPACT_BELOW = 720;
+
+const ALL_VIEWS: CalendarViewMode[] = ["month", "week", "day", "agenda"];
+/** What the switcher offers once the surface is too narrow for a grid. */
+const COMPACT_VIEWS: CalendarViewMode[] = ["agenda", "day"];
 
 export interface CalendarViewProps<T = unknown> {
   events: CalendarEvent<T>[];
-  defaultView?: CalendarViewMode;
+  /** Controlled anchor date. Omit and pass `defaultDate` for the drop-in form. */
+  date?: Date;
   defaultDate?: Date;
+  onDateChange?: (date: Date) => void;
+  /** Controlled view. Omit and pass `defaultView` for the drop-in form. */
+  view?: CalendarViewMode;
+  defaultView?: CalendarViewMode;
+  onViewChange?: (view: CalendarViewMode) => void;
+  /** Which modes the built-in toolbar offers. Default: all four. */
+  views?: CalendarViewMode[];
   weekStartsOn?: Weekday;
   locale?: string;
-  /** User-facing chrome strings; defaults to English. */
-  labels?: Partial<CalendarLabels>;
+  /** Per-instance overrides; the rest resolve from `LoticsLocale.calendarView`. */
+  labels?: Partial<CalendarViewLabels>;
+  /** Default visible hours of a day in the time grid. A viewport, not a filter —
+   *  an event outside it still widens the grid rather than disappearing. */
+  dayStartHour?: number;
+  dayEndHour?: number;
+  /** Width below which month/week fall back to the agenda. */
+  compactBelow?: number;
+  /**
+   * What counts as "now" — the today badge, the now line, the hour a time grid
+   * opens at. Defaults to the browser's clock.
+   *
+   * **This is not a timezone conversion, and the calendar deliberately has no
+   * `timeZone` prop.** Lotics stores a datetime as a naive WALL CLOCK, so
+   * "14:30" means 14:30 to the business and there is nothing to convert; a
+   * calendar that re-projected it into the viewer's zone would move every
+   * event. What genuinely does depend on where the reader is sitting is the
+   * answer to "what day is it", so that is the only thing taken as a prop.
+   */
+  now?: Date;
   onEventPress?: (event: CalendarEvent<T>) => void;
-  onDayPress?: (day: Date) => void;
-  /** When set, month-view event chips become draggable; dropping on another day
-   *  reschedules the event (duration preserved). Receives event + new start/end. */
-  onEventDrop?: (event: CalendarEvent<T>, newStart: Date, newEnd: Date | null) => void;
+  /** An empty day cell or hour slot was pressed. The calendar never writes —
+   *  this hands you a range so your own form or drawer can. */
+  onSlotPress?: (start: Date, end: Date) => void;
+  /** Replace the contents of an event chip; the press target, the lane and the
+   *  geometry stay the calendar's. One slot rather than a prop per decoration.
+   *  It is called for banners and timed chips alike — branch on the exported
+   *  `isBanner(event)` when a multi-day bar should render differently. */
+  renderEvent?: (event: CalendarEvent<T>) => ReactNode;
+  /** Compose the parts yourself — `CalendarToolbar`, `CalendarMonth`,
+   *  `CalendarWeek`, `CalendarDay`, `CalendarAgenda`. Omit for toolbar + view. */
+  children?: ReactNode;
 }
 
 /**
- * Full calendar: a toolbar (prev / today / next + month/week/day switch) over
- * the month grid or the week/day time grid. Date + view are owned here so the
- * primitive is drop-in; the consumer only supplies events + callbacks.
+ * A calendar of events — month grid, week/day time grid, or agenda.
+ *
+ * **Drop-in or composed.** `<CalendarView events={…} />` renders the toolbar and
+ * the current view. Passing children replaces that with whatever you mount,
+ * against the same state: an app screen already has a header band, and a
+ * calendar that welds its own on stacks two.
+ *
+ * **Controlled or not.** `date`/`view` with their `on*Change` callbacks let the
+ * surrounding screen drive — a filter chip, a route, a "jump to today" that
+ * lives in the app's own header. Omit them and the calendar owns its state.
+ *
+ * **It never writes.** Press an event or an empty slot and you get a callback;
+ * every mutation is the app's, through whatever form or workflow it uses.
+ *
+ * For rows that are RESOURCES rather than days — a channel, an owner, a vehicle
+ * — reach for `GanttView` instead. Both pack bars with the same layout core.
  */
 export function CalendarView<T = unknown>(props: CalendarViewProps<T>) {
-  const { events, defaultView = "month", defaultDate, weekStartsOn = 1, locale, onEventPress, onDayPress, onEventDrop } = props;
-  const L = { ...DEFAULT_CALENDAR_LABELS, ...props.labels };
-  const [view, setView] = useState<CalendarViewMode>(defaultView);
-  const [date, setDate] = useState<Date>(defaultDate ?? new Date());
+  const {
+    events, weekStartsOn = 1, locale, views = ALL_VIEWS,
+    dayStartHour = 0, dayEndHour = 24, compactBelow = DEFAULT_COMPACT_BELOW, now,
+    onEventPress, onSlotPress, renderEvent, children,
+  } = props;
 
-  const step = (dir: number) =>
-    setDate((d) => (view === "month" ? addMonths(d, dir) : addDays(d, dir * (view === "week" ? 7 : 1))));
+  const pack = useLoticsLocale();
+  const labels: CalendarViewLabels = { ...pack.calendarView, ...props.labels };
 
-  // Drilling into a day (month "+N more" or a day cell) opens the day grid.
-  const drillToDay = (day: Date) => {
-    setDate(day);
-    setView("day");
-    onDayPress?.(day);
+  // One reading of the clock for the whole tree, so the badge, the now line and
+  // the scroll target cannot disagree across a midnight boundary mid-render.
+  const referenceNow = now ?? new Date();
+  const [ownDate, setOwnDate] = useState<Date>(() => startOfDay(props.defaultDate ?? now ?? new Date()));
+  const [ownView, setOwnView] = useState<CalendarViewMode>(props.defaultView ?? "month");
+  const date = props.date ?? ownDate;
+  const view = props.view ?? ownView;
+
+  const setDate = (next: Date) => {
+    if (props.date === undefined) setOwnDate(next);
+    props.onDateChange?.(next);
+  };
+  const setView = (next: CalendarViewMode) => {
+    if (props.view === undefined) setOwnView(next);
+    props.onViewChange?.(next);
   };
 
-  return (
-    <View style={styles.root}>
-      <View style={styles.toolbar}>
-        <View style={styles.navGroup}>
-          <FocusRingPressable accessibilityRole="button" onPress={() => step(-1)} accessibilityLabel={L.previous} style={styles.iconBtn}>
-            <Text size="lg" color="muted">‹</Text>
-          </FocusRingPressable>
-          <FocusRingPressable accessibilityRole="button" onPress={() => setDate(new Date())} style={styles.todayBtn}>
-            <Text size="sm" weight="medium">{L.today}</Text>
-          </FocusRingPressable>
-          <FocusRingPressable accessibilityRole="button" onPress={() => step(1)} accessibilityLabel={L.next} style={styles.iconBtn}>
-            <Text size="lg" color="muted">›</Text>
-          </FocusRingPressable>
-        </View>
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  const onLayout = (e: LayoutChangeEvent) => {
+    const { width: w, height: h } = e.nativeEvent.layout;
+    const next = { width: Math.round(w), height: Math.round(h) };
+    setSize((prev) =>
+      Math.abs(prev.width - next.width) > 1 || Math.abs(prev.height - next.height) > 1 ? next : prev,
+    );
+  };
+  // 0 means "not measured yet" — assume roomy, so the first paint of a normal
+  // desktop calendar is not an agenda that flips to a grid a frame later.
+  const tooNarrow = size.width > 0 && size.width < compactBelow;
+  // A grid is unreadable in TWO directions, and only width was ever checked. A
+  // 900px-wide, 360px-tall month gave every row 20px of lane area and rendered
+  // nothing but "+N more" on all thirty-one days.
+  //
+  // The measurement is of the WHOLE calendar, so the chrome comes off before
+  // the grid is asked whether it fits — comparing the total against a grid-only
+  // floor let a 420px calendar through and it rendered exactly the wall of
+  // "+N more" this check exists to prevent.
+  const chromeHeight = children ? 0 : CALENDAR_TOOLBAR_HEIGHT;
+  const tooShort = size.height > 0 && size.height - chromeHeight < MIN_MONTH_HEIGHT;
+  const compact = tooNarrow || tooShort;
+  const effectiveView: CalendarViewMode =
+    compact && (view === "month" || view === "week") ? "agenda" : view;
 
-        <Text size="lg" weight="semibold" style={styles.title} numberOfLines={1}>
-          {viewTitle(view, date, weekStartsOn, locale)}
-        </Text>
+  // Repeating events are expanded to the VIEW's own range, so a daily timetable
+  // costs one event rather than a year of them, and navigating a month back
+  // does not have to have been materialised in advance.
+  const days = useMemo(
+    () => daysInView(effectiveView, date, weekStartsOn),
+    [effectiveView, date, weekStartsOn],
+  );
+  const shown = useMemo(
+    () => expandRepeats(events, days[0], days[days.length - 1]),
+    [events, days],
+  );
 
-        <View style={styles.viewSwitch}>
-          {VIEW_ORDER.map((v) => (
-            <FocusRingPressable accessibilityRole="button"
-              key={v}
-              onPress={() => setView(v)}
-              style={[styles.viewBtn, view === v && styles.viewBtnActive]}
-            >
-              <Text size="sm" weight={view === v ? "medium" : "regular"} color={view === v ? "default" : "muted"}>
-                {L[v]}
-              </Text>
-            </FocusRingPressable>
-          ))}
-        </View>
-      </View>
+  // Resolved against the typed array, so no part ever handles a type it doesn't
+  // know and nothing has to be cast back on the way out. An occurrence resolves
+  // through its source id, so pressing the third Tuesday of a series still
+  // hands the caller the row the series came from.
+  const byId = useMemo(() => new Map(events.map((e) => [e.id, e])), [events]);
+  const resolve = (id: string) => byId.get(id) ?? byId.get(sourceEventId(id));
 
-      <View style={{ flex: 1 }}>
-        {view === "month" ? (
-          <MonthView
-            date={date}
-            events={events}
-            weekStartsOn={weekStartsOn}
-            locale={locale}
-            moreLabel={L.more}
-            onEventPress={onEventPress}
-            onDayPress={drillToDay}
-            onEventDrop={onEventDrop}
-          />
-        ) : (
-          <TimeGridView
-            mode={view}
-            date={date}
-            events={events}
-            weekStartsOn={weekStartsOn}
-            locale={locale}
-            allDayLabel={L.allDay}
-            onEventPress={onEventPress}
-          />
+  const value: CalendarContextValue = {
+    events: shown,
+    date,
+    setDate,
+    view: effectiveView,
+    setView,
+    views: compact ? COMPACT_VIEWS.filter((v) => views.includes(v)) : views,
+    weekStartsOn,
+    locale,
+    labels,
+    now: referenceNow,
+    dayStartMinutes: Math.max(0, Math.min(23, dayStartHour)) * 60,
+    dayEndMinutes: Math.max(1, Math.min(24, dayEndHour)) * 60,
+    onEventPress: onEventPress
+      ? (id) => {
+          const event = resolve(id);
+          if (event) onEventPress(event);
+        }
+      : undefined,
+    onSlotPress,
+    renderEvent: renderEvent
+      ? (event) => {
+          const typed = resolve(event.id);
+          return typed ? renderEvent(typed) : null;
+        }
+      : undefined,
+  };
+
+  return (
+    <View style={styles.root} onLayout={onLayout}>
+      <CalendarProvider value={value}>
+        {children ?? (
+          <>
+            <CalendarToolbar />
+            <CalendarBody />
+          </>
         )}
-      </View>
+      </CalendarProvider>
+    </View>
+  );
+}
+
+/** The current view's grid, without the toolbar — for composing your own chrome
+ *  over the calendar's own view state. */
+export function CalendarBody() {
+  const { view } = useCalendar();
+  return (
+    <View style={styles.body}>
+      {view === "month" ? (
+        <CalendarMonth />
+      ) : view === "week" ? (
+        <CalendarWeek />
+      ) : view === "day" ? (
+        <CalendarDay />
+      ) : (
+        <CalendarAgenda />
+      )}
     </View>
   );
 }
 
 const styles = StyleSheet.create({
-  root: { flex: 1, backgroundColor: colors.white },
-  toolbar: {
-    flexDirection: "row",
-    alignItems: "center",
-    justifyContent: "space-between",
-    paddingHorizontal: 14,
-    paddingVertical: 10,
-    gap: 12,
-    borderBottomWidth: 1,
-    borderBottomColor: colors.border,
-  },
-  navGroup: { flexDirection: "row", alignItems: "center", gap: 4 },
-  iconBtn: { width: 30, height: 30, borderRadius: 6, alignItems: "center", justifyContent: "center" },
-  todayBtn: { paddingHorizontal: 12, height: 30, borderRadius: 6, borderWidth: 1, borderColor: colors.border, alignItems: "center", justifyContent: "center" },
-  title: { flex: 1, textAlign: "center" },
-  viewSwitch: { flexDirection: "row", backgroundColor: colors.zinc[100], borderRadius: 10, padding: 2 },
-  viewBtn: { paddingHorizontal: 12, paddingVertical: 5, borderRadius: 8 },
-  viewBtnActive: { backgroundColor: colors.white },
+  root: { flex: 1, backgroundColor: colors.white, minWidth: 0 },
+  body: { flex: 1, minWidth: 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") {