@nomideusz/svelte-calendar 0.5.2 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @nomideusz/svelte-calendar
 
-A themeable **Svelte 5** calendar with **Day/Week Planner & Agenda** views.
+A themeable **Svelte 5** calendar with **Day/Week Planner & Agenda** views, touch-first mobile views, and a smart auto-theme that adapts to any page.
 
 ## Installation
 
@@ -13,145 +13,353 @@ pnpm add @nomideusz/svelte-calendar
 ## Quick Start
 
 ```svelte
-<script lang="ts">
-  import {
-    Calendar, Planner, Agenda,
-    createMemoryAdapter, neutral,
-  } from '@nomideusz/svelte-calendar';
-  import type { CalendarView, TimelineEvent } from '@nomideusz/svelte-calendar';
-
-  const events: TimelineEvent[] = [
-    { id: '1', title: 'Yoga Flow', start: new Date('2025-03-01T09:00'), end: new Date('2025-03-01T10:00'), color: '#818cf8' },
-    { id: '2', title: 'Meditation', start: new Date('2025-03-01T12:00'), end: new Date('2025-03-01T12:45'), color: '#34d399' },
-  ];
+<script>
+  import { Calendar, createMemoryAdapter } from '@nomideusz/svelte-calendar';
+
+  const adapter = createMemoryAdapter([
+    { id: '1', title: 'Team Sync', start: new Date('2026-03-01T09:00'), end: new Date('2026-03-01T10:00') },
+    { id: '2', title: 'Lunch',     start: new Date('2026-03-01T12:00'), end: new Date('2026-03-01T13:00') },
+  ]);
+</script>
+
+<Calendar {adapter} />
+```
+
+That's it — 6 views (Day/Week × Planner, Agenda, Mobile), auto-coloring, drag-and-drop, all out of the box. The default `auto` theme probes your page's background, accent color, and fonts, so the calendar adapts to any design.
+
+## Views
+
+Switch between **Planner** (time grid) and **Agenda** (list) in Day or Week mode:
+
+```svelte
+<Calendar {adapter} view="week-planner" />  <!-- default -->
+<Calendar {adapter} view="day-planner" />
+<Calendar {adapter} view="week-agenda" />
+<Calendar {adapter} view="day-agenda" />
+```
+
+Users can also switch via the built-in Day/Week pills.
+
+Hide the pills when your app controls the view externally:
+
+```svelte
+<Calendar {adapter} view="day-planner" showModePills={false} />
+```
+
+## Mobile
+
+On narrow screens (`< 768px`), the calendar automatically remaps Planner views to touch-first Mobile views with swipe navigation, a centralized header with Day/Week pills, and a compact layout:
+
+```svelte
+<!-- Auto-detect (default) — switches at 768px -->
+<Calendar {adapter} />
+
+<!-- Force mobile layout -->
+<Calendar {adapter} mobile={true} />
+
+<!-- Force desktop layout -->
+<Calendar {adapter} mobile={false} />
+```
+
+Mobile views include:
+- **MobileDay** — vertical time grid with hour labels, swipe left/right to change days, all-day event chips at the top, tap-to-create
+- **MobileWeek** — vertical day list showing each day's events with relative labels (Today, Tomorrow, etc.)
+
+Agenda views keep their list-based layout on mobile but hide desktop floating navigation in favor of the centralized header.
+
+## Callbacks
+
+```svelte
+<Calendar
+  {adapter}
+  oneventclick={(event) => console.log('Clicked', event.title)}
+  oneventcreate={(range) => console.log('New slot', range.start, range.end)}
+  oneventmove={(event, start, end) => console.log('Moved', event.title, start, end)}
+  onviewchange={(viewId) => console.log('View', viewId)}
+/>
+```
+
+Set `readOnly` to disable drag, resize, and click-to-create:
+
+```svelte
+<Calendar {adapter} readOnly />
+```
+
+Hide nav controls (prev/next/today) and treat all days equally (no past-day dimming):
+
+```svelte
+<!-- Yoga studio: fixed weekly schedule, no browsing, all days equal -->
+<Calendar
+  {adapter}
+  view="week-agenda"
+  readOnly
+  showNavigation={false}
+  showDates={false}
+  equalDays
+/>
+```
+
+Hide weekends for a workweek view:
+
+```svelte
+<!-- Office planner: Mon–Fri only -->
+<Calendar {adapter} view="week-planner" hideDays={[6, 7]} />
+```
+
+Control which date the calendar shows from your app:
+
+```svelte
+<script>
+  let date = $state(new Date());
+</script>
+
+<Calendar
+  {adapter}
+  currentDate={date}
+  ondatechange={(d) => date = d}
+/>
+```
+
+Show a rolling 3-day view:
+
+```svelte
+<Calendar {adapter} view="week-planner" days={3} />
+```
+
+Block lunch hours and enforce 30–120 min events:
 
