kalendly 0.2.2 → 0.3.1

package/README.md

@@ -62,7 +62,7 @@ npm install kalendly
 />
 <script src="https://unpkg.com/kalendly/dist/index.umd.js"></script>
 
-<kal-calendar id="cal" title="My Calendar"></kal-calendar>
+<kal-calendar id="cal" heading="My Calendar"></kal-calendar>
 
 <script>
   const cal = document.getElementById('cal');
@@ -104,7 +104,7 @@ import 'kalendly/styles';
 function App() {
   return (
     <kal-calendar
-      title="My Calendar"
+      heading="My Calendar"
       events={events}
       oncal-date-select={e => console.log(e.detail.date)}
       oncal-month-change={e => console.log(e.detail.year, e.detail.month)}
@@ -198,7 +198,7 @@ Without this the component still renders correctly — Vue falls back to a nativ
 ```vue
 <template>
   <kal-calendar
-    title="My Calendar"
+    heading="My Calendar"
     :events="events"
     @cal-date-select="onDateSelect"
     @cal-month-change="onMonthChange"
@@ -236,7 +236,7 @@ import 'kalendly/styles';
 ```html
 <!-- app.component.html -->
 <kal-calendar
-  title="My Calendar"
+  heading="My Calendar"
   [events]="events"
   (cal-date-select)="onDateSelect($event)"
   (cal-month-change)="onMonthChange($event)"
@@ -280,7 +280,7 @@ import 'kalendly/styles';
 function App() {
   return (
     <kal-calendar
-      title="My Calendar"
+      heading="My Calendar"
       prop:events={events}
       on:cal-date-select={e => console.log(e.detail.date)}
     />
@@ -316,7 +316,7 @@ kalendly uses Light DOM — all standard CSS techniques work:
 }
 
 /* 2. Direct class overrides */
-.kalendly-calendar .calendar--card {
+.kalendly-calendar .calendar-card {
   border-radius: 12px;
 }
 ```
@@ -333,40 +333,50 @@ document.querySelector('kal-calendar').theme = {
 
 Primitives are set as HTML attributes:
 
-| Attribute               | Type             | Default          | Description                                      |
-| ----------------------- | ---------------- | ---------------- | ------------------------------------------------ |
-| `title`                 | `string`         | —                | Calendar title                                   |
-| `initial-date`          | `string`         | today            | ISO date string for initial view                 |
-| `min-year`              | `string`         | currentYear - 30 | Minimum year in picker                           |
-| `max-year`              | `string`         | currentYear + 10 | Maximum year in picker                           |
-| `week-starts-on`        | `"0"\|"1"`       | `"0"`            | Week start: 0 = Sunday, 1 = Monday               |
-| `use-short-month-names` | `string`         | —                | Present = use abbreviated month names            |
-| `availability-mode`     | `"day"\|"time"`  | —                | Hides event details; shows booked/free cells     |
-| `selectable`            | `"range"`        | —                | Enables day/slot selection (requires avail mode) |
-| `loading`               | `boolean` (flag) | —                | Present = render skeleton shimmer cells          |
+| Attribute               | Type              | Default          | Description                                        |
+| ----------------------- | ----------------- | ---------------- | -------------------------------------------------- |
+| `heading`               | `string`          | —                | Calendar heading                                   |
+| `title`                 | `string`          | —                | **Deprecated** — use `heading`                     |
+| `initial-date`          | `string`          | today            | ISO date string for initial view                   |
+| `months`                | `"1"\|"2"`        | `"1"`            | Render two months side by side                     |
+| `min-year`              | `string`          | currentYear - 30 | Minimum year in picker                             |
+| `max-year`              | `string`          | currentYear + 10 | Maximum year in picker                             |
+| `week-starts-on`        | `"0"\|"1"`        | `"0"`            | Week start: 0 = Sunday, 1 = Monday                 |
+| `use-short-month-names` | `string`          | —                | Present = use abbreviated month names              |
+| `availability-mode`     | `"day"\|"time"`   | —                | Hides event details; shows booked/free cells       |
+| `slot-duration`         | `string` (number) | `"60"`           | Time-grid granularity in minutes; must divide 1440 |
+| `selectable`            | `"range"`         | —                | Enables day/slot selection (requires avail mode)   |
+| `loading`               | `boolean` (flag)  | —                | Present = render skeleton shimmer cells            |
 
 ## Properties
 
 Rich objects are set as JS properties (not attributes):
 
-| Property         | Type                               | Description                                       |
-| ---------------- | ---------------------------------- | ------------------------------------------------- |
-| `events`         | `CalendarEvent[]`                  | Events to display                                 |
-| `loading`        | `boolean`                          | `true` = render skeleton cells; `false` = restore |
-| `theme`          | `CalendarTheme`                    | Custom theme colors                               |
-| `categoryColors` | `CategoryColorMap`                 | Per-category color overrides                      |
-| `renderEvent`    | `(event: CalendarEvent) => string` | Custom event HTML renderer                        |
-| `renderNoEvents` | `() => string`                     | Custom empty-state HTML renderer                  |
+| Property             | Type                               | Description                                       |
+| -------------------- | ---------------------------------- | ------------------------------------------------- |
+| `events`             | `CalendarEvent[]`                  | Events to display                                 |
+| `loading`            | `boolean`                          | `true` = render skeleton cells; `false` = restore |
+| `theme`              | `CalendarTheme`                    | Custom theme colors                               |
+| `categoryColors`     | `CategoryColorMap`                 | Per-category color overrides                      |
+| `renderEvent`        | `(event: CalendarEvent) => string` | Custom event HTML renderer                        |
+| `renderNoEvents`     | `() => string`                     | Custom empty-state HTML renderer                  |
+| `availabilityColors` | `Record<string, string>`           | Colour per availability bucket                    |
+| `selectableStatuses` | `string[]`                         | Buckets a range may start, end or span            |
 
 > `renderEvent` and `renderNoEvents` are ignored when `availability-mode` is set.
 
+### Why `heading` and not `title`
+
+`title` is a global HTML attribute, so the browser renders it as a tooltip floating over the whole calendar as well as using it as the heading. `heading` does the same job without the tooltip. `title` still works and warns once per page; it will be removed in a future release.
+
 ## Custom Events
 
-| Event                     | `detail` shape                                                         | Description                            |
-| ------------------------- | ---------------------------------------------------------------------- | -------------------------------------- |
-| `cal-date-select`         | `{ date: Date, events: CalendarEvent[] }`                              | User clicked a date (normal mode)      |
-| `cal-month-change`        | `{ year: number, month: number }`                                      | Fires **before** the new month renders |
-| `cal-availability-select` | `{ startDate: Date, endDate: Date }` or `{ date, startTime, endTime }` | Day/slot selected in availability mode |
+| Event                     | `detail` shape                                                         | Description                                               |
+| ------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
+| `cal-date-select`         | `{ date: Date, events: CalendarEvent[] }`                              | User clicked a date (normal mode)                         |
+| `cal-month-change`        | `{ year: number, month: number }`                                      | Fires **before** the new month renders                    |
+| `cal-availability-select` | `{ startDate: Date, endDate: Date }` or `{ date, startTime, endTime }` | Day/slot selected in availability mode                    |
+| `cal-slot-select`         | `{ date: Date, startTime: string, endTime: string, booked: boolean }`  | Any time slot clicked, whether or not `selectable` is set |
 
 All events bubble and are composed (cross Shadow DOM boundaries).
 
@@ -385,7 +395,70 @@ Hides all event details from the end user — only booked/free state is shown. D
 <kal-calendar availability-mode="day"></kal-calendar>
 ```
 
-Days with events are tinted red (booked); days without events are tinted green (free). Only cells in the current month are colour-coded — other-month cells remain grayed out. Clicking a day fires no popup and reveals no event details.
+Every event must declare `availabilityStatus`. Three buckets ship built in, coloured as a traffic light:
+
+| Bucket        | Colour | Meaning                                   |
+| ------------- | ------ | ----------------------------------------- |
+| `open`        | green  | nothing claims this day                   |
+| `conditional` | amber  | claimed, but not necessarily hard-blocked |
+| `blocked`     | red    | not available                             |
+
+```js
+cal.events = [
+  { id: 1, date: '2026-03-02', availabilityStatus: 'blocked' },
+  { id: 2, date: '2026-03-05', availabilityStatus: 'conditional' },
+];
+```
+
+Only cells in the current month are colour-coded — other-month cells remain grayed out. Clicking a day fires no popup and reveals no event details.
+
+A day holding several events resolves by severity: `blocked` beats `conditional` beats `open`, so a day with both a conditional and a blocked booking reads blocked. Precedence never depends on the order events arrive in.
+
+#### Your own buckets
+
+`availabilityColors` merges over the built-in three — override one, or add your own:
+
+```js
+cal.availabilityColors = {
+  conditional: '#7c3aed', // recolour a built-in
+  maintenance: '#0891b2', // add a bucket
+};
+cal.events = [{ id: 3, date: '2026-03-09', availabilityStatus: 'maintenance' }];
+```
+
+A bucket named in `availabilityColors` paints from an inline colour, which takes precedence over the same colour set through `theme`. The built-in three paint from CSS variables and are themeable the usual way.
+
+Caller-defined buckets resolve by the order their keys appear in `availabilityColors`.
+
+#### Which days are selectable
+
+By default only `open` days can start, end or span a range. `selectableStatuses` widens that:
+
+```js
+cal.selectableStatuses = ['open', 'conditional'];
+```
+
+#### Misconfiguration throws
+
+An event with no `availabilityStatus`, or one naming a bucket that is neither built in nor declared in `availabilityColors`, throws and names the offending events:
+
+```
+<kal-calendar> availability-mode requires availabilityStatus on every event. Missing on: 7, 9.
+```
+
+Setting `events` throws where you set it. One case cannot: markup parsed before the module defines the element configures the calendar inside a custom element upgrade, and the browser reports exceptions there as uncaught rather than passing them to your code. The failure is kept, so the next call to `getEngine()`, `getCurrentDate()` or `goToDate()` throws it, and correcting `events` or `availabilityColors` clears it.
+
+#### Two months side by side
+
+```html
+<kal-calendar
+  availability-mode="day"
+  months="2"
+  selectable="range"
+></kal-calendar>
+```
+
+Navigation advances one month at a time, so a range spanning a month boundary stays visible. Ranges cross panes freely, and it works in standard and time modes too. Panes stack vertically on narrow screens.
 
 <div align="center">
   <img src="./docs/images/day.png" alt="Availability day view — month grid with red booked cells and green free cells"/>
@@ -408,13 +481,81 @@ cal.events = [
 <kal-calendar availability-mode="time"></kal-calendar>
 ```
 
-Clicking a day opens a popup with a 24-slot hourly grid (00:00 – 23:00). Each slot shows only "Booked" or "Available" — no event name or organiser is ever rendered. A slot is booked if any event's time window overlaps that hour; the rest are free.
+Clicking a day opens a popup with a grid of slots. Each shows only "Booked" or "Available" — no event name or organiser is ever rendered. A slot is booked when any booking overlaps it.
+
+#### Slot length
+
+`slot-duration` sets the grid granularity in minutes. It must divide 1440 evenly; anything else falls back to 60 with a console warning.
+
+```html
+<kal-calendar availability-mode="time" slot-duration="30"></kal-calendar>
+```
+
+The grid renders `1440 / slot-duration` slots, and `cal-availability-select` emits times on that granularity — half-hour slots produce half-hour selections.
+
+Precision below `slot-duration` is not representable: a booking from 17:30 on a 60-minute grid marks 17:00–18:00 booked, because that hour cannot be sold. A vendor working in half-hours sets `slot-duration="30"` rather than expecting the grid to subdivide itself.
+
+#### Bookings that cross midnight
+
+An `endTime` at or before its `startTime` is treated as the next day, so a booking runs as one interval rather than two half-days:
+
+```js
+{ id: 1, date: '2026-03-15', startTime: '22:00', endTime: '06:00' }
+```
+
+That marks 22:00–24:00 on 15 March and 00:00–06:00 on the 16th. Each day's grid shows the portion of any booking falling on that day.
+
+#### A booking with no end time
+
+An event with a `startTime` and no `endTime` occupies **one slot**, and the library warns once naming the event. The supported fix is an end time in your data — the duration is a fallback, not a feature.
+
+Overlapping bookings merge rather than double-count, so a 09:00–17:00 meeting and a 17:30–22:00 class on the same day mark 09:00–22:00 booked between them.
 
 <div align="center">
   <img src="./docs/images/time.png" alt="Availability time view — day popup showing 24 hourly slots coloured red (booked) or green (available)"/>
   <p><em>Time view: clicking a day opens an hourly grid — booked slots in red, available slots in green; no event details exposed</em></p>
 </div>
 
+#### Reacting to a slot click
+
+`cal-slot-select` fires on every slot click, the way `cal-date-select` fires for
+every day — including booked slots, and whether or not `selectable` is set. Use it
+to drive your own booking flow without turning on range selection:
+
+```js
+cal.addEventListener('cal-slot-select', e => {
+  const { date, startTime, endTime, booked } = e.detail;
+  if (booked) return showTakenMessage(startTime);
+  openBookingForm(date, startTime, endTime);
+});
+```
+
+`selectable="range"` still governs `cal-availability-select`, the three-click
+range machine and the range highlighting. It also controls the cursor: slots only
+show a pointer when the grid can actually be booked from.
+
+#### Round-tripping a selection
+
+`cal-availability-select` emits an inclusive `endDate`, so a saved selection goes
+straight back as a single event — no expanding into one event per day:
+
+```js
+cal.addEventListener('cal-availability-select', async e => {
+  const { startDate, endDate } = e.detail;
+  const booking = await save({ startDate, endDate });
+
+  cal.events = [
+    ...cal.events,
+    {
+      id: booking.id,
+      date: startDate,
+      endDate,
+      availabilityStatus: 'blocked',
+    },
+  ];
+});
+```
+
 ### Selectable range
 
 Add `selectable="range"` to let the user pick a free day or time slot:
@@ -489,30 +630,57 @@ cal.getEngine();
 
 ## CalendarEvent Interface
 
+> **Event text renders as text.** `name`, `description`, `location`,
+> `organizer`, `notes`, `tags` and `attendees` are HTML-escaped, so markup in
+> those fields shows as characters rather than being parsed. Use `renderEvent`
+> if you need to emit your own markup. `url` accepts `http:`, `https:`,
+> `mailto:` and relative URLs; anything else becomes `#`. `color` accepts hex
+> values and CSS colour keywords.
+
+> **Multi-day events.** `endDate` is the last day of a span and is **inclusive** —
+> `date: '2026-03-03', endDate: '2026-03-05'` covers three days. That matches the
+> `endDate` `cal-availability-select` emits, so a selection can be handed straight
+> back as one event. It deliberately differs from RFC 5545, whose all-day `DTEND`
+> is exclusive; adjust if you map to iCalendar. An `endDate` before `date`, or one
+> that cannot be read, throws and names the event.
+>
+> Times on a span repeat daily: `09:00`–`17:00` across three days means that
+> window on each of the three, not one continuous block. A hall can hold a
+> 09:00–17:00 meeting and a 17:30–22:00 class on overlapping days.
+>
+> `recurring` is declared on the type but not implemented — nothing reads it.
+
+> **Custom values.** `status`, `category` and `priority` accept any string. An
+> unrecognised value renders as an uppercased badge with a neutral fill, which
+> you can style via `.badge.status-<your-value>` or recolour through
+> `--calendar-badge-bg` / `--calendar-badge-text`.
+
 ```typescript
 interface CalendarEvent {
   id: string | number;
   name: string;
   date: string | Date;
 
+  endDate?: string | Date; // last day of a span, inclusive
+
   startTime?: string; // e.g. "09:00"
   endTime?: string; // e.g. "10:00"
   allDay?: boolean;
 
   description?: string;
   color?: string;
-  category?:
-    | 'work'
-    | 'personal'
-    | 'meeting'
-    | 'deadline'
-    | 'appointment'
-    | 'other';
+  // Known values keep autocomplete; any other string is accepted
+  category?: Open<
+    'work' | 'personal' | 'meeting' | 'deadline' | 'appointment' | 'other'
+  >;
   location?: string;
   url?: string;
 
-  status?: 'scheduled' | 'completed' | 'cancelled' | 'tentative';
-  priority?: 'low' | 'medium' | 'high';
+  status?: Open<'scheduled' | 'completed' | 'cancelled' | 'tentative'>;
+  priority?: Open<'low' | 'medium' | 'high'>;
+
+  // Required under availability-mode; see Availability Mode below
+  availabilityStatus?: Open<'open' | 'conditional' | 'blocked'>;
 
   attendees?: string[];
   organizer?: string;
@@ -532,26 +700,77 @@ interface CalendarEvent {
 
 ## Theming
 
-### All CSS variables
+### Design tokens
+
+Every colour, size, radius, shadow and spacing step is a custom property. Two
+tiers: `--kal-*` holds the raw palette, `--calendar-*` names what each value is
+for. Override the `--calendar-*` layer — the primitives are internal.
 
 ```css
 :root {
+  /* Brand */
   --calendar-primary-color: #fc8917;
   --calendar-secondary-color: #fca045;
   --calendar-tertiary-color: #fdb873;
+
+  /* Surfaces and text */
   --calendar-text-color: #2c3e50;
   --calendar-text-light: #6b7280;
-  --calendar-border-color: #dee2e6;
-  --calendar-today-outline: #f7db04;
-  --calendar-event-indicator: #1890ff;
+  --calendar-on-accent: #fff;
   --calendar-background: #fff;
+  --calendar-border-color: #dee2e6;
   --calendar-cell-hover: #f3f4f6;
+  --calendar-header-bg: #f8f9fa;
   --calendar-selected-bg: #eff6ff;
+  --calendar-popup-bg: #fff;
+  --calendar-picker-bg: #fff;
+  --calendar-today-outline: #f7db04;
+  --calendar-event-indicator: #1890ff;
+  --calendar-input-invalid: #ef4444;
+  --calendar-link: #2563eb;
+  --calendar-skeleton-base: #f0f0f0;
+  --calendar-skeleton-highlight: #e8e8e8;
+
+  /* Availability */
+  --calendar-open-bg: #dcfce7;
+  --calendar-open-fg: #16a34a;
+  --calendar-conditional-bg: #fef3c7;
+  --calendar-conditional-fg: #d97706;
+  --calendar-blocked-bg: #fee2e2;
+  --calendar-blocked-fg: #dc2626;
+  --calendar-range-bg: #16a34a;
+  --calendar-range-outline: #15803d;
+  --calendar-in-range-bg: #bbf7d0;
+  --calendar-in-range-outline: #86efac;
+
+  /* Badges — bg/text is the fallback for caller-defined values */
+  --calendar-badge-bg: #f3f4f6;
+  --calendar-badge-text: #4b5563;
+  --calendar-badge-success-bg: #d1fae5;
+  --calendar-badge-success-text: #059669;
+  --calendar-badge-info-bg: #dbeafe;
+  --calendar-badge-info-text: #2563eb;
+  --calendar-badge-warning-bg: #fef3c7;
+  --calendar-badge-warning-text: #d97706;
+  --calendar-badge-danger-bg: #fee2e2;
+  --calendar-badge-danger-text: #dc2626;
+  --calendar-badge-neutral-bg: #f3f4f6;
+  --calendar-badge-neutral-text: #6b7280;
+  --calendar-badge-positive-bg: #dcfce7;
+  --calendar-badge-positive-text: #16a34a;
+  --calendar-badge-tentative-bg: #e0e7ff;
+  --calendar-badge-tentative-text: #4f46e5;
 }
 ```
 
+Type, radius, elevation and spacing scales are exposed the same way —
+`--calendar-font-*`, `--calendar-radius-*`, `--calendar-shadow-*` and
+`--calendar-space-*`. See `dist/styles/calendar.css` for the full set.
+
 ### JS theme property (full reference)
 
+Every `--calendar-*` colour token has a matching camelCase theme key.
+
 ```js
 cal.theme = {
   primary: '#3b82f6',
@@ -559,15 +778,54 @@ cal.theme = {
   tertiary: '#93c5fd',
   textColor: '#111827',
   textLight: '#6b7280',
+  onAccent: '#ffffff',
   background: '#ffffff',
   cellHover: '#f3f4f6',
   borderColor: '#e5e7eb',
   todayOutline: '#fbbf24',
   selectedBg: '#eff6ff',
+  headerBg: '#f8f9fa',
+  popupBg: '#ffffff',
+  pickerBg: '#ffffff',
+  pickerShadow: '0 4px 20px rgba(0, 0, 0, 0.15)',
   eventIndicator: '#10b981',
+  link: '#2563eb',
+
+  // Availability
+  openBg: '#dcfce7',
+  openFg: '#16a34a',
+  conditionalBg: '#fef3c7',
+  conditionalFg: '#d97706',
+  blockedBg: '#fee2e2',
+  blockedFg: '#dc2626',
+  rangeBg: '#16a34a',
+  rangeOutline: '#15803d',
+  inRangeBg: '#bbf7d0',
+  inRangeOutline: '#86efac',
+
+  // Badges
+  badgeBg: '#f3f4f6',
+  badgeText: '#4b5563',
+  badgeSuccessBg: '#d1fae5',
+  badgeSuccessText: '#059669',
+  badgeInfoBg: '#dbeafe',
+  badgeInfoText: '#2563eb',
+  badgeWarningBg: '#fef3c7',
+  badgeWarningText: '#d97706',
+  badgeDangerBg: '#fee2e2',
+  badgeDangerText: '#dc2626',
+  badgeNeutralBg: '#f3f4f6',
+  badgeNeutralText: '#6b7280',
+  badgePositiveBg: '#dcfce7',
+  badgePositiveText: '#16a34a',
+  badgeTentativeBg: '#e0e7ff',
+  badgeTentativeText: '#4f46e5',
 };
 ```
 
+> `availabilityColors` writes an inline colour on the cell, so for any bucket it
+> names it takes precedence over the matching `theme` key.
+
 ### Dark theme example
 
 ```js

package/dist/core/index.d.mts

@@ -1,17 +1,20 @@
+type Open<T extends string> = T | (string & {});
 interface CalendarEvent {
     id: string | number;
     name: string;
     date: string | Date;
+    endDate?: string | Date;
     startTime?: string;
     endTime?: string;
     allDay?: boolean;
     description?: string;
     color?: string;
-    category?: 'work' | 'personal' | 'meeting' | 'deadline' | 'appointment' | 'other';
+    category?: Open<'work' | 'personal' | 'meeting' | 'deadline' | 'appointment' | 'other'>;
     location?: string;
     url?: string;
-    status?: 'scheduled' | 'completed' | 'cancelled' | 'tentative';
-    priority?: 'low' | 'medium' | 'high';
+    status?: Open<'scheduled' | 'completed' | 'cancelled' | 'tentative'>;
+    priority?: Open<'low' | 'medium' | 'high'>;
+    availabilityStatus?: Open<'open' | 'conditional' | 'blocked'>;
     attendees?: string[];
     organizer?: string;
     reminders?: number[];
@@ -52,6 +55,13 @@ interface CalendarConfig {
     maxYear?: number;
     weekStartsOn?: 0 | 1;
     categoryColors?: CategoryColorMap;
+    monthCount?: number;
+}
+interface CalendarPane {
+    year: number;
+    month: number;
+    monthAndYearText: string;
+    calendarDates: CalendarDate[][];
 }
 interface CalendarActions {
     next: () => void;
@@ -62,18 +72,14 @@ interface CalendarActions {
     selectDate: (date: Date) => void;
     updateTasks: () => void;
 }
-interface PopupPosition {
-    class: 'popup-left' | 'popup-right' | 'popup-center-top' | 'popup-center-bottom';
-    style?: Record<string, string | number>;
-}
 interface CalendarViewModel extends CalendarState {
     months: string[];
     days: string[];
     years: number[];
     monthAndYearText: string;
     scheduleDay: string;
+    panes: CalendarPane[];
     calendarDates: CalendarDate[][];
-    popupPositionClass: string;
 }
 type CalendarEventHandler = (event: CalendarEvent) => void;
 interface CalendarProps {
@@ -100,7 +106,37 @@ interface CalendarTheme {
     selectedBg?: string;
     headerBg?: string;
     popupBg?: string;
+    pickerBg?: string;
+    pickerShadow?: string;
     eventIndicator?: string;
+    onAccent?: string;
+    link?: string;
+    openBg?: string;
+    openFg?: string;
+    conditionalBg?: string;
+    conditionalFg?: string;
+    blockedBg?: string;
+    blockedFg?: string;
+    rangeBg?: string;
+    rangeOutline?: string;
+    inRangeBg?: string;
+    inRangeOutline?: string;
+    badgeBg?: string;
+    badgeText?: string;
+    badgeSuccessBg?: string;
+    badgeSuccessText?: string;
+    badgeInfoBg?: string;
+    badgeInfoText?: string;
+    badgeWarningBg?: string;
+    badgeWarningText?: string;
+    badgeDangerBg?: string;
+    badgeDangerText?: string;
+    badgeNeutralBg?: string;
+    badgeNeutralText?: string;
+    badgePositiveBg?: string;
+    badgePositiveText?: string;
+    badgeTentativeBg?: string;
+    badgeTentativeText?: string;
 }
 
 declare const MONTHS: string[];
@@ -110,10 +146,10 @@ declare function normalizeDate(date: Date): Date;
 declare function isSameDay(date1: Date, date2: Date): boolean;
 declare function isToday(date: Date): boolean;
 declare function generateYears(minYear?: number, maxYear?: number): number[];
+declare function eventCoversDate(event: CalendarEvent, date: Date): boolean;
 declare function getEventsForDate(events: CalendarEvent[], date: Date): CalendarEvent[];
 declare function hasEvents(events: CalendarEvent[], date: Date): boolean;
 declare function generateCalendarDates(year: number, month: number, events?: CalendarEvent[], weekStartsOn?: 0 | 1): CalendarDate[][];
-declare function getPopupPositionClass(selectedDayIndex: number | null): string;
 declare function getCellClasses(calendarDate: CalendarDate): string[];
 declare function formatDateForDisplay(date: Date): string;
 declare function getMonthYearText(year: number, month: number): string;
@@ -125,6 +161,17 @@ declare function getDefaultEventColor(category?: string, customColors?: Category
 declare function mergeCategoryColors(customColors?: CategoryColorMap): CategoryColorMap;
 declare function isValidHexColor(color: string): boolean;
 declare function getCategoryColor(category: string, customColors?: CategoryColorMap): string;
+declare function escapeHtml(value: unknown): string;
+declare function slugifyToken(value: string): string;
+declare function safeUrl(value: string): string;
+declare function safeColor(value: string): string;
+declare const MINUTES_PER_DAY = 1440;
+declare const DEFAULT_SLOT_DURATION = 60;
+declare function parseTimeToMinutes(time: unknown): number | null;
+declare function formatMinutes(total: number): string;
+declare function eventInterval(event: CalendarEvent, slotDuration: number, onDay: Date): [number, number] | null;
+declare function mergeIntervals(intervals: Array<[number, number]>): Array<[number, number]>;
+declare function bookedSlots(events: CalendarEvent[], date: Date, slotDuration?: number): boolean[];
 
 declare class CalendarEngine {
     private state;
@@ -222,4 +269,4 @@ declare class CalendarEngine {
     destroy(): void;
 }
 
-export { type CalendarActions, type CalendarConfig, type CalendarDate, CalendarEngine, type CalendarEvent, type CalendarEventHandler, type CalendarProps, type CalendarState, type CalendarTheme, type CalendarViewModel, type CategoryColorMap, DAYS, DEFAULT_CATEGORY_COLORS, MONTHS, MONTHS_FULL, type PopupPosition, formatAttendees, formatDateForDisplay, formatTimeRange, generateCalendarDates, generateYears, getCategoryColor, getCellClasses, getDefaultEventColor, getEventsForDate, getMonthYearText, getPopupPositionClass, hasEvents, isSameDay, isToday, isValidHexColor, mergeCategoryColors, normalizeDate, sortEventsByTime };
+export { type CalendarActions, type CalendarConfig, type CalendarDate, CalendarEngine, type CalendarEvent, type CalendarEventHandler, type CalendarPane, type CalendarProps, type CalendarState, type CalendarTheme, type CalendarViewModel, type CategoryColorMap, DAYS, DEFAULT_CATEGORY_COLORS, DEFAULT_SLOT_DURATION, MINUTES_PER_DAY, MONTHS, MONTHS_FULL, bookedSlots, escapeHtml, eventCoversDate, eventInterval, formatAttendees, formatDateForDisplay, formatMinutes, formatTimeRange, generateCalendarDates, generateYears, getCategoryColor, getCellClasses, getDefaultEventColor, getEventsForDate, getMonthYearText, hasEvents, isSameDay, isToday, isValidHexColor, mergeCategoryColors, mergeIntervals, normalizeDate, parseTimeToMinutes, safeColor, safeUrl, slugifyToken, sortEventsByTime };