kalendly 0.2.0 → 0.2.2

package/README.md

@@ -9,6 +9,8 @@ A universal calendar web component — works in React, Vue, Svelte, Angular, Sol
 - **Themeable**: CSS variables + JS property API
 - **Type Safe**: Full TypeScript support
 - **Event-rich**: Categories, priorities, time ranges, attendees, and more
+- **Availability mode**: Day and time views for booking flows — hides event details, shows booked/free cells
+- **Lazy loading**: Per-month on-demand fetch with skeleton shimmer state
 - **Accessible**: Built with accessibility in mind
 - **Tree-shakeable**: Import only what you need
 
@@ -60,11 +62,7 @@ npm install kalendly
 />
 <script src="https://unpkg.com/kalendly/dist/index.umd.js"></script>
 
-<kal-calendar
-  id="cal"
-  title="My Calendar"
-  initial-date="2025-01-15"
-></kal-calendar>
+<kal-calendar id="cal" title="My Calendar"></kal-calendar>
 
 <script>
   const cal = document.getElementById('cal');
@@ -147,7 +145,55 @@ function App() {
 
 ### Vue 3
 
-Vue 3 supports custom elements natively — bind props with `:` and listen to events with `@`:
+Vue 3 supports custom elements natively — bind props with `:` and listen to events with `@`.
+
+> **Vue-specific:** Vue's template compiler warns on unknown tags. React, Solid.js, and Svelte treat hyphenated tags as DOM elements natively — no config needed. Angular uses `CUSTOM_ELEMENTS_SCHEMA` (see the Angular section below).
+
+Tell Vue's compiler that `<kal-*>` tags are native custom elements. The config location depends on your build tool:
+
+**Vite** (`vite.config.ts`):
+
+```ts
+vue({
+  template: {
+    compilerOptions: {
+      isCustomElement: tag => tag.startsWith('kal-'),
+    },
+  },
+});
+```
+
+**Nuxt 3** (`nuxt.config.ts`):
+
+```ts
+export default defineNuxtConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: tag => tag.startsWith('kal-'),
+    },
+  },
+});
+```
+
+**webpack / Vue CLI** (`vue.config.js`):
+
+```js
+module.exports = {
+  chainWebpack: config => {
+    config.module
+      .rule('vue')
+      .use('vue-loader')
+      .tap(options => ({
+        ...options,
+        compilerOptions: {
+          isCustomElement: tag => tag.startsWith('kal-'),
+        },
+      }));
+  },
+};
+```
+
+Without this the component still renders correctly — Vue falls back to a native DOM element. This only suppresses the console warning.
 
 ```vue
 <template>
@@ -242,20 +288,6 @@ function App() {
 }
 ```
 
-## Migration from v0.1.x
-
-v0.2.0 replaces the four separate framework packages with a single web component.
-
-| Before (v0.1.x)                                     | After (v0.2.0+)                    |
-| --------------------------------------------------- | ---------------------------------- |
-| `import { Calendar } from 'kalendly/react'`         | `import 'kalendly'`                |
-| `import { Calendar } from 'kalendly/vue'`           | `import 'kalendly'`                |
-| `import { Calendar } from 'kalendly/react-native'`  | Not supported                      |
-| `import { createCalendar } from 'kalendly/vanilla'` | `import 'kalendly'`                |
-| `<Calendar events={events} />`                      | `<kal-calendar events={events} />` |
-
-React Native is out of scope and not replaced.
-
 ## Styling
 
 ### Loading styles
@@ -301,46 +333,158 @@ 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 |
+| 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          |
 
 ## Properties
 
 Rich objects are set as JS properties (not attributes):
 
-| Property         | Type                               | Description                      |
-| ---------------- | ---------------------------------- | -------------------------------- |
-| `events`         | `CalendarEvent[]`                  | Events to display                |
-| `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                  |
+
+> `renderEvent` and `renderNoEvents` are ignored when `availability-mode` is set.
 
 ## Custom Events
 
-| Event              | `detail` shape                            | Description               |
-| ------------------ | ----------------------------------------- | ------------------------- |
-| `cal-date-select`  | `{ date: Date, events: CalendarEvent[] }` | User clicked a date       |
-| `cal-month-change` | `{ year: number, month: number }`         | Month navigation occurred |
+| 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 |
+
+All events bubble and are composed (cross Shadow DOM boundaries).
+
+`cal-availability-select` detail shape depends on mode:
+
+- **Day mode** (`availability-mode="day"`): `{ startDate: Date, endDate: Date }` — first click gives `startDate === endDate`; second click extends the range; third click resets
+- **Time mode** (`availability-mode="time"`): `{ date: Date, startTime: string, endTime: string }` — first click selects a single slot; second click extends; third click resets
+
+## Availability Mode
+
+Hides all event details from the end user — only booked/free state is shown. Designed for scheduling and booking flows where the server's event data must not be exposed to the viewer.
+
+### Day view
+
+```html
+<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.
+
+<div align="center">
+  <img src="./docs/images/day.png" alt="Availability day view — month grid with red booked cells and green free cells"/>
+  <p><em>Day view: the month grid shows only booked/free state per day — event names, times, and attendees are never revealed</em></p>
+</div>
+
+Pass the minimal event shape — only `id` and `date` are required; `startTime`/`endTime` are optional and mark the whole day as booked regardless:
 
-Both events bubble and are composed (cross Shadow DOM boundaries).
+```js
+cal.events = [
+  { id: 1, date: new Date(2025, 4, 8) },
+  { id: 2, date: new Date(2025, 4, 8), startTime: '14:00', endTime: '16:00' },
+  { id: 3, date: new Date(2025, 4, 20), startTime: '10:00', endTime: '12:00' },
+];
+```
+
+### Time view
+
+```html
+<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.
+
+<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>
+
+### Selectable range
+
+Add `selectable="range"` to let the user pick a free day or time slot:
+
+```html
+<kal-calendar availability-mode="day" selectable="range"></kal-calendar>
+<kal-calendar availability-mode="time" selectable="range"></kal-calendar>
+```
+
+```js
+// Day mode — fires on every click
+cal.addEventListener('cal-availability-select', e => {
+  const { startDate, endDate } = e.detail;
+  console.log('Selected:', startDate, '→', endDate);
+});
+
+// Time mode — fires on every slot click
+cal.addEventListener('cal-availability-select', e => {
+  const { date, startTime, endTime } = e.detail;
+  console.log('Slot:', date, startTime, '–', endTime);
+});
+```
+
+Booked days/slots cannot be selected. The 3-click state machine: first click selects, second extends, third resets.
+
+## Lazy Event Fetching
+
+`cal-month-change` fires **before** the new month renders, so you can set `loading = true` synchronously — the calendar shows skeleton shimmer cells from the first frame with no empty-calendar flash.
+
+```js
+cal.addEventListener('cal-month-change', async ({ detail }) => {
+  const { year, month } = detail;
+  cal.loading = true;
+  cal.events = await fetchEvents(year, month); // your API call
+  cal.loading = false;
+});
+```
+
+The "dump all events upfront" pattern still works unchanged — `cal-month-change` is optional:
+
+```js
+// Load once, component handles all months
+cal.events = allEvents;
+```
+
+## Core API
+
+`querySelector('kal-calendar')` returns `CalendarElement | null` automatically — no cast needed:
+
+```ts
+import type { CalendarElement } from 'kalendly';
+
+const cal = document.querySelector('kal-calendar'); // CalendarElement | null
+cal?.goToDate(new Date());
+cal?.updateEvents(events);
+cal?.updateTheme(theme);
+cal?.getCurrentDate(); // Date | null
+cal?.getEngine(); // CalendarEngine
+```
 
-## JavaScript API
+**JavaScript** works the same way without the import:
 
 ```js
 const cal = document.querySelector('kal-calendar');
 
-cal.updateEvents(newEvents); // Re-render with new events
-cal.updateTheme(newTheme); // Apply new theme
-cal.goToDate(new Date(2025, 5, 1)); // Navigate to date
-cal.getCurrentDate(); // Returns currently selected Date
-cal.getEngine(); // Access CalendarEngine directly
+cal.updateEvents(newEvents);
+cal.updateTheme(newTheme);
+cal.goToDate(new Date());
+cal.getCurrentDate();
+cal.getEngine();
 ```
 
 ## CalendarEvent Interface
@@ -470,14 +614,6 @@ Custom Elements v1 — Chrome 67+, Firefox 63+, Safari 12.1+, Edge 79+.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-```bash
-git clone https://github.com/callezenwaka/kalendly.git
-cd kalendly
-npm install
-npm test
-npm run dev:examples
-```
-
 ## License
 
 MIT © Callis Ezenwaka
@@ -488,7 +624,8 @@ See [CHANGELOG.md](CHANGELOG.md).
 
 ### Recent Updates
 
-- **v0.2.0**: Migrated to a single `<kal-calendar>` web component — works natively in React, Vue, Angular, and plain HTML with no framework dependency
+- **v0.2.1**: Add availability mode (day/time views), selectable range, lazy event fetching with skeleton loading
+- **v0.2.0**: Migrated to a single `<kal-calendar>` web component — works natively in React, Vue, Angular, Svelte, Solid.js, and plain HTML with no framework dependency
 - **v0.1.7**: Vanilla calendar performance optimization with event delegation
 - **v0.1.6**: Navigation enhancements — Today button, month/year picker, optional `title` prop
 - **v0.1.5**: Universal theming system, TypeScript improvements

package/dist/core/index.d.mts

@@ -98,6 +98,8 @@ interface CalendarTheme {
     borderColor?: string;
     todayOutline?: string;
     selectedBg?: string;
+    headerBg?: string;
+    popupBg?: string;
     eventIndicator?: string;
 }
 

package/dist/core/index.d.ts

@@ -98,6 +98,8 @@ interface CalendarTheme {
     borderColor?: string;
     todayOutline?: string;
     selectedBg?: string;
+    headerBg?: string;
+    popupBg?: string;
     eventIndicator?: string;
 }
 

package/dist/index.d.mts

@@ -98,6 +98,8 @@ interface CalendarTheme {
     borderColor?: string;
     todayOutline?: string;
     selectedBg?: string;
+    headerBg?: string;
+    popupBg?: string;
     eventIndicator?: string;
 }
 
@@ -239,15 +241,23 @@ declare class CalendarElement extends HTMLElement {
     private _categoryColors;
     private _renderEvent;
     private _renderNoEvents;
+    private _rangeStart;
+    private _rangeEnd;
+    private _timeRangeDate;
+    private _timeRangeStart;
+    private _timeRangeEnd;
+    private _timeRangeComplete;
     get events(): CalendarEvent[];
     set events(val: CalendarEvent[]);
     set theme(val: CalendarTheme);
     set categoryColors(val: CategoryColorMap);
     set renderEvent(val: (e: CalendarEvent) => string);
     set renderNoEvents(val: () => string);
+    get loading(): boolean;
+    set loading(val: boolean);
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldVal: string | null, newVal: string | null): void;
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
     private get minYear();
     private get maxYear();
     private initEngine;
@@ -265,6 +275,11 @@ declare class CalendarElement extends HTMLElement {
     getEngine(): CalendarEngine;
 }
 declare function defineCalendarElement(tagName?: string): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'kal-calendar': CalendarElement;
+    }
+}
 
 interface CalendarElementProps {
     events?: CalendarEvent[];

package/dist/index.d.ts

@@ -98,6 +98,8 @@ interface CalendarTheme {
     borderColor?: string;
     todayOutline?: string;
     selectedBg?: string;
+    headerBg?: string;
+    popupBg?: string;
     eventIndicator?: string;
 }
 
@@ -239,15 +241,23 @@ declare class CalendarElement extends HTMLElement {
     private _categoryColors;
     private _renderEvent;
     private _renderNoEvents;
+    private _rangeStart;
+    private _rangeEnd;
+    private _timeRangeDate;
+    private _timeRangeStart;
+    private _timeRangeEnd;
+    private _timeRangeComplete;
     get events(): CalendarEvent[];
     set events(val: CalendarEvent[]);
     set theme(val: CalendarTheme);
     set categoryColors(val: CategoryColorMap);
     set renderEvent(val: (e: CalendarEvent) => string);
     set renderNoEvents(val: () => string);
+    get loading(): boolean;
+    set loading(val: boolean);
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldVal: string | null, newVal: string | null): void;
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
     private get minYear();
     private get maxYear();
     private initEngine;
@@ -265,6 +275,11 @@ declare class CalendarElement extends HTMLElement {
     getEngine(): CalendarEngine;
 }
 declare function defineCalendarElement(tagName?: string): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'kal-calendar': CalendarElement;
+    }
+}
 
 interface CalendarElementProps {
     events?: CalendarEvent[];