-  const adapter = createMemoryAdapter(events);
+```svelte
+<script>
+  import type { BlockedSlot } from '@nomideusz/svelte-calendar';
 
-  const views: CalendarView[] = [
-    { id: 'day-planner',   label: 'Planner', granularity: 'day',  component: Planner, props: { mode: 'day' } },
-    { id: 'week-planner',  label: 'Planner', granularity: 'week', component: Planner, props: { mode: 'week' } },
-    { id: 'day-agenda', label: 'Agenda',  granularity: 'day',  component: Agenda,  props: { mode: 'day' } },
-    { id: 'week-agenda',label: 'Agenda',  granularity: 'week', component: Agenda,  props: { mode: 'week' } },
+  const blocked: BlockedSlot[] = [
+    { start: 12, end: 13, label: 'Lunch' },          // every day 12–1 PM
+    { day: 6, start: 0, end: 24, label: 'Saturday' }, // block all Saturday
   ];
 </script>
 
+<Calendar {adapter} blockedSlots={blocked} minDuration={30} maxDuration={120} />
+```
+
+Disable specific dates:
+
+```svelte
 <Calendar
-  {views}
   {adapter}
-  defaultView="week-planner"
-  theme={neutral}
-  height={600}
-  oneventclick={(ev) => console.log('clicked', ev.id)}
-  oneventcreate={(range) => console.log('create', range)}
+  disabledDates={[new Date('2026-03-25'), new Date('2026-04-01')]}
 />
 ```
 
-## Calendar Props
+Custom day headers and hover previews:
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `adapter` | `CalendarAdapter` | *required* | Data layer (memory, recurring, REST) |
-| `views` | `CalendarView[]` | `[]` | Registered view components |
-| `defaultView` | `string` | `'week-planner'` | Initial view ID |
-| `theme` | `string` | `''` | CSS theme string (`--dt-*` custom properties) |
-| `height` | `number` | `600` | Total height in pixels |
-| `locale` | `string` | `'en-US'` | BCP 47 locale tag |
-| `dir` | `'ltr' \| 'rtl' \| 'auto'` | - | Text direction |
-| `mondayStart` | `boolean` | `true` | Start week on Monday |
-| `readOnly` | `boolean` | `false` | Disable drag, resize, and click-to-create |
-| `visibleHours` | `[number, number]` | - | Crop grid to `[startHour, endHour)` |
-| `initialDate` | `Date` | today | Date to focus on at mount |
-| `snapInterval` | `number` | `15` | Drag snap in minutes |
-| `oneventclick` | `(event) => void` | - | Event clicked |
-| `oneventcreate` | `(range) => void` | - | New time range selected |
-| `oneventmove` | `(event, start, end) => void` | - | Event dragged to new time |
-| `onviewchange` | `(viewId) => void` | - | Active view changed |
-| `event` | `Snippet<[TimelineEvent]>` | - | Custom event rendering |
-| `empty` | `Snippet` | - | Empty state content |
+```svelte
+<Calendar {adapter} oneventhover={(ev) => showTooltip(ev)}>
+  {#snippet dayHeader({ date, isToday, dayName })}
+    <span style:font-weight={isToday ? 'bold' : 'normal'}>{dayName}</span>
+  {/snippet}
+</Calendar>
+```
 
