@nomideusz/svelte-calendar 1.2.0 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://badgen.net/npm/v/@nomideusz/svelte-calendar)](https://www.npmjs.com/package/@nomideusz/svelte-calendar) [![license](https://badgen.net/badge/license/MIT/blue)](https://github.com/nomideusz/svelte-calendar/blob/main/LICENSE)
 
-A themeable **Svelte 5** calendar: day and week **Planner** time grids, a multi-week **Scroll** view, **Agenda** lists, a **Month** grid and touch-first **Mobile** layouts — with drag-and-drop, timezones, a headless API, an embeddable web component, and a smart auto-theme that adapts to any page.
+A themeable **Svelte 5** calendar: day and week **Planner** time grids, a multi-week **Scroll** view, **Agenda** lists, a **Month** grid and touch-first **Mobile** layouts, with drag-and-drop, timezones, a headless API, an embeddable web component, and a smart auto-theme that adapts to any page.
 
 **[Live demo → svelte-calendar.xyz](https://svelte-calendar.xyz/)**
 
@@ -14,7 +14,7 @@ pnpm add @nomideusz/svelte-calendar
 
 Requirements:
 
-- **Svelte `^5.29.0`** (peer dependency — the package uses attachments, `{@attach}`).
+- **Svelte `^5.29.0`** (peer dependency: the package uses attachments, `{@attach}`).
 - Runtime dependencies (installed for you): `date-fns`, `date-fns-tz`, `@chenglou/pretext`.
 - Node ≥ 22 is only needed to develop the package itself, not to use it.
 
@@ -34,24 +34,24 @@ Requirements:
   ]);
 </script>
 
-<Calendar {adapter} />
+<Calendar {adapter} view="week-planner" />
 ```
 
-That's it — 8 built-in views, auto-coloring, drag-and-drop with live previews, 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.
+That's it: eight built-in views and drag-and-drop with live previews, out of the box. The default `auto` theme probes your page's background, accent color and fonts, so the calendar adapts to any design. Events without a `color` draw in ink; to color them automatically, give the adapter a [`palette`](#event-colors).
 
 ## Views
 
-The default registry (`defaultViews`) holds eight views:
+The default registry (`defaultViews`) holds eight views. Six are the ones you choose with `view`; the two `*-mobile` views are what the others swap to in a narrow container (see [Mobile](#mobile)), so the demo's view list shows six.
 
 | View ID | Mode | What it is |
 |---------|------|------------|
-| `day-planner` | day | Vertical time grid, one column. **The default view** (first registered). |
+| `day-planner` | day | Vertical time grid, one column. Opens when `view` is unset (the first registered view). The examples here, the demo, the widget and `createCalendar` open on `week-planner`. |
 | `week-planner` | week | The same time grid, one column per day (`days`, default 7). |
 | `week-scroll` | week | Weeks stacked in one infinite vertical scroller (Hey-Calendar style): each chip sits at the height of its start time, month names run down the side. Drag to move, drop onto a day; it scrolls under a drag. |
 | `day-agenda` | day | Live list for one day: now / up next / done. |
 | `week-agenda` | week | List of the week's days (`columns` turns it into a timetable grid). |
-| `day-mobile` | day | Touch-first time grid with swipe navigation. |
-| `week-mobile` | week | Touch-first list of the week's days. |
+| `day-mobile` | day | Touch-first time grid with swipe navigation. Used automatically in a narrow container. |
+| `week-mobile` | week | Touch-first list of the week's days. Used automatically in a narrow container. |
 | `month-grid` | month | Week-aligned month grid, chips per day with a "+N more" overflow. |
 
 ```svelte
@@ -68,10 +68,10 @@ Users switch with the built-in pills: **Day / Week / Month** for the mode, plus
 
 Planner views are designed for direct manipulation:
 
-- **Move** — drag an event to another day or time; a ghost previews the target before the move commits.
-- **Resize** — drag an event's top/bottom grip to change its duration; `minDuration`/`maxDuration` clamp the result.
-- **Create** — press on empty canvas and sweep to draw a range, or click for a default-length slot. Both go through the same validation (blocked slots, disabled dates, `minDuration`/`maxDuration`) and then fire `oneventcreate`.
-- **External drop** — an HTML5 drag from outside the calendar (a class chip, a template) dropped on the planner or `week-scroll` fires `onexternaldrop({ start, dataTransfer })`.
+- **Move**: drag an event to another day or time; a ghost previews the target before the move commits.
+- **Resize**: drag an event's top/bottom grip to change its duration; `minDuration`/`maxDuration` clamp the result.
+- **Create**: press on empty canvas and sweep to draw a range, or click for a default-length slot. Both go through the same validation (blocked slots, disabled dates, `minDuration`/`maxDuration`) and then fire `oneventcreate`.
+- **External drop**: an HTML5 drag from outside the calendar (a class chip, a template) dropped on the planner or `week-scroll` fires `onexternaldrop({ start, dataTransfer })`.
 
 `week-scroll` supports move, click-to-create and external drops. In `week-agenda` with `columns` and an `oneventmove` handler, a card can be dragged to another day (it keeps its time of day); that move goes straight to `oneventmove` without writing the adapter.
 
@@ -81,8 +81,8 @@ The month grid shows up to three chips per day. Clicking a day or its "+N more"
 
 When focus is inside the calendar:
 
-- `t` — go to today.
-- `←` / `→` — previous / next period (mirrored in RTL). Ignored while typing in a field or inside a pill group, where arrows move between pills.
+- `t`: go to today.
+- `←` / `→`: previous / next period (mirrored in RTL). Ignored while typing in a field or inside a pill group, where arrows move between pills.
 - In `month-grid`: arrow keys move between days, `Enter` / `Space` opens the focused day (`ondayclick`).
 - In `week-planner` / `day-planner`: the day columns are one tab stop; `←` / `→` move between days, `Enter` / `Space` creates an event (`oneventcreate`) at the next slot today, or 09:00. On a focused event, `Alt+↑` / `Alt+↓` move it one `snapInterval`, `Alt+←` / `Alt+→` move it a day, and `Alt+Shift+↑` / `Alt+Shift+↓` move its end; each goes through the same validation as a drag and fires `oneventmove`.
 
