@cocoar/vue-calendar 3.1.0 → 3.2.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/README.md +33 -6
  2. package/dist/builders/calendar-builder-config.d.ts +171 -0
  3. package/dist/builders/calendar-builder-config.d.ts.map +1 -0
  4. package/dist/builders/calendar-builder-handlers.d.ts +50 -0
  5. package/dist/builders/calendar-builder-handlers.d.ts.map +1 -0
  6. package/dist/builders/calendar-builder-internals.d.ts +18 -2
  7. package/dist/builders/calendar-builder-internals.d.ts.map +1 -1
  8. package/dist/builders/calendar-builder-state.d.ts +232 -0
  9. package/dist/builders/calendar-builder-state.d.ts.map +1 -0
  10. package/dist/builders/calendar-builder.d.ts +41 -452
  11. package/dist/builders/calendar-builder.d.ts.map +1 -1
  12. package/dist/builders/internal/event-validation.d.ts +13 -0
  13. package/dist/builders/internal/event-validation.d.ts.map +1 -0
  14. package/dist/builders/internal/events-for-window.d.ts +6 -0
  15. package/dist/builders/internal/events-for-window.d.ts.map +1 -0
  16. package/dist/builders/internal/loader-pipeline.d.ts +50 -0
  17. package/dist/builders/internal/loader-pipeline.d.ts.map +1 -0
  18. package/dist/builders/internal/loading-tracker.d.ts +12 -0
  19. package/dist/builders/internal/loading-tracker.d.ts.map +1 -0
  20. package/dist/builders/internal/navigation.d.ts +28 -0
  21. package/dist/builders/internal/navigation.d.ts.map +1 -0
  22. package/dist/builders/internal/range-label.d.ts +7 -0
  23. package/dist/builders/internal/range-label.d.ts.map +1 -0
  24. package/dist/builders/internal/series-pipeline.d.ts +67 -0
  25. package/dist/builders/internal/series-pipeline.d.ts.map +1 -0
  26. package/dist/builders/internal/window-utils.d.ts +44 -0
  27. package/dist/builders/internal/window-utils.d.ts.map +1 -0
  28. package/dist/builders/types.d.ts +18 -3
  29. package/dist/builders/types.d.ts.map +1 -1
  30. package/dist/components/CoarAgendaView.vue.d.ts +18 -0
  31. package/dist/components/CoarAgendaView.vue.d.ts.map +1 -1
  32. package/dist/components/CoarCalendar.vue.d.ts +25 -1
  33. package/dist/components/CoarCalendar.vue.d.ts.map +1 -1
  34. package/dist/components/CoarContinuousMonthView.vue.d.ts.map +1 -1
  35. package/dist/components/CoarDayView.vue.d.ts +16 -2
  36. package/dist/components/CoarDayView.vue.d.ts.map +1 -1
  37. package/dist/components/CoarMonthListView.vue.d.ts.map +1 -1
  38. package/dist/components/CoarMonthView.vue.d.ts.map +1 -1
  39. package/dist/components/CoarTimeGrid.vue.d.ts +33 -7
  40. package/dist/components/CoarTimeGrid.vue.d.ts.map +1 -1
  41. package/dist/components/CoarTimelineView.vue.d.ts.map +1 -1
  42. package/dist/components/CoarWeekView.vue.d.ts.map +1 -1
  43. package/dist/components/CoarWorkWeekView.vue.d.ts +1 -2
  44. package/dist/components/CoarWorkWeekView.vue.d.ts.map +1 -1
  45. package/dist/components/CoarYearView.vue.d.ts.map +1 -1
  46. package/dist/components/VirtualizedSurface1DY.vue.d.ts.map +1 -1
  47. package/dist/components/internal/CoarEventDecorations.vue.d.ts.map +1 -1
  48. package/dist/components/internal/agenda/agendaTimeLabel.d.ts +4 -0
  49. package/dist/components/internal/agenda/agendaTimeLabel.d.ts.map +1 -0
  50. package/dist/components/internal/month/CoarMonthBar.vue.d.ts +2 -0
  51. package/dist/components/internal/month/CoarMonthBar.vue.d.ts.map +1 -1
  52. package/dist/components/internal/month/CoarMonthCell.vue.d.ts +3 -1
  53. package/dist/components/internal/month/CoarMonthCell.vue.d.ts.map +1 -1
  54. package/dist/components/internal/month/CoarMonthPill.vue.d.ts +2 -0
  55. package/dist/components/internal/month/CoarMonthPill.vue.d.ts.map +1 -1
  56. package/dist/components/internal/originatesFromEvent.d.ts +18 -0
  57. package/dist/components/internal/originatesFromEvent.d.ts.map +1 -0
  58. package/dist/components/internal/time-grid/CoarTimeGridAllDayBand.vue.d.ts +15 -1
  59. package/dist/components/internal/time-grid/CoarTimeGridAllDayBand.vue.d.ts.map +1 -1
  60. package/dist/components/internal/time-grid/CoarTimeGridAllDayBar.vue.d.ts +2 -0
  61. package/dist/components/internal/time-grid/CoarTimeGridAllDayBar.vue.d.ts.map +1 -1
  62. package/dist/components/internal/time-grid/CoarTimeGridAllDayOverflow.vue.d.ts +27 -0
  63. package/dist/components/internal/time-grid/CoarTimeGridAllDayOverflow.vue.d.ts.map +1 -0
  64. package/dist/components/internal/time-grid/CoarTimeGridColumn.vue.d.ts +2 -0
  65. package/dist/components/internal/time-grid/CoarTimeGridColumn.vue.d.ts.map +1 -1
  66. package/dist/components/internal/time-grid/CoarTimeGridEvent.vue.d.ts +12 -1
  67. package/dist/components/internal/time-grid/CoarTimeGridEvent.vue.d.ts.map +1 -1
  68. package/dist/components/internal/time-grid/CoarTimeGridHeader.vue.d.ts +12 -1
  69. package/dist/components/internal/time-grid/CoarTimeGridHeader.vue.d.ts.map +1 -1
  70. package/dist/components/internal/time-grid/CoarTimeGridSurface.vue.d.ts +53 -0
  71. package/dist/components/internal/time-grid/CoarTimeGridSurface.vue.d.ts.map +1 -0
  72. package/dist/composables/useMonthExpansion.d.ts +0 -5
  73. package/dist/composables/useMonthExpansion.d.ts.map +1 -1
  74. package/dist/composables/useTimeGridSwipe.d.ts +47 -0
  75. package/dist/composables/useTimeGridSwipe.d.ts.map +1 -0
  76. package/dist/composables/useViewWindow.d.ts +4 -2
  77. package/dist/composables/useViewWindow.d.ts.map +1 -1
  78. package/dist/core/allDayBandCap.d.ts +41 -0
  79. package/dist/core/allDayBandCap.d.ts.map +1 -0
  80. package/dist/core/eventTextContrast.d.ts +53 -2
  81. package/dist/core/eventTextContrast.d.ts.map +1 -1
  82. package/dist/core/index.d.ts +5 -1
  83. package/dist/core/index.d.ts.map +1 -1
  84. package/dist/core/rangeLabel.d.ts +14 -0
  85. package/dist/core/rangeLabel.d.ts.map +1 -0
  86. package/dist/core/timeGridRange.d.ts +50 -0
  87. package/dist/core/timeGridRange.d.ts.map +1 -0
  88. package/dist/core/timedCardAnatomy.d.ts +47 -0
  89. package/dist/core/timedCardAnatomy.d.ts.map +1 -0
  90. package/dist/core/viewWindow.d.ts +17 -4
  91. package/dist/core/viewWindow.d.ts.map +1 -1
  92. package/dist/{core-CiKX2hZM.js → core-COjCRcPw.js} +266 -80
  93. package/dist/core.js +2 -2
  94. package/dist/i18n/messages.d.ts +16 -0
  95. package/dist/i18n/messages.d.ts.map +1 -0
  96. package/dist/index.d.ts +3 -1
  97. package/dist/index.d.ts.map +1 -1
  98. package/dist/index.js +2383 -1655
  99. package/dist/vue-calendar.css +1 -1
  100. package/package.json +4 -3
