@midnight-owl/ui 1.0.0

package/dist/components/data-display/calendar/Calendar.vue.d.ts

@@ -0,0 +1,116 @@
+import { type Locale } from 'date-fns';
+import type { BusinessHours, CalendarEvent, CalendarProvider, CalendarSize, CalendarView, EventChange, NormalizedEvent, RangeSelection, WeekdayIndex } from './types';
+interface Props {
+    /** Active view. Also emits `update:view` so it works with v-model:view. */
+    view?: CalendarView;
+    /** Focal date. Emits `update:date` on navigation for v-model:date. */
+    date?: Date | string;
+    events?: CalendarEvent[];
+    size?: CalendarSize;
+    firstDayOfWeek?: WeekdayIndex;
+    timeZone?: string;
+    locale?: Locale;
+    provider?: CalendarProvider;
+    dayStartHour?: number;
+    dayEndHour?: number;
+    agendaDayCount?: number;
+    businessHours?: BusinessHours | boolean;
+    /** Which view buttons to show in the toolbar. Defaults to all five. */
+    availableViews?: CalendarView[];
+    /** Show the built-in toolbar (nav + title + view switcher). */
+    showToolbar?: boolean;
+    /** Show the toolbar's prev/next navigation buttons. */
+    showNav?: boolean;
+    /** Show the toolbar's Today button. */
+    showToday?: boolean;
+    /** Show the toolbar's period title (cal.title). */
+    showTitle?: boolean;
+    /** Below the `sm` breakpoint, swap month→agenda and week→day for readability. */
+    mobileFallback?: boolean;
+    /** Master switch for drag/resize/edit/delete affordances. */
+    editable?: boolean;
+    /** Open the built-in event popover on click (else just emit `event-click`). */
+    showPopover?: boolean;
+    /** Show the toolbar's print button. */
+    printable?: boolean;
+    /** Show the built-in loading spinner (ORed with a provider fetch's own isLoading). */
+    loading?: boolean;
+    /** Show the built-in error banner (ORed with a provider fetch's own error). */
+    error?: string | Error | null;
+    /** T = today, ←/→ = prev/next, M/W/D = switch view. Scoped to this instance's own focus. */
+    keyboardShortcuts?: boolean;
+}
+declare var __VLS_1: {
+    cal: import("./useCalendar").UseCalendarReturn;
+    title: string;
+    view: CalendarView;
+    next: () => void;
+    prev: () => void;
+    today: () => void;
+    setView: (view: CalendarView) => void;
+}, __VLS_79: any, __VLS_82: any, __VLS_85: {}, __VLS_97: {
+    event: NormalizedEvent;
+    close: () => void;
+    edit: () => void;
+    delete: () => void;
+};
+type __VLS_Slots = {} & {
+    toolbar?: (props: typeof __VLS_1) => any;
+} & {
+    event?: (props: typeof __VLS_79) => any;
+} & {
+    dayCell?: (props: typeof __VLS_82) => any;
+} & {
+    empty?: (props: typeof __VLS_85) => any;
+} & {
+    eventPopover?: (props: typeof __VLS_97) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    "event-click": (event: NormalizedEvent, native: MouseEvent) => any;
+    "date-click": (date: Date) => any;
+    "event-drag": (event: NormalizedEvent, change: EventChange) => any;
+    "event-resize": (event: NormalizedEvent, change: EventChange) => any;
+    "range-select": (range: RangeSelection) => any;
+    "update:view": (view: CalendarView) => any;
+    "update:date": (date: Date) => any;
+    "view-change": (view: CalendarView) => any;
+    "event-edit": (event: NormalizedEvent) => any;
+    "event-delete": (event: NormalizedEvent) => any;
+    retry: () => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    "onEvent-click"?: ((event: NormalizedEvent, native: MouseEvent) => any) | undefined;
+    "onDate-click"?: ((date: Date) => any) | undefined;
+    "onEvent-drag"?: ((event: NormalizedEvent, change: EventChange) => any) | undefined;
+    "onEvent-resize"?: ((event: NormalizedEvent, change: EventChange) => any) | undefined;
+    "onRange-select"?: ((range: RangeSelection) => any) | undefined;
+    "onUpdate:view"?: ((view: CalendarView) => any) | undefined;
+    "onUpdate:date"?: ((date: Date) => any) | undefined;
+    "onView-change"?: ((view: CalendarView) => any) | undefined;
+    "onEvent-edit"?: ((event: NormalizedEvent) => any) | undefined;
+    "onEvent-delete"?: ((event: NormalizedEvent) => any) | undefined;
+    onRetry?: (() => any) | undefined;
+}>, {
+    size: CalendarSize;
+    loading: boolean;
+    view: CalendarView;
+    error: string | Error | null;
+    editable: boolean;
+    firstDayOfWeek: WeekdayIndex;
+    availableViews: CalendarView[];
+    showToolbar: boolean;
+    showNav: boolean;
+    showToday: boolean;
+    showTitle: boolean;
+    mobileFallback: boolean;
+    showPopover: boolean;
+    printable: boolean;
+    keyboardShortcuts: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/data-display/calendar/CalendarAgendaView.vue.d.ts

@@ -0,0 +1,31 @@
+import type { CalendarSize, NormalizedEvent } from './types';
+import type { UseCalendarReturn } from './useCalendar';
+interface Props {
+    cal: UseCalendarReturn;
+    size?: CalendarSize;
+}
+declare var __VLS_1: {
+    event: NormalizedEvent;
+    timeLabel: string;
+    display: string;
+}, __VLS_8: {};
+type __VLS_Slots = {} & {
+    event?: (props: typeof __VLS_1) => any;
+} & {
+    empty?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    "event-click": (event: NormalizedEvent, native: MouseEvent) => any;
+    "date-click": (date: Date) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    "onEvent-click"?: ((event: NormalizedEvent, native: MouseEvent) => any) | undefined;
+    "onDate-click"?: ((date: Date) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/data-display/calendar/CalendarEventDetails.vue.d.ts

@@ -0,0 +1,23 @@
+import type { NormalizedEvent } from './types';
+interface Props {
+    event: NormalizedEvent;
+    /** Pre-formatted, timezone-aware date/time range from the parent. */
+    whenText?: string;
+    /** Show the Edit/Delete footer (event is editable and the source allows it). */
+    editable?: boolean;
+    /** Whether a delete affordance is available (provider supports it, etc.). */
+    canDelete?: boolean;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    delete: () => any;
+    edit: () => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    onDelete?: (() => any) | undefined;
+    onEdit?: (() => any) | undefined;
+}>, {
+    editable: boolean;
+    whenText: string;
+    canDelete: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/data-display/calendar/CalendarEventPill.vue.d.ts

@@ -0,0 +1,39 @@
+import type { NormalizedEvent } from './types';
+interface Props {
+    event: NormalizedEvent;
+    /**
+     * dot = compact month chip, block = time-grid fill, list = agenda row,
+     * bar = continuous multi-day/all-day span (month grid + all-day gutter).
+     */
+    display?: 'dot' | 'block' | 'list' | 'bar';
+    /** Localized time label, computed by the parent (timezone-aware). */
+    timeLabel?: string;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * For `block` display: the rendered band is too short for the stacked
+     * title/time/location layout, so collapse to a single truncated line. Set by
+     * the time-grid view from the event's actual pixel height.
+     */
+    compact?: boolean;
+    /** For `bar` display: the span is clipped at this row's start edge (earlier). */
+    continuesBefore?: boolean;
+    /** For `bar` display: the span is clipped at this row's end edge (later). */
+    continuesAfter?: boolean;
+    /**
+     * Show timeLabel even when event.allDay — used by the month-grid drag
+     * ghost, which always wants its live date-range text regardless of the
+     * real event's own all-day-ness.
+     */
+    forceShowTimeLabel?: boolean;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {
+    size: "xs" | "sm" | "md" | "lg" | "xl";
+    compact: boolean;
+    display: "dot" | "block" | "list" | "bar";
+    timeLabel: string;
+    continuesBefore: boolean;
+    continuesAfter: boolean;
+    forceShowTimeLabel: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/data-display/calendar/CalendarEventPopover.vue.d.ts

@@ -0,0 +1,68 @@
+import type { PopoverVirtualReference } from '../../panel/Popover.vue';
+import type { Boundary } from '@floating-ui/vue';
+import type { CalendarSize, NormalizedEvent } from './types';
+interface Props {
+    /** Virtual anchor (the clicked pill's rect). Passed straight to Popover. */
+    reference?: PopoverVirtualReference | null;
+    event?: NormalizedEvent | null;
+    /** Pre-formatted, timezone-aware date/time range from the parent. */
+    whenText?: string;
+    editable?: boolean;
+    canDelete?: boolean;
+    /**
+     * Present as a bottom sheet instead of a floating popover. Driven by the
+     * parent's existing mobile detection — presentational only, no forked state.
+     */
+    mobile?: boolean;
+    size?: CalendarSize;
+    /** Forwarded to the underlying Popover's collision boundary. */
+    boundary?: Boundary;
+}
+type __VLS_Props = Props;
+type __VLS_ModelProps = {
+    modelValue?: boolean;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare var __VLS_9: {
+    event: NormalizedEvent;
+    close: () => void;
+    edit: () => void;
+    delete: () => void;
+}, __VLS_37: {
+    event: NormalizedEvent;
+    close: () => void;
+    edit: () => void;
+    delete: () => void;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_9) => any;
+} & {
+    default?: (props: typeof __VLS_37) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: boolean) => any;
+} & {
+    close: () => any;
+    delete: (event: NormalizedEvent) => any;
+    edit: (event: NormalizedEvent) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
+    onClose?: (() => any) | undefined;
+    onDelete?: ((event: NormalizedEvent) => any) | undefined;
+    onEdit?: ((event: NormalizedEvent) => any) | undefined;
+}>, {
+    mobile: boolean;
+    reference: PopoverVirtualReference | null;
+    editable: boolean;
+    event: NormalizedEvent | null;
+    whenText: string;
+    canDelete: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/data-display/calendar/CalendarMonthView.vue.d.ts

@@ -0,0 +1,54 @@
+import type { CalendarDayCell, CalendarSize, EventChange, NormalizedEvent, RangeSelection } from './types';
+import type { UseCalendarReturn } from './useCalendar';
+interface Props {
+    cal: UseCalendarReturn;
+    size?: CalendarSize;
+    editable?: boolean;
+    /** Max stacked rows (spanning bars + chips) per cell before a "+N more" row. */
+    maxPerCell?: number;
+}
+declare var __VLS_1: {
+    cell: CalendarDayCell;
+}, __VLS_3: {
+    event: NormalizedEvent;
+    timeLabel: string;
+    compact: boolean;
+    display: string;
+}, __VLS_23: {
+    event: NormalizedEvent;
+    timeLabel: string;
+    compact: boolean;
+    display: string;
+};
+type __VLS_Slots = {} & {
+    dayCell?: (props: typeof __VLS_1) => any;
+} & {
+    event?: (props: typeof __VLS_3) => any;
+} & {
+    event?: (props: typeof __VLS_23) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    "event-click": (event: NormalizedEvent, native: MouseEvent) => any;
+    "date-click": (date: Date) => any;
+    "event-drag": (event: NormalizedEvent, change: EventChange) => any;
+    "event-resize": (event: NormalizedEvent, change: EventChange) => any;
+    "range-select": (range: RangeSelection) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    "onEvent-click"?: ((event: NormalizedEvent, native: MouseEvent) => any) | undefined;
+    "onDate-click"?: ((date: Date) => any) | undefined;
+    "onEvent-drag"?: ((event: NormalizedEvent, change: EventChange) => any) | undefined;
+    "onEvent-resize"?: ((event: NormalizedEvent, change: EventChange) => any) | undefined;
+    "onRange-select"?: ((range: RangeSelection) => any) | undefined;
+}>, {
+    size: CalendarSize;
+    editable: boolean;
+    maxPerCell: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/data-display/calendar/CalendarTimeGridView.vue.d.ts

@@ -0,0 +1,47 @@
+import type { CalendarSize, EventChange, NormalizedEvent, RangeSelection } from './types';
+import type { UseCalendarReturn } from './useCalendar';
+interface Props {
+    cal: UseCalendarReturn;
+    size?: CalendarSize;
+    editable?: boolean;
+}
+declare var __VLS_1: {
+    event: NormalizedEvent;
+    timeLabel: string;
+    compact: boolean;
+    display: string;
+}, __VLS_8: {
+    event: NormalizedEvent;
+    timeLabel: string;
+    compact: boolean;
+    display: string;
+};
+type __VLS_Slots = {} & {
+    event?: (props: typeof __VLS_1) => any;
+} & {
+    event?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    "event-click": (event: NormalizedEvent, native: MouseEvent) => any;
+    "date-click": (date: Date) => any;
+    "event-drag": (event: NormalizedEvent, change: EventChange) => any;
+    "event-resize": (event: NormalizedEvent, change: EventChange) => any;
+    "range-select": (range: RangeSelection) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    "onEvent-click"?: ((event: NormalizedEvent, native: MouseEvent) => any) | undefined;
+    "onDate-click"?: ((date: Date) => any) | undefined;
+    "onEvent-drag"?: ((event: NormalizedEvent, change: EventChange) => any) | undefined;
+    "onEvent-resize"?: ((event: NormalizedEvent, change: EventChange) => any) | undefined;
+    "onRange-select"?: ((range: RangeSelection) => any) | undefined;
+}>, {
+    size: CalendarSize;
+    editable: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/data-display/calendar/CalendarYearView.vue.d.ts

@@ -0,0 +1,17 @@
+import type { CalendarSize } from './types';
+import type { UseCalendarReturn } from './useCalendar';
+interface Props {
+    cal: UseCalendarReturn;
+    size?: CalendarSize;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    "date-click": (date: Date) => any;
+    "month-click": (date: Date) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    "onDate-click"?: ((date: Date) => any) | undefined;
+    "onMonth-click"?: ((date: Date) => any) | undefined;
+}>, {
+    size: CalendarSize;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/data-display/calendar/layout.d.ts

@@ -0,0 +1,39 @@
+import type { NormalizedEvent } from './types';
+export interface PositionedEvent {
+    event: NormalizedEvent;
+    /** Top offset as a 0–100 percentage of the visible grid height. */
+    top: number;
+    /** Height as a 0–100 percentage of the visible grid height. */
+    height: number;
+    /** 0-based column within its overlap cluster. */
+    lane: number;
+    /** Total columns in this event's overlap cluster. */
+    lanes: number;
+}
+export interface DayLayoutOptions {
+    dayStartHour: number;
+    dayEndHour: number;
+    timeZone?: string;
+    /** Minimum band height in percent so a short event stays clickable. */
+    minHeightPct?: number;
+}
+export declare function layoutDayEvents(events: NormalizedEvent[], options: DayLayoutOptions): PositionedEvent[];
+export interface SpanSegment {
+    event: NormalizedEvent;
+    /** First covered column within this row (0-based, inclusive). */
+    startCol: number;
+    /** Last covered column within this row (0-based, inclusive). */
+    endCol: number;
+    /** Vertical lane within the row; bars on the same lane never overlap. */
+    lane: number;
+    /** The event's true start is earlier than this row — clip/chevron the left edge. */
+    continuesBefore: boolean;
+    /** The event's true end is later than this row — clip/chevron the right edge. */
+    continuesAfter: boolean;
+}
+export interface SpanLayout {
+    segments: SpanSegment[];
+    /** Highest lane index used + 1 (0 when the row has no spanning events). */
+    laneCount: number;
+}
+export declare function layoutSpanRow(days: Date[], events: NormalizedEvent[]): SpanLayout;

package/dist/components/data-display/calendar/providers/google.d.ts

@@ -0,0 +1,16 @@
+import type { CalendarProvider, CalendarProviderAuth } from '../types';
+export interface GoogleAdapterOptions {
+    /** Returns a valid OAuth 2.0 access token (Calendar scope). You own the flow. */
+    getAccessToken: () => string | Promise<string>;
+    /** Target calendar. Defaults to the signed-in user's `primary` calendar. */
+    calendarId?: string;
+    name?: string;
+    /** Optional sign-in/out surface, forwarded to the composable's connect/disconnect. */
+    auth?: CalendarProviderAuth;
+}
+/**
+ * Build a read/write CalendarProvider for Google Calendar. Requires a
+ * `getAccessToken` — see the file header on why the OAuth flow itself is
+ * out of scope for this PR.
+ */
+export declare function createGoogleAdapter(options: GoogleAdapterOptions): CalendarProvider;

package/dist/components/data-display/calendar/providers/ics.d.ts

@@ -0,0 +1,23 @@
+import type { CalendarEvent, CalendarProvider } from '../types';
+/** Parse a full ICS document into CalendarEvents. */
+export declare function parseIcs(text: string): CalendarEvent[];
+/** Serialize CalendarEvents into a complete ICS document. */
+export declare function generateIcs(events: CalendarEvent[], meta?: {
+    prodId?: string;
+    calName?: string;
+}): string;
+export interface IcsAdapterOptions {
+    /**
+     * The ICS document. A string, or a (possibly async) getter — e.g. one that
+     * `fetch`es a subscription URL. Called on every `fetchEvents`, so a getter
+     * can return fresh data.
+     */
+    source: string | (() => string | Promise<string>);
+    name?: string;
+}
+/**
+ * Build a read-only CalendarProvider backed by an ICS document. Mutation hooks
+ * are intentionally omitted — a `.ics` file/feed is a snapshot, not a writable
+ * store — so the UI hides create/edit/delete affordances automatically.
+ */
+export declare function createIcsAdapter(options: IcsAdapterOptions): CalendarProvider;

package/dist/components/data-display/calendar/recurrence.d.ts

@@ -0,0 +1,12 @@
+import type { DateRange, RecurrenceRule } from './types';
+/**
+ * Expand a recurring series into the concrete occurrence **start** dates that
+ * fall within `range` (padded by the caller for multi-day overlap). Returns an
+ * ascending list; the caller reapplies the event's duration to derive each end.
+ *
+ * `count` is measured from the true series start, so when it's set we generate
+ * from `dtstart` to honor it exactly. When it's absent, we fast-forward close to
+ * the range first — otherwise a long-running rule would generate every
+ * occurrence since its start just to reach the visible range.
+ */
+export declare function expandRecurrence(dtstart: Date, rule: RecurrenceRule, range: DateRange): Date[];

package/dist/components/data-display/calendar/types.d.ts

@@ -0,0 +1,154 @@
+/** The five first-class layouts. Keyed everywhere as a Record, never branched. */
+export type CalendarView = 'month' | 'week' | 'day' | 'agenda' | 'year';
+/** Density scale, shared with the rest of the library's `size` convention. */
+export type CalendarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Event color intent. The six standard library severities only — the calendar
+ * deliberately does not introduce its own color system (see PROJECT.md's
+ * theming rule); an event's color is always one of these semantic tokens.
+ */
+export type EventSeverity = 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info';
+/** 0 = Sunday … 6 = Saturday, matching JS `Date.getDay()` and date-fns. */
+export type WeekdayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Accepted anywhere a weekday is named — numeric index or the iCal 2-letter code. */
+export type WeekdayCode = 'su' | 'mo' | 'tu' | 'we' | 'th' | 'fr' | 'sa';
+export type Weekday = WeekdayIndex | WeekdayCode;
+/**
+ * Hand-rolled recurrence rule — a pragmatic subset of RFC 5545's RRULE that
+ * covers the overwhelming majority of real calendars without pulling in the
+ * `rrule` dependency. Expanded by `expandRecurrence()`; unsupported edge cases
+ * (BYSETPOS, BYYEARDAY, nested FREQ) are intentionally out of scope.
+ */
+export interface RecurrenceRule {
+    freq: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    /** Step between occurrences in `freq` units. Defaults to 1. */
+    interval?: number;
+    /** Total number of occurrences, counted from the series start (inclusive). */
+    count?: number;
+    /** Last date an occurrence may fall on (inclusive). Date or ISO string. */
+    until?: Date | string;
+    /** For `weekly` (and as a filter for `monthly`/`yearly`): which weekdays. */
+    byWeekday?: Weekday[];
+    /** For `monthly`/`yearly`: which day-of-month numbers (1–31). */
+    byMonthday?: number[];
+    /** Dates to skip even though the rule would otherwise generate them (EXDATE). */
+    exceptions?: (Date | string)[];
+}
+/**
+ * The event shape a consumer passes in. `start`/`end` accept a `Date` or an ISO
+ * string; everything is normalized internally to `NormalizedEvent`.
+ */
+export interface CalendarEvent {
+    id: string;
+    title: string;
+    start: Date | string;
+    /** Omit for a zero-length / point-in-time event. */
+    end?: Date | string;
+    /** All-day (and multi-day all-day) events render in the all-day gutter. */
+    allDay?: boolean;
+    severity?: EventSeverity;
+    location?: string;
+    description?: string;
+    /** When set, the event is a recurring series expanded across the visible range. */
+    recurrence?: RecurrenceRule;
+    /** Gates drag-to-move / drag-to-resize per event once those land. Defaults true. */
+    editable?: boolean;
+    /** Arbitrary passthrough — provider ids, attendee lists, etc. Never touched by core. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Internal, render-ready form of an event: real `Date` instants, and — for a
+ * recurring series — the specific occurrence this instance represents. One
+ * source `CalendarEvent` fans out into many `NormalizedEvent`s.
+ */
+export interface NormalizedEvent {
+    /** Stable per-occurrence id (`<event.id>` or `<event.id>__<occurrence-ISO>`). */
+    key: string;
+    /** The source event id — identical across every occurrence of a series. */
+    id: string;
+    title: string;
+    start: Date;
+    end: Date;
+    allDay: boolean;
+    severity: EventSeverity;
+    location?: string;
+    description?: string;
+    editable: boolean;
+    /** True when this instance was generated from a recurrence rule. */
+    isOccurrence: boolean;
+    /** True when the event spans more than one calendar day. */
+    isMultiDay: boolean;
+    source: CalendarEvent;
+}
+/** Half-open date window `[start, end)` used for fetching/expansion. */
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
+/**
+ * Optional auth surface a provider can expose so the UI can drive a
+ * connect/disconnect affordance without knowing the provider's mechanism.
+ */
+export interface CalendarProviderAuth {
+    isAuthenticated?: () => boolean | Promise<boolean>;
+    authenticate?: () => Promise<void>;
+    signOut?: () => Promise<void>;
+}
+/**
+ * Pluggable event source. `useCalendar()` accepts one optional provider; the
+ * shipped ICS and Google adapters both implement this. Only `fetchEvents` is
+ * required — a read-only source may omit the mutation hooks, and the UI hides
+ * the corresponding affordances when they're absent.
+ */
+export interface CalendarProvider {
+    /** Human label for connect UIs / debugging (e.g. "Google Calendar"). */
+    name: string;
+    fetchEvents: (range: DateRange) => Promise<CalendarEvent[]>;
+    createEvent?: (event: CalendarEvent) => Promise<CalendarEvent>;
+    updateEvent?: (event: CalendarEvent) => Promise<CalendarEvent>;
+    deleteEvent?: (eventId: string) => Promise<void>;
+    auth?: CalendarProviderAuth;
+}
+/** One day in a month grid or agenda list, with the events overlapping it. */
+export interface CalendarDayCell {
+    date: Date;
+    /** `YYYY-MM-DD` identity, cheap key for lists and lookups. */
+    key: string;
+    isToday: boolean;
+    /** Belongs to the month currently in focus (false for leading/trailing days). */
+    isCurrentMonth: boolean;
+    isWeekend: boolean;
+    events: NormalizedEvent[];
+}
+/** A week row in the month grid. */
+export interface CalendarWeekRow {
+    key: string;
+    days: CalendarDayCell[];
+}
+/**
+ * The new start/end an interaction produced. Emitted by drag-to-move and
+ * drag-to-resize; the consumer (or a provider's `updateEvent`) persists it —
+ * the source `CalendarEvent` is never mutated in place.
+ */
+export interface EventChange {
+    start: Date;
+    end: Date;
+}
+/**
+ * A time/day span the user swept out on empty space (drag-to-create). `allDay`
+ * is true when the sweep was over a month day cell or the all-day gutter.
+ */
+export interface RangeSelection {
+    start: Date;
+    end: Date;
+    allDay: boolean;
+}
+/** `{ start, end }` in minutes-from-midnight for the business-hours highlight. */
+export interface BusinessHours {
+    /** Weekdays the highlight applies to. Defaults to Mon–Fri. */
+    daysOfWeek?: WeekdayIndex[];
+    /** Minutes from midnight, e.g. 540 = 09:00. */
+    startMinute: number;
+    /** Minutes from midnight, e.g. 1020 = 17:00. */
+    endMinute: number;
+}

package/dist/components/data-display/calendar/tz.d.ts

@@ -0,0 +1,17 @@
+export interface ZonedParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    /** 0 = Sunday … 6 = Saturday. */
+    weekday: number;
+}
+/** Wall-clock parts of `date` in `timeZone` (or local time when omitted). */
+export declare function getZonedParts(date: Date, timeZone?: string): ZonedParts;
+/** `YYYY-MM-DD` identity of the calendar day `date` lands on in `timeZone`. */
+export declare function dayKey(date: Date, timeZone?: string): string;
+/** `YYYY-MM-DD` identity of a calendar-date cell (always read in local time). */
+export declare function cellKey(date: Date): string;
+/** Minutes-from-midnight of `date`'s wall-clock time in `timeZone`. */
+export declare function minutesInDay(date: Date, timeZone?: string): number;