@nomideusz/svelte-calendar 0.6.0 → 0.6.4

package/README.md

@@ -160,6 +160,37 @@ Custom day headers and hover previews:
 </Calendar>
 ```
 
+Replace the built-in navigation or the entire header chrome with your own controls:
+
+```svelte
+<Calendar {adapter}>
+  {#snippet navigation({ prev, next, goToday, isViewOnToday, mode })}
+    <button onclick={prev}>‹</button>
+    {#if !isViewOnToday}<button onclick={goToday}>Today</button>{/if}
+    <button onclick={next}>›</button>
+  {/snippet}
+</Calendar>
+
+<Calendar {adapter}>
+  {#snippet header({ dateLabel, mode, switchMode, prev, next, goToday })}
+    <nav class="my-toolbar">
+      <h2>{dateLabel}</h2>
+      <button class:active={mode === 'day'} onclick={() => switchMode('day')}>Day</button>
+      <button class:active={mode === 'week'} onclick={() => switchMode('week')}>Week</button>
+      <button onclick={prev}>←</button>
+      <button onclick={goToday}>Today</button>
+      <button onclick={next}>→</button>
+    </nav>
+  {/snippet}
+</Calendar>
+```
+
+Let agenda content determine height instead of forcing a fixed box — useful when embedding inside a scrolling page:
+
+```svelte
+<Calendar {adapter} view="week-agenda" height="auto" compact />
+```
+
 ## Themes
 
 Three built-in presets:
@@ -288,8 +319,14 @@ const custom = `${neutral}; --dt-accent: #e11d48;`;
 | `subtitle` | `string?` | Secondary text below the title |
 | `tags` | `string[]?` | Small accent-colored pills |
 | `allDay` | `boolean?` | Render as an all-day event |
+| `location` | `string?` | Room, venue, or address (universal across domains) |
+| `status` | `EventStatus?` | `'confirmed'` (default), `'cancelled'`, `'tentative'`, `'full'`, `'limited'` |
+| `externalId` | `string?` | ID from an upstream system (booking platform, CRM, LMS) |
+| `resourceId` | `string?` | Resource this event belongs to (room, instructor, court) for multi-resource views |
 | `data` | `Record?` | Arbitrary payload for your app |
 
+Cancelled events render with a strikethrough on the grid but remain visible so the slot isn't confused for free time.
+
 ### Auto-Coloring
 
 Omit `color` and events are auto-assigned a vivid palette color, grouped by `category` (or `title`):
@@ -400,6 +437,74 @@ const adapter = createRestAdapter({
 
 The adapter calls `GET /events?start=...&end=...`, `POST /events`, `PATCH /events/:id`, and `DELETE /events/:id`.
 
+## Mapped Adapter
+
+Wrap any static array of external records (yoga classes, gym 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, color assignment, tag extraction, and status coercion:
+
+```ts
+import { createMappedAdapter } from '@nomideusz/svelte-calendar';
+
+const adapter = createMappedAdapter(rawClasses, {
+  fields: {
+    title: 'class_name',
+    start: 'starts_at_iso',
+    end: 'ends_at_iso',
+    subtitle: 'teacher',
+    location: 'room',
+    color: 'color',
+    externalId: 'reference_id',
+    status: 'is_cancelled',           // boolean → 'cancelled' / 'confirmed'
+    tags: ['is_free', 'is_bookable_online'],
+  },
+});
+```
+
+`start`/`end` accept ISO strings, `Date` objects, or Unix timestamps. When source records split date and time (`date: "2026-03-03"`, `startTime: "07:00"`), use `date` + `startTime` / `endTime` instead.
+
+For full control, pass a `mapEvent` transform and skip `fields` entirely:
+
+```ts
+const adapter = createMappedAdapter(rawData, {
+  mapEvent: (raw) => ({
+    id: raw.uid,
+    title: raw.procedure_name,
+    start: new Date(raw.scheduled_at),
+    end: new Date(raw.scheduled_end),
+    location: raw.office,
+    resourceId: raw.doctor_id,
+  }),
+});
+```
+
+Mapped adapters are read-only by default. Set `readOnly: false` and supply `onMutate: { onCreate, onUpdate, onDelete }` handlers to enable writes.
+
+## Composite Adapter
+
+Merge multiple adapters into one — e.g. a recurring weekly schedule combined with one-off events:
+
+```ts
+import {
+  Calendar,
+  createMemoryAdapter,
+  createRecurringAdapter,
+  createCompositeAdapter,
+} from '@nomideusz/svelte-calendar';
+
+const memory    = createMemoryAdapter(oneOffEvents);
+const recurring = createRecurringAdapter(weeklySchedule);
+
+const adapter = createCompositeAdapter([memory, recurring]);
+// Reads from both; writes go to memory (the primary — first adapter by default)
+```
+
+Change which adapter handles mutations with `primaryIndex`:
+
+```ts
+const adapter = createCompositeAdapter([recurring, memory], { primaryIndex: 1 });
+```
+
+Updates and deletes fall through each adapter in order — handy when the recurring adapter generates occurrences that the primary memory adapter doesn't know about.
+
 ## Custom Adapter
 
 Implement the `CalendarAdapter` interface to connect any data source:
@@ -415,6 +520,61 @@ const adapter: CalendarAdapter = {
 };
 ```
 
+## Headless API
+
+For full control over rendering, skip the `<Calendar>` component and drive everything from reactive state. `createCalendar()` returns computed layouts, navigation actions, drag helpers, and raw engines — zero DOM, bring your own UI:
+
+```svelte
+<script lang="ts">
+  import { createCalendar, createMemoryAdapter } from '@nomideusz/svelte-calendar';
+
+  const adapter = createMemoryAdapter([/* ... */]);
+  const cal = createCalendar({ adapter, view: 'week-planner' });
+</script>
+
+<header>
+  <button onclick={cal.prev}>←</button>
+  <span>{cal.headerContext.dateLabel}</span>
+  <button onclick={cal.next}>→</button>
+  <button onclick={cal.goToday}>Today</button>
+</header>
+
+{#each cal.weeks as week}
+  <div class="week-row">
+    {#each week.days as day}
+      <div class:today={day.isToday} class:past={day.isPast}>
+        <h3>{day.dayNum}</h3>
+        {#each day.events as ev}
+          <div style:background={ev.color}>{ev.title}</div>
+        {/each}
+      </div>
+    {/each}
+  </div>
+{/each}
+```
+
+`cal.days` gives flat `HeadlessDay[]` with events attached; `cal.weeks` groups them into periods. `cal.todayQueue` returns `{ past, current, upcoming }` for today — updates every second via the built-in clock. `cal.hours` yields the visible hour numbers (cropped by `visibleHours`). Drag support is fully wired: `beginDragMove`, `beginDragCreate`, `updateDrag`, `commitDrag`, `cancelDrag`, plus `isDragging` / `dragPayload` / `dragMode` signals. Raw engines (`store`, `viewState`, `selection`, `dragState`, `clock`) are exposed for advanced cases.
+
+For a simpler day-only list view, use `createAgenda()`:
+
+```svelte
+<script lang="ts">
+  import { createAgenda, createMemoryAdapter } from '@nomideusz/svelte-calendar';
+
+  const adapter = createMemoryAdapter([/* ... */]);
+  const agenda = createAgenda({ adapter });
+</script>
+
+<h2>{agenda.dateLabel}</h2>
+{#each agenda.upcoming as ev}
+  <div>
+    <time>{agenda.fmtTime(ev.start)}</time>
+    <span>{ev.title}</span>
+    <small>{agenda.eta(ev)}</small>
+  </div>
+{/each}
+```
+
 ## Localization (i18n)
 
 The `locale` prop controls date/time formatting (BCP 47):
@@ -489,7 +649,7 @@ const now = nowInZone('Asia/Tokyo');
 
 ## Embeddable Widget
 
-Drop into any HTML page — no build tools needed:
+Drop into any HTML page — no build tools needed. Registers a `<day-calendar>` custom element:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@nomideusz/svelte-calendar/widget/widget.js"></script>
@@ -497,10 +657,25 @@ Drop into any HTML page — no build tools needed:
 <day-calendar
   api="https://myschool.com/api/events"
   theme="neutral"
+  view="week-planner"
   height="600"
+  locale="en-US"
+  mondaystart="true"
 ></day-calendar>
 ```
 
+| Attribute | Description |
+|-----------|-------------|
+| `api` | REST endpoint — fetched as `GET {api}?start=...&end=...` |
+| `events` | Inline JSON array of events (alternative to `api`) |
+| `view` | Initial view ID (`week-planner`, `day-agenda`, …) |
+| `theme` | `auto`, `neutral`, or `midnight` |
+| `height` | Calendar height in px |
+| `locale` | BCP 47 locale tag |
+| `dir` | `ltr` or `rtl` |
+| `mondaystart` | `"true"` / `"false"` — week-start day |
+| `headers` | JSON string of extra headers to send with `api` requests |
+
 ## All Props
 
 <details>
@@ -508,13 +683,13 @@ Drop into any HTML page — no build tools needed:
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `adapter` | `CalendarAdapter` | *required* | Data layer (memory, recurring, REST, or custom) |
-| `views` | `CalendarView[]` | all 4 built-in | Registered view components |
+| `adapter` | `CalendarAdapter` | *required* | Data layer (memory, recurring, mapped, composite, REST, or custom) |
+| `views` | `CalendarView[]` | 6 built-in | Registered view components (4 desktop + 2 mobile variants) |
 | `view` | `string` | first view | Active view ID |
 | `theme` | `string` | `auto` | CSS theme string (`--dt-*` custom properties). `auto` probes the host page and generates matching tokens. |
 | `autoTheme` | `AutoThemeOptions \| false` | `{}` | Fine-tune auto-detection: `{ mode, accent, font }`. Set `false` to disable probing. |
-| `mobile` | `'auto' \| boolean` | `'auto'` | Mobile mode. `'auto'` detects via `matchMedia(<768px)`. Remaps Planner→Mobile views. |
-| `height` | `number` | `600` | Total height in pixels |
+| `mobile` | `'auto' \| boolean` | `'auto'` | Mobile mode. `'auto'` detects via container width (<768px). Remaps Planner→Mobile views. |
+| `height` | `number \| 'auto'` | `600` | Height in pixels, or `'auto'` to let content grow naturally (ideal for Agenda views) |
 | `borderRadius` | `number` | `12` | Border radius in pixels. Set to `0` for no rounding. |
 | `locale` | `string` | `'en-US'` | BCP 47 locale tag |
 | `dir` | `'ltr' \| 'rtl' \| 'auto'` | — | Text direction |
@@ -534,7 +709,10 @@ Drop into any HTML page — no build tools needed:
 | `disabledDates` | `Date[]` | — | Dates that are fully disabled (dimmed, no interaction) |
 | `minDuration` | `number` | — | Minimum event duration in minutes (enforced on create & resize) |
 | `maxDuration` | `number` | — | Maximum event duration in minutes (enforced on create & resize) |
+| `compact` | `boolean` | `false` | Minimal text-row rendering in Agenda views (dot + time + title) |
 | `dayHeader` | `Snippet<[{ date, isToday, dayName }]>` | — | Custom day header snippet for planner/agenda views |
+| `header` | `Snippet<[HeaderContext]>` | — | Replace entire header chrome (date label + mode pills + nav) |
+| `navigation` | `Snippet<[NavigationContext]>` | — | Replace just the prev/next/today controls |
 | `oneventclick` | `(event) => void` | — | Event clicked |
 | `oneventcreate` | `(range) => void` | — | New time range selected |
 | `oneventmove` | `(event, start, end) => void` | — | Event dragged to new time |

package/dist/adapters/composite.d.ts

@@ -0,0 +1,15 @@
+import type { CalendarAdapter } from './types.js';
+export interface CompositeAdapterOptions {
+    /**
+     * Index of the adapter that handles mutations (create/update/delete).
+     * Defaults to `0` (the first adapter).
+     */
+    primaryIndex?: number;
+}
+/**
+ * Create a CalendarAdapter that merges events from multiple child adapters.
+ *
+ * @param adapters  Array of child adapters to merge.
+ * @param options   Optional configuration.
+ */
+export declare function createCompositeAdapter(adapters: CalendarAdapter[], options?: CompositeAdapterOptions): CalendarAdapter;

package/dist/adapters/composite.js

@@ -0,0 +1,65 @@
+/**
+ * Create a CalendarAdapter that merges events from multiple child adapters.
+ *
+ * @param adapters  Array of child adapters to merge.
+ * @param options   Optional configuration.
+ */
+export function createCompositeAdapter(adapters, options = {}) {
+    if (adapters.length === 0) {
+        throw new Error('createCompositeAdapter requires at least one adapter');
+    }
+    const { primaryIndex = 0 } = options;
+    if (primaryIndex < 0 || primaryIndex >= adapters.length) {
+        throw new Error(`primaryIndex ${primaryIndex} is out of range [0, ${adapters.length - 1}]`);
+    }
+    const primary = adapters[primaryIndex];
+    return {
+        async fetchEvents(range) {
+            const results = await Promise.all(adapters.map((a) => a.fetchEvents(range)));
+            // Flatten and deduplicate by id (first occurrence wins)
+            const seen = new Set();
+            const merged = [];
+            for (const batch of results) {
+                for (const ev of batch) {
+                    if (!seen.has(ev.id)) {
+                        seen.add(ev.id);
+                        merged.push(ev);
+                    }
+                }
+            }
+            return merged;
+        },
+        // Create always goes to primary
+        ...(primary.createEvent ? { createEvent: (event) => primary.createEvent(event) } : {}),
+        // Update/delete: try each adapter that supports the operation.
+        // This handles the case where a recurring adapter generates events
+        // that the primary (memory) adapter doesn't know about.
+        async updateEvent(id, patch) {
+            for (const adapter of adapters) {
+                if (!adapter.updateEvent)
+                    continue;
+                try {
+                    return await adapter.updateEvent(id, patch);
+                }
+                catch {
+                    // Event not in this adapter, try next
+                }
+            }
+            throw new Error(`Event not found in any adapter: ${id}`);
+        },
+        async deleteEvent(id) {
+            for (const adapter of adapters) {
+                if (!adapter.deleteEvent)
+                    continue;
+                try {
+                    await adapter.deleteEvent(id);
+                    return;
+                }
+                catch {
+                    // Event not in this adapter, try next
+                }
+            }
+            throw new Error(`Event not found in any adapter: ${id}`);
+        },
+    };
+}

package/dist/adapters/index.d.ts

@@ -1,7 +1,11 @@
-export type { CalendarAdapter, DateRange } from './types.js';
+export type { CalendarAdapter, WritableCalendarAdapter, DateRange } from './types.js';
 export { createMemoryAdapter } from './memory.js';
 export type { MemoryAdapterOptions } from './memory.js';
 export { createRestAdapter } from './rest.js';
 export type { RestAdapterOptions } from './rest.js';
 export { createRecurringAdapter } from './recurring.js';
 export type { RecurringEvent, RecurringAdapterOptions } from './recurring.js';
+export { createMappedAdapter } from './mapped.js';
+export type { FieldMapping, MappedAdapterOptions, MutationHandler } from './mapped.js';
+export { createCompositeAdapter } from './composite.js';
+export type { CompositeAdapterOptions } from './composite.js';

package/dist/adapters/index.js

@@ -1,3 +1,5 @@
 export { createMemoryAdapter } from './memory.js';
 export { createRestAdapter } from './rest.js';
 export { createRecurringAdapter } from './recurring.js';
+export { createMappedAdapter } from './mapped.js';
+export { createCompositeAdapter } from './composite.js';

package/dist/adapters/mapped.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Mapped adapter — universal adapter factory for external schedule data.
+ *
+ * Takes any array of external records (yoga classes, gym schedules,
+ * medical appointments, school timetables, etc.) and a mapping
+ * configuration that describes how to extract `TimelineEvent` fields
+ * from each record.
+ *
+ * Two usage modes:
+ *   1. **Field mapping** — declarative config mapping field names:
+ *        createMappedAdapter(rawEvents, {
+ *          fields: { title: 'class_name', start: 'starts_at_iso', ... }
+ *        });
+ *
+ *   2. **Custom mapper** — full control via a transform function:
+ *        createMappedAdapter(rawEvents, {
+ *          mapEvent: (raw, i) => ({ id: raw.ref, title: raw.name, ... })
+ *        });
+ *
+ * The adapter is read-only by default (no create/update/delete).
+ * Pass `readOnly: false` and supply mutation callbacks to enable writes.
+ */
+import type { TimelineEvent } from '../core/types.js';
+import type { CalendarAdapter } from './types.js';
+/**
+ * Declarative field mapping from external record keys to TimelineEvent fields.
+ *
+ * Each value is a key name (string) of the source object whose value
+ * will be used for the corresponding TimelineEvent field.
+ *
+ * For `start` and `end`, the source value can be:
+ *   - an ISO 8601 string  ("2026-03-03T07:00:00+01:00")
+ *   - a Date object
+ *   - a Unix timestamp (number, ms)
+ *   - a pair of date + time strings when using `startDate`+`startTime`
+ */
+export interface FieldMapping {
+    /** Source key for `id`. Falls back to `reference_id`, `externalId`, or auto-generated. */
+    id?: string;
+    /** Source key for `title` (required unless `mapEvent` is used) */
+    title?: string;
+    /** Source key for a full start timestamp (ISO string, Date, or ms) */
+    start?: string;
+    /** Source key for a full end timestamp */
+    end?: string;
+    /**
+     * Source key for a date-only string (e.g. "2026-03-03").
+     * Combined with `startTime` / `endTime` when `start`/`end` are not available.
+     */
+    date?: string;
+    /** Source key for start time string (e.g. "07:00") — combined with `date` */
+    startTime?: string;
+    /** Source key for end time string (e.g. "08:15") — combined with `date` */
+    endTime?: string;
+    /** Source key for `color` */
+    color?: string;
+    /** Source key for `subtitle` */
+    subtitle?: string;
+    /** Source key for `location` */
+    location?: string;
+    /** Source key for `category` */
+    category?: string;
+    /** Source key for `resourceId` */
+    resourceId?: string;
+    /** Source key for `externalId` */
+    externalId?: string;
+    /**
+     * Source key for status. The source value is coerced:
+     *   - boolean `true`/`false` on an `is_cancelled`-type field → 'cancelled'/'confirmed'
+     *   - string 'cancelled'/'tentative'/'confirmed' used directly
+     */
+    status?: string;
+    /**
+     * Source keys that should be collected as tags.
+     * Each key's value is included as a tag if truthy/non-empty.
+     * String values are used directly; booleans use the key name.
+     */
+    tags?: string[];
+}
+export interface MappedAdapterOptions<T = Record<string, unknown>> {
+    /**
+     * Declarative field mapping — quick way to wire external fields
+     * to TimelineEvent properties.
+     */
+    fields?: FieldMapping;
+    /**
+     * Custom mapper function — full control over the transformation.
+     * When provided, `fields` is ignored.
+     */
+    mapEvent?: (raw: T, index: number) => TimelineEvent;
+    /**
+     * Fields to always include in `data` (the catch-all payload).
+     * Pass `'*'` to include all unmapped source fields.
+     * @default '*'
+     */
+    includeData?: string[] | '*';
+    /**
+     * When true (default), ignore source colors and auto-assign from
+     * the palette grouped by category / title.  This keeps the calendar
+     * visually consistent regardless of the upstream source.
+     * Set to `false` to preserve the original colors from the data.
+     * @default true
+     */
+    autoColor?: boolean;
+    /**
+     * Color palette used for auto-coloring.
+     * Defaults to VIVID_PALETTE.
+     */
+    palette?: string[];
+    /**
+     * When true (default), create/update/delete throw an error.
+     * Set to false and provide `onMutate` to enable writes.
+     */
+    readOnly?: boolean;
+    /**
+     * Optional mutation handler for write operations.
+     * Only used when `readOnly` is false.
+     */
+    onMutate?: MutationHandler<T>;
+}
+export interface MutationHandler<T = Record<string, unknown>> {
+    onCreate?: (event: Omit<TimelineEvent, 'id'>) => Promise<T>;
+    onUpdate?: (id: string, patch: Partial<TimelineEvent>) => Promise<T>;
+    onDelete?: (id: string) => Promise<void>;
+}
+/**
+ * Create a CalendarAdapter from an array of external records + mapping config.
+ *
+ * @example
+ * ```ts
+ * // Yoga school schedule
+ * const adapter = createMappedAdapter(yogaSchedule.events, {
+ *   fields: {
+ *     title: 'class_name',
+ *     start: 'starts_at_iso',
+ *     end: 'ends_at_iso',
+ *     subtitle: 'teacher',
+ *     location: 'room',
+ *     color: 'color',
+ *     externalId: 'reference_id',
+ *     status: 'is_cancelled',
+ *     tags: ['is_free', 'is_bookable_online'],
+ *   },
+ * });
+ *
+ * // Medical appointments
+ * const adapter = createMappedAdapter(appointments, {
+ *   fields: {
+ *     title: 'procedure_name',
+ *     start: 'scheduled_at',
+ *     end: 'scheduled_end',
+ *     subtitle: 'doctor_name',
+ *     location: 'office',
+ *     resourceId: 'doctor_id',
+ *   },
+ * });
+ *
+ * // Full custom mapper
+ * const adapter = createMappedAdapter(rawData, {
+ *   mapEvent: (raw) => ({
+ *     id: raw.uid,
+ *     title: `${raw.first_name} ${raw.last_name}`,
+ *     start: new Date(raw.timestamp),
+ *     end: new Date(raw.timestamp + raw.duration_ms),
+ *     location: raw.room,
+ *   }),
+ * });
+ * ```
+ */
+export declare function createMappedAdapter<T extends Record<string, unknown> = Record<string, unknown>>(sourceData: T[], options?: MappedAdapterOptions<T>): CalendarAdapter;