package/README.md CHANGED
@@ -17,6 +17,30 @@ Peer deps: `vue ^3.5`, `@cocoar/vue-ui workspace:*`,
17
17
  `@cocoar/vue-localization workspace:*`. Direct dep:
18
18
  `@js-temporal/polyfill ^0.5` (re-exported as `Temporal`).
19
19
 
20
+ The component styles ship as one stylesheet on the `./styles` subpath —
21
+ import it once next to the design-system styles:
22
+
23
+ ```ts
24
+ import '@cocoar/vue-ui/styles';
25
+ import '@cocoar/vue-calendar/styles';
26
+ ```
27
+
28
+ Every visible label (`Today`, `Month`, `All day`, the a11y announcements, …)
29
+ is looked up as a `coar.calendar.*` key through the host's
30
+ `@cocoar/vue-localization` service. English fallbacks are inline; German and
31
+ English catalogs ship with the package, so a host registers them instead of
32
+ maintaining the key list by hand:
33
+
34
+ ```ts
35
+ import { createCoarLocalization } from '@cocoar/vue-localization';
36
+ import { createCalendarTranslationSource } from '@cocoar/vue-calendar';
37
+
38
+ const localization = createCoarLocalization({ defaultLanguage: 'de-AT' });
39
+ localization.service.addTranslationSource(createCalendarTranslationSource());
40
+ // A host source registered AFTER this one overrides per key.
41
+ app.use(localization);
42
+ ```
43
+
20
44
  ## Quick start
21
45
 
22
46
  ```vue
@@ -80,13 +104,20 @@ specific web UX:
80
104
 
81
105
  ```ts
82
106
  builder
83
- .onDateClick(({ date, native }) => openCreate(date, native.currentTarget))
84
- .onTimeClick(({ date, time, native }) => openCreateAt(date, time, native.currentTarget))
107
+ .onDateClick(({ date }) => selectDay(date))
108
+ .onTimeClick(({ date, time }) => selectSlot(date, time))
109
+ .onDateDoubleClick(({ date, native }) => openCreate(date, native.currentTarget))
110
+ .onTimeDoubleClick(({ date, time, native }) => openCreateAt(date, time, native.currentTarget))
85
111
  .onEventClick(({ event, native }) => openDetails(event, native.currentTarget))
86
112
  .onEventDoubleClick(({ event }) => openEditor(event))
87
113
  .onEventDrop(({ event, next }) => persistMove(event.id, next));