@@ -106,13 +106,13 @@ The `views` prop replaces the registry. Spread `defaultViews` to add your own vi
 
 A `CalendarView` is `{ id, label, mode: 'day' | 'week' | 'month', component, props? }`. `label` names the view-type pill; views sharing a label across modes are what the Day/Week/Month pills switch between.
 
-The component receives `CalendarViewProps` (plus your `props`) — declare only the ones it uses:
+The component receives `CalendarViewProps` (plus your `props`); declare only the ones it uses:
 
 | Prop | Type | Notes |
 |------|------|-------|
 | `events` | `TimelineEvent[]` | Everything loaded for the current range |
 | `style` | `string` | The active `--dt-*` theme string |
-| `height` | `number \| null` | Currently always `null` — size to the container |
+| `height` | `number \| null` | Currently always `null`: size to the container |
 | `mode` | `'day' \| 'week' \| 'month'` | |
 | `mondayStart` | `boolean` | |
 | `locale` | `string \| undefined` | |
@@ -143,15 +143,15 @@ The component receives `CalendarViewProps` (plus your `props`) — declare only
 
 `useCalendarContext()` (type `CalendarContext`) gives a view the running Calendar's engines and config: `viewState`, `drag`, `commitDrag`, `labels`, `readOnly`, `snapInterval`, `minColumnWidth`, `blockedSlots`, `disabledDates` / `disabledSet`, `minDuration` / `maxDuration`, `hideDays`, `equalDays`, `showDates`, `compact`, `columns`, `isMobile`, `autoHeight`, `timezone`, `oneventmove`, `oneventhover`, `ondayclick`, `eventSnippet`, `emptySnippet`, `dayHeaderSnippet` and `loadRange` (a view can widen the range the store loads). Call it at component init, inside a `<Calendar>`.
 