-## TimelineEvent
+## Themes
+
+Three built-in presets:
+
+| Preset | Description |
+|--------|-------------|
+| `auto` | **Default.** Probes the host page at mount — background, accent color, fonts, light/dark mode — and generates matching `--dt-*` tokens automatically. Reactively watches for host theme changes. |
+| `neutral` | Explicit light theme. White bg, blue accent, inherits host fonts. Use when embedding standalone. |
+| `midnight` | Explicit dark theme. Charcoal bg, red accent. |
+
+```svelte
+<script>
+  import { Calendar, neutral, midnight } from '@nomideusz/svelte-calendar';
+</script>
+
+<Calendar {adapter} />                     <!-- auto: adapts to host page -->
+<Calendar {adapter} theme={neutral} />     <!-- explicit light mode -->
+<Calendar {adapter} theme={midnight} />    <!-- explicit dark mode -->
+```
+
+### Smart Auto Theme
+
+The default `auto` preset probes the host page's design and generates a calendar that blends in — no configuration needed. It detects:
+
+- **Background color** — from CSS variables, inline styles, or computed styles
+- **Light/dark mode** — from background luminance
+- **Accent/brand color** — from CSS variables (`--accent`, `--primary`, `--bs-primary`, etc.), link colors, or button colors
+- **Text color** — validated for contrast against the background
+- **Fonts** — inherited via CSS cascade
+
+It also watches for changes (e.g. dark mode toggle) and updates automatically.
+
+Fine-tune auto-detection with the `autoTheme` prop:
+
+```svelte
+<!-- Force dark mode even if the page background is light -->
+<Calendar {adapter} autoTheme={{ mode: 'dark' }} />
+
+<!-- Override the accent color (skip probing) -->
+<Calendar {adapter} autoTheme={{ accent: '#e11d48' }} />
+
+<!-- Override the font stack -->
+<Calendar {adapter} autoTheme={{ font: '"Poppins", sans-serif' }} />
+
+<!-- Combine overrides -->
+<Calendar {adapter} autoTheme={{ mode: 'dark', accent: '#10b981' }} />
+
+<!-- Disable auto-probing entirely (passive CSS inheritance only) -->
+<Calendar {adapter} autoTheme={false} />
+```
+
+### Manual CSS Variables
+
+Override any design token by setting `--dt-*` custom properties on an ancestor:
+
+```html
+<!-- Wrap in a div with your overrides -->
+<div style="--dt-accent: #e11d48; --dt-bg: #1a1a2e; --dt-text: rgba(255,255,255,0.87);">
+  <Calendar {adapter} />
+</div>
+```
+
+Or set them at the page level:
+
+```css
+:root {
+  --dt-bg: #fafafa;
+  --dt-accent: #2563eb;
+  --dt-text: rgba(0, 0, 0, 0.87);
+  --dt-border: rgba(0, 0, 0, 0.08);
+}
+```
+
+The auto-probe reads these first — if you set `--dt-bg` or `--accent` on `:root`, the calendar picks them up.
+
+### Extending Presets
+
+Build on a preset by appending overrides:
+
+```ts
+import { neutral } from '@nomideusz/svelte-calendar';
+
+// neutral base + custom accent + rounded feel
+const custom = `${neutral}; --dt-accent: #e11d48;`;
+```
+
+```svelte
+<Calendar {adapter} theme={custom} />
+```
+
+<details>
+<summary>All design tokens</summary>
+
+| Token | Purpose |
+|-------|---------|
+| `--dt-stage-bg` | Background behind the calendar (page area) |
+| `--dt-bg` | Calendar card background |
+| `--dt-surface` | Elevated surface (alternating rows, headers) |
+| `--dt-border` | Default border |
+| `--dt-border-day` | Day-column dividers |
+| `--dt-text` | Primary text |
+| `--dt-text-2` | Secondary text |
+| `--dt-text-3` | Tertiary text |
+| `--dt-accent` | Accent color |
+| `--dt-accent-dim` | Accent at ~12% opacity |
+| `--dt-glow` | Accent glow / focus ring |
+| `--dt-today-bg` | Today column highlight |
+| `--dt-btn-text` | Button label color |
+| `--dt-scrollbar` | Scrollbar thumb |
+| `--dt-success` | Completed indicator |
+| `--dt-serif` / `--dt-sans` / `--dt-mono` | Font stacks |
+
+</details>
+
+## Events
+
+### TimelineEvent
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `string` | Unique identifier |
 | `title` | `string` | Event title |
 | `start` / `end` | `Date` | Time range |
-| `color` | `string?` | Accent color |
-| `category` | `string?` | For grouping / colorMap |
-| `subtitle` | `string?` | Secondary text |
+| `color` | `string?` | Accent color (auto-assigned if omitted) |
+| `category` | `string?` | Grouping key — events with the same category share a color |
+| `subtitle` | `string?` | Secondary text below the title |
 | `tags` | `string[]?` | Small accent-colored pills |
 | `allDay` | `boolean?` | Render as an all-day event |
-| `data` | `Record?` | Arbitrary payload |
+| `data` | `Record?` | Arbitrary payload for your app |
 
-## Multi-day & All-day Events
+### Auto-Coloring
 
-Events that span multiple days or are flagged `allDay: true` are rendered in a
-dedicated strip above timed events in every view:
+Omit `color` and events are auto-assigned a vivid palette color, grouped by `category` (or `title`):
 
 ```ts
