@nomideusz/svelte-calendar 1.3.0 → 1.4.1

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 to move, resize and create events, 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.
 
@@ -28,30 +28,43 @@ Requirements:
   const today = new Date();
   const at = (hour) => new Date(today.getFullYear(), today.getMonth(), today.getDate(), hour);
 
-  const adapter = createMemoryAdapter([
+  let events = $state([
     { id: '1', title: 'Team Sync', start: at(9),  end: at(10) },
     { id: '2', title: 'Lunch',     start: at(12), end: at(13) },
   ]);
+  // A new adapter whenever the events change; the calendar reloads without blanking
+  const adapter = $derived(createMemoryAdapter(events));
+
+  // Drag on empty time (or press Enter on a day column) to create
+  function create({ start, end }) {
+    events = [...events, { id: crypto.randomUUID(), title: 'New event', start, end }];
+  }
+  // Drag an event to move it, or its edge to resize it
+  function move(event, start, end) {
+    events = events.map((e) => (e.id === event.id ? { ...e, start, end } : e));
+  }
 </script>
 
-<Calendar {adapter} view="week-planner" />
+<Calendar {adapter} view="week-planner" oneventcreate={create} oneventmove={move} />
 ```
 
-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 a working, editable calendar. The calendar stores nothing on create: without `oneventcreate`, dragging on empty time does nothing. Moves and resizes write to the adapter by themselves, and `oneventmove` keeps your own data in step, so a move survives the next new adapter. 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:
+Without `view` the calendar opens on `day-planner`, the first registered view. The Quick Start, the demo, the widget and `createCalendar` open on `week-planner`, so pass `view="week-planner"` for the week grid.
+
+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. The default when `view` is unset. |
 | `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 +81,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 +94,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 +119,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` | Always `null`: the view fills its container, sized by the Calendar's own [`height`](#display) (default `600`) |
 | `mode` | `'day' \| 'week' \| 'month'` | |
 | `mondayStart` | `boolean` | |
 | `locale` | `string \| undefined` | |
@@ -143,14 +156,14 @@ 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 -->
+<!-- Auto-detect (default): switches at a 768px container width -->
 <Calendar {adapter} view="week-planner" />
 
 <!-- Force mobile layout -->
@@ -160,10 +173,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 +198,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 +210,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 +259,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 +333,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, which suits holidays or fully booked days. In the planner, agenda and mobile views their existing events stay visible and clickable; `month-grid` dims a disabled day, and its chips ignore clicks.
 
 Custom day headers and hover previews:
 
@@ -358,7 +371,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 +383,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 +403,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 +433,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 +445,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 +470,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 +495,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 +508,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 +535,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 +550,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 +561,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):
@@ -584,13 +618,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 +680,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 +701,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 +723,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 +735,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 +758,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 +767,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 +784,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 +792,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 +827,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 +855,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 +879,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 +887,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 +905,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 +945,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 +953,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 +1004,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 +1058,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 (dimmed and inert in `month-grid`) |
+
+### 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,7 +1140,15 @@ 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>
+## Troubleshooting
+
+- **Dragging on empty time does nothing.** Creating needs an `oneventcreate` handler (and no `readOnly`); see the [Quick Start](#quick-start).
+- **A created event doesn't appear.** The calendar stores nothing on create: add the event to your data and hand the Calendar a new adapter (`$derived(createMemoryAdapter(events))`).
+- **Moved events jump back after the next change.** A new adapter is built from your array, so write each move into it in `oneventmove`.
+- **The `auto` theme picked the wrong colours.** It probes the host page around the calendar, and probes again when `<html>`/`<body>` change class, style or `data-theme`, when the system scheme flips and when a background transition ends. Steer it with [`autoTheme`](#smart-auto-theme), or set `theme` to a preset or your own tokens to opt out.
+- **Events are all one colour.** Since 1.4 events without a `color` draw in ink; give the adapter a [`palette`](#event-colors).
+- **The calendar stops at 600px.** That's the default `height`; pass a number, or `'auto'` to grow with the content.
+- **The phone layout shows on a wide page (or the desktop one in a narrow column).** The switch reads the calendar's container, not the window; force it with `mobile={false}` or `mobile={true}`.
 
 ## Versioning
 
@@ -1084,7 +1157,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