88
114
  ```
89
115
 
116
+ Single-click and double-click on empty cells / slots are separate hooks, so
117
+ the desktop convention "click selects, double-click creates" needs no timer on
118
+ the host side. A double-click on an event element never reaches the date /
119
+ time hooks — it routes to `onEventDoubleClick` only.
120
+
90
121
  Use the supplied DOM target with `@cocoar/vue-ui` for an anchored popover, or
91
122
  ignore it and open a modal, side panel, routed page, or custom view. The calendar
92
123
  does not ship a fixed create/edit overlay. Recurring occurrences expose stable
@@ -273,10 +304,6 @@ would duplicate the same capability.
273
304
  - **Timezone abbreviations (`'EST'`, `'CET'`, etc.)** — the underlying
274
305
  Temporal polyfill resolves these to fixed-offset zones rather than
275
306
  rejecting them. The calendar accepts whatever Temporal accepts.
276
- - **`onMoreClick`** — typed setter exists, but the "+N more" overflow
277
- surface in `<CoarMonthView>` is a post-2.0 visual-polish item. Setting
278
- the handler today emits a one-shot dev-warn; the handler starts firing
279
- once the overflow surface ships.
280
307
 
281
308
  ## Architecture decisions (locked)
282
309
 
@@ -0,0 +1,171 @@
1
+ import { MaybeRefOrGetter, Ref } from 'vue';
2
+ import { AllDayBandMode, CalendarDayMode, CalendarEvent, CalendarMonthDensity, CalendarView, DayOfWeek, EventTextContrastPolicy, RecurringSeries, Temporal, TimeGridRangeSpec } from '../core';
3
+ import { CalendarDensity, DstPolicy, EventsLoader, SeriesLoader, TimeRange } from './types';
4
+ import { RecurrenceEngine } from '../recurrence/types';
5
+ import { CalendarBuilderState } from './calendar-builder-state';
6
+ export declare abstract class CalendarBuilderConfig<TMeta extends Record<string, unknown> = Record<string, unknown>> {
7
+ /** Reactive state — single source of truth (C7 read site). */
8
+ readonly state: CalendarBuilderState<TMeta>;
9
+ protected constructor(state: CalendarBuilderState<TMeta>);
10
+ /** C1 boundary validation (memoized per event object). Throws on the first bad event. */
11
+ protected abstract _validateEvents(events: ReadonlyArray<CalendarEvent<TMeta>>): void;
12
+ /** The loader source changed — its cache is stale. */
13
+ protected abstract _resetLoaderCache(): void;
14
+ /** The series source changed — drop the series cache; `rerun` re-expands the current window. */
15
+ protected abstract _invalidateSeries(rerun: boolean): void;
16
+ /** The recurrence engine changed — forget the resolved instance and re-expand. */
17
+ protected abstract _resetRecurrenceEngine(): void;
18
+ /**
19
+ * Bind the event source. Mutually exclusive with `eventsLoader()` —
20
+ * clears a previously-set loader and its cache. Only
21
+ * `Temporal.ZonedDateTime` (timed) / `Temporal.PlainDate` (all-day)
22
+ * are accepted on start/end; anything else throws (C1).
23
+ */
24
+ events(source: MaybeRefOrGetter<CalendarEvent<TMeta>[]>): this;
25
+ /**
26
+ * Bind a calendar-managed loader, called per visible-window change
27
+ * and cached per `(view, timezone, start, end)`. Mutually exclusive
28
+ * with `events()`.
29
+ */
30
+ eventsLoader(loader: EventsLoader<TMeta>): this;
31
+ /**
32
+ * Phase 4 — bind a recurring-series source. Reactive: expansion
33
+ * re-runs whenever the source or the visible range changes.
34
+ * Composes with `events()` / `eventsLoader()` (merged in
35
+ * `getVisibleEvents()`); mutually exclusive with `seriesLoader()`.
36
+ * Uses `recurrenceEngine()` if set, else the lazy default; the
37
+ * `dstPolicy()` applies to every expanded occurrence.
38
+ */
39
+ series(source: MaybeRefOrGetter<RecurringSeries<TMeta>[]>): this;
40
+ /**
41
+ * Phase 4 — bind a calendar-managed recurring-series loader.
42
+ * Called per visible-range change; results expanded by the
43
+ * configured engine and cached per-window. Mutually exclusive with
44
+ * `series()`.
45
+ */
46
+ seriesLoader(loader: SeriesLoader<TMeta>): this;
47
+ /** C5 — Display zone (IANA). Source zones on individual events
48
+ * remain independent and per-endpoint preserved (C3). */
49
+ timezone(tz: MaybeRefOrGetter<string>): this;
50
+ locale(loc: MaybeRefOrGetter<string>): this;
51
+ firstDayOfWeek(d: MaybeRefOrGetter<DayOfWeek>): this;
52
+ /**
53
+ * Working-day set for the `'workWeek'` view. 0 = Sun … 6 = Sat.
54
+ * Default is Mon–Fri. Reactive — changing it while a workWeek
55
+ * view is active reflows the rendered columns.
56
+ */
57
+ workDays(d: MaybeRefOrGetter<readonly DayOfWeek[]>): this;
58
+ /** Tint Saturday and Sunday cells in month views. */
59
+ shadeWeekends(enabled: MaybeRefOrGetter<boolean>): this;
60
+ /**
61
+ * Contrast policy for the automatic black/white text on event
62
+ * surfaces: `'wcag'` (WCAG 2 ratio, default) or `'apca'` (WCAG 3
63
+ * draft; picks white on saturated mid-tones like `#e03131` where
64
+ * WCAG 2 narrowly picks black). A per-event `meta.textColor` wins
65
+ * over either policy.
66
+ */
67
+ eventTextContrast(policy: MaybeRefOrGetter<EventTextContrastPolicy>): this;
68
+ /**
69
+ * Cap the all-day band (week / work-week / day) at `n` lanes —
70
+ * default 3, like the system calendar. Beyond that, the last
71
+ * visible lane carries per-day "+N" markers; a click expands the
72
+ * band, a collapse control folds it back. `null` shows every lane.
73
+ */
74
+ allDayMaxVisibleLanes(n: MaybeRefOrGetter<number | null>): this;
75
+ /**
76
+ * Unobscured width (px) below which an overlapped Day / Week card
77
+ * switches to the compact anatomy — one end-truncated title line, no
78
+ * location, no time. Default 112 like iOS; `0` disables the switch.
79
+ */
80
+ timedEventDetailMinWidth(px: MaybeRefOrGetter<number>): this;
81
+ /**
82
+ * How much height the all-day band claims (the hour axis starts
83
+ * below it, so every height change moves the whole grid):
84
+ * `'fitsContent'` (default) follows the content, `'alwaysOneLane'`
85
+ * removes the 0↔1 jump, `'reservesCap'` is always
86
+ * `allDayMaxVisibleLanes` tall so the axis never moves between days.
87
+ */
88
+ allDayBandMode(mode: MaybeRefOrGetter<AllDayBandMode>): this;
89
+ /**
90
+ * Touch paging on week / work-week / day: a horizontal pan moves the
91
+ * grid with the finger and pages on release past a quarter of the
92
+ * width or on a fast flick. A touch that never moves is a tap and
93
+ * reaches `onTimeClick` on release; mouse and pen are unchanged.
94
+ * Default on; honours `prefers-reduced-motion`.
95
+ */
96
+ swipeNavigation(enabled: MaybeRefOrGetter<boolean>): this;
97
+ /**
98
+ * Warm the caches for the previous / next time-grid page so the
99
+ * neighbour pages drawn during a swipe carry their events. Default
100
+ * on; one extra fetch per neighbour in loader mode.
101
+ */
102
+ prefetchNeighbours(enabled: MaybeRefOrGetter<boolean>): this;
103
+ density(d: MaybeRefOrGetter<CalendarDensity>): this;
104
+ monthDensity(density: MaybeRefOrGetter<CalendarMonthDensity>): this;
105
+ dayMode(mode: MaybeRefOrGetter<CalendarDayMode>): this;
106
+ /**
107
+ * The `day` view's columns and paging as one spec — `anchor`, `span`
108
+ * (days or `'responsive'`), `filter` (all / `workDays`), `step` (days
109
+ * per page or `'span'`); Week and Work week are fixed presets of it.
110
+ * `null` restores the `dayMode` presets.
111
+ */
112
+ timeGridRange(spec: MaybeRefOrGetter<TimeGridRangeSpec | null>): this;
113
+ /** C6 — independent of timeStyle / hour12. */
114
+ dateStyle(s: MaybeRefOrGetter<'short' | 'medium' | 'long' | 'full'>): this;
115
+ /** C6 — independent of dateStyle / hour12. */
116
+ timeStyle(s: MaybeRefOrGetter<'short' | 'medium' | 'long'>): this;
117
+ /**
118
+ * C6 — independent of locale. `undefined` lets Intl derive from
119
+ * locale (default); `true` / `false` overrides explicitly.
120
+ */
121
+ hour12(h: MaybeRefOrGetter<boolean | undefined>): this;
122
+ /**
123
+ * C4 — DST disambiguation policy. Read by every wall-time → instant
124
+ * conversion in the drop pipeline. Default `'compatible'`.
125
+ */
126
+ dstPolicy(p: MaybeRefOrGetter<DstPolicy>): this;
127
+ /**
128
+ * Recurrence engine for this builder's `expandSeries` calls (default:
129
+ * the lazy rrule-temporal adapter; the factory form is the SSR
130
+ * escape). **Set once at construction** — a swap does not cancel or
131
+ * re-route in-flight expansions.
132
+ */
133
+ recurrenceEngine(engineOrFactory: RecurrenceEngine | (() => RecurrenceEngine)): this;
134
+ /**
135
+ * Active view. Setter accepts a `Ref<CalendarView>` (two-way
136
+ * binding) or a plain value (wrapped into an internal ref).
137
+ * Function-getters are rejected — `api.setView` must be able to
138
+ * write back.
139
+ */
140
+ view(v: Ref<CalendarView> | CalendarView): this;
141
+ availableViews(views: MaybeRefOrGetter<readonly CalendarView[]>): this;
142
+ /**
143
+ * Cursor date. Setter accepts a `Ref<PlainDate>` or a plain
144
+ * `PlainDate`; function-getters rejected (api.next/prev/goTo
145
+ * must write).
146
+ */
147
+ date(d: Ref<Temporal.PlainDate> | Temporal.PlainDate): this;
148
+ /** Time-grid view setting (`day` / `week`). */
149
+ timeRange(r: MaybeRefOrGetter<TimeRange>): this;
150
+ slotDuration(minutes: MaybeRefOrGetter<number>): this;
151
+ pixelsPerHour(px: MaybeRefOrGetter<number>): this;
152
+ /** Month view setting — pills before "+N more". */
153
+ maxEventsPerCell(n: MaybeRefOrGetter<number>): this;
154
+ /** Responsive day view: minimum number of full day columns. */
155
+ dayColumnCount(n: MaybeRefOrGetter<number>): this;
156
+ /** Responsive day view: target width used to derive additional columns. */
157
+ dayColumnMinWidth(px: MaybeRefOrGetter<number>): this;
158
+ /** Agenda view setting — number of days the linear list covers. */
159
+ agendaLengthDays(n: MaybeRefOrGetter<number>): this;
160
+ /** Agenda view setting — show day headers even when no events. */
161
+ showEmptyDays(b: MaybeRefOrGetter<boolean>): this;
162
+ /** Days the `'timeline'` view spans starting from the cursor. Default 60. */
163
+ timelineRangeDays(n: MaybeRefOrGetter<number>): this;
164
+ /** Horizontal pixel density of the `'timeline'` view (pixels per day). Default 56. */
165
+ timelinePixelsPerDay(p: MaybeRefOrGetter<number>): this;
166
+ /** Event-row height in the `'timeline'` view, in pixels. Default 32. */
167
+ timelineRowHeight(h: MaybeRefOrGetter<number>): this;
168
+ /** Left-pane label width in the `'timeline'` view, in pixels. Default 200. */
169
+ timelineLabelWidth(w: MaybeRefOrGetter<number>): this;
170
+ }
171
+ //# sourceMappingURL=calendar-builder-config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"calendar-builder-config.d.ts","sourceRoot":"","sources":["../../src/builders/calendar-builder-config.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,50 @@
1
+ import { CanDropFn, DateClickHandler, DateDoubleClickHandler, DayHeaderRenderer, EventClickHandler, EventDoubleClickHandler, EventDropHandler, EventHoverHandler, EventHoverLeaveHandler, EventRenderer, RangeChangeHandler, TimeClickHandler, TimeDoubleClickHandler } from './types';
2
+ import { CalendarBuilderConfig } from './calendar-builder-config';
3
+ export declare abstract class CalendarBuilderHandlers<TMeta extends Record<string, unknown> = Record<string, unknown>> extends CalendarBuilderConfig<TMeta> {
4
+ /**
5
+ * Drop validator. Read on EVERY hit-test (C7 + D4 — no library-
6
+ * side memoization). If you do expensive work in here, memoize
7
+ * client-side; the library reading fresh state is the correct
8
+ * behaviour and intentionally not cached.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * // Consumer-side memoization for expensive checks:
13
+ * const memoized = computed(() => {
14
+ * const rules = expensivelyCompiledRules.value;
15
+ * return (event, target) => rules.matches(event, target);
16
+ * });
17
+ * builder.canDrop(memoized.value);
18
+ * ```
19
+ */
20
+ canDrop(fn: CanDropFn<TMeta>): this;
21
+ eventRenderer(r: EventRenderer<TMeta>): this;
22
+ dayHeaderRenderer(r: DayHeaderRenderer): this;
23
+ onEventClick(h: EventClickHandler<TMeta>): this;
24
+ onEventDoubleClick(h: EventDoubleClickHandler<TMeta>): this;
25
+ /**
26
+ * Fires on `pointerenter` over an event element in any view.
27
+ * Pair with `useOverlay()` (from `@cocoar/vue-ui`) to anchor a
28
+ * popover at `payload.native.currentTarget`. The library does
29
+ * NOT apply hover delay — consumer wraps the handler if a delay
30
+ * is wanted.
31
+ */
32
+ onEventHover(h: EventHoverHandler<TMeta>): this;
33
+ /** Companion to `onEventHover` — fires on `pointerleave`. */
34
+ onEventHoverLeave(h: EventHoverLeaveHandler<TMeta>): this;
35
+ onEventDrop(h: EventDropHandler<TMeta>): this;
36
+ onDateClick(h: DateClickHandler): this;
37
+ onTimeClick(h: TimeClickHandler): this;
38
+ /**
39
+ * Double-click on an empty day cell (month grid, all-day band).
40
+ * Desktop "double-click creates" convention; the single-click
41
+ * handlers keep firing for the two clicks that precede it, so a
42
+ * host that selects on click and creates on double-click needs no
43
+ * timer of its own.
44
+ */
45
+ onDateDoubleClick(h: DateDoubleClickHandler): this;
46
+ /** Double-click on an empty time slot (week / work-week / day). */
47
+ onTimeDoubleClick(h: TimeDoubleClickHandler): this;
48
+ onRangeChange(h: RangeChangeHandler): this;
49
+ }
50
+ //# sourceMappingURL=calendar-builder-handlers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"calendar-builder-handlers.d.ts","sourceRoot":"","sources":["../../src/builders/calendar-builder-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,8BAAsB,uBAAuB,CAC3C,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC/D,SAAQ,qBAAqB,CAAC,KAAK,CAAC;IAGpC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI;IAKnC,aAAa,CAAC,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,IAAI;IAK5C,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAO7C,YAAY,CAAC,CAAC,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,IAAI;IAK/C,kBAAkB,CAAC,CAAC,EAAE,uBAAuB,CAAC,KAAK,CAAC,GAAG,IAAI;IAK3D;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,IAAI;IAK/C,6DAA6D;IAC7D,iBAAiB,CAAC,CAAC,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAAG,IAAI;IAKzD,WAAW,CAAC,CAAC,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI;IAK7C,WAAW,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAKtC,WAAW,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAKtC;;;;;;OAMG;IACH,iBAAiB,CAAC,CAAC,EAAE,sBAAsB,GAAG,IAAI;IAKlD,mEAAmE;IACnE,iBAAiB,CAAC,CAAC,EAAE,sBAAsB,GAAG,IAAI;IAKlD,aAAa,CAAC,CAAC,EAAE,kBAAkB,GAAG,IAAI;CAI3C"}
@@ -1,14 +1,30 @@
1
- import { ViewWindow } from '../core';
1
+ import { Temporal, ViewWindow } from '../core';
2
2
  /** Privileged method symbol — see `CalendarBuilder` for the impl. */