-The raw view components — `Planner`, `PlannerScroll`, `Agenda`, `Mobile`, `MonthGrid` — are exported so you can register them under your own ids. Building blocks for custom views are exported as primitives: `EventBlock` (an event card), `TimeGutter` (hour labels), `DayHeader`, `NowIndicator`, `EmptySlot` (click-to-create target) and `FloatingPanel` (see [Event details panel](#event-details-panel)).
+The raw view components (`Planner`, `PlannerScroll`, `Agenda`, `Mobile`, `MonthGrid`) are exported so you can register them under your own ids. Building blocks for custom views are exported as primitives: `EventBlock` (an event card), `TimeGutter` (hour labels), `DayHeader`, `NowIndicator`, `EmptySlot` (click-to-create target) and `FloatingPanel` (see [Event details panel](#event-details-panel)).
 
 ## Mobile
 
 When the calendar's **container** is narrower than 768px, it swaps to touch-first Mobile views with swipe navigation and a compact header:
 
 ```svelte
-<!-- Auto-detect (default) — switches at a 768px container width -->
-<Calendar {adapter} />
+<!-- Auto-detect (default): switches at a 768px container width -->
+<Calendar {adapter} view="week-planner" />
 
 <!-- Force mobile layout -->
 <Calendar {adapter} mobile={true} />
@@ -160,10 +160,10 @@ When the calendar's **container** is narrower than 768px, it swaps to touch-firs
 <Calendar {adapter} mobile={false} />
 ```
 
-- **MobileDay** — vertical time grid with hour labels, swipe left/right to change days, all-day chips at the top, tap-to-create, stable columns for overlapping events.
-- **MobileWeek** — vertical day list with relative labels (Today, Tomorrow, …) and accessible event buttons in each row.
+- **MobileDay**: vertical time grid with hour labels, swipe left/right to change days, all-day chips at the top, tap-to-create, stable columns for overlapping events.
+- **MobileWeek**: vertical day list with relative labels (Today, Tomorrow, …) and accessible event buttons in each row.
 
-In mobile mode every view except `*-agenda` and `*-mobile` is swapped for the `{mode}-mobile` entry of the same mode when one is registered — this includes custom views. Agenda views keep their list layout; `month-grid` has no mobile entry and stays. The mobile header shows only the Day/Week/Month pills.
+In mobile mode every view except `*-agenda` and `*-mobile` is swapped for the `{mode}-mobile` entry of the same mode when one is registered, custom views included. Agenda views keep their list layout; `month-grid` has no mobile entry and stays. The mobile header shows only the Day/Week/Month pills.
 
 With `'auto'`, the first render (and the server render) is the desktop layout; the container is measured on mount, so SSR hydrates cleanly.
 
@@ -185,9 +185,9 @@ With `'auto'`, the first render (and the server render) is the desktop layout; t
 
 | Callback | When it fires |
 |----------|---------------|
-| `oneventclick(event, anchor?)` | An event is clicked. The event is also selected (highlighted across views). `anchor` is the clicked block's viewport rect where the view has one (planner, `week-scroll`, `month-grid`) — for positioning a `FloatingPanel`. |
+| `oneventclick(event, anchor?)` | An event is clicked. The event is also selected (highlighted across views). `anchor` is the clicked block's viewport rect where the view has one (planner, `week-scroll`, `month-grid`), for positioning a `FloatingPanel`. |
 | `oneventcreate({ start, end })` | A drag-create or click-to-create passed validation. The calendar does **not** store anything: add the event to your data and hand the Calendar the updated adapter. |
-| `oneventmove(event, start, end)` | A drag or resize committed — **after** the adapter stored it, or when the adapter refused with a read-only error (the host owns persistence then; the block stays where it was dropped). Other adapter failures revert the block and go to `onerror`. (The `week-agenda` columns day-drag is the exception: it only calls `oneventmove`.) |
+| `oneventmove(event, start, end)` | A drag or resize committed: **after** the adapter stored it, or when the adapter refused with a read-only error (the host owns persistence then; the block stays where it was dropped). Other adapter failures revert the block and go to `onerror`. (The `week-agenda` columns day-drag is the exception: it only calls `oneventmove`.) |
 | `onexternaldrop({ start, dataTransfer })` | An outside HTML5 drag was dropped on the grid; `start` is the pointer's time, snapped. |
 | `onviewchange(viewId)` | Once on mount, then on every view change. |
 | `ondatechange(date)` | Once on mount, then whenever the focused date changes (navigation, scrolling, a tapped day). |
@@ -197,7 +197,7 @@ With `'auto'`, the first render (and the server render) is the desktop layout; t
 
 `oneventcreate`, `oneventmove` and `onexternaldrop` receive real instants, also with [`timezone`](#timezone-support). None of the write callbacks fire when `readOnly` is set.
 
-To show a newly created or moved event, update your data and give the Calendar a new adapter — the store reloads on a new adapter identity without blanking the grid:
+To show a newly created or moved event, update your data and give the Calendar a new adapter. The store reloads on a new adapter identity without blanking the grid:
 
 ```svelte
 <script lang="ts">
@@ -246,7 +246,7 @@ To lock single events, set `data.readOnly: true` on them: views refuse to move o
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `title` | `string` | `''` | Header text and dialog label |
-| `anchor` | `FloatingPanelAnchor` | `{ x: 24, y: 24 }` | `{ x, y, width?, height? }` — a `DOMRect` works as is |
+| `anchor` | `FloatingPanelAnchor` | `{ x: 24, y: 24 }` | `{ x, y, width?, height? }`; a `DOMRect` works as is |
 | `width` | `number` | `440` | Panel width in px |
 | `theme` | `string` | `''` | A `--dt-*` theme string, as the Calendar takes |
 | `closeLabel` | `string` | `'Close'` | Close button label |
@@ -320,7 +320,7 @@ Disable specific dates:
 />
 ```
 
-Disabled dates refuse creating or moving events into those days. Existing events stay visible and clickable — useful for holidays or fully booked days.
+Disabled dates refuse creating or moving events into those days. Existing events stay visible and clickable, which suits holidays or fully booked days.
 
 Custom day headers and hover previews:
 
@@ -358,7 +358,7 @@ Replace the built-in navigation or the entire header chrome with your own contro
 </Calendar>
 ```
 
-Let agenda content determine height instead of forcing a fixed box — useful inside a scrolling page:
+Let agenda content determine height instead of forcing a fixed box, for a calendar inside a scrolling page:
 
 ```svelte
 <Calendar {adapter} view="week-agenda" height="auto" compact />
@@ -370,7 +370,7 @@ Three built-in presets:
 
 | Preset | Description |
 |--------|-------------|
-| `auto` | **Default.** Probes the host page at mount — background, accent color, fonts, light/dark mode — and writes matching `--dt-*` tokens. Re-probes when the host theme changes. |
+| `auto` | **Default.** Probes the host page at mount (background, accent color, fonts, light/dark mode) and writes matching `--dt-*` tokens. Re-probes when the host theme changes. |
 | `neutral` | Explicit light theme. White bg, blue accent. Use when embedding standalone. |
 | `midnight` | Explicit dark theme. Charcoal bg, red accent. |
 
@@ -390,11 +390,11 @@ Three built-in presets:
 
 The default `auto` preset probes the page around the calendar and generates a theme that blends in. It detects:
 
-- **Background color** — from common CSS variables on `:root` (`--bg`, `--background`, `--color-bg`, `--bs-body-bg`, …), inline styles, or computed styles
-- **Light/dark mode** — from background luminance
-- **Accent/brand color** — from common CSS variables (`--accent`, `--primary`, `--brand`, `--bs-primary`, …), link colors, or button colors
-- **Text color** — validated for contrast against the background
-- **Fonts** — the host's computed font stack; the mono stack from `--font-mono` and similar variables
+- **Background color**: from common CSS variables on `:root` (`--bg`, `--background`, `--color-bg`, `--bs-body-bg`, …), inline styles, or computed styles
+- **Light/dark mode**: from background luminance
+- **Accent/brand color**: from common CSS variables (`--accent`, `--primary`, `--brand`, `--bs-primary`, …), link colors, or button colors
+- **Text color**: validated for contrast against the background
+- **Fonts**: the host's computed font stack; the mono stack from `--font-mono` and similar variables
 
 It watches for changes (a dark-mode toggle on `<html>`/`<body>`, the system color scheme) and updates automatically.
 
@@ -420,7 +420,7 @@ Fine-tune auto-detection with the `autoTheme` prop (`AutoThemeOptions`):
 
 The calendar writes its theme inline on its own root element, so it **wins over** `--dt-*` values set on an ancestor or `:root`. With the default `auto` theme it writes a full probed set. To use your own values:
 
-- **Change a few tokens** — append them to a preset (later declarations win):
+- **Change a few tokens**: append them to a preset (later declarations win):
 
   ```ts
   import { neutral } from '@nomideusz/svelte-calendar';
@@ -432,8 +432,8 @@ The calendar writes its theme inline on its own root element, so it **wins over*
   <Calendar {adapter} theme={custom} />
   ```
 
-- **Write your own theme string** — any `--dt-*` declarations; tokens you leave out are inherited from ancestors or fall back to neutral defaults.
-- **Inherit from the page** — pass `autoTheme={false}` (keeping the default `auto` theme). The calendar then writes no tokens and reads whatever `--dt-*` its ancestors define:
+- **Write your own theme string**: any `--dt-*` declarations; tokens you leave out are inherited from ancestors or fall back to neutral defaults.
+- **Inherit from the page**: pass `autoTheme={false}` (keeping the default `auto` theme). The calendar then writes no tokens and reads whatever `--dt-*` its ancestors define:
 
   ```svelte
   <div style="--dt-accent: #e11d48; --dt-bg: #1a1a2e; --dt-text: rgba(255,255,255,0.87);">
@@ -457,6 +457,7 @@ Component fallbacks use system fonts and a neutral blue accent, so the package s
 | `--dt-text-3` | Tertiary text |
 | `--dt-accent` | Accent color |
 | `--dt-accent-dim` | Accent at ~12% opacity (selection, highlights) |
+| `--dt-event` | Bar color of an event without its own `color` (the presets set it to the text color, so such events draw in ink) |
 | `--dt-accent-fg` | Text on the planner's today-number badge (default `#fff`; not set by the presets) |
 | `--dt-btn-text` | Text on accent-filled buttons and badges |
 | `--dt-glow` | Accent glow / focus ring |
@@ -481,8 +482,8 @@ Component fallbacks use system fonts and a neutral blue accent, so the package s
 | `id` | `string` | Unique identifier |
 | `title` | `string` | Event title |
 | `start` / `end` | `Date` | Time range |
-| `color` | `string?` | Accent color (auto-assigned if omitted) |
-| `category` | `string?` | Grouping key — events with the same category share a color |
+| `color` | `string?` | The event's bar color. Without it the event draws in `--dt-event` (ink), or takes a color from the adapter's `palette` |
+| `category` | `string?` | Grouping key: with a `palette`, events of 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 |
@@ -494,19 +495,25 @@ Component fallbacks use system fonts and a neutral blue accent, so the package s
 
 Cancelled events render with a strikethrough but stay visible, so the slot isn't mistaken for free time.
 
-### Auto-Coloring
+### Event colors
+
+An event with a `color` draws its bar in that color. An event without one draws in ink: `--dt-event`, which the presets set to the text color. Nothing is colored for you unless you ask.
 
-Omit `color` and the built-in adapters assign a vivid palette color, grouped by `category` (or `title`):
+To color events automatically, pass a `palette` to the memory, recurring or mapped adapter. Events without a `color` then take a palette color, grouped by `category` (or `title`):
 
 ```ts
+import { createMemoryAdapter, VIVID_PALETTE } from '@nomideusz/svelte-calendar';
+
 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
 ];
+
+const adapter = createMemoryAdapter(events, { palette: VIVID_PALETTE });
 ```
 
-Generate a theme-harmonious palette from any accent color:
+Or generate a theme-harmonious palette from any accent color:
 
 ```ts
 import { createMemoryAdapter, generatePalette } from '@nomideusz/svelte-calendar';
@@ -515,7 +522,7 @@ const palette = generatePalette('#e11d48'); // (accent?, count = 15)
 const adapter = createMemoryAdapter(events, { palette });
 ```
 
-Related exports: `VIVID_PALETTE` (the default palette) and `extractAccent(themeString)` (the accent color of a `--dt-*` theme string).
+Related exports: `VIVID_PALETTE` (the vivid palette, the default before 1.4) and `extractAccent(themeString)` (the accent color of a `--dt-*` theme string).
 
 ### Multi-day & All-day
 
@@ -530,7 +537,7 @@ const events = [
 
 ### Custom Event Rendering
 
-The `event` snippet replaces the event *content* in every view (the interactive shell — click, keyboard, drag, selection — stays intact). The `empty` snippet replaces the empty state of the day agenda, the day on mobile, and an empty planner week:
+The `event` snippet replaces the event *content* in every view (the interactive shell for click, keyboard, drag and selection stays intact). The `empty` snippet replaces the empty state of the day agenda, the day on mobile, and an empty planner week:
 
 ```svelte
 <Calendar {adapter}>
@@ -541,11 +548,25 @@ The `event` snippet replaces the event *content* in every view (the interactive
     </div>
   {/snippet}
   {#snippet empty()}
-    <p>Nothing booked — drag on the grid to add a class.</p>
+    <p>Nothing booked. Drag on the grid to add a class.</p>
   {/snippet}
 </Calendar>
 ```
 
+## Adapters
+
+The calendar reads its events through an adapter. Which one:
+
+| Adapter | Use it when |
+|---------|-------------|
+| `createMemoryAdapter(events)` | The events are already in the page (a fixed list, your own state). Writes stay in memory. See [Quick Start](#quick-start). |
+| [`createRecurringAdapter(rules)`](#recurring-schedules) | The schedule repeats by rule: class timetables, office hours. Read-only. |
+| [`createRestAdapter(options)`](#rest-adapter) | The events live behind your own HTTP API, which also stores creates and moves. |
+| [`createJmapAdapter(client, options)`](#jmap-adapter) | The events are in a JMAP Calendars server (Fastmail, Stalwart, Cyrus). Read-only. |
+| [`createMappedAdapter(records, options)`](#mapped-adapter) | You have records from another system with their own field names: map the fields instead of writing an adapter. |
+| [`createCompositeAdapter(adapters)`](#composite-adapter) | One calendar shows several sources, e.g. a recurring timetable plus one-off events. |
+| [Custom `CalendarAdapter`](#custom-adapter) | None of the above fits: implement `fetchEvents`, plus the writes you need. |
+
 ## Recurring Schedules
 
 For fixed repeating events (class timetables, office hours):
@@ -564,7 +585,7 @@ For fixed repeating events (class timetables, office hours):
   ]);
 </script>
 
-<Calendar {adapter} />
+<Calendar {adapter} view="week-planner" />
 ```
 
 <details>
@@ -584,13 +605,13 @@ For fixed repeating events (class timetables, office hours):
 | `until` | `string` | — | Last possible occurrence `"YYYY-MM-DD"` |
 | `count` | `number` | — | Max occurrences from `startDate` (requires it). With `until`, the stricter wins. |
 | `excludeDates` | `string[]` | — | `"YYYY-MM-DD"` dates this rule skips |
-| `color` | `string` | auto | Accent color |
+| `color` | `string` | — | Bar color; else from `palette`, else ink (`--dt-event`) |
 | `subtitle` / `tags` / `category` / `location` / `resourceId` | | — | Copied to every occurrence |
 | `data` | `Record<string, unknown>` | — | Copied to every occurrence, plus `recurringId` |
 
 </details>
 
-Options (`RecurringAdapterOptions`): `mondayStart` (default `true`), `palette`, `movable` (default `false`).
+Options (`RecurringAdapterOptions`): `mondayStart` (default `true`), `palette` (colors rules without a `color`; off by default), `movable` (default `false`).
 
 Occurrences get the id `` `${rule.id}--YYYYMMDD` `` and `data.recurringId`. The adapter projects and stores nothing, so by default every occurrence carries `data.readOnly` and can't be dragged (it can still be clicked). With `movable: true` the views allow the drag and the adapter refuses the write with a read-only error, so `oneventmove` fires and the host stores the move: add the date to the rule's `excludeDates` and keep the moved occurrence with your one-off events (for example the memory side of a [composite adapter](#composite-adapter)).
 
@@ -646,7 +667,7 @@ Read-only. Expands recurrences server-side and handles all-day events, ISO-durat
 
 ## Mapped Adapter
 
-Wrap any static array of external records (class schedules, appointments, timetables) without writing a custom adapter. Supply a declarative field mapping — or a `mapEvent` function for full control — and the adapter handles parsing, colors, tags and status:
+Wrap any static array of external records (class schedules, appointments, timetables) without writing a custom adapter. Supply a declarative field mapping (or a `mapEvent` function for full control) and the adapter handles parsing, colors, tags and status:
 
 ```ts
 import { createMappedAdapter } from '@nomideusz/svelte-calendar';
@@ -667,7 +688,7 @@ const adapter = createMappedAdapter(rawClasses, {
 
 - Works without options too: it looks for common keys (`id`, `title`/`name`, `start`/`end`, `starts_at_iso`/`ends_at_iso`, `date` + `start_time`/`end_time`, `room`/`location`, `is_cancelled`). A missing end defaults to one hour after the start.
 - `start`/`end` accept ISO strings, `Date`s or millisecond timestamps. When records split date and time (`date: "2026-03-03"`, `startTime: "07:00"`), map `date` + `startTime` / `endTime`; times may be `7:00`, `07:00` or `07:00:00`.
-- `autoColor` defaults to **`true`**: source colors are ignored and events are colored from `palette` by category/title. Pass `autoColor: false` to keep the colors from your data.
+- Source colors are kept. Records without one draw in ink, unless you pass a `palette` to fill them by category/title. `autoColor: true` ignores the source colors and colors every event from `palette` (default `VIVID_PALETTE`).
 - `includeData` (default `'*'`) copies unmapped source fields into `event.data`; pass a list of keys to limit it.
 
 For full control, pass `mapEvent(raw, index)` and skip `fields`:
@@ -689,7 +710,7 @@ Mapped adapters are read-only by default (writes throw a read-only error, so dra
 
 ## Composite Adapter
 
-Merge several adapters into one — e.g. a recurring weekly schedule plus one-off events:
+Merge several adapters into one, e.g. a recurring weekly schedule plus one-off events:
 
 ```ts
 import { createMemoryAdapter, createRecurringAdapter, createCompositeAdapter } from '@nomideusz/svelte-calendar';
@@ -701,9 +722,9 @@ const adapter = createCompositeAdapter([memory, recurring]);
 ```
 
 - **Reads** query every child in parallel and merge the results (the first event with a given id wins).
-- **Creates** go to the primary child — the first by default, or `primaryIndex`.
+- **Creates** go to the primary child: the first by default, or `primaryIndex`.
 - **Updates and deletes** go to the child that returned the event. If that child can't write, the composite refuses with a read-only error (so `oneventmove` reaches the host). An id no fetch returned is offered to each writable child in turn.
-- **`onFetchError(error, adapterIndex)`** — with it, a failing child is reported to you and the others still load; without it, one failing child fails the whole load (surfacing through `onerror`).
+- **`onFetchError(error, adapterIndex)`**: with it, a failing child is reported to you and the others still load; without it, one failing child fails the whole load (surfacing through `onerror`).
 
 ```ts
 const adapter = createCompositeAdapter([recurring, memory], {
@@ -724,7 +745,7 @@ const adapter: CalendarAdapter = {
   fetchEvents: async (range: DateRange) => { /* return TimelineEvent[] */ },
   // Optional: the same answer synchronously, when the data is already in memory
   fetchEventsSync: (range) => { /* return TimelineEvent[], or undefined to go async */ },
-  // Optional writes — omit them for a read-only source
+  // Optional writes; omit them for a read-only source
   createEvent: async (event) => { /* return the created TimelineEvent with its id */ },
   updateEvent: async (id, patch) => { /* return the updated TimelineEvent */ },
   deleteEvent: async (id) => { /* void */ },
@@ -733,7 +754,7 @@ const adapter: CalendarAdapter = {
 
 `WritableCalendarAdapter` is the same interface with all three write methods required.
 
-**`fetchEventsSync`** lets the first render — including the server render — hold the events instead of a loading state. The memory, recurring and seeded adapters implement it. To seed an async adapter with events you already loaded on the server, wrap it:
+**`fetchEventsSync`** lets the first render (the server render too) hold the events instead of a loading state. The memory, recurring and seeded adapters implement it. To seed an async adapter with events you already loaded on the server, wrap it:
 
 ```ts
 import { createRestAdapter, withInitialEvents } from '@nomideusz/svelte-calendar';
@@ -750,7 +771,7 @@ The Calendar tells two refusals apart when `updateEvent` throws:
 
 | Throw | Meaning | What happens |
 |-------|---------|--------------|
-| `new CalendarReadOnlyError(message?)` | "I hold this event but can't store the change." | The block stays where it was dropped and `oneventmove` fires — the host stores the move and refreshes. |
+| `new CalendarReadOnlyError(message?)` | "I hold this event but can't store the change." | The block stays where it was dropped and `oneventmove` fires; the host stores the move and refreshes. |
 | `new EventNotFoundError(id)` | "Not my event." | A composite asks its next child; a drag ends quietly. |
 | any other error | A real failure | The block reverts and the error goes to `onerror` (or `console.warn`). |
 
@@ -758,7 +779,7 @@ An adapter without `updateEvent` counts as read-only. Plain `Error`s whose messa
 
 ## Headless API
 
-For full control over rendering, skip `<Calendar>` and drive everything from reactive state. `createCalendar()` returns computed layouts, navigation actions, drag helpers and the raw engines — zero DOM, bring your own UI. Call it during component initialisation.
+For full control over rendering, skip `<Calendar>` and drive everything from reactive state. `createCalendar()` returns computed layouts, navigation actions, drag helpers and the raw engines. Zero DOM: bring your own UI. Call it during component initialisation.
 
 ```svelte
 <script lang="ts">
@@ -793,7 +814,7 @@ Options (`HeadlessCalendarOptions`) mirror the Calendar props: `adapter`, `view`
 
 `cal.days` gives flat `HeadlessDay[]` with events attached; `cal.weeks` groups them into periods (`HeadlessWeek`). `cal.todayQueue` returns `{ past, current, upcoming }` for today (`TodayQueue`), updated every second. `cal.hours` yields the visible hour numbers. Drag is fully wired: `beginDragMove`, `beginDragCreate`, `updateDrag`, `commitDrag` (validates like the Calendar), `cancelDrag`, plus `isDragging` / `dragPayload` / `dragMode`. `headerContext` / `navigationContext` match the Calendar's `header` / `navigation` snippet contexts. Raw engines (`store`, `viewState`, `selection`, `dragState`, `clock`) are exposed for advanced cases.
 
-The engine factories are exported individually — `createEventStore(adapter)`, `createViewState(options)`, `createSelection()`, `createDragState()`, `createClock(timezone?)` — if you want to compose your own calendar loop (types: `EventStore`, `ViewState`, `ViewStateOptions`, `CalendarSelection`, `DragState`, `DragMode`, `DragPayload`, `CalendarViewId`, `BuiltInViewId`, `ViewMode`).
+The engine factories are exported individually (`createEventStore(adapter)`, `createViewState(options)`, `createSelection()`, `createDragState()`, `createClock(timezone?)`) if you want to compose your own calendar loop (types: `EventStore`, `ViewState`, `ViewStateOptions`, `CalendarSelection`, `DragState`, `DragMode`, `DragPayload`, `CalendarViewId`, `BuiltInViewId`, `ViewMode`).
 
 ### createAgenda
 
@@ -821,7 +842,7 @@ It returns `dayEvents`, `allDay`, `past`, `current`, `upcoming`, `upcomingSlots`
 
 ### createRangeAgenda
 
-A window of days with events grouped per day — no clock, drag or selection. Built for read-only schedule surfaces (public timetables, embeds):
+A window of days with events grouped per day; no clock, drag or selection. Built for read-only schedule surfaces (public timetables, embeds):
 
 ```svelte
 <script lang="ts">
@@ -845,7 +866,7 @@ Options (`RangeAgendaOptions`): `adapter` (or a getter), `days` (default 7), `in
 
 ## Localization (i18n)
 
-The `locale` prop controls date/time formatting (BCP 47). Without it, the global default locale is used — `'en-US'` unless you call `setDefaultLocale()`:
+The `locale` prop controls date/time formatting (BCP 47). Without it, the global default locale is used: `'en-US'` unless you call `setDefaultLocale()`:
 
 ```svelte
 <Calendar {adapter} locale="de-DE" />
@@ -853,7 +874,7 @@ The `locale` prop controls date/time formatting (BCP 47). Without it, the global
 
 `setDefaultLocale('de-DE')` sets it for every calendar and formatter; `getDefaultLocale()` reads it back; `is24HourLocale(tag?)` tells you how times will format. An RTL locale (`ar-SA`, `he-IL`, …) sets `dir="rtl"` where the browser reports the locale's text direction (`Intl.Locale` text info); pass `dir` to be explicit.
 
-Override UI labels per calendar with the `labels` prop — it's reactive (swap it to switch language live) and instance-scoped (two calendars on one page can carry different languages):
+Override UI labels per calendar with the `labels` prop. It's reactive (swap it to switch language live) and instance-scoped (two calendars on one page can carry different languages):
 
 ```svelte
 <Calendar {adapter} locale="de-DE" labels={{
@@ -871,7 +892,7 @@ import { setLabels } from '@nomideusz/svelte-calendar';
 setLabels({ today: 'Heute', day: 'Tag', week: 'Woche' });
 ```
 
-Both take a `Partial<CalendarLabels>` — that is the supported input: pass the keys you translate, and keys added in later minor releases fall back to English. The `labels` prop merges over the global set. `resetLabels()` restores English (`defaultLabels` exports it; `getLabels()` reads the active set). Global `setLabels()` calls after mount don't re-render mounted calendars — use the `labels` prop to switch language live. Standalone primitives (`DayHeader`, `EventBlock`, …) and the format helpers read the global set.
+Both take a `Partial<CalendarLabels>`, and that is the supported input: pass the keys you translate, and keys added in later minor releases fall back to English. The `labels` prop merges over the global set. `resetLabels()` restores English (`defaultLabels` exports it; `getLabels()` reads the active set). Global `setLabels()` calls after mount don't re-render mounted calendars; use the `labels` prop to switch language live. Standalone primitives (`DayHeader`, `EventBlock`, …) and the format helpers read the global set.
 
 <details>
 <summary>All label keys</summary>
@@ -911,7 +932,7 @@ Both take a `Partial<CalendarLabels>` — that is the supported input: pass the
 
 ## Timezone Support
 
-Render the whole calendar in any IANA timezone — events, the now-indicator and day boundaries all shift:
+Render the whole calendar in any IANA timezone: events, the now-indicator and day boundaries all shift:
 
 ```svelte
 <Calendar {adapter} timezone="Europe/Warsaw" />
@@ -919,7 +940,7 @@ Render the whole calendar in any IANA timezone — events, the now-indicator and
 
 - `initialDate` and `currentDate` are instants, read in that zone.
 - `oneventcreate`, `oneventmove` and `onexternaldrop` receive real instants.
-- `ondatechange` and `ondayclick` receive instants too — the start of that day in the zone — so feeding one back is stable: `currentDate={date} ondatechange={(d) => (date = d)}`. To read the date, format it in the zone:
+- `ondatechange` and `ondayclick` receive instants too (the start of that day in the zone), so feeding one back is stable: `currentDate={date} ondatechange={(d) => (date = d)}`. To read the date, format it in the zone:
 
   ```ts
   import { formatInTimeZone } from '@nomideusz/svelte-calendar';
@@ -970,20 +991,20 @@ Small helpers used by the built-in views, exported for custom rendering. Formatt
 | `weekdayShort` / `weekdayLong` / `monthShort` / `monthLong` | Name parts of a timestamp |
 | `sod(ms)` | Start of that day (local midnight) |
 | `startOfWeek(ms, mondayStart = true)` | Start-of-week timestamp |
-| `addDaysMs(ms, n)` / `diffDays(a, b)` | Add / count **calendar** days — DST-safe (a DST day is 23 or 25 hours, so don't add `n * 86_400_000`) |
+| `addDaysMs(ms, n)` / `diffDays(a, b)` | Add / count **calendar** days, DST-safe (a DST day is 23 or 25 hours, so don't add `n * 86_400_000`) |
 | `isAllDay(ev)` / `isMultiDay(ev)` | Event classification |
 | `segmentForDay(ev, dayMs)` | The slice of a multi-day event on one day (`DaySegment`), or `null` |
 | `createClock(timezone?)` | Reactive clock: `tick` (ms, every second), `today`, `hm`, `s`, `fractionalHour`, `destroy()` |
-| `textWidth(text, font)` / `textHeight(text, font, width, lineHeight)` / `lineCount(text, font, width, options?)` / `fits(text, font, width, lines = 1)` | Text measurement via [pretext](https://github.com/chenglou/pretext) — before render, no layout thrash. `options` is `TextLayoutOptions` (`whiteSpace`, `wordBreak`, `letterSpacing`). Browser-only. |
+| `textWidth(text, font)` / `textHeight(text, font, width, lineHeight)` / `lineCount(text, font, width, options?)` / `fits(text, font, width, lines = 1)` | Text measurement via [pretext](https://github.com/chenglou/pretext), before render, no layout thrash. `options` is `TextLayoutOptions` (`whiteSpace`, `wordBreak`, `letterSpacing`). Browser-only. |
 | `pickFit(candidates, font, width, lines = 1)` | The longest candidate that fits |
 | `fitLabel(candidates, lines = 1)` | Attachment: `<span {@attach fitLabel([ev.title, ev.short])}>` keeps the longest label that fits its box, re-fitting on resize |
 | `fontOf(el)` | An element's computed font as a canvas font string |
 | `fitParts(parts, budget, measure?)` | Which parts of a dense chip fit, along either axis → `Record<key, boolean>`. Each `ChipPart` is `{ key, text, font }` to measure or `{ key, size }` to state its cost, plus `priority` (`0` is an anchor and never drops; higher numbers drop first) and `extra` (a gap or icon). The first optional part that doesn't fit ends the list, so a chip never keeps a later detail after dropping an earlier one. A budget of `0` (server-rendered, not yet measured) leaves only the anchors. |
-| `typeset(text)` / `breakLines(text, font, width)` | Knuth-Plass paragraph breaking over the text's own spaces and soft hyphens. `<p {@attach typeset(text)}>` sets justified lines, re-done on resize; if the browser disagrees with the measure, the plain text goes back. Progressive — SSR text stays. |
+| `typeset(text)` / `breakLines(text, font, width)` | Knuth-Plass paragraph breaking over the text's own spaces and soft hyphens. `<p {@attach typeset(text)}>` sets justified lines, re-done on resize; if the browser disagrees with the measure, the plain text goes back. Progressive: SSR text stays. |
 
 ## Embeddable Widget
 
-Drop into any HTML page — no build tools needed. Registers a `<day-calendar>` custom element:
+Drop into any HTML page, no build tools needed. Registers a `<day-calendar>` custom element:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@nomideusz/svelte-calendar/widget/widget.js"></script>
@@ -1024,47 +1045,78 @@ Each event in `api` responses and `events` needs `start` and `end` as date strin
 
 ## All Props
 
-<details>
-<summary>Full Calendar props reference (<code>CalendarProps</code>)</summary>
+Every `<Calendar>` prop (`CalendarProps`), grouped by what it controls.
+
+### Data and editing
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `adapter` | `CalendarAdapter` | *required* | Data source (memory, recurring, mapped, composite, REST, JMAP, or custom) |
-| `views` | `readonly CalendarView[]` | `defaultViews` | View registry (the 8 built-ins). Spread `defaultViews` to add your own. |
-| `view` | `CalendarViewId` | first registered (`'day-planner'`) | Active view ID. Reactive. |
-| `theme` | `string` | `auto` | CSS theme string of `--dt-*` properties. `auto` probes the host page. |
-| `autoTheme` | `AutoThemeOptions \| false` | `undefined` (probe) | Fine-tune auto-detection: `{ mode, accent, font }`. `false` disables probing. |
-| `mobile` | `'auto' \| boolean` | `'auto'` | `'auto'` switches to mobile views below a 768px container width |
-| `height` | `number \| 'auto'` | `600` | Height in px, or `'auto'` to grow with content (ideal for Agenda views) |
-| `borderRadius` | `number` | `12` | Border radius in px. `0` for none. |
-| `locale` | `string` | global default (`'en-US'`) | BCP 47 locale tag; see `setDefaultLocale` |
-| `labels` | `Partial<CalendarLabels>` | — | Per-instance UI labels, merged over the global set. Reactive. |
-| `dir` | `'ltr' \| 'rtl' \| 'auto'` | from `locale` | Text direction |
-| `mondayStart` | `boolean` | `true` | Start weeks on Monday |
 | `readOnly` | `boolean` | `false` | Disable drag, resize, click-to-create and external drops |
-| `visibleHours` | `[number, number]` | — | Crop the grid to `[startHour, endHour)` |
+| `snapInterval` | `number` | `15` | Drag snap in minutes |
+| `minDuration` | `number` | — | Minimum duration in minutes; clamps creates and resizes |
+| `maxDuration` | `number` | — | Maximum duration in minutes; clamps creates and resizes |
+| `blockedSlots` | `BlockedSlot[]` | — | `{ day?, start, end, label? }` hour ranges that can't be booked (hatched in planner views) |
+| `disabledDates` | `Date[]` | — | Dates that refuse creates/moves; existing events stay visible and clickable |
+
+### View and navigation
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `view` | `CalendarViewId` | first registered (`'day-planner'`) | Active view ID. Reactive. |
+| `views` | `readonly CalendarView[]` | `defaultViews` | View registry (the eight built-ins). Spread `defaultViews` to add your own. |
 | `initialDate` | `Date` | today | Date to focus at mount (an instant; read in `timezone`) |
 | `currentDate` | `Date` | — | Controlled focus date (an instant; read in `timezone`) |
-| `timezone` | `string` | viewer's zone | IANA zone to render in. Read at mount. |
-| `snapInterval` | `number` | `15` | Drag snap in minutes |
-| `minColumnWidth` | `number` | `110` | Minimum day-column width (px) in planner views; below the total the grid scrolls horizontally |
 | `days` | `number` | `7` | Days shown in week mode (e.g. `3` for a rolling 3-day view) |
-| `hideDays` | `number[]` | — | ISO weekdays to hide (1=Mon … 7=Sun), e.g. `[6, 7]` |
+| `mobile` | `'auto' \| boolean` | `'auto'` | `'auto'` switches to mobile views below a 768px container width |
 | `showModePills` | `boolean` | `true` | Show the Day/Week/Month pills and the view-type pills |
 | `showNavigation` | `boolean` | `true` | Show prev/next/today |
+
+### Display
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `height` | `number \| 'auto'` | `600` | Height in px, or `'auto'` to grow with content (ideal for Agenda views) |
+| `visibleHours` | `[number, number]` | — | Crop the grid to `[startHour, endHour)` |
+| `hideDays` | `number[]` | — | ISO weekdays to hide (1=Mon … 7=Sun), e.g. `[6, 7]` |
+| `mondayStart` | `boolean` | `true` | Start weeks on Monday |
 | `showDates` | `boolean` | `true` | Show date numbers and the date label. `false` = day names only (templates, recurring schedules) |
 | `equalDays` | `boolean` | `false` | Treat all days equally (no past-day dimming/collapsing) |
-| `blockedSlots` | `BlockedSlot[]` | — | `{ day?, start, end, label? }` hour ranges that can't be booked (hatched in planner views) |
-| `disabledDates` | `Date[]` | — | Dates that refuse creates/moves; existing events stay visible and clickable |
-| `minDuration` | `number` | — | Minimum duration in minutes; clamps creates and resizes |
-| `maxDuration` | `number` | — | Maximum duration in minutes; clamps creates and resizes |
 | `compact` | `boolean` | `false` | Minimal text rows in Agenda views (dot + time + title) |
 | `columns` | `boolean` | `false` | Timetable layout: `week-agenda` days side by side on desktop. Pairs with `equalDays`; overrides `compact` |
+| `minColumnWidth` | `number` | `110` | Minimum day-column width (px) in planner views; below the total the grid scrolls horizontally |
+
+### Theming
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `string` | `auto` | CSS theme string of `--dt-*` properties. `auto` probes the host page. |
+| `autoTheme` | `AutoThemeOptions \| false` | `undefined` (probe) | Fine-tune auto-detection: `{ mode, accent, font }`. `false` disables probing. |
+| `borderRadius` | `number` | `0` | Corner radius in px (square by default) |
+
+### Locale and timezone
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `locale` | `string` | global default (`'en-US'`) | BCP 47 locale tag; see `setDefaultLocale` |
+| `labels` | `Partial<CalendarLabels>` | — | Per-instance UI labels, merged over the global set. Reactive. |
+| `dir` | `'ltr' \| 'rtl' \| 'auto'` | from `locale` | Text direction |
+| `timezone` | `string` | viewer's zone | IANA zone to render in. Read at mount. |
+
+### Snippets
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
 | `event` | `Snippet<[TimelineEvent]>` | — | Custom event content |
 | `empty` | `Snippet` | — | Empty state for the day agenda, mobile day and an empty planner week |
 | `dayHeader` | `Snippet<[{ date, isToday, dayName }]>` | — | Custom day header |
 | `header` | `Snippet<[HeaderContext]>` | — | Replace the whole header (`dateLabel`, `mode`, `modes`, `switchMode`, `prev`, `next`, `goToday`, `isViewOnToday`, `focusDate`) |
 | `navigation` | `Snippet<[NavigationContext]>` | — | Replace prev/next/today (`prev`, `next`, `goToday`, `isViewOnToday`, `focusDate`, `mode`) |
+
+### Callbacks
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
 | `oneventclick` | `(event, anchor?: DOMRect) => void` | — | Event clicked (and selected) |
 | `oneventcreate` | `(range: { start, end }) => void` | — | A validated new range (real instants) |
 | `oneventmove` | `(event, start, end) => void` | — | Drag/resize stored, or refused read-only (real instants) |
@@ -1075,8 +1127,6 @@ Each event in `api` responses and `events` needs `start` and `end` as date strin
 | `oneventhover` | `(event) => void` | — | Pointer enters an event |
 | `onerror` | `(error: Error) => void` | — | Load and commit failures |
 
-</details>
-
 ## Versioning
 
 The package follows [semver](https://semver.org/) from 1.0:
@@ -1084,7 +1134,7 @@ The package follows [semver](https://semver.org/) from 1.0:
 - The public API is exactly what the `.` and `./widget` entry points export. Deep imports into `dist/` are not supported.
 - `TimelineEvent`, `CalendarAdapter` and `DateRange` are stable shapes: fields may be added in minor releases, never renamed, removed or given new meaning outside a major.
 - The `--dt-*` theme tokens are part of the contract, as are the `<day-calendar>` attributes.
-- `CalendarLabels` gains keys in minor releases — pass a `Partial` (see [Localization](#localization-i18n)).
+- `CalendarLabels` gains keys in minor releases, so pass a `Partial` (see [Localization](#localization-i18n)).
 
 ## Development