kalendly 0.1.7 → 0.2.1

package/README.md

@@ -1,25 +1,26 @@
-# kalendly Universal Calendar
+# kalendly
 
-A universal calendar component that works seamlessly across React, Vue, and React Native with full TypeScript support.
+A universal calendar web component — works in React, Vue, Svelte, Angular, Solid.js, and plain HTML with no framework dependency.
 
 ## Features
 
-- 🚀 **Universal**: Works with React, Vue, React Native, and Vanilla JavaScript
-- 📱 **Responsive**: Mobile-friendly design that matches your existing UI implementation
-- 🎨 **Customizable**: Easy to theme and customize with CSS variables
-- 🔒 **Type Safe**: Full TypeScript support
-- 📅 **Event Management**: Add, display, and manage events with rich metadata
-- 🔔 **Advanced Features**: Recurring events, reminders, categories, priorities, and collaboration
-- 🌐 **Accessible**: Built with accessibility in mind
-- 📦 **Tree Shakeable**: Import only what you need
+- **Framework-agnostic**: Single `<kal-calendar>` custom element, no framework required
+- **Responsive**: Mobile-friendly, matches your existing UI
+- **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
 
-## 🎯 Live Demo
+## Live Demo
 
 <div align="center">
 
 [![Kalendly Calendar Demo](./docs/images/calendar-demo.gif)](https://kalendly-example.netlify.app/)
 
-**[🚀 Try the Interactive Demo →](https://kalendly-example.netlify.app/)**
+**[Try the Interactive Demo →](https://kalendly-example.netlify.app/)**
 
 </div>
 
@@ -33,811 +34,527 @@ A universal calendar component that works seamlessly across React, Vue, and Reac
   <a href="https://kalendly-example.netlify.app/vue">
     <img src="https://img.shields.io/badge/Vue-4FC08D?style=for-the-badge&logo=vue.js&logoColor=white" alt="Vue Demo"/>
   </a>
+  <a href="https://kalendly-example.netlify.app/angular">
+    <img src="https://img.shields.io/badge/Angular-DD0031?style=for-the-badge&logo=angular&logoColor=white" alt="Angular Demo"/>
+  </a>
+  <a href="https://kalendly-example.netlify.app/svelte">
+    <img src="https://img.shields.io/badge/Svelte-FF3E00?style=for-the-badge&logo=svelte&logoColor=white" alt="Svelte Demo"/>
+  </a>
+  <a href="https://kalendly-example.netlify.app/solid">
+    <img src="https://img.shields.io/badge/Solid.js-2C4F7C?style=for-the-badge&logo=solid&logoColor=white" alt="Solid.js Demo"/>
+  </a>
 </p>
 
 ## Installation
 
 ```bash
 npm install kalendly
-# or
-yarn add kalendly
-# or
-pnpm add kalendly
 ```
 
 ## Usage
 
-### React
-
-```jsx
-import React from 'react';
-import { Calendar } from 'kalendly/react';
-import 'kalendly/styles';
-
-const events = [
-  {
-    id: 1,
-    name: 'Team Meeting',
-    date: '2025-01-15',
-  },
-  {
-    id: 2,
-    name: 'Project Deadline',
-    date: '2025-01-20',
-  },
-];
-
-function App() {
-  const handleDateSelect = date => {
-    console.log('Selected date:', date);
-  };
-
-  return (
-    <div>
-      <Calendar
-        events={events}
-        onDateSelect={handleDateSelect}
-        title="My Calendar"
-      />
-    </div>
-  );
-}
+### Vanilla HTML / CDN
 
-export default App;
+```html
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/kalendly/dist/styles/calendar.css"
+/>
+<script src="https://unpkg.com/kalendly/dist/index.umd.js"></script>
+
+<kal-calendar id="cal" title="My Calendar"></kal-calendar>
+
+<script>
+  const cal = document.getElementById('cal');
+
+  // Set events (JS property — not an attribute)
+  cal.events = [
+    { id: 1, name: 'Team Meeting', date: new Date(2025, 0, 15) },
+    { id: 2, name: 'Project Deadline', date: new Date(2025, 0, 20) },
+  ];
+
+  // Listen to custom events
+  cal.addEventListener('cal-date-select', e => {
+    console.log('Selected:', e.detail.date, e.detail.events);
+  });
+
+  cal.addEventListener('cal-month-change', e => {
+    console.log('Month:', e.detail.year, e.detail.month);
+  });
+</script>
 ```
 
-### Vue
-
-```vue
-<template>
-  <div>
-    <Calendar
-      :events="events"
-      @date-select="handleDateSelect"
-      title="My Calendar"
-    >
-      <template #event="{ event }">
-        <div class="custom-event">{{ event.name }}</div>
-      </template>
-    </Calendar>
-  </div>
-</template>
+### ES Modules
 
-<script setup>
-import { Calendar } from 'kalendly/vue';
+```js
+import 'kalendly';
 import 'kalendly/styles';
 
-const events = [
-  {
-    id: 1,
-    name: 'Team Meeting',
-    date: '2025-01-15',
-  },
-  {
-    id: 2,
-    name: 'Project Deadline',
-    date: '2025-01-20',
-  },
-];
-
-const handleDateSelect = date => {
-  console.log('Selected date:', date);
-};
-</script>
+// <kal-calendar> is now registered and ready
 ```
 
-### React Native
+### React 19
+
+React 19 has full custom element support — pass objects/arrays as props and listen to custom events directly.
 
 ```jsx
-import React from 'react';
-import { View } from 'react-native';
-import { Calendar } from 'kalendly/react-native';
-
-const events = [
-  {
-    id: 1,
-    name: 'Team Meeting',
-    date: '2025-01-15',
-  },
-  {
-    id: 2,
-    name: 'Project Deadline',
-    date: '2025-01-20',
-  },
-];
+import 'kalendly';
+import 'kalendly/styles';
 
 function App() {
-  const handleDateSelect = date => {
-    console.log('Selected date:', date);
-  };
-
   return (
-    <View style={{ flex: 1 }}>
-      <Calendar
-        events={events}
-        onDateSelect={handleDateSelect}
-        title="My Calendar"
-      />
-    </View>
+    <kal-calendar
+      title="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)}
+    />
   );
 }
-
-export default App;
 ```
 
-### Vanilla JavaScript
-
-#### Modern ES Modules (Recommended)
+> **React 18 users:** React 18 does not forward object/array props or custom events to custom elements. You need to wire these up via a `ref`:
+>
+> ```jsx
+> import { useRef, useEffect } from 'react';
+> import 'kalendly';
+>
+> function Calendar({ events, onDateSelect, onMonthChange, ...attrs }) {
+>   const ref = useRef(null);
+>
+>   useEffect(() => {
+>     if (ref.current) ref.current.events = events;
+>   }, [events]);
+>
+>   useEffect(() => {
+>     const el = ref.current;
+>     if (!el) return;
+>     const onSelect = e => onDateSelect?.(e.detail.date, e.detail.events);
+>     const onChange = e => onMonthChange?.(e.detail.year, e.detail.month);
+>     el.addEventListener('cal-date-select', onSelect);
+>     el.addEventListener('cal-month-change', onChange);
+>     return () => {
+>       el.removeEventListener('cal-date-select', onSelect);
+>       el.removeEventListener('cal-month-change', onChange);
+>     };
+>   }, [onDateSelect, onMonthChange]);
+>
+>   return <kal-calendar ref={ref} {...attrs} />;
+> }
+> ```
+
+### Vue 3
+
+Vue 3 supports custom elements natively — bind props with `:` and listen to events with `@`:
 
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <link
-      rel="stylesheet"
-      href="node_modules/kalendly/dist/styles/calendar.css"
-    />
-    <title>Vanilla JS Calendar</title>
-  </head>
-  <body>
-    <div id="calendar"></div>
-
-    <script type="module">
-      import { createCalendar } from 'kalendly/vanilla';
-
-      const events = [
-        { id: 1, name: 'Team Meeting', date: '2025-01-15' },
-        { id: 2, name: 'Project Deadline', date: '2025-01-20' },
-      ];
-
-      const calendar = createCalendar({
-        container: '#calendar',
-        events: events,
-        title: 'My Calendar',
-      });
-
-      // Listen to events (note: use addEventListener, not onclick)
-      document.getElementById('calendar').addEventListener('dateSelect', e => {
-        console.log('Selected date:', e.detail.date);
-      });
-
-      document.getElementById('calendar').addEventListener('monthChange', e => {
-        console.log('Month changed:', e.detail.year, e.detail.month);
-      });
-
-      // Update events dynamically
-      // calendar.updateEvents(newEvents);
-
-      // Navigate to specific date
-      // calendar.goToDate(new Date(2025, 5, 15));
-
-      // Cleanup when done
-      // calendar.destroy();
-    </script>
-  </body>
-</html>
-```
+```vue
+<template>
+  <kal-calendar
+    title="My Calendar"
+    :events="events"
+    @cal-date-select="onDateSelect"
+    @cal-month-change="onMonthChange"
+  />
+</template>
 
-#### CDN Usage (Browser)
+<script setup>
+import 'kalendly';
+import 'kalendly/styles';
 
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <link
-      rel="stylesheet"
-      href="https://unpkg.com/kalendly/dist/styles/calendar.css"
-    />
-  </head>
-  <body>
-    <div id="calendar"></div>
-
-    <script type="module">
-      import { createCalendar } from 'https://unpkg.com/kalendly/dist/vanilla/index.mjs';
-
-      const calendar = createCalendar({
-        container: '#calendar',
-        events: [{ id: 1, name: 'Meeting', date: '2025-01-15' }],
-        title: 'My Calendar',
-      });
-    </script>
-  </body>
-</html>
-```
+const events = [{ id: 1, name: 'Team Meeting', date: new Date(2025, 0, 15) }];
 
-#### Legacy/Global Usage (Without Modules)
+function onDateSelect(e) {
+  console.log('Selected:', e.detail.date);
+}
 
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <link
-      rel="stylesheet"
-      href="https://unpkg.com/kalendly/dist/styles/calendar.css"
-    />
-  </head>
-  <body>
-    <div id="calendar"></div>
-
-    <script src="https://unpkg.com/kalendly/dist/vanilla/index.umd.js"></script>
-    <script>
-      const { createCalendar } = Kalendly;
-
-      const calendar = createCalendar({
-        container: '#calendar',
-        events: [{ id: 1, name: 'Meeting', date: '2025-01-15' }],
-        title: 'My Calendar',
-      });
-
-      // Now you can use global functions with onclick
-      function handleDateSelect() {
-        console.log('Date selected!');
-      }
-
-      document
-        .getElementById('calendar')
-        .addEventListener('dateSelect', handleDateSelect);
-    </script>
-  </body>
-</html>
+function onMonthChange(e) {
+  console.log('Month:', e.detail.year, e.detail.month);
+}
+</script>
 ```
 
-## API Reference
-
-### Props
-
-| Prop                 | Type                                    | Default            | Description                             |
-| -------------------- | --------------------------------------- | ------------------ | --------------------------------------- |
-| `events`             | `CalendarEvent[]`                       | `[]`               | Array of events to display              |
-| `initialDate`        | `Date`                                  | `new Date()`       | Initial date to display                 |
-| `minYear`            | `number`                                | `currentYear - 30` | Minimum selectable year                 |
-| `maxYear`            | `number`                                | `currentYear + 10` | Maximum selectable year                 |
-| `weekStartsOn`       | `0 \| 1`                                | `0`                | Week start day (0 = Sunday, 1 = Monday) |
-| `useShortMonthNames` | `boolean`                               | `false`            | Use abbreviated month names (Jan, Feb)  |
-| `categoryColors`     | `CategoryColorMap`                      | `{}`               | Custom colors for event categories      |
-| `theme`              | `CalendarTheme`                         | `undefined`        | Custom theme colors for the calendar    |
-| `title`              | `string`                                | `undefined`        | Optional calendar title displayed above |
-| `onDateSelect`       | `(date: Date) => void`                  | -                  | Callback when date is selected          |
-| `onEventClick`       | `(event: CalendarEvent) => void`        | -                  | Callback when event is clicked          |
-| `onMonthChange`      | `(year: number, month: number) => void` | -                  | Callback when month changes             |
+### Angular
 
-### CalendarEvent Interface
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
 
-```typescript
-interface CalendarEvent {
-  // Required fields
-  id: string | number;
-  name: string;
-  date: string | Date;
-
-  // Time fields
-  startTime?: string; // e.g., "09:00", "14:30"
-  endTime?: string; // e.g., "10:00", "16:00"
-  allDay?: boolean; // True for all-day events
-
-  // Display & categorization
-  description?: string;
-  color?: string; // Custom event color
-  category?:
-    | 'work'
-    | 'personal'
-    | 'meeting'
-    | 'deadline'
-    | 'appointment'
-    | 'other';
-  location?: string; // Event location
-  url?: string; // Related URL or meeting link
-
-  // Status & priority
-  status?: 'scheduled' | 'completed' | 'cancelled' | 'tentative';
-  priority?: 'low' | 'medium' | 'high';
-
-  // Collaboration
-  attendees?: string[]; // List of attendee names/emails
-  organizer?: string; // Event organizer
-
-  // Reminders & recurrence
-  reminders?: number[]; // Minutes before event to remind (e.g., [15, 60])
-  recurring?: {
-    frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
-    interval?: number; // Every X days/weeks/months/years
-    endDate?: string | Date; // When recurrence ends
-    daysOfWeek?: number[]; // For weekly recurrence (0 = Sunday)
-  };
-
-  // Metadata
-  notes?: string; // Additional notes
-  tags?: string[]; // Event tags
-  createdAt?: string | Date; // Creation timestamp
-  updatedAt?: string | Date; // Last update timestamp
-
-  // Flexibility for custom fields
-  [key: string]: unknown;
-}
+// app.component.ts
+import 'kalendly';
+import 'kalendly/styles';
 ```
 
-#### Example with Enhanced Fields
-
-```typescript
-const events = [
-  {
-    id: 1,
-    name: 'Team Standup',
-    date: '2025-01-15',
-    startTime: '09:00',
-    endTime: '09:30',
-    category: 'meeting',
-    location: 'Conference Room A',
-    url: 'https://meet.google.com/abc-defg-hij',
-    attendees: ['john@example.com', 'jane@example.com'],
-    organizer: 'team-lead@example.com',
-    priority: 'high',
-    status: 'scheduled',
-    reminders: [15, 60],
-    recurring: {
-      frequency: 'daily',
-      interval: 1,
-      daysOfWeek: [1, 2, 3, 4, 5], // Mon-Fri
-      endDate: '2025-12-31',
-    },
-    tags: ['team', 'sync'],
-  },
-  {
-    id: 2,
-    name: 'Project Deadline',
-    date: '2025-01-20',
-    allDay: true,
-    category: 'deadline',
-    priority: 'high',
-    status: 'scheduled',
-    description: 'Final submission for Q1 project',
-    notes: 'Make sure all tests pass before submission',
-  },
-];
+```html
+<!-- app.component.html -->
+<kal-calendar
+  title="My Calendar"
+  [events]="events"
+  (cal-date-select)="onDateSelect($event)"
+  (cal-month-change)="onMonthChange($event)"
+></kal-calendar>
 ```
 
-#### Category Colors
+### Svelte 5
 
-You can customize colors for different event categories:
-
-```typescript
-const categoryColors = {
-  work: '#4CAF50',
-  personal: '#2196F3',
-  meeting: '#FF9800',
-  deadline: '#F44336',
-  appointment: '#9C27B0',
-  other: '#607D8B'
-};
+```svelte
+<script>
+  import 'kalendly';
+  import 'kalendly/styles';
+  let { events = [] } = $props();
+</script>
 
-<Calendar events={events} categoryColors={categoryColors} />
+<kal-calendar {events} oncal-date-select={e => console.log(e.detail.date)} />
 ```
 
-## Theming
-
-Kalendly supports custom theming across all frameworks with a **consistent API**. Customize calendar colors to match your brand or create light/dark themes.
-
-### CalendarTheme Interface
+### Svelte 4
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import 'kalendly';
+  import 'kalendly/styles';
+  export let events = [];
+  let calEl;
+  onMount(() => { calEl.events = events; });
+  $: if (calEl) calEl.events = events;
+</script>
 
-```typescript
-interface CalendarTheme {
-  primary?: string; // Primary brand color
-  secondary?: string; // Secondary brand color
-  tertiary?: string; // Tertiary/accent color
-  textColor?: string; // Main text color
-  textLight?: string; // Light/secondary text color
-  background?: string; // Background color
-  cellHover?: string; // Cell hover state color
-  borderColor?: string; // Border color
-  todayOutline?: string; // Today indicator color
-  selectedBg?: string; // Selected date background
-  eventIndicator?: string; // Event indicator dot color
-}
+<kal-calendar bind:this={calEl} on:cal-date-select on:cal-month-change />
 ```
 
-### Basic Theme Example
-
-**React:**
+### Solid.js
 
-```tsx
-import { Calendar } from 'kalendly/react';
+```jsx
+import 'kalendly';
 import 'kalendly/styles';
 
 function App() {
   return (
-    <Calendar
-      events={events}
-      theme={{
-        primary: '#3b82f6',
-        secondary: '#60a5fa',
-        tertiary: '#93c5fd',
-        borderColor: '#e5e7eb',
-        todayOutline: '#fbbf24',
-        eventIndicator: '#10b981',
-      }}
+    <kal-calendar
+      title="My Calendar"
+      prop:events={events}
+      on:cal-date-select={e => console.log(e.detail.date)}
     />
   );
 }
 ```
 
-**Vue:**
+## Styling
 
-```vue
-<template>
-  <Calendar :events="events" :theme="calendarTheme" />
-</template>
+### Loading styles
 
-<script setup lang="ts">
-import { Calendar } from 'kalendly/vue';
+```js
+// Bundler (Vite, webpack) — add once in your app entry (e.g. main.tsx)
 import 'kalendly/styles';
 
-const calendarTheme = {
-  primary: '#3b82f6',
-  secondary: '#60a5fa',
-  tertiary: '#93c5fd',
-  borderColor: '#e5e7eb',
-  todayOutline: '#fbbf24',
-  eventIndicator: '#10b981',
-};
-</script>
-```
-
-**Vanilla JavaScript:**
-
-```javascript
-import { createCalendar } from 'kalendly/vanilla';
-import 'kalendly/styles';
+// Plain HTML
+// <link rel="stylesheet" href="/node_modules/kalendly/dist/styles/calendar.css">
 
-const calendar = createCalendar({
-  container: '#calendar',
-  events: events,
-  theme: {
-    primary: '#3b82f6',
-    secondary: '#60a5fa',
-    tertiary: '#93c5fd',
-    borderColor: '#e5e7eb',
-    todayOutline: '#fbbf24',
-    eventIndicator: '#10b981',
-  },
-});
+// Angular — add to angular.json → projects → architect → build → styles
+// "node_modules/kalendly/dist/styles/calendar.css"
 ```
 
-**React Native:**
+### Overriding styles
 
-```tsx
-import { Calendar } from 'kalendly/react-native';
+kalendly uses Light DOM — all standard CSS techniques work:
 
-function App() {
-  return (
-    <Calendar
-      events={events}
-      theme={{
-        primary: '#3b82f6',
-        secondary: '#60a5fa',
-        tertiary: '#93c5fd',
-        borderColor: '#e5e7eb',
-        todayOutline: '#fbbf24',
-        eventIndicator: '#10b981',
-      }}
-    />
-  );
+```css
+/* 1. CSS custom properties (recommended) */
+:root {
+  --calendar-primary-color: #6366f1;
+  --calendar-background: #1e1e2e;
+  --calendar-border-color: #334155;
 }
-```
 
-### Dark Theme Example
+/* 2. Direct class overrides */
+.kalendly-calendar .calendar--card {
+  border-radius: 12px;
+}
+```
 
-```typescript
-const darkTheme = {
+```js
+// 3. JS theme property
+document.querySelector('kal-calendar').theme = {
   primary: '#6366f1',
-  secondary: '#818cf8',
-  tertiary: '#a5b4fc',
-  textColor: '#f9fafb',
-  textLight: '#d1d5db',
-  background: '#1f2937',
-  cellHover: '#374151',
-  borderColor: '#4b5563',
-  todayOutline: '#fbbf24',
-  selectedBg: '#312e81',
-  eventIndicator: '#34d399'
+  background: '#1e1e2e',
 };
-
-<Calendar events={events} theme={darkTheme} />
 ```
 
-### Dynamic Theme Switching
+## Attributes
 
-**React:**
+Primitives are set as HTML attributes:
 
-```tsx
-import { useState } from 'react';
-import { Calendar } from 'kalendly/react';
+| 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          |
 
-const themes = {
-  blue: { primary: '#3b82f6', secondary: '#60a5fa' },
-  purple: { primary: '#8b5cf6', secondary: '#a78bfa' },
-  green: { primary: '#10b981', secondary: '#34d399' },
-};
-
-function App() {
-  const [currentTheme, setCurrentTheme] = useState('blue');
+## Properties
 
-  return (
-    <>
-      <button onClick={() => setCurrentTheme('blue')}>Blue</button>
-      <button onClick={() => setCurrentTheme('purple')}>Purple</button>
-      <button onClick={() => setCurrentTheme('green')}>Green</button>
-
-      <Calendar events={events} theme={themes[currentTheme]} />
-    </>
-  );
-}
-```
+Rich objects are set as JS properties (not attributes):
 
-**Vue:**
+| 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                  |
 
-```vue
-<template>
-  <div>
-    <button @click="currentTheme = 'blue'">Blue</button>
-    <button @click="currentTheme = 'purple'">Purple</button>
-    <button @click="currentTheme = 'green'">Green</button>
+> `renderEvent` and `renderNoEvents` are ignored when `availability-mode` is set.
 
-    <Calendar :events="events" :theme="themes[currentTheme]" />
-  </div>
-</template>
+## Custom Events
 
-<script setup lang="ts">
-import { ref } from 'vue';
-import { Calendar } from 'kalendly/vue';
+| 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 |
 
-const themes = {
-  blue: { primary: '#3b82f6', secondary: '#60a5fa' },
-  purple: { primary: '#8b5cf6', secondary: '#a78bfa' },
-  green: { primary: '#10b981', secondary: '#34d399' },
-};
+All events bubble and are composed (cross Shadow DOM boundaries).
 
-const currentTheme = ref('blue');
-</script>
-```
+`cal-availability-select` detail shape depends on mode:
 
-**Vanilla JavaScript:**
+- **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
 
-```javascript
-import { createCalendar } from 'kalendly/vanilla';
+## Availability Mode
 
-const themes = {
-  blue: { primary: '#3b82f6', secondary: '#60a5fa' },
-  purple: { primary: '#8b5cf6', secondary: '#a78bfa' },
-  green: { primary: '#10b981', secondary: '#34d399' },
-};
+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.
 
-const calendar = createCalendar({
-  container: '#calendar',
-  events: events,
-  theme: themes.blue,
-});
+### Day view
 
-// Update theme dynamically without recreation
-document.getElementById('purple-btn').addEventListener('click', () => {
-  calendar.updateTheme(themes.purple);
-});
+```html
+<kal-calendar availability-mode="day"></kal-calendar>
 ```
 
-> **Note:** The `updateTheme()` method is available in Vanilla JavaScript for efficient theme updates without recreating the calendar instance.
-
-## Framework-Specific Features
+Days with events get a red tint (booked); days without get a green tint (free). Clicking a day opens no popup.
 
-### React Props
+Pass the minimal event shape — no names, no descriptions:
 
-| Prop             | Type                                  | Description              |
-| ---------------- | ------------------------------------- | ------------------------ |
-| `className`      | `string`                              | CSS class name           |
-| `style`          | `React.CSSProperties`                 | Inline styles            |
-| `renderEvent`    | `(event: CalendarEvent) => ReactNode` | Custom event renderer    |
-| `renderNoEvents` | `() => ReactNode`                     | Custom no events message |
-
-### Vue Props & Slots
+```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' },
+];
+```
 
-| Slot        | Props                      | Description              |
-| ----------- | -------------------------- | ------------------------ |
-| `title`     | -                          | Custom title content     |
-| `event`     | `{ event: CalendarEvent }` | Custom event display     |
-| `no-events` | -                          | Custom no events message |
+### Time view
 
-### React Native Props
+```html
+<kal-calendar availability-mode="time"></kal-calendar>
+```
 
-| Prop              | Type        | Description                |
-| ----------------- | ----------- | -------------------------- |
-| `style`           | `ViewStyle` | Container style            |
-| `headerStyle`     | `ViewStyle` | Header style               |
-| `cellStyle`       | `ViewStyle` | Calendar cell style        |
-| `showCloseButton` | `boolean`   | Show close button in popup |
+Clicking a day opens a time-grid popup showing which hours are booked (red) and free (green). No event name or organiser is ever rendered.
 
-### Vanilla JavaScript Options
+### Selectable range
 
-| Option           | Type                               | Description                   |
-| ---------------- | ---------------------------------- | ----------------------------- |
-| `container`      | `HTMLElement \| string`            | Container element or selector |
-| `className`      | `string`                           | Additional CSS class          |
-| `renderEvent`    | `(event: CalendarEvent) => string` | Custom event HTML renderer    |
-| `renderNoEvents` | `() => string`                     | Custom no events HTML         |
+Add `selectable="range"` to let the user pick a free day or time slot:
 
-### Vanilla JavaScript Events
+```html
+<kal-calendar availability-mode="day" selectable="range"></kal-calendar>
+<kal-calendar availability-mode="time" selectable="range"></kal-calendar>
+```
 
-```javascript
-// Listen to calendar events
-calendar.container.addEventListener('dateSelect', e => {
-  console.log('Date selected:', e.detail.date);
+```js
+// Day mode — fires on every click
+cal.addEventListener('cal-availability-select', e => {
+  const { startDate, endDate } = e.detail;
+  console.log('Selected:', startDate, '→', endDate);
 });
 
-calendar.container.addEventListener('monthChange', e => {
-  console.log('Month changed:', e.detail.year, e.detail.month);
+// 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);
 });
 ```
 
-### Vanilla JavaScript API
+Booked days/slots cannot be selected. The 3-click state machine: first click selects, second extends, third resets.
 
-```javascript
-const calendar = createCalendar(options);
+## Lazy Event Fetching
 
-// Methods
-calendar.updateEvents(newEvents); // Update events
-calendar.getCurrentDate(); // Get selected date
-calendar.goToDate(new Date()); // Navigate to date
-calendar.getEngine(); // Access core engine
-calendar.destroy(); // Cleanup
+`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;
+});
 ```
 
-## Common Issues & Solutions
+The "dump all events upfront" pattern still works unchanged — `cal-month-change` is optional:
+
+```js
+// Load once, component handles all months
+cal.events = allEvents;
+```
 
-### Vanilla JavaScript
+## Core API
 
-**Issue: "Function is not defined" errors with onclick handlers**
+`querySelector('kal-calendar')` returns `CalendarElement | null` automatically — no cast needed:
 
-❌ **Wrong:**
+```ts
+import type { CalendarElement } from 'kalendly';
 
-```html
-<button onclick="myFunction()">Click me</button>
-<script type="module">
-  function myFunction() {} // Not accessible globally in modules
-</script>
+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
 ```
 
-✅ **Correct:**
+**JavaScript** works the same way without the import:
 
-```html
-<button id="myButton">Click me</button>
-<script type="module">
-  function myFunction() {}
-  document.getElementById('myButton').addEventListener('click', myFunction);
-</script>
+```js
+const cal = document.querySelector('kal-calendar');
+
+cal.updateEvents(newEvents);
+cal.updateTheme(newTheme);
+cal.goToDate(new Date());
+cal.getCurrentDate();
+cal.getEngine();
 ```
 
-**Issue: Module imports not working**
+## CalendarEvent Interface
 
-Use the correct import paths:
+```typescript
+interface CalendarEvent {
+  id: string | number;
+  name: string;
+  date: string | Date;
 
-- Local: `'./dist/vanilla/index.mjs'`
-- NPM: `'kalendly/vanilla'`
-- CDN: `'https://unpkg.com/kalendly/dist/vanilla/index.mjs'`
+  startTime?: string; // e.g. "09:00"
+  endTime?: string; // e.g. "10:00"
+  allDay?: boolean;
 
-**Issue: Styles not loading**
+  description?: string;
+  color?: string;
+  category?:
+    | 'work'
+    | 'personal'
+    | 'meeting'
+    | 'deadline'
+    | 'appointment'
+    | 'other';
+  location?: string;
+  url?: string;
 
-Always include the CSS file:
+  status?: 'scheduled' | 'completed' | 'cancelled' | 'tentative';
+  priority?: 'low' | 'medium' | 'high';
 
-```html
-<link rel="stylesheet" href="path/to/kalendly/dist/styles/calendar.css" />
+  attendees?: string[];
+  organizer?: string;
+  reminders?: number[]; // minutes before event
+  recurring?: {
+    frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    interval?: number;
+    endDate?: string | Date;
+    daysOfWeek?: number[];
+  };
+
+  notes?: string;
+  tags?: string[];
+  [key: string]: unknown;
+}
 ```
 
-## Customization
+## Theming
 
-### CSS Variables (React/Vue)
+### All CSS variables
 
 ```css
 :root {
   --calendar-primary-color: #fc8917;
-  --calendar-primary-color-rgb: 252, 137, 23;
   --calendar-secondary-color: #fca045;
-  --calendar-secondary-color-rgb: 252, 160, 69;
   --calendar-tertiary-color: #fdb873;
   --calendar-text-color: #2c3e50;
+  --calendar-text-light: #6b7280;
   --calendar-border-color: #dee2e6;
   --calendar-today-outline: #f7db04;
   --calendar-event-indicator: #1890ff;
   --calendar-background: #fff;
+  --calendar-cell-hover: #f3f4f6;
+  --calendar-selected-bg: #eff6ff;
 }
 ```
 
-> **Note:** The `-rgb` variables are used for semi-transparent backgrounds (e.g., hover states) and provide compatibility with older browsers (Chrome < 111, Safari iOS < 16.2).
+### JS theme property (full reference)
 
-### React Native Theming
+```js
+cal.theme = {
+  primary: '#3b82f6',
+  secondary: '#60a5fa',
+  tertiary: '#93c5fd',
+  textColor: '#111827',
+  textLight: '#6b7280',
+  background: '#ffffff',
+  cellHover: '#f3f4f6',
+  borderColor: '#e5e7eb',
+  todayOutline: '#fbbf24',
+  selectedBg: '#eff6ff',
+  eventIndicator: '#10b981',
+};
+```
 
-```javascript
-import { calendarStyles } from 'kalendly/react-native';
+### Dark theme example
 
-// Customize styles
-const customStyles = {
-  ...calendarStyles,
-  container: {
-    ...calendarStyles.container,
-    backgroundColor: '#f5f5f5',
-  },
+```js
+cal.theme = {
+  primary: '#6366f1',
+  secondary: '#818cf8',
+  textColor: '#f9fafb',
+  textLight: '#d1d5db',
+  background: '#1f2937',
+  cellHover: '#374151',
+  borderColor: '#4b5563',
+  todayOutline: '#fbbf24',
+  selectedBg: '#312e81',
+  eventIndicator: '#34d399',
 };
 ```
 
-## Core API
-
-You can also use the core calendar engine directly:
+## Core Engine (advanced)
 
 ```typescript
 import { CalendarEngine } from 'kalendly/core';
 
-const engine = new CalendarEngine({
-  events: myEvents,
-  initialDate: new Date(),
-});
+const engine = new CalendarEngine({ events, initialDate: new Date() });
 
-// Subscribe to changes
 const unsubscribe = engine.subscribe(() => {
-  console.log('Calendar state changed');
+  const viewModel = engine.getViewModel();
+  // re-render
 });
 
-// Get current state
-const viewModel = engine.getViewModel();
-const actions = engine.getActions();
+engine.getActions().next();
+engine.getActions().previous();
+engine.getActions().jump(2025, 5);
+engine.getActions().goToToday();
 
-// Navigate months
-actions.next();
-actions.previous();
-actions.jump(2025, 5); // June 2025
-actions.goToToday(); // Navigate to current month
-
-// Check current view
-const isCurrentMonth = actions.isCurrentMonth(); // true if viewing today's month
-
-// Clean up
 unsubscribe();
 engine.destroy();
 ```
 
-## TypeScript Support
-
-The package is written in TypeScript and provides full type definitions:
-
-```typescript
-import type { CalendarEvent, CalendarProps, CalendarState } from 'kalendly';
-```
-
 ## Browser Support
 
-- **React/Vue**: Modern browsers (Chrome 90+, Firefox 88+, Safari 14+)
-- **React Native**: iOS 12+, Android API 21+
+Custom Elements v1 — Chrome 67+, Firefox 63+, Safari 12.1+, Edge 79+.
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on:
-
-- Development setup
-- Project structure
-- Building and testing
-- Running examples
-- Submitting pull requests
-- Release process
-
-Quick start:
-
-```bash
-# Clone and install
-git clone https://github.com/callezenwaka/kalendly.git
-cd kalendly
-npm install
-
-# Run tests
-npm test
-
-# Run examples locally
-npm run dev:examples
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
@@ -845,15 +562,13 @@ MIT © Callis Ezenwaka
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
+See [CHANGELOG.md](CHANGELOG.md).
 
 ### Recent Updates
 
-- **v0.1.7**: Vanilla calendar performance optimization with event delegation, targeted DOM updates for picker navigation
-- **v0.1.6**: Navigation enhancements with Today button, month/year picker dropdown, optional `title` prop, calendar grid improvements showing previous/next month days, and browser compatibility fixes
-- **v0.1.5**: Universal theming system, TypeScript support improvements, integration test enhancements
-- **v0.1.4**: Netlify configuration updates
-- **v0.1.3**: Vue types generation improvements
-- **v0.1.2**: Enhanced event parameters with structured metadata, categories, recurrence, collaboration features
-- **v0.1.1**: Pre-commit hooks and trusted publishing with OIDC
+- **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
 - **v0.1.0**: Initial release with React, Vue, React Native, and Vanilla JavaScript support