3
3
  export declare const SET_VISIBLE_RANGE: unique symbol;
4
4
  /** Privileged method symbol — see `CalendarBuilder` for the impl. */
5
5
  export declare const INVALIDATE_LOADER_CACHE: unique symbol;
6
+ /**
7
+ * Privileged method symbol — warm the loader / series caches for
8
+ * windows the user is about to see (the neighbour pages the time
9
+ * grid draws while it is being swiped). Never touches
10
+ * `_visibleRange` and never fires `onRangeChange`.
11
+ */
12
+ export declare const PREFETCH_WINDOWS: unique symbol;
13
+ /**
14
+ * Privileged method symbol — the continuous month surface reports the
15
+ * month of its topmost visible section while the user scrolls. Feeds
16
+ * `api.topmostVisibleMonth` and the month label; never moves the
17
+ * cursor (the surface does that itself once the scroll settles).
18
+ */
19
+ export declare const SET_TOPMOST_VISIBLE_MONTH: unique symbol;
6
20
  /**
7
21
  * Type-narrowed surface a `CalendarBuilder` exposes to internal
8
- * composables (only `useViewWindow` today).
22
+ * composables (`useViewWindow`, the time-grid surface).
9
23
  */
10
24
  export interface PrivilegedBuilder {
11
25
  [SET_VISIBLE_RANGE](window: ViewWindow | null): void;
12
26
  [INVALIDATE_LOADER_CACHE](): void;
27
+ [PREFETCH_WINDOWS](windows: ReadonlyArray<ViewWindow>): void;
28
+ [SET_TOPMOST_VISIBLE_MONTH](month: Temporal.PlainYearMonth | null): void;
13
29
  }
