kalendly 0.3.0 → 0.3.2

package/README.md

@@ -333,19 +333,24 @@ document.querySelector('kal-calendar').theme = {
 
 Primitives are set as HTML attributes:
 
-| 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     |
-| `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                             |
+| `min-date`              | `string`          | —                | Earliest bookable day, inclusive                   |
+| `max-date`              | `string`          | —                | Latest bookable day, inclusive                     |
+| `available-days`        | `string`          | —                | Bookable weekdays, e.g. `"1,2,3,4,5"`              |
+| `available-hours`       | `string`          | —                | Bookable hours, e.g. `"09:00-17:00"`               |
+| `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
 
@@ -370,11 +375,12 @@ Rich objects are set as JS properties (not attributes):
 
 ## 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).
 
@@ -479,13 +485,115 @@ 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.
+
+### Booking constraints
+
+Four optional attributes describe when a vendor is open. Omit them all and nothing is constrained.
+
+```html
+<kal-calendar
+  availability-mode="time"
+  min-date="2026-09-01"
+  max-date="2026-12-31"
+  available-days="1,2,3,4,5"
+  available-hours="09:00-12:00,13:00-17:00"
+></kal-calendar>
+```
+
+They express two different kinds of rule, which is why there are four and not two:
+
+|                         | Kind             | Says                                          |
+| ----------------------- | ---------------- | --------------------------------------------- |
+| `min-date` / `max-date` | one-off horizon  | "we take bookings from September to December" |
+| `available-days`        | recurring weekly | "we work weekdays"                            |
+| `available-hours`       | recurring daily  | "we work 9 to 5, closed for lunch"            |
+
+None substitutes for another. A horizon cannot say "weekdays only", a weekday list cannot say "not past December", and neither says anything about the working day.
+
+`min-date` and `max-date` are **inclusive** and parse like `initial-date`. `available-days` uses `Date.prototype.getDay()` numbering — `0` is Sunday — which is independent of `week-starts-on`, a display setting.
+
+`available-hours` takes a comma-separated list because a working day is not always contiguous: `"09:00-12:00,13:00-17:00"` closes for lunch, and `"09:00-17:00,17:30-22:00"` runs meetings then an evening class. Each range is half-open, `[start, end)` — `"09:00-17:00"` on an hourly grid makes 16:00–17:00 the last bookable slot, the same convention events use.
+
+Excluded **days** are not click targets at all: no hover response, and neither `cal-date-select` nor `cal-availability-select` fires. Excluded **hours** render greyed and marked `Closed`, and emit no `cal-slot-select`. They are shown rather than hidden so a booking that falls outside the window is still visible to the vendor.
+
+Style either with `--calendar-out-of-range-bg` and `--calendar-out-of-range-fg`, or the `outOfRangeBg` / `outOfRangeFg` theme keys.
+
+Bad input throws and names the attribute — an unreadable date, `min-date` after `max-date`, a weekday outside `0`–`6`, a malformed or inverted range, ranges that overlap, or a boundary that misses the `slot-duration` grid (`"09:30-17:00"` with hourly slots has no slot to land on).
+
+#### 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:
@@ -567,6 +675,27 @@ cal.getEngine();
 > `mailto:` and relative URLs; anything else becomes `#`. `color` accepts hex
 > values and CSS colour keywords.
 
+> **`name` is optional.** It is rendered only as the event card's title, and
+> availability mode never renders the card — so callers there need not supply one.
+> An event without a name renders a card with no title rather than an empty one.
+> Note this is a type-level break for anyone _reading_ `name` off
+> `cal-date-select`: the field can now be absent, so `strictNullChecks` requires a
+> guard. Nothing changes at runtime — events are handed back by reference, so
+> whatever you supply comes back intact.
+
+> **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
@@ -575,8 +704,10 @@ cal.getEngine();
 ```typescript
 interface CalendarEvent {
   id: string | number;
-  name: string;
   date: string | Date;
+  name?: string; // event card title; omit it and no title renders
+
+  endDate?: string | Date; // last day of a span, inclusive
 
   startTime?: string; // e.g. "09:00"
   endTime?: string; // e.g. "10:00"
@@ -637,6 +768,8 @@ for. Override the `--calendar-*` layer — the primitives are internal.
   --calendar-cell-hover: #f3f4f6;
   --calendar-header-bg: #f8f9fa;
   --calendar-selected-bg: #eff6ff;
+  --calendar-out-of-range-bg: #f3f4f6;
+  --calendar-out-of-range-fg: #6b7280;
   --calendar-popup-bg: #fff;
   --calendar-picker-bg: #fff;
   --calendar-today-outline: #f7db04;
@@ -699,6 +832,8 @@ cal.theme = {
   borderColor: '#e5e7eb',
   todayOutline: '#fbbf24',
   selectedBg: '#eff6ff',
+  outOfRangeBg: '#f3f4f6',
+  outOfRangeFg: '#6b7280',
   headerBg: '#f8f9fa',
   popupBg: '#ffffff',
   pickerBg: '#ffffff',

package/dist/core/index.d.mts

@@ -1,8 +1,9 @@
 type Open<T extends string> = T | (string & {});
 interface CalendarEvent {
     id: string | number;
-    name: string;
     date: string | Date;
+    name?: string;
+    endDate?: string | Date;
     startTime?: string;
     endTime?: string;
     allDay?: boolean;
@@ -103,6 +104,8 @@ interface CalendarTheme {
     borderColor?: string;
     todayOutline?: string;
     selectedBg?: string;
+    outOfRangeBg?: string;
+    outOfRangeFg?: string;
     headerBg?: string;
     popupBg?: string;
     pickerBg?: string;
@@ -145,6 +148,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 parseHourRanges(value: string, slotDuration: number): Array<[number, number]>;
+declare function isDateWithinWindow(date: Date, min: Date | null, max: Date | null): boolean;
+declare function isDayAllowed(date: Date, days: number[] | null): boolean;
+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[][];
@@ -163,6 +170,13 @@ 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;
@@ -260,4 +274,4 @@ declare class CalendarEngine {
     destroy(): void;
 }
 
-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, MONTHS, MONTHS_FULL, escapeHtml, formatAttendees, formatDateForDisplay, formatTimeRange, generateCalendarDates, generateYears, getCategoryColor, getCellClasses, getDefaultEventColor, getEventsForDate, getMonthYearText, hasEvents, isSameDay, isToday, isValidHexColor, mergeCategoryColors, normalizeDate, safeColor, safeUrl, slugifyToken, 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, isDateWithinWindow, isDayAllowed, isSameDay, isToday, isValidHexColor, mergeCategoryColors, mergeIntervals, normalizeDate, parseHourRanges, parseTimeToMinutes, safeColor, safeUrl, slugifyToken, sortEventsByTime };

package/dist/core/index.d.ts

@@ -1,8 +1,9 @@
 type Open<T extends string> = T | (string & {});
 interface CalendarEvent {
     id: string | number;
-    name: string;
     date: string | Date;
+    name?: string;
+    endDate?: string | Date;
     startTime?: string;
     endTime?: string;
     allDay?: boolean;
@@ -103,6 +104,8 @@ interface CalendarTheme {
     borderColor?: string;
     todayOutline?: string;
     selectedBg?: string;
+    outOfRangeBg?: string;
+    outOfRangeFg?: string;
     headerBg?: string;
     popupBg?: string;
     pickerBg?: string;
@@ -145,6 +148,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 parseHourRanges(value: string, slotDuration: number): Array<[number, number]>;
+declare function isDateWithinWindow(date: Date, min: Date | null, max: Date | null): boolean;
+declare function isDayAllowed(date: Date, days: number[] | null): boolean;
+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[][];
@@ -163,6 +170,13 @@ 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;
@@ -260,4 +274,4 @@ declare class CalendarEngine {
     destroy(): void;
 }
 
-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, MONTHS, MONTHS_FULL, escapeHtml, formatAttendees, formatDateForDisplay, formatTimeRange, generateCalendarDates, generateYears, getCategoryColor, getCellClasses, getDefaultEventColor, getEventsForDate, getMonthYearText, hasEvents, isSameDay, isToday, isValidHexColor, mergeCategoryColors, normalizeDate, safeColor, safeUrl, slugifyToken, 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, isDateWithinWindow, isDayAllowed, isSameDay, isToday, isValidHexColor, mergeCategoryColors, mergeIntervals, normalizeDate, parseHourRanges, parseTimeToMinutes, safeColor, safeUrl, slugifyToken, sortEventsByTime };

package/dist/core/index.js

@@ -23,11 +23,17 @@ __export(core_exports, {
   CalendarEngine: () => CalendarEngine,
   DAYS: () => DAYS,
   DEFAULT_CATEGORY_COLORS: () => DEFAULT_CATEGORY_COLORS,
+  DEFAULT_SLOT_DURATION: () => DEFAULT_SLOT_DURATION,
+  MINUTES_PER_DAY: () => MINUTES_PER_DAY,
   MONTHS: () => MONTHS,
   MONTHS_FULL: () => MONTHS_FULL,
+  bookedSlots: () => bookedSlots,
   escapeHtml: () => escapeHtml,
+  eventCoversDate: () => eventCoversDate,
+  eventInterval: () => eventInterval,
   formatAttendees: () => formatAttendees,
   formatDateForDisplay: () => formatDateForDisplay,
+  formatMinutes: () => formatMinutes,
   formatTimeRange: () => formatTimeRange,
   generateCalendarDates: () => generateCalendarDates,
   generateYears: () => generateYears,
@@ -37,11 +43,16 @@ __export(core_exports, {
   getEventsForDate: () => getEventsForDate,
   getMonthYearText: () => getMonthYearText,
   hasEvents: () => hasEvents,
+  isDateWithinWindow: () => isDateWithinWindow,
+  isDayAllowed: () => isDayAllowed,
   isSameDay: () => isSameDay,
   isToday: () => isToday,
   isValidHexColor: () => isValidHexColor,
   mergeCategoryColors: () => mergeCategoryColors,
+  mergeIntervals: () => mergeIntervals,
   normalizeDate: () => normalizeDate,
+  parseHourRanges: () => parseHourRanges,
+  parseTimeToMinutes: () => parseTimeToMinutes,
   safeColor: () => safeColor,
   safeUrl: () => safeUrl,
   slugifyToken: () => slugifyToken,
@@ -102,12 +113,76 @@ function generateYears(minYear, maxYear) {
   const max = maxYear ?? currentYear + 10;
   return Array.from({ length: max - min + 1 }, (_, i) => min + i);
 }
-function getEventsForDate(events, date) {
-  const normalizedTargetDate = normalizeDate(date);
-  return events.filter((event) => {
-    const eventDate = normalizeDate(new Date(event.date));
-    return eventDate.getTime() === normalizedTargetDate.getTime();
+function parseHourRanges(value, slotDuration) {
+  const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+  if (parts.length === 0) {
+    throw new Error(
+      `<kal-calendar> available-hours is empty. Omit the attribute to allow every hour, or name at least one HH:MM-HH:MM range.`
+    );
+  }
+  const ranges = parts.map((part) => {
+    const halves = part.split("-");
+    if (halves.length !== 2) {
+      throw new Error(
+        `<kal-calendar> available-hours range "${part}" is not HH:MM-HH:MM.`
+      );
+    }
+    const [start, end] = halves.map((half) => parseTimeToMinutes(half.trim()));
+    if (start === null || end === null) {
+      throw new Error(
+        `<kal-calendar> available-hours range "${part}" has an unreadable time. Use 24-hour HH:MM.`
+      );
+    }
+    if (start >= end) {
+      throw new Error(
+        `<kal-calendar> available-hours range "${part}" starts at or after it ends.`
+      );
+    }
+    if (start % slotDuration !== 0 || end % slotDuration !== 0) {
+      throw new Error(
+        `<kal-calendar> available-hours range "${part}" does not land on a ${slotDuration}-minute slot boundary.`
+      );
+    }
+    return [start, end];
   });
+  if (mergeIntervals(ranges).length !== ranges.length) {
+    throw new Error(
+      `<kal-calendar> available-hours ranges overlap or touch: "${value}". Write each bookable window once.`
+    );
+  }
+  return ranges;
+}
+function isDateWithinWindow(date, min, max) {
+  const target = normalizeDate(date).getTime();
+  if (min && target < normalizeDate(min).getTime()) return false;
+  if (max && target > normalizeDate(max).getTime()) return false;
+  return true;
+}
+function isDayAllowed(date, days) {
+  return days === null || days.includes(date.getDay());
+}
+function eventCoversDate(event, date) {
+  const start = normalizeDate(new Date(event.date)).getTime();
+  const target = normalizeDate(date).getTime();
+  if (Number.isNaN(start)) return false;
+  if (event.endDate === void 0 || event.endDate === null) {
+    return start === target;
+  }
+  const end = normalizeDate(new Date(event.endDate)).getTime();
+  if (Number.isNaN(end)) {
+    throw new Error(
+      `<kal-calendar> event ${event.id} has an unreadable endDate: ${String(event.endDate)}.`
+    );
+  }
+  if (end < start) {
+    throw new Error(
+      `<kal-calendar> event ${event.id} has an endDate before its date: ${String(event.endDate)} < ${String(event.date)}.`
+    );
+  }
+  return target >= start && target <= end;
+}
+function getEventsForDate(events, date) {
+  return events.filter((event) => eventCoversDate(event, date));
 }
 function hasEvents(events, date) {
   return getEventsForDate(events, date).length > 0;
@@ -266,6 +341,68 @@ function safeColor(value) {
   const trimmed = String(value).trim();
   return isValidHexColor(trimmed) || /^[a-z]+$/i.test(trimmed) ? trimmed : "#3b82f6";
 }
+var MINUTES_PER_DAY = 1440;
+var DEFAULT_SLOT_DURATION = 60;
+function parseTimeToMinutes(time) {
+  if (typeof time !== "string") return null;
+  const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+  if (!match) return null;
+  const hours = Number(match[1]);
+  const mins = Number(match[2]);
+  if (hours > 24 || mins > 59 || hours === 24 && mins > 0) return null;
+  return hours * 60 + mins;
+}
+function formatMinutes(total) {
+  const hours = Math.floor(total / 60);
+  const mins = total % 60;
+  return `${String(hours).padStart(2, "0")}:${String(mins).padStart(2, "0")}`;
+}
+function eventInterval(event, slotDuration, onDay) {
+  const day = normalizeDate(onDay).getTime();
+  if (Number.isNaN(day)) return null;
+  const base = day / 6e4;
+  const wholeDay = [base, base + MINUTES_PER_DAY];
+  if (event.allDay || !event.startTime) return wholeDay;
+  const from = parseTimeToMinutes(event.startTime);
+  if (from === null) return wholeDay;
+  if (event.endTime === void 0 || event.endTime === null) {
+    return [base + from, base + from + slotDuration];
+  }
+  const to = parseTimeToMinutes(event.endTime);
+  if (to === null) return wholeDay;
+  return [base + from, base + (to <= from ? to + MINUTES_PER_DAY : to)];
+}
+function mergeIntervals(intervals) {
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
+  return sorted.reduce((merged, [start, end]) => {
+    const last = merged[merged.length - 1];
+    if (last && start <= last[1]) last[1] = Math.max(last[1], end);
+    else merged.push([start, end]);
+    return merged;
+  }, []);
+}
+function bookedSlots(events, date, slotDuration = DEFAULT_SLOT_DURATION) {
+  const base = normalizeDate(date).getTime() / 6e4;
+  const previousDay = new Date(date);
+  previousDay.setDate(previousDay.getDate() - 1);
+  const intervals = [];
+  for (const event of new Set(events)) {
+    for (const day of [previousDay, date]) {
+      if (!eventCoversDate(event, day)) continue;
+      const interval = eventInterval(event, slotDuration, day);
+      if (interval) intervals.push(interval);
+    }
+  }
+  const merged = mergeIntervals(intervals);
+  return Array.from(
+    { length: Math.floor(MINUTES_PER_DAY / slotDuration) },
+    (_, index) => {
+      const start = base + index * slotDuration;
+      const end = start + slotDuration;
+      return merged.some(([from, to]) => start < to && end > from);
+    }
+  );
+}
 
 // src/core/calendar-engine.ts
 var CalendarEngine = class {
@@ -513,11 +650,17 @@ var CalendarEngine = class {
   CalendarEngine,
   DAYS,
   DEFAULT_CATEGORY_COLORS,
+  DEFAULT_SLOT_DURATION,
+  MINUTES_PER_DAY,
   MONTHS,
   MONTHS_FULL,
+  bookedSlots,
   escapeHtml,
+  eventCoversDate,
+  eventInterval,
   formatAttendees,
   formatDateForDisplay,
+  formatMinutes,
   formatTimeRange,
   generateCalendarDates,
   generateYears,
@@ -527,11 +670,16 @@ var CalendarEngine = class {
   getEventsForDate,
   getMonthYearText,
   hasEvents,
+  isDateWithinWindow,
+  isDayAllowed,
   isSameDay,
   isToday,
   isValidHexColor,
   mergeCategoryColors,
+  mergeIntervals,
   normalizeDate,
+  parseHourRanges,
+  parseTimeToMinutes,
   safeColor,
   safeUrl,
   slugifyToken,