-const events: TimelineEvent[] = [
-  // Explicit all-day flag
-  { id: '1', title: 'Conference', start: new Date('2025-03-15'), end: new Date('2025-03-18'), allDay: true },
-  // Auto-detected: starts at midnight and spans ≥ 24 h
-  { id: '2', title: 'Sprint', start: new Date('2025-03-15T00:00'), end: new Date('2025-03-17T00:00') },
-  // Overnight timed event — also renders in the all-day strip
-  { id: '3', title: 'Hackathon', start: new Date('2025-03-15T18:00'), end: new Date('2025-03-16T06:00') },
+const events = [
+  { id: '1', title: 'Yoga',  category: 'wellness', start: ..., end: ... },
+  { id: '2', title: 'Pilates', category: 'wellness', start: ..., end: ... },  // same color
+  { id: '3', title: 'Standup', start: ..., end: ... },                        // different color
 ];
 ```
 
-Utility helpers are exported for custom views:
+Generate a theme-harmonious palette from any accent color:
 
 ```ts
-import { isAllDay, isMultiDay, segmentForDay } from '@nomideusz/svelte-calendar';
+import { createMemoryAdapter, generatePalette } from '@nomideusz/svelte-calendar';
 
-segmentForDay(event, dayTimestamp);
-// → { ev, start, end, isStart, isEnd, dayIndex, totalDays, allDay } | null
+// Colors that harmonize with your theme's accent
+const palette = generatePalette('#e11d48');
+const adapter = createMemoryAdapter(events, { palette });
 ```
 
-## Views
+### Multi-day & All-day
+
+Events spanning multiple days or flagged `allDay: true` render in a dedicated strip above timed events:
+
+```ts
+const events = [
+  { id: '1', title: 'Conference', start: new Date('2026-03-15'), end: new Date('2026-03-18'), allDay: true },
+  { id: '2', title: 'Sprint',    start: new Date('2026-03-15T00:00'), end: new Date('2026-03-17T00:00') },
+];
+```
+
+### Custom Event Rendering
 
-| Concept | Day | Week | Description |
-|---------|-----|------|-------------|
-| **Planner** | `mode="day"` | `mode="week"` | Time blocks on a scrollable grid |
-| **Agenda** | `mode="day"` | `mode="week"` | List view — Done, Now, Next (day) or grouped-by-day (week) |
+Use the `event` snippet to fully control how events look:
+
+```svelte
+<Calendar {adapter}>
+  {#snippet event(ev)}
+    <div style="padding: 4px 8px;">
+      <strong>{ev.title}</strong>
+      {#if ev.subtitle}<small>{ev.subtitle}</small>{/if}
+    </div>
+  {/snippet}
+</Calendar>
+```
 
 ## Recurring Schedules
 
+For fixed repeating events (class timetables, office hours):
+
 ```svelte
-<script lang="ts">
-  import { Calendar, Planner, createRecurringAdapter, neutral } from '@nomideusz/svelte-calendar';
-  import type { CalendarView, RecurringEvent } from '@nomideusz/svelte-calendar';
-
-  const schedule: RecurringEvent[] = [
-    // Every Monday
-    { id: '1', title: 'Morning Yoga', dayOfWeek: 1, startTime: '07:00', endTime: '08:30', color: '#818cf8' },
-    // Mon/Wed/Fri during semester
-    { id: '2', title: 'Math', dayOfWeek: [1, 3, 5], startTime: '09:00', endTime: '10:00',
-      startDate: '2025-09-01', until: '2025-12-15' },
-    // Biweekly team sync
-    { id: '3', title: 'Sync', frequency: 'weekly', interval: 2, dayOfWeek: 2,
-      startTime: '14:00', endTime: '15:00', startDate: '2025-03-01' },
-    // Daily standup, March only
-    { id: '4', title: 'Standup', frequency: 'daily', startTime: '09:00', endTime: '09:15',
-      startDate: '2025-03-01', until: '2025-03-31' },
-    // Workshop — 8 Saturday sessions
-    { id: '5', title: 'Workshop', dayOfWeek: 6, startTime: '10:00', endTime: '12:00',
-      startDate: '2025-03-01', count: 8 },
-    // Monthly review on the 15th
-    { id: '6', title: 'Review', frequency: 'monthly', dayOfMonth: 15,
+<script>
+  import { Calendar, createRecurringAdapter } from '@nomideusz/svelte-calendar';
+
+  const adapter = createRecurringAdapter([
+    { id: '1', title: 'Yoga',    dayOfWeek: 1, startTime: '07:00', endTime: '08:30' },
+    { id: '2', title: 'Standup', frequency: 'daily', startTime: '09:00', endTime: '09:15',
+      startDate: '2026-03-01', until: '2026-03-31' },
+    { id: '3', title: 'Review',  frequency: 'monthly', dayOfMonth: 15,
       startTime: '10:00', endTime: '11:00' },
-  ];
-
-  const adapter = createRecurringAdapter(schedule);
-  const views: CalendarView[] = [
-    { id: 'week-planner', label: 'Planner', granularity: 'week', component: Planner, props: { mode: 'week' } },
-  ];
+  ]);
 </script>
 
-<Calendar {views} {adapter} defaultView="week-planner" theme={neutral} readOnly />
+<Calendar {adapter} readOnly />
 ```
 
-### RecurringEvent
+<details>
+<summary>RecurringEvent fields</summary>
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -166,66 +374,79 @@ segmentForDay(event, dayTimestamp);
 | `startDate` | `string` | — | First occurrence `"YYYY-MM-DD"` |
 | `until` | `string` | — | Last occurrence `"YYYY-MM-DD"` |
 | `count` | `number` | — | Max occurrences from `startDate` |
-| `color` | `string?` | — | Accent color |
+| `color` | `string?` | — | Accent color (auto-assigned if omitted) |
 
-## Color Map & Auto-Coloring
+</details>
 
-```ts
-// Explicit mapping
-const adapter = createMemoryAdapter(events, { colorMap: { yoga: '#818cf8', wellness: '#34d399' } });
+## REST Adapter
 
-// Auto-assign from accent color
-const adapter = createMemoryAdapter(events, { autoColor: '#6366f1' });
+Connect to any REST API:
 
-// Fixed vivid palette
-const adapter = createMemoryAdapter(events, { autoColor: true });
+```ts
+import { Calendar, createRestAdapter } from '@nomideusz/svelte-calendar';
+
+const adapter = createRestAdapter({
+  baseUrl: 'https://api.example.com/v1',
+  headers: { Authorization: 'Bearer TOKEN' },
+  // Optional: map your API shape to TimelineEvent[]
+  mapEvents: (data) => data.items.map(item => ({
+    id: item.id,
+    title: item.name,
+    start: new Date(item.startAt),
+    end: new Date(item.endAt),
+  })),
+});
 ```
 
-Events with explicit `color` always take priority.
+The adapter calls `GET /events?start=...&end=...`, `POST /events`, `PATCH /events/:id`, and `DELETE /events/:id`.
+
+## Custom Adapter
+
+Implement the `CalendarAdapter` interface to connect any data source:
+
+```ts
+import type { CalendarAdapter, DateRange, TimelineEvent } from '@nomideusz/svelte-calendar';
+
+const adapter: CalendarAdapter = {
+  fetchEvents: async (range: DateRange) => { /* return TimelineEvent[] */ },
+  createEvent: async (event) => { /* return created TimelineEvent with id */ },
+  updateEvent: async (id, patch) => { /* return updated TimelineEvent */ },
+  deleteEvent: async (id) => { /* void */ },
+};
+```
 
 ## Localization (i18n)
 
-All UI strings are configurable via the labels system:
+The `locale` prop controls date/time formatting (BCP 47):
+
+```svelte
+<Calendar {adapter} locale="de-DE" />
+```
+
+Override UI labels for full translation:
 
 ```ts
-import { setLabels, resetLabels, getLabels } from '@nomideusz/svelte-calendar';
-import type { CalendarLabels } from '@nomideusz/svelte-calendar';
+import { setLabels } from '@nomideusz/svelte-calendar';
 
-// Override any subset — unset keys stay English
 setLabels({
-  today: 'Heute',
-  yesterday: 'Gestern',
-  tomorrow: 'Morgen',
-  day: 'Tag',
-  week: 'Woche',
-  now: 'jetzt',
-  free: 'frei',
-  allDay: 'Ganztägig',
-  done: 'Erledigt',
-  upNext: 'Als Nächstes',
+  today: 'Heute', day: 'Tag', week: 'Woche',
   noEvents: 'Keine Termine',
-  goToToday: 'Heute anzeigen',
   nMore: (n) => `+${n} weitere`,
-  nEvents: (n) => `${n} Termin${n === 1 ? '' : 'e'}`,
 });
-
-// Reset to English
-resetLabels();
-
-// Read current labels
-const labels = getLabels();
 ```
 
+Call `resetLabels()` to restore English defaults.
+
 <details>
-<summary><strong>Full label keys</strong></summary>
+<summary>All label keys</summary>
 
 | Key | Default | Description |
 |-----|---------|-------------|
 | `today` | `'Today'` | Relative day label / nav button |
 | `yesterday` | `'Yesterday'` | Relative day label |
 | `tomorrow` | `'Tomorrow'` | Relative day label |
-| `day` | `'Day'` | Granularity pill |
-| `week` | `'Week'` | Granularity pill |
+| `day` | `'Day'` | Mode pill |
+| `week` | `'Week'` | Mode pill |
 | `planner` | `'Planner'` | View label |
 | `agenda` | `'Agenda'` | View label |
 | `now` | `'now'` | Live indicator badge |
@@ -249,55 +470,26 @@ const labels = getLabels();
 
 </details>
 
-## Themes
-
-| Preset | Description |
-|--------|-------------|
-| `midnight` | Dark navy/slate, red accent |
-| `neutral` | White/gray, blue accent, inherits fonts — **recommended** |
+## Timezone Support
 
-```svelte
-<Calendar {views} {adapter} theme={neutral} />
-```
-
-Customize any token:
+Convert events between timezones using the built-in helpers:
 
 ```ts
-const myTheme = `
-  ${neutral}
-  --dt-accent: #e11d48;
-  --dt-bg: var(--my-app-surface);
-  --dt-text: var(--my-app-text);
-`;
-```
-```
+import { toZonedTime, fromZonedTime, nowInZone } from '@nomideusz/svelte-calendar';
 
-<details>
-<summary><strong>Full token reference</strong></summary>
+// Display a UTC date in a specific timezone
+const local = toZonedTime(utcDate, 'America/New_York');
 
-| Token | Purpose |
-|-------|---------|
-| `--dt-bg` | Main background |
-| `--dt-surface` | Elevated surface |
-| `--dt-border` | Default border |
-| `--dt-border-day` | Day-column dividers |
-| `--dt-text` | Primary text |
-| `--dt-text-2` | Secondary text |
-| `--dt-text-3` | Tertiary text |
-| `--dt-accent` | Accent color |
-| `--dt-accent-dim` | Accent at ~12% opacity |
-| `--dt-glow` | Accent glow / focus ring |
-| `--dt-today-bg` | Today column highlight |
-| `--dt-btn-text` | Button label color |
-| `--dt-scrollbar` | Scrollbar thumb |
-| `--dt-success` | Completed indicator |
-| `--dt-serif` / `--dt-sans` / `--dt-mono` | Font stacks |
+// Convert back to UTC before saving
+const utc = fromZonedTime(localDate, 'America/New_York');
 
-</details>
+// Current time in a timezone
+const now = nowInZone('Asia/Tokyo');
+```
 
 ## Embeddable Widget
 
-Drop into any HTML page - no build tools needed:
+Drop into any HTML page — no build tools needed:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@nomideusz/svelte-calendar/widget/widget.js"></script>
@@ -309,12 +501,50 @@ Drop into any HTML page - no build tools needed:
 ></day-calendar>
 ```
 
-## Standalone Views
+## All Props
 
-```svelte
-<Planner style={midnight} mode="day" events={events} height={600} />
-<Agenda mode="day" events={events} height={520} />
-```
+<details>
+<summary>Full Calendar props reference</summary>
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `adapter` | `CalendarAdapter` | *required* | Data layer (memory, recurring, REST, or custom) |
+| `views` | `CalendarView[]` | all 4 built-in | Registered view components |
+| `view` | `string` | first view | Active view ID |
+| `theme` | `string` | `auto` | CSS theme string (`--dt-*` custom properties). `auto` probes the host page and generates matching tokens. |
+| `autoTheme` | `AutoThemeOptions \| false` | `{}` | Fine-tune auto-detection: `{ mode, accent, font }`. Set `false` to disable probing. |
+| `mobile` | `'auto' \| boolean` | `'auto'` | Mobile mode. `'auto'` detects via `matchMedia(<768px)`. Remaps Planner→Mobile views. |
+| `height` | `number` | `600` | Total height in pixels |
+| `borderRadius` | `number` | `12` | Border radius in pixels. Set to `0` for no rounding. |
+| `locale` | `string` | `'en-US'` | BCP 47 locale tag |
+| `dir` | `'ltr' \| 'rtl' \| 'auto'` | — | Text direction |
+| `mondayStart` | `boolean` | `true` | Start week on Monday |
+| `readOnly` | `boolean` | `false` | Disable drag, resize, and click-to-create |
+| `visibleHours` | `[number, number]` | — | Crop grid to `[startHour, endHour)` |
+| `initialDate` | `Date` | today | Date to focus on at mount |
+| `snapInterval` | `number` | `15` | Drag snap in minutes |
+| `showModePills` | `boolean` | `true` | Show the Day/Week mode pills |
+| `showNavigation` | `boolean` | `true` | Show prev/next/today navigation |
+| `equalDays` | `boolean` | `false` | Treat all days equally (no past-day dimming/collapsing) |
+| `showDates` | `boolean` | `true` | Show date numbers in headers. `false` = day names only (Mon, Tue, …) |
+| `hideDays` | `number[]` | — | ISO weekdays to hide (1=Mon … 7=Sun). E.g. `[6, 7]` hides weekends |
+| `currentDate` | `Date` | — | Controlled focus date (drives which date the calendar shows) |
+| `days` | `number` | `7` | Number of days shown in week views (e.g. `3` for a rolling 3-day view) |
+| `blockedSlots` | `BlockedSlot[]` | — | Time ranges that cannot be booked (hatched overlay in planner views) |
+| `disabledDates` | `Date[]` | — | Dates that are fully disabled (dimmed, no interaction) |
+| `minDuration` | `number` | — | Minimum event duration in minutes (enforced on create & resize) |
+| `maxDuration` | `number` | — | Maximum event duration in minutes (enforced on create & resize) |
+| `dayHeader` | `Snippet<[{ date, isToday, dayName }]>` | — | Custom day header snippet for planner/agenda views |
+| `oneventclick` | `(event) => void` | — | Event clicked |
+| `oneventcreate` | `(range) => void` | — | New time range selected |
+| `oneventmove` | `(event, start, end) => void` | — | Event dragged to new time |
+| `onviewchange` | `(viewId) => void` | — | Active view changed |
+| `oneventhover` | `(event) => void` | — | Pointer enters an event (for tooltips, previews) |
+| `ondatechange` | `(date) => void` | — | Focused date changed (navigation, scroll, etc.) |
+| `event` | `Snippet<[TimelineEvent]>` | — | Custom event rendering |
+| `empty` | `Snippet` | — | Empty state content |
+
+</details>
 
 ## Development