14
30
  //# sourceMappingURL=calendar-builder-internals.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"calendar-builder-internals.d.ts","sourceRoot":"","sources":["../../src/builders/calendar-builder-internals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAAkD,CAAC;AAE1F,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,EAAE,OAAO,MAE5C,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,iBAAiB,CAAC,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;IACrD,CAAC,uBAAuB,CAAC,IAAI,IAAI,CAAC;CACnC"}
1
+ {"version":3,"file":"calendar-builder-internals.d.ts","sourceRoot":"","sources":["../../src/builders/calendar-builder-internals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAAkD,CAAC;AAE1F,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,EAAE,OAAO,MAE5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAkD,CAAC;AACzF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,MAE9C,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,iBAAiB,CAAC,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;IACrD,CAAC,uBAAuB,CAAC,IAAI,IAAI,CAAC;IAClC,CAAC,gBAAgB,CAAC,CAAC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IAC7D,CAAC,yBAAyB,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC;CAC1E"}
@@ -0,0 +1,232 @@
1
+ import { MaybeRefOrGetter, ComputedRef, Ref, ShallowRef } from 'vue';
2
+ import { AllDayBandMode, CalendarDayMode, CalendarEvent, CalendarMonthDensity, CalendarView, DayOfWeek, EventTextContrastPolicy, RecurringSeries, TimeGridRangeSpec, ViewWindow, Temporal } from '../core';
3
+ import { CalendarDensity, CanDropFn, DateClickHandler, DateDoubleClickHandler, DayHeaderRenderer, DstPolicy, EventClickHandler, EventDoubleClickHandler, EventDropHandler, EventHoverHandler, EventHoverLeaveHandler, EventRenderer, EventsLoader, RangeChangeHandler, SeriesLoader, TimeClickHandler, TimeDoubleClickHandler, TimeRange } from './types';
4
+ import { RecurrenceEngine } from '../recurrence/types';
5
+ /**
6
+ * Reactive state owned by a `CalendarBuilder`. All reads go through
7
+ * `toValue()` for `MaybeRefOrGetter<T>` fields and `.value` for
8
+ * `Ref<T>` fields. Function fields (canDrop / handlers / renderers)
9
+ * are stored verbatim and called at the read site.
10
+ */
11
+ export interface CalendarBuilderState<TMeta extends Record<string, unknown> = Record<string, unknown>> {
12
+ events: MaybeRefOrGetter<CalendarEvent<TMeta>[]> | null;
13
+ eventsLoader: EventsLoader<TMeta> | null;
14
+ /**
15
+ * Recurring-series source (Phase 4). Reactive — expansion re-runs
16
+ * when the source changes or the visible range changes.
17
+ * Mutually exclusive with `seriesLoader`.
18
+ */
19
+ series: MaybeRefOrGetter<RecurringSeries<TMeta>[]> | null;
20
+ /**
21
+ * Calendar-managed recurring-series loader (Phase 4). Called per
22
+ * visible-range change; results are expanded by the configured
23
+ * engine and cached per-window key. Mutually exclusive with `series`.
24
+ */
25
+ seriesLoader: SeriesLoader<TMeta> | null;
26
+ /** Display zone (C5). Defaults to the browser's IANA zone. */
27
+ timezone: MaybeRefOrGetter<string>;
28
+ /**
29
+ * BCP-47 display locale. `undefined` (the default) defers to the host's
30
+ * `@cocoar/vue-localization` language, then `'en-US'`.
31
+ */
32
+ locale: MaybeRefOrGetter<string | undefined>;
33
+ /** Locale-derived when undefined (Article 9 — defaults are not decisions). */
34
+ firstDayOfWeek: MaybeRefOrGetter<DayOfWeek | undefined>;
35
+ /**
36
+ * Days that count as "working days" for the `'workWeek'` view.
37
+ * 0 = Sun … 6 = Sat. Default is Mon–Fri (`[1, 2, 3, 4, 5]`).
38
+ * Empty array yields an empty workWeek (rendered as "no working
39
+ * days configured" — UI concern, not a runtime error).
40
+ *
41
+ * Article 9: this is an explicit decision — the locale gets a
42
+ * vote on `firstDayOfWeek` but NOT on which weekdays are
43
+ * working days (varies by country/industry independently of
44
+ * BCP-47).
45
+ */
46
+ workDays: MaybeRefOrGetter<readonly DayOfWeek[]>;
47
+ /** Tint Saturday and Sunday cells in month views. Enabled by default. */
48
+ shadeWeekends: MaybeRefOrGetter<boolean>;
49
+ /**
50
+ * How the black/white text colour on event surfaces is chosen when
51
+ * the event supplies no `meta.textColor`. `'wcag'` (default) keeps
52
+ * the historical behaviour; `'apca'` fixes saturated mid-tones.
53
+ */
54
+ eventTextContrast: MaybeRefOrGetter<EventTextContrastPolicy>;
55
+ /**
56
+ * Lanes the all-day band shows before it folds the rest behind
57
+ * per-day "+N" markers (week / work-week / day). `null` = unlimited.
58
+ */
59
+ allDayMaxVisibleLanes: MaybeRefOrGetter<number | null>;
60
+ /** How much height the all-day band claims — see `AllDayBandMode`. */
61
+ allDayBandMode: MaybeRefOrGetter<AllDayBandMode>;
62
+ /**
63
+ * Unobscured width (px) below which an overlapped Day / Week card
64
+ * switches to the compact anatomy (one title line, no location, no
65
+ * time). iOS `timedEventDetailMinimumWidth`; `0` disables.
66
+ */
67
+ timedEventDetailMinWidth: MaybeRefOrGetter<number>;
68
+ /**
69
+ * Touch paging on the time grids: a horizontal pan moves the grid
70
+ * with the finger and pages on release. Mouse / pen unaffected.
71
+ */
72
+ swipeNavigation: MaybeRefOrGetter<boolean>;
73
+ /**
74
+ * Warm the loader / series caches for the previous and next page
75
+ * of the time grids as soon as a page is visible, so the neighbour
76
+ * pages drawn during a swipe carry their events. Costs one extra
77
+ * fetch per neighbour in loader mode; a no-op in `events()` mode.
78
+ */
79
+ prefetchNeighbours: MaybeRefOrGetter<boolean>;
80
+ density: MaybeRefOrGetter<CalendarDensity>;
81
+ /** Apple-style month presentation. Default `details` preserves the classic web grid. */
82
+ monthDensity: MaybeRefOrGetter<CalendarMonthDensity>;
83
+ /** One fixed day or a width-driven 1…7-day surface. */
84
+ dayMode: MaybeRefOrGetter<CalendarDayMode>;
85
+ /**
86
+ * Explicit range spec for the `day` view — anchor, span, filter,
87
+ * step (see `TimeGridRangeSpec`). `null` (default) follows
88
+ * `dayMode`. `week` / `workWeek` are fixed presets of the same
89
+ * model and ignore it.
90
+ */
91
+ timeGridRange: MaybeRefOrGetter<TimeGridRangeSpec | null>;
92
+ /** Intl date style (C6 — independent of timeStyle / hour12).
93
+ * Locale-derived when undefined (Article 9). */
94
+ dateStyle: MaybeRefOrGetter<'short' | 'medium' | 'long' | 'full' | undefined>;
95
+ /** Intl time style (C6). Locale-derived when undefined (Article 9). */
96
+ timeStyle: MaybeRefOrGetter<'short' | 'medium' | 'long' | undefined>;
97
+ /** 12h vs 24h clock (C6 — independent of locale). */
98
+ hour12: MaybeRefOrGetter<boolean | undefined>;
99
+ /** DST disambiguation policy (C4). Default `'compatible'`. */
100
+ dstPolicy: MaybeRefOrGetter<DstPolicy>;
101
+ /**
102
+ * Recurrence engine (Phase 4 §A8). One of:
103
+ * - `RecurrenceEngine` instance — eager.
104
+ * - `() => RecurrenceEngine` factory — SSR-friendly lazy.
105
+ * - `null` — defer to the lazy default (rrule-temporal adapter
106
+ * loaded via dynamic import on first `expandSeries` call).
107
+ *
108
+ * Intentionally NOT `MaybeRefOrGetter`: mid-session swap has no
109
+ * sensible semantics (in-flight requests, worker lifecycle). Set
110
+ * once at construction.
111
+ */
112
+ recurrenceEngine: RecurrenceEngine | (() => RecurrenceEngine) | null;
113
+ /** Subset of CalendarView the view-switcher offers. */
114
+ availableViews: MaybeRefOrGetter<readonly CalendarView[]>;
115
+ timeRange: MaybeRefOrGetter<TimeRange>;
116
+ slotDuration: MaybeRefOrGetter<number>;
117
+ pixelsPerHour: MaybeRefOrGetter<number>;
118
+ maxEventsPerCell: MaybeRefOrGetter<number>;
119
+ /** Minimum number of adjacent columns in the responsive day view. */
120
+ dayColumnCount: MaybeRefOrGetter<number>;
121
+ /** Target width of one responsive day column in CSS pixels. */
122
+ dayColumnMinWidth: MaybeRefOrGetter<number>;
123
+ agendaLengthDays: MaybeRefOrGetter<number>;
124
+ showEmptyDays: MaybeRefOrGetter<boolean>;
125
+ /**
126
+ * Number of days the `'timeline'` view spans starting from the
127
+ * cursor. Default 60 (~two months — fits sprint-planning horizons
128
+ * without overwhelming the horizontal scroll).
129
+ */
130
+ timelineRangeDays: MaybeRefOrGetter<number>;
131
+ /**
132
+ * Horizontal pixel density of the `'timeline'` view's time axis.
133
+ * Default 56 — a localized "DD. Mon" label (e.g. "15. Juni") fits
134
+ * on one line at the default font size. Bump to 80 for hour-
135
+ * granularity layout, drop to 24 for quarter-zoomed sprint
136
+ * overviews.
137
+ */
138
+ timelinePixelsPerDay: MaybeRefOrGetter<number>;
139
+ /**
140
+ * Height of each event row in the `'timeline'` view, in pixels.
141
+ * Default 32 — matches the default density's pill height.
142
+ */
143
+ timelineRowHeight: MaybeRefOrGetter<number>;
144
+ /**
145
+ * Width of the left label-pane in the `'timeline'` view, in pixels.
146
+ * Default 200 — wide enough for most event titles without
147
+ * crowding the time-grid.
148
+ */
149
+ timelineLabelWidth: MaybeRefOrGetter<number>;
150
+ /** Active view. Held as Ref so api.setView can write back. */
151
+ view: Ref<CalendarView>;
152
+ /** Cursor date. Held as Ref so api.next/prev/goTo can write back. */
153
+ date: Ref<Temporal.PlainDate>;
154
+ canDrop: CanDropFn<TMeta> | null;
155
+ eventRenderer: EventRenderer<TMeta> | null;
156
+ dayHeaderRenderer: DayHeaderRenderer | null;
157
+ onEventClick: EventClickHandler<TMeta> | null;
158
+ onEventDoubleClick: EventDoubleClickHandler<TMeta> | null;
159
+ onEventHover: EventHoverHandler<TMeta> | null;
160
+ onEventHoverLeave: EventHoverLeaveHandler<TMeta> | null;
161
+ onEventDrop: EventDropHandler<TMeta> | null;
162
+ onDateClick: DateClickHandler | null;
163
+ onTimeClick: TimeClickHandler | null;
164
+ onDateDoubleClick: DateDoubleClickHandler | null;
165
+ onTimeDoubleClick: TimeDoubleClickHandler | null;
166
+ onRangeChange: RangeChangeHandler | null;
167
+ }
168
+ /**
169
+ * The state of an untouched builder. `detectedZone` is the display
170
+ * zone the builder resolved at construction (C5 default; consumers
171
+ * SHOULD call `.timezone(...)` explicitly — Article 9).
172
+ *
173
+ * Navigation refs are created up-front so `view` and `date` are
174
+ * always writable Refs. `date` is initialised in the DETECTED zone so
175
+ * the cursor's first day matches what the user sees, not whatever
176
+ * the JS engine's system zone happens to be (Docker / TZ env
177
+ * mismatches).
178
+ */
179
+ export declare function createCalendarBuilderState<TMeta extends Record<string, unknown>>(detectedZone: string): CalendarBuilderState<TMeta>;
180
+ /**
181
+ * Imperative + reactive surface returned alongside the builder.
182
+ */
183
+ export interface CalendarApi<TMeta extends Record<string, unknown> = Record<string, unknown>> {
184
+ /** `true` while at least one `eventsLoader` invocation is in flight. */
185
+ readonly loading: Readonly<Ref<boolean>>;
186
+ /** Currently rendered window. `null` before first paint. */
187
+ readonly visibleRange: Readonly<ShallowRef<ViewWindow | null>>;
188
+ /** `true` once the active view's grid has reported ready. */
189
+ readonly gridReady: Readonly<Ref<boolean>>;
190
+ /**
191
+ * The title of the visible window, exactly as the built-in header
192
+ * shows it ("15.–21. Juni 2026", "June 2026", "2026"). For hosts
193
+ * that hide the header and draw their own navigation. Right before
194
+ * any view has mounted, too (computed from the configured window).
195
+ */
196
+ readonly rangeLabel: Readonly<ComputedRef<string>>;
197
+ /**
198
+ * Continuous month view only: the month of the topmost visible
199
+ * section, live while the user scrolls (finger down, deceleration).
200
+ * The cursor (`state.date`) follows only once the scroll settles;
201
+ * `rangeLabel` uses this anchor in the meantime, like iOS. `null`
202
+ * when no continuous month surface is mounted.
203
+ */
204
+ readonly topmostVisibleMonth: Readonly<ShallowRef<Temporal.PlainYearMonth | null>>;
205
+ goTo(date: Temporal.PlainDate): void;
206
+ goToToday(): void;
207
+ next(): void;
208
+ prev(): void;
209
+ setView(view: CalendarView): void;
210
+ setMonthDensity(density: CalendarMonthDensity): void;
211
+ setDayMode(mode: CalendarDayMode): void;
212
+ /** Wired by the active view on mount. Dev-warns (once) until then. */
213
+ scrollToTime(time: Temporal.PlainTime): void;
214
+ /** Wired by the active view on mount. Dev-warns (once) until then. */
215
+ scrollToDate(date: Temporal.PlainDate): void;
216
+ /** Invalidate the entire loader cache and re-fetch the current window. */
217
+ refresh(): void;
218
+ /** Invalidate any cached entries that intersect `window` and re-fetch
219
+ * if the current window intersects. */
220
+ refreshRange(window: ViewWindow): void;
221
+ /** Synchronous read of the current window. `null` before first paint. */
222
+ getVisibleRange(): ViewWindow | null;
223
+ /** Snapshot of events visible in the current window — from
224
+ * `events()` source if set, else the loader cache (or empty if no
225
+ * cache hit yet). */
226
+ getVisibleEvents(): CalendarEvent<TMeta>[];
227
+ /** Same read for an arbitrary window (the neighbour pages the time
228
+ * grid draws while it is being swiped). Loader mode returns whatever
229
+ * the cache holds for that window — nothing until it was fetched. */
230
+ getEventsForWindow(window: ViewWindow): CalendarEvent<TMeta>[];
231
+ }
232
+ //# sourceMappingURL=calendar-builder-state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"calendar-builder-state.d.ts","sourceRoot":"","sources":["../../src/builders/calendar-builder-state.ts"],"names":[],"mappings":"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"}