@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/calendar/index.ts

@@ -0,0 +1,39 @@
+export { useMonth } from './useMonth';
+export type { UseMonthOptions } from './useMonth';
+export { useWeek } from './useWeek';
+export type { UseWeekOptions, WeekResult } from './useWeek';
+export { useDay } from './useDay';
+export type { UseDayOptions, DayResult } from './useDay';
+export { useAgenda } from './useAgenda';
+export type { UseAgendaOptions, AgendaResult } from './useAgenda';
+export type { Day, Week, MonthGrid } from './types';
+
+export {
+  addDays,
+  addMonths,
+  addWeeks,
+  startOfDay,
+  startOfWeek,
+  startOfMonth,
+  endOfMonth,
+  isSameDay,
+  isSameMonth,
+  isToday,
+  isWeekend,
+  daysBetween,
+  toDateKey,
+  fromDateKey,
+} from './dateMath';
+
+export {
+  formatMonth,
+  formatWeekdayShort,
+  formatWeekdayNarrow,
+  formatDayShort,
+  formatDayLong,
+  formatRange,
+  formatHour,
+  formatTime,
+} from './formatters';
+
+export { getFirstDayOfWeek, getWeekendDays } from './weekInfo';

package/src/calendar/types.ts

@@ -0,0 +1,36 @@
+/**
+ * A single calendar day. Produced by every Calendar primitive hook so consumer
+ * components render a consistent shape regardless of view (month/week/day/agenda).
+ */
+export interface Day {
+  /** Local midnight of this calendar day. Time component is always 00:00:00.000. */
+  date: Date;
+  /** 1..31. */
+  dayOfMonth: number;
+  /** False for trailing/leading days from adjacent months in a `useMonth` grid. */
+  isCurrentMonth: boolean;
+  isToday: boolean;
+  /** Locale-aware — `[5, 6]` (Fri/Sat) for ar-SA/he-IL, `[0, 6]` (Sat/Sun) for most. */
+  isWeekend: boolean;
+  /** 0..6, where 0 is the locale's first-day-of-week. Useful for styling column position. */
+  weekday: number;
+  /** 'YYYY-MM-DD' in local time. Stable React key, comparison handle, event-lookup index. */
+  key: string;
+}
+
+/** A full week, always seven `Day`s. */
+export type Week = readonly [Day, Day, Day, Day, Day, Day, Day];
+
+/** Result of `useMonth`. */
+export interface MonthGrid {
+  /** Calendar year of the anchor month (e.g., 2026). */
+  year: number;
+  /** 0..11, JS Date convention. */
+  month: number;
+  /** Localized month + year label, e.g., "May 2026" / "Май 2026". */
+  monthLabel: string;
+  /** Length 7, in display order (locale's first-day-of-week first). */
+  weekdayLabels: readonly string[];
+  /** 4–6 full weeks; leading/trailing days are filled from adjacent months. */
+  weeks: readonly Week[];
+}

package/src/calendar/useAgenda.ts

@@ -0,0 +1,70 @@
+import { useMemo } from 'react';
+import { useLocale } from '../i18n/useLocale';
+import {
+  addDays,
+  daysBetween,
+  isSameMonth,
+  isToday,
+  isWeekend,
+  startOfDay,
+  toDateKey,
+} from './dateMath';
+import { formatRange } from './formatters';
+import { getFirstDayOfWeek, getWeekendDays } from './weekInfo';
+import type { Day } from './types';
+
+/** Options for {@link useAgenda}. */
+export interface UseAgendaOptions {
+  /** Override the active locale. */
+  locale?: string;
+  /** Override the first day of the week. Defaults to `getFirstDayOfWeek(locale)`. */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+/** Result shape returned by {@link useAgenda}. */
+export interface AgendaResult {
+  /** One `Day` per calendar day in `[from, to]`, inclusive at both ends. */
+  days: readonly Day[];
+  /** Localized range label spanning `from` to `to`. */
+  rangeLabel: string;
+}
+
+/**
+ * Returns one `Day` entry per calendar day in `[from, to]` (inclusive at both
+ * ends). When `from > to` the result is a single-day agenda for `from` — pass
+ * `from <= to` to the hook to get the intended range.
+ *
+ * Used by `<AgendaView>` (via the `<Calendar>` shell) to group events by day.
+ */
+export function useAgenda(from: Date, to: Date, options: UseAgendaOptions = {}): AgendaResult {
+  const contextLocale = useLocale();
+  const locale = options.locale ?? contextLocale;
+  const weekStartsOn = options.weekStartsOn ?? getFirstDayOfWeek(locale);
+
+  return useMemo(() => {
+    const start = startOfDay(from);
+    const end = startOfDay(to);
+    const count = Math.max(0, daysBetween(start, end)) + 1;
+    const weekendDays = getWeekendDays(locale);
+
+    const days: Day[] = [];
+    for (let i = 0; i < count; i++) {
+      const date = addDays(start, i);
+      days.push({
+        date,
+        dayOfMonth: date.getDate(),
+        isCurrentMonth: isSameMonth(date, start),
+        isToday: isToday(date),
+        isWeekend: isWeekend(date, weekendDays),
+        weekday: (date.getDay() - weekStartsOn + 7) % 7,
+        key: toDateKey(date),
+      });
+    }
+
+    return {
+      days,
+      rangeLabel: formatRange(start, end, locale),
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [from.getTime(), to.getTime(), locale, weekStartsOn]);
+}

package/src/calendar/useDay.ts

@@ -0,0 +1,51 @@
+import { useMemo } from 'react';
+import { useLocale } from '../i18n/useLocale';
+import { isToday, isWeekend, startOfDay, toDateKey } from './dateMath';
+import { formatDayLong, formatDayShort } from './formatters';
+import { getFirstDayOfWeek, getWeekendDays } from './weekInfo';
+import type { Day } from './types';
+
+/** Options for {@link useDay}. */
+export interface UseDayOptions {
+  /** Override the active locale. */
+  locale?: string;
+}
+
+/** Result shape returned by {@link useDay}. */
+export interface DayResult {
+  day: Day;
+  /** "Wednesday, May 20" */
+  dayLabel: string;
+  /** "Wed 20" */
+  dayShortLabel: string;
+}
+
+/**
+ * Returns the canonical `Day` for `date` plus localized labels. Used by
+ * the future `<DayView>` (1 column × 24 hours).
+ */
+export function useDay(date: Date, options: UseDayOptions = {}): DayResult {
+  const contextLocale = useLocale();
+  const locale = options.locale ?? contextLocale;
+
+  return useMemo(() => {
+    const normalized = startOfDay(date);
+    const weekendDays = getWeekendDays(locale);
+    const weekStartsOn = getFirstDayOfWeek(locale);
+    const day: Day = {
+      date: normalized,
+      dayOfMonth: normalized.getDate(),
+      isCurrentMonth: true,
+      isToday: isToday(normalized),
+      isWeekend: isWeekend(normalized, weekendDays),
+      weekday: (normalized.getDay() - weekStartsOn + 7) % 7,
+      key: toDateKey(normalized),
+    };
+    return {
+      day,
+      dayLabel: formatDayLong(normalized, locale),
+      dayShortLabel: formatDayShort(normalized, locale),
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [date.getTime(), locale]);
+}

package/src/calendar/useMonth.ts

@@ -0,0 +1,82 @@
+import { useMemo } from 'react';
+import { useLocale } from '../i18n/useLocale';
+import {
+  addDays,
+  endOfMonth,
+  isSameMonth,
+  isToday,
+  isWeekend,
+  startOfMonth,
+  startOfWeek,
+  toDateKey,
+} from './dateMath';
+import { formatMonth, formatWeekdayShort } from './formatters';
+import { getFirstDayOfWeek, getWeekendDays } from './weekInfo';
+import type { Day, MonthGrid, Week } from './types';
+
+/** Options for {@link useMonth}. */
+export interface UseMonthOptions {
+  /** Override the active locale. Defaults to `useLocale()`. */
+  locale?: string;
+  /** Override the first day of the week. Defaults to `getFirstDayOfWeek(locale)`. */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+/**
+ * Returns the month grid containing `anchor`, with leading/trailing days from
+ * adjacent months so every week has exactly 7 days. Locale-aware month label,
+ * weekday header labels, and first-day-of-week.
+ *
+ * The result is `useMemo`-stable across re-renders for the same
+ * `(anchor.getTime(), locale, weekStartsOn)`.
+ */
+export function useMonth(anchor: Date, options: UseMonthOptions = {}): MonthGrid {
+  const contextLocale = useLocale();
+  const locale = options.locale ?? contextLocale;
+  const weekStartsOn = options.weekStartsOn ?? getFirstDayOfWeek(locale);
+
+  return useMemo(() => {
+    const anchorMonth = startOfMonth(anchor);
+    const gridStart = startOfWeek(anchorMonth, weekStartsOn);
+    const weekendDays = getWeekendDays(locale);
+
+    const weeks: Week[] = [];
+    let cursor = gridStart;
+    const anchorEnd = endOfMonth(anchor);
+    for (let w = 0; w < 6; w++) {
+      // Stop if the next week would start entirely after the anchor month.
+      if (w > 0 && cursor > anchorEnd) {
+        break;
+      }
+      const week: Day[] = [];
+      for (let d = 0; d < 7; d++) {
+        const date = new Date(cursor);
+        week.push({
+          date,
+          dayOfMonth: date.getDate(),
+          isCurrentMonth: isSameMonth(date, anchor),
+          isToday: isToday(date),
+          isWeekend: isWeekend(date, weekendDays),
+          weekday: d,
+          key: toDateKey(date),
+        });
+        cursor = addDays(cursor, 1);
+      }
+      weeks.push(week as unknown as Week);
+    }
+
+    const weekdayLabels: string[] = [];
+    for (let d = 0; d < 7; d++) {
+      weekdayLabels.push(formatWeekdayShort(addDays(gridStart, d), locale));
+    }
+
+    return {
+      year: anchor.getFullYear(),
+      month: anchor.getMonth(),
+      monthLabel: formatMonth(anchor, locale),
+      weekdayLabels,
+      weeks,
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [anchor.getTime(), locale, weekStartsOn]);
+}

package/src/calendar/useWeek.ts

@@ -0,0 +1,62 @@
+import { useMemo } from 'react';
+import { useLocale } from '../i18n/useLocale';
+import { addDays, isToday, isWeekend, isSameMonth, startOfWeek, toDateKey } from './dateMath';
+import { formatRange, formatWeekdayShort } from './formatters';
+import { getFirstDayOfWeek, getWeekendDays } from './weekInfo';
+import type { Day, Week } from './types';
+
+/** Options for {@link useWeek}. */
+export interface UseWeekOptions {
+  /** Override the active locale. */
+  locale?: string;
+  /** Override the first day of the week. */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+/** Result shape returned by {@link useWeek}. */
+export interface WeekResult {
+  /** Localized range label, e.g., "May 18 – 24, 2026". */
+  weekLabel: string;
+  /** Seven days starting from the locale-determined (or overridden) week start. */
+  days: Week;
+  /** Length 7, display order. */
+  weekdayLabels: readonly string[];
+}
+
+/**
+ * Returns the 7-day week containing `anchor`, starting from the locale's
+ * first-day-of-week. Useful for the future `<WeekView>` (7 columns × 24 hours).
+ */
+export function useWeek(anchor: Date, options: UseWeekOptions = {}): WeekResult {
+  const contextLocale = useLocale();
+  const locale = options.locale ?? contextLocale;
+  const weekStartsOn = options.weekStartsOn ?? getFirstDayOfWeek(locale);
+
+  return useMemo(() => {
+    const start = startOfWeek(anchor, weekStartsOn);
+    const weekendDays = getWeekendDays(locale);
+
+    const days: Day[] = [];
+    for (let i = 0; i < 7; i++) {
+      const date = addDays(start, i);
+      days.push({
+        date,
+        dayOfMonth: date.getDate(),
+        isCurrentMonth: isSameMonth(date, anchor),
+        isToday: isToday(date),
+        isWeekend: isWeekend(date, weekendDays),
+        weekday: i,
+        key: toDateKey(date),
+      });
+    }
+
+    const weekdayLabels = days.map((d) => formatWeekdayShort(d.date, locale));
+
+    return {
+      weekLabel: formatRange(start, days[6].date, locale),
+      days: days as unknown as Week,
+      weekdayLabels,
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [anchor.getTime(), locale, weekStartsOn]);
+}

package/src/calendar/weekInfo.ts

@@ -0,0 +1,83 @@
+type DayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+// Static fallbacks for when Intl.Locale.getWeekInfo is unavailable (older runtimes).
+// firstDay: 0=Sun, 1=Mon (JS day numbering).
+const FALLBACK_FIRST_DAY: Record<string, DayIndex> = {
+  'en-US': 0,
+  'en-CA': 0,
+  'ja-JP': 0,
+};
+
+// weekend: arrays in JS day numbering (0=Sun, 6=Sat), sorted ascending.
+const FALLBACK_WEEKEND: Record<string, readonly DayIndex[]> = {
+  'ar-SA': [5, 6],
+  'he-IL': [5, 6],
+};
+
+/**
+ * Try `Intl.Locale(locale).getWeekInfo()`; return `undefined` if the API
+ * is unavailable (older runtimes) or the locale throws.
+ *
+ * NOTE: getWeekInfo uses ISO weekday numbering (Mon=1…Sun=7).
+ * We normalise to JS day numbering (Sun=0…Sat=6) via `isoDay % 7`.
+ */
+function tryWeekInfo(
+  locale: string,
+): { firstDay: DayIndex; weekend: readonly DayIndex[] } | undefined {
+  try {
+    const loc = new Intl.Locale(locale);
+    const getWeekInfo = (
+      loc as Intl.Locale & { getWeekInfo?: () => { firstDay: number; weekend: number[] } }
+    ).getWeekInfo;
+    if (!getWeekInfo) return undefined;
+    const info = getWeekInfo.call(loc);
+    if (!info) return undefined;
+    // Convert ISO weekday (1=Mon…7=Sun) → JS day (0=Sun…6=Sat)
+    const firstDay = (info.firstDay % 7) as DayIndex;
+    const weekend = info.weekend.map((d) => (d % 7) as DayIndex).sort((a, b) => a - b);
+    return { firstDay, weekend };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Lookup `locale` in a fallback map first by exact tag (`en-US`), then by
+ * primary language subtag (`en`), then return `defaultValue`.
+ */
+function lookup<T>(map: Record<string, T>, locale: string, defaultValue: T): T {
+  if (locale in map) return map[locale];
+  const primary = locale.split('-')[0];
+  if (primary in map) return map[primary];
+  return defaultValue;
+}
+
+/**
+ * Returns the first day of the week for the given locale as a JS day index
+ * (0=Sunday, 1=Monday, …, 6=Saturday).
+ *
+ * Uses `Intl.Locale.getWeekInfo()` when available; falls back to a static
+ * table for well-known locales, then defaults to Monday (1).
+ */
+export function getFirstDayOfWeek(locale: string): DayIndex {
+  const info = tryWeekInfo(locale);
+  if (info !== undefined) {
+    return info.firstDay;
+  }
+  return lookup(FALLBACK_FIRST_DAY, locale, 1);
+}
+
+/**
+ * Returns the weekend days for the given locale as an array of JS day indices
+ * (0=Sunday, 6=Saturday), sorted ascending.
+ *
+ * Uses `Intl.Locale.getWeekInfo()` when available; falls back to a static
+ * table for well-known locales, then defaults to [0, 6] (Sat/Sun).
+ */
+export function getWeekendDays(locale: string): readonly DayIndex[] {
+  const info = tryWeekInfo(locale);
+  if (info !== undefined) {
+    return info.weekend;
+  }
+  return lookup(FALLBACK_WEEKEND, locale, [0, 6]);
+}