@super-calendar/core 2.1.4 → 2.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@super-calendar/core?style=flat-square&color=1F6FEB)](https://www.npmjs.com/package/@super-calendar/core) [![JSR](https://img.shields.io/jsr/v/@super-calendar/core?style=flat-square&label=JSR&color=F7DF1E)](https://jsr.io/@super-calendar/core) [![npmx](https://img.shields.io/badge/npmx-view-8A2BE2?style=flat-square)](https://npmx.dev/package/@super-calendar/core)
 
-The render-agnostic core of [super-calendar](https://github.com/afonsojramos/react-native-super-calendar): date math, the selection model, event layout, the month-grid builder, the headless hooks, and the neutral theme tokens.
+The render-agnostic core of [super-calendar](https://github.com/afonsojramos/super-calendar): date math, the selection model, event layout, the month-grid builder, the headless hooks, and the neutral theme tokens.
 
 It imports nothing from React Native, react-dom, Reanimated, Gesture Handler, or Legend List, so it bundles into any renderer. Use it to drive your own UI, or pair it with [`@super-calendar/dom`](https://www.npmjs.com/package/@super-calendar/dom) (react-dom) or [`@super-calendar/native`](https://www.npmjs.com/package/@super-calendar/native) (React Native).
 

package/dist/index.d.mts

@@ -51,6 +51,41 @@ interface RecurrenceRule {
    * the event's time of day. Omit to repeat on the start date's own weekday.
    */
   weekdays?: WeekStartsOn[];
+  /**
+   * For `monthly`/`yearly`: repeat on the Nth weekday of the period instead of the
+   * start date's day-of-month — e.g. `{ week: 3, weekday: 1 }` is the 3rd Monday.
+   * `week` is 1–5, or -1 for the last such weekday. Maps to an ordinal iCal `BYDAY`
+   * (e.g. `3MO`, `-1FR`).
+   */
+  nthWeekday?: {
+    week: number;
+    weekday: WeekStartsOn;
+  };
+  /**
+   * For `monthly`: the day(s) of the month to repeat on — 1–31, or negative to
+   * count from the month's end (-1 is the last day, -2 the second-to-last). Days
+   * that don't exist in a given month (e.g. the 31st in February) are skipped.
+   * Takes precedence over the start date's own day-of-month. Maps to iCal
+   * `BYMONTHDAY`.
+   */
+  monthDays?: number[];
+  /**
+   * For `yearly`: the month(s) to repeat in (1 = January … 12 = December), keeping
+   * the start date's day-of-month. Years where a listed month lacks that day are
+   * skipped. Maps to iCal `BYMONTH`.
+   */
+  months?: number[];
+  /**
+   * Dates to skip (exceptions). An occurrence whose day matches one of these is
+   * dropped by `expandRecurringEvents`. Maps to iCal `EXDATE`.
+   */
+  exdates?: Date[];
+  /**
+   * Extra one-off start dates added to the set, even ones the rule wouldn't
+   * produce. Merged in chronological order and de-duplicated against rule
+   * occurrences; `exdates` still apply. Maps to iCal `RDATE`.
+   */
+  rdates?: Date[];
 }
 /**
  * An event carrying arbitrary extra fields `T` alongside the required shape.
@@ -333,6 +368,26 @@ declare function eventAccessibilityLabel(args: {
   ampm: boolean; /** Spoken text for an all-day event. Default "all day". */
   allDayLabel?: string;
 }): string;
+/**
+ * Context describing how an event is being rendered, passed to a consumer's
+ * {@link EventAccessibilityLabeler} so the label can adapt to the view (e.g. omit
+ * the time in month mode, or read the 12-hour clock when `ampm` is set).
+ */
+interface EventAccessibilityLabelContext {
+  /** The view the event is rendered in. */
+  mode: CalendarMode;
+  /** Whether the event sits in the all-day lane (or is an all-day event in month view). */
+  isAllDay: boolean;
+  /** Whether times are formatted as 12-hour AM/PM. */
+  ampm: boolean;
+}
+/**
+ * Override for an event's screen-reader label. Return the full text to announce
+ * for `event`; each renderer uses it verbatim in place of the built-in
+ * {@link eventAccessibilityLabel}. Shared by both renderers, so a custom label
+ * reads the same on web and native.
+ */
+type EventAccessibilityLabeler<T = unknown> = (event: CalendarEvent<T>, context: EventAccessibilityLabelContext) => string;
 /**
  * Month cells and the all-day lane show a single clipped line; timed-grid titles
  * (`undefined`) wrap to fill the box.
@@ -418,6 +473,47 @@ declare function monthEventCapacity(availableHeightPx: number, chipRowHeightPx:
  */
 declare function monthVisibleCount(total: number, capacity: MonthEventCapacity): number;
 //#endregion
+//#region src/utils/ical.d.ts
+/** An event parsed from iCal, carrying the standard fields it also round-trips. */
+interface ICalEvent extends ICalendarEvent {
+  /** The VEVENT `UID`, if present. */
+  uid?: string;
+  /** The VEVENT `DESCRIPTION`, if present. */
+  description?: string;
+  /** The VEVENT `LOCATION`, if present. */
+  location?: string;
+}
+/** Options for {@link toICalendar}. */
+interface ToICalendarOptions {
+  /** `PRODID` written to the calendar header. Default `-//super-calendar//EN`. */
+  prodId?: string;
+  /** The `DTSTAMP` stamped on every event (when it was written). Default: now. */
+  now?: Date;
+}
+/**
+ * Parse an iCalendar (`.ics`) string into events. Reads every `VEVENT`; ignores
+ * VTODO/VJOURNAL/VTIMEZONE and unknown properties. Events without a usable
+ * `DTSTART` are skipped. All-day events (`VALUE=DATE`) with no `DTEND` get a
+ * one-day span.
+ *
+ * @example
+ * ```ts
+ * const events = parseICalendar(await file.text());
+ * ```
+ */
+declare function parseICalendar(ics: string): ICalEvent[];
+/**
+ * Serialize events to an iCalendar (`.ics`) string. Timed events are written in
+ * UTC (`...Z`); all-day events (`allDay: true`) use `VALUE=DATE`. A `recurrence`
+ * becomes an `RRULE`, and `uid` / `description` / `location` round-trip.
+ *
+ * @example
+ * ```ts
+ * const ics = toICalendar(events);
+ * ```
+ */
+declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
+//#endregion
 //#region src/utils/layout.d.ts
 /** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
 type PositionedEvent<T> = {
@@ -521,10 +617,23 @@ interface MonthGrid {
   /** The weekday header cells, in display order. */
   weekdays: MonthGridWeekday[];
 }
+/**
+ * Weekday header label width: `narrow` ("M"), `short` ("Mon", the default), or
+ * `long` ("Monday").
+ */
+type WeekdayFormat = "narrow" | "short" | "long";
+/**
+ * The date-fns format token for a {@link WeekdayFormat}. Exposed so a renderer
+ * that formats its own weekday header (rather than reading {@link buildMonthGrid})
+ * keeps the same mapping.
+ */
+declare function weekdayFormatToken(format: WeekdayFormat): string;
 /** Options for {@link buildMonthGrid} and {@link useMonthGrid}. */
 interface UseMonthGridOptions extends DateSelectionConstraints {
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
+  /** Weekday header label width. Default `short` ("Mon"). */
+  weekdayFormat?: WeekdayFormat;
   /** Always return six week rows for a fixed-height grid. Default false. */
   showSixWeeks?: boolean;
   /** Reverse each week's day order (right-to-left). Default false. */
@@ -575,6 +684,14 @@ declare function expandRecurringEvents<T>(events: CalendarEvent<T>[], rangeStart
  * original UTC instant, so don't round-trip it back to a real time.
  */
 declare function toZonedTime(date: Date, timeZone: string): Date;
+/**
+ * The inverse of {@link toZonedTime}: given a wall-clock time in `timeZone`,
+ * return the absolute UTC instant. Pass the wall clock as a `Date` whose **UTC**
+ * fields hold the components (e.g. `new Date(Date.UTC(y, m, d, h, min))`). Used to
+ * resolve iCal `TZID` times; DST-correct via a two-pass offset (ambiguous
+ * fall-back times resolve to the post-transition offset).
+ */
+declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
 /**
  * Map every event's `start`/`end` through {@link toZonedTime} so the calendar
  * displays them in `timeZone`. Other fields are preserved. Memoize the result
@@ -582,4 +699,4 @@ declare function toZonedTime(date: Date, timeZone: string): Date;
  */
 declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
 //#endregion
-export { BusinessHours, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventChipLayout, EventKeyExtractor, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, WeekStartsOn, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount };
+export { BusinessHours, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventAccessibilityLabelContext, EventAccessibilityLabeler, EventChipLayout, EventKeyExtractor, ICalEvent, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, ToICalendarOptions, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, WeekStartsOn, WeekdayFormat, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };

package/dist/index.d.ts

@@ -51,6 +51,41 @@ interface RecurrenceRule {
    * the event's time of day. Omit to repeat on the start date's own weekday.
    */
   weekdays?: WeekStartsOn[];
+  /**
+   * For `monthly`/`yearly`: repeat on the Nth weekday of the period instead of the
+   * start date's day-of-month — e.g. `{ week: 3, weekday: 1 }` is the 3rd Monday.
+   * `week` is 1–5, or -1 for the last such weekday. Maps to an ordinal iCal `BYDAY`
+   * (e.g. `3MO`, `-1FR`).
+   */
+  nthWeekday?: {
+    week: number;
+    weekday: WeekStartsOn;
+  };
+  /**
+   * For `monthly`: the day(s) of the month to repeat on — 1–31, or negative to
+   * count from the month's end (-1 is the last day, -2 the second-to-last). Days
+   * that don't exist in a given month (e.g. the 31st in February) are skipped.
+   * Takes precedence over the start date's own day-of-month. Maps to iCal
+   * `BYMONTHDAY`.
+   */
+  monthDays?: number[];
+  /**
+   * For `yearly`: the month(s) to repeat in (1 = January … 12 = December), keeping
+   * the start date's day-of-month. Years where a listed month lacks that day are
+   * skipped. Maps to iCal `BYMONTH`.
+   */
+  months?: number[];
+  /**
+   * Dates to skip (exceptions). An occurrence whose day matches one of these is
+   * dropped by `expandRecurringEvents`. Maps to iCal `EXDATE`.
+   */
+  exdates?: Date[];
+  /**
+   * Extra one-off start dates added to the set, even ones the rule wouldn't
+   * produce. Merged in chronological order and de-duplicated against rule
+   * occurrences; `exdates` still apply. Maps to iCal `RDATE`.
+   */
+  rdates?: Date[];
 }
 /**
  * An event carrying arbitrary extra fields `T` alongside the required shape.
@@ -333,6 +368,26 @@ declare function eventAccessibilityLabel(args: {
   ampm: boolean; /** Spoken text for an all-day event. Default "all day". */
   allDayLabel?: string;
 }): string;
+/**
+ * Context describing how an event is being rendered, passed to a consumer's
+ * {@link EventAccessibilityLabeler} so the label can adapt to the view (e.g. omit
+ * the time in month mode, or read the 12-hour clock when `ampm` is set).
+ */
+interface EventAccessibilityLabelContext {
+  /** The view the event is rendered in. */
+  mode: CalendarMode;
+  /** Whether the event sits in the all-day lane (or is an all-day event in month view). */
+  isAllDay: boolean;
+  /** Whether times are formatted as 12-hour AM/PM. */
+  ampm: boolean;
+}
+/**
+ * Override for an event's screen-reader label. Return the full text to announce
+ * for `event`; each renderer uses it verbatim in place of the built-in
+ * {@link eventAccessibilityLabel}. Shared by both renderers, so a custom label
+ * reads the same on web and native.
+ */
+type EventAccessibilityLabeler<T = unknown> = (event: CalendarEvent<T>, context: EventAccessibilityLabelContext) => string;
 /**
  * Month cells and the all-day lane show a single clipped line; timed-grid titles
  * (`undefined`) wrap to fill the box.
@@ -418,6 +473,47 @@ declare function monthEventCapacity(availableHeightPx: number, chipRowHeightPx:
  */
 declare function monthVisibleCount(total: number, capacity: MonthEventCapacity): number;
 //#endregion
+//#region src/utils/ical.d.ts
+/** An event parsed from iCal, carrying the standard fields it also round-trips. */
+interface ICalEvent extends ICalendarEvent {
+  /** The VEVENT `UID`, if present. */
+  uid?: string;
+  /** The VEVENT `DESCRIPTION`, if present. */
+  description?: string;
+  /** The VEVENT `LOCATION`, if present. */
+  location?: string;
+}
+/** Options for {@link toICalendar}. */
+interface ToICalendarOptions {
+  /** `PRODID` written to the calendar header. Default `-//super-calendar//EN`. */
+  prodId?: string;
+  /** The `DTSTAMP` stamped on every event (when it was written). Default: now. */
+  now?: Date;
+}
+/**
+ * Parse an iCalendar (`.ics`) string into events. Reads every `VEVENT`; ignores
+ * VTODO/VJOURNAL/VTIMEZONE and unknown properties. Events without a usable
+ * `DTSTART` are skipped. All-day events (`VALUE=DATE`) with no `DTEND` get a
+ * one-day span.
+ *
+ * @example
+ * ```ts
+ * const events = parseICalendar(await file.text());
+ * ```
+ */
+declare function parseICalendar(ics: string): ICalEvent[];
+/**
+ * Serialize events to an iCalendar (`.ics`) string. Timed events are written in
+ * UTC (`...Z`); all-day events (`allDay: true`) use `VALUE=DATE`. A `recurrence`
+ * becomes an `RRULE`, and `uid` / `description` / `location` round-trip.
+ *
+ * @example
+ * ```ts
+ * const ics = toICalendar(events);
+ * ```
+ */
+declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
+//#endregion
 //#region src/utils/layout.d.ts
 /** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
 type PositionedEvent<T> = {
@@ -521,10 +617,23 @@ interface MonthGrid {
   /** The weekday header cells, in display order. */
   weekdays: MonthGridWeekday[];
 }
+/**
+ * Weekday header label width: `narrow` ("M"), `short` ("Mon", the default), or
+ * `long` ("Monday").
+ */
+type WeekdayFormat = "narrow" | "short" | "long";
+/**
+ * The date-fns format token for a {@link WeekdayFormat}. Exposed so a renderer
+ * that formats its own weekday header (rather than reading {@link buildMonthGrid})
+ * keeps the same mapping.
+ */
+declare function weekdayFormatToken(format: WeekdayFormat): string;
 /** Options for {@link buildMonthGrid} and {@link useMonthGrid}. */
 interface UseMonthGridOptions extends DateSelectionConstraints {
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
+  /** Weekday header label width. Default `short` ("Mon"). */
+  weekdayFormat?: WeekdayFormat;
   /** Always return six week rows for a fixed-height grid. Default false. */
   showSixWeeks?: boolean;
   /** Reverse each week's day order (right-to-left). Default false. */
@@ -575,6 +684,14 @@ declare function expandRecurringEvents<T>(events: CalendarEvent<T>[], rangeStart
  * original UTC instant, so don't round-trip it back to a real time.
  */
 declare function toZonedTime(date: Date, timeZone: string): Date;
+/**
+ * The inverse of {@link toZonedTime}: given a wall-clock time in `timeZone`,
+ * return the absolute UTC instant. Pass the wall clock as a `Date` whose **UTC**
+ * fields hold the components (e.g. `new Date(Date.UTC(y, m, d, h, min))`). Used to
+ * resolve iCal `TZID` times; DST-correct via a two-pass offset (ambiguous
+ * fall-back times resolve to the post-transition offset).
+ */
+declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
 /**
  * Map every event's `start`/`end` through {@link toZonedTime} so the calendar
  * displays them in `timeZone`. Other fields are preserved. Memoize the result
@@ -582,4 +699,4 @@ declare function toZonedTime(date: Date, timeZone: string): Date;
  */
 declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
 //#endregion
-export { BusinessHours, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventChipLayout, EventKeyExtractor, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, WeekStartsOn, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount };
+export { BusinessHours, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventAccessibilityLabelContext, EventAccessibilityLabeler, EventChipLayout, EventKeyExtractor, ICalEvent, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, ToICalendarOptions, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, WeekStartsOn, WeekdayFormat, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };