@nomideusz/svelte-calendar 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+# @svelte-calendar/core
+
+A themeable, pluggable **Svelte 5** calendar component library with **Day** and **Week** views  ready for yoga studios, tour bookings, concerts, language schools, and more.
+
+## Views — Concept-Paired
+
+Views are organised into **concepts** that span both Day and Week granularity.
+Switching between Day and Week preserves the active concept.
+
+| Concept | Day View | Week View | Description |
+|---------|----------|-----------|-------------|
+| **Grid** | DayTimeline (horizontal) | WeekGrid (vertical) | The primary planner — time blocks on a scrollable grid. |
+| **Agenda** | DayAgenda | WeekAgenda | List / feed — Done, Now, Next (day) or grouped-by-day scroll (week). |
+| **Heatmap** | — | WeekHeatmap | Density view — 24 cells per day showing busy/free intensity. Week-only. |
+
+## Installation
+
+```bash
+npm install @svelte-calendar/core
+```
+
+> **Peer dependency:** Svelte 5 (`^5.0.0`)
+
+## Quick Start
+
+```svelte
+<script lang="ts">
+  import {
+    Calendar,
+    DayTimeline,
+    DayAgenda,
+    WeekGrid,
+    WeekAgenda,
+    WeekHeatmap,
+    createMemoryAdapter,
+    midnight,
+  } from '@svelte-calendar/core';
+  import type { CalendarView, TimelineEvent } from '@svelte-calendar/core';
+
+  const events: TimelineEvent[] = [
+    { id: '1', title: 'Yoga Flow', start: new Date('2025-03-01T09:00'), end: new Date('2025-03-01T10:00'), color: '#818cf8' },
+    { id: '2', title: 'Meditation', start: new Date('2025-03-01T12:00'), end: new Date('2025-03-01T12:45'), color: '#34d399' },
+  ];
+
+  // Adapters provide the data layer (in-memory, REST, etc.)
+  const adapter = createMemoryAdapter(events);
+
+  // Concepts are paired by label — switching Day↔Week preserves the concept
+  const views: CalendarView[] = [
+    { id: 'day-grid',     label: 'Grid',    granularity: 'day',  component: DayTimeline },
+    { id: 'week-grid',    label: 'Grid',    granularity: 'week', component: WeekGrid },
+    { id: 'day-agenda',   label: 'Agenda',  granularity: 'day',  component: DayAgenda },
+    { id: 'week-agenda',  label: 'Agenda',  granularity: 'week', component: WeekAgenda },
+    { id: 'week-heatmap', label: 'Heatmap', granularity: 'week', component: WeekHeatmap },
+  ];
+</script>
+
+<Calendar
+  {views}
+  {adapter}
+  defaultView="week-grid"
+  theme={midnight}
+  height={600}
+  oneventclick={(ev) => console.log('clicked', ev.id)}
+  oneventcreate={(range) => console.log('create', range.start, range.end)}
+/>
+```
+
+## Themes
+
+Three built-in presets  each view reads from the same `--dt-*` CSS custom property contract:
+
+| Preset | Tone |
+|--------|------|
+| `midnight` | Dark (deep navy/slate) |
+| `parchment` | Warm light (cream, amber accents) |
+| `indigo` | Cool light (white surface, indigo accents) |
+
+```svelte
+<script>
+  import { midnight, parchment, indigo, presets } from '@svelte-calendar/core';
+</script>
+
+<!-- Apply directly -->
+<WeekGrid style={midnight} events={events} />
+
+<!-- Or use the presets map -->
+<WeekGrid style={presets['parchment']} events={events} />
+```
+
+### Custom Themes
+
+Pass any string of `--dt-*` custom property declarations:
+
+```ts
+const custom = `
+  --dt-bg: #0a0a0a;
+  --dt-surface: #111;
+  --dt-border: rgba(255,255,255,0.06);
+  --dt-text: #e0e0e0;
+  --dt-accent: #10b981;
+  /* ...see presets.ts for the full token list */
+`;
+```
+
+## Architecture
+
+```
+src/lib/
++-- core/          # Clock, time utils, locale, types
++-- engine/        # Reactive state: event-store, view-state, selection, drag
++-- adapters/      # Data layer: memory adapter, REST adapter
++-- primitives/    # Low-level UI atoms: NowIndicator, EventBlock, TimeGutter...
++-- calendar/      # Calendar shell, Toolbar
++-- views/         # The 6 view components (day/ + week/)
++-- theme/         # Preset themes and token definitions
+```
+
+## Engine
+
+```ts
+import {
+  createEventStore,
+  createViewState,
+  createSelection,
+  createDragState,
+} from '@svelte-calendar/core';
+```
+
+- **`createEventStore(adapter)`**  reactive event list with fetch/add/update/remove
+- **`createViewState(options)`**  current view, date range, navigation (prev/next/today)
+- **`createSelection()`**  selected event tracking
+- **`createDragState()`**  drag-to-create and drag-to-move state machine
+
+## Adapters
+
+| Adapter | Use |
+|---------|-----|
+| `createMemoryAdapter(events)` | In-memory  great for demos and prototyping |
+| `createRestAdapter(options)` | Fetch from a REST API with configurable endpoints |
+
+## Standalone Views
+
+Each view works independently without the Calendar shell:
+
+```svelte
+<!-- Horizontal day timeline -->
+<DayTimeline style={midnight} events={events} />
+
+<!-- Vertical day grid with elastic night compression -->
+<DayGrid style={midnight} events={events} height={600} elastic />
+
+<!-- Week density heatmap -->
+<WeekHeatmap style={parchment} events={events} height={320} />
+```
+
+## Development
+
+```bash
+npm install
+npm run dev          # SvelteKit dev server (demo app)
+npm run check        # Type check
+npm run package      # Build the library into dist/
+```
+
+## License
+
+MIT

package/dist/adapters/index.d.ts

@@ -0,0 +1,4 @@
+export type { CalendarAdapter, DateRange } from './types.js';
+export { createMemoryAdapter } from './memory.js';
+export { createRestAdapter } from './rest.js';
+export type { RestAdapterOptions } from './rest.js';

package/dist/adapters/index.js

@@ -0,0 +1,2 @@
+export { createMemoryAdapter } from './memory.js';
+export { createRestAdapter } from './rest.js';

package/dist/adapters/memory.d.ts

@@ -0,0 +1,14 @@
+/**
+ * In-memory adapter — the default for demos and testing.
+ *
+ * Events are stored in a plain array. No persistence across page loads.
+ * Perfect for prototyping and unit tests.
+ *
+ * Usage:
+ *   import { createMemoryAdapter } from './';
+ *   const adapter = createMemoryAdapter(initialEvents);
+ *   const store = createEventStore(adapter);
+ */
+import type { TimelineEvent } from '../core/types.js';
+import type { CalendarAdapter } from './types.js';
+export declare function createMemoryAdapter(initial?: TimelineEvent[]): CalendarAdapter;

package/dist/adapters/memory.js

@@ -0,0 +1,33 @@
+let counter = 0;
+function uid() {
+    return `mem-${Date.now()}-${++counter}`;
+}
+export function createMemoryAdapter(initial = []) {
+    const events = [...initial];
+    function overlaps(ev, range) {
+        return ev.start < range.end && ev.end > range.start;
+    }
+    return {
+        async fetchEvents(range) {
+            return events.filter((ev) => overlaps(ev, range));
+        },
+        async createEvent(data) {
+            const ev = { ...data, id: uid() };
+            events.push(ev);
+            return ev;
+        },
+        async updateEvent(id, patch) {
+            const idx = events.findIndex((e) => e.id === id);
+            if (idx < 0)
+                throw new Error(`Event not found: ${id}`);
+            events[idx] = { ...events[idx], ...patch, id };
+            return events[idx];
+        },
+        async deleteEvent(id) {
+            const idx = events.findIndex((e) => e.id === id);
+            if (idx < 0)
+                throw new Error(`Event not found: ${id}`);
+            events.splice(idx, 1);
+        },
+    };
+}

package/dist/adapters/rest.d.ts

@@ -0,0 +1,20 @@
+/**
+ * REST adapter skeleton — connect to any REST API.
+ *
+ * Override the URL builder and response mapper for your API shape.
+ * This is a starting point; production use should add auth headers,
+ * error handling, retry logic, etc.
+ */
+import type { TimelineEvent } from '../core/types.js';
+import type { CalendarAdapter } from './types.js';
+export interface RestAdapterOptions {
+    /** Base URL of the API (e.g. "https://api.example.com/v1") */
+    baseUrl: string;
+    /** Custom headers (e.g. Authorization) */
+    headers?: Record<string, string>;
+    /** Map API response to TimelineEvent[] */
+    mapEvents?: (data: unknown) => TimelineEvent[];
+    /** Map API response to a single TimelineEvent */
+    mapEvent?: (data: unknown) => TimelineEvent;
+}
+export declare function createRestAdapter(options: RestAdapterOptions): CalendarAdapter;

package/dist/adapters/rest.js

@@ -0,0 +1,48 @@
+export function createRestAdapter(options) {
+    const { baseUrl, headers = {} } = options;
+    const mapEvents = options.mapEvents ?? ((data) => data);
+    const mapEvent = options.mapEvent ?? ((data) => data);
+    async function request(path, init) {
+        const res = await fetch(`${baseUrl}${path}`, {
+            ...init,
+            headers: {
+                'Content-Type': 'application/json',
+                ...headers,
+                ...(init?.headers ?? {}),
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`Calendar API error: ${res.status} ${res.statusText}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        return res.json();
+    }
+    return {
+        async fetchEvents(range) {
+            const params = new URLSearchParams({
+                start: range.start.toISOString(),
+                end: range.end.toISOString(),
+            });
+            const data = await request(`/events?${params}`);
+            return mapEvents(data);
+        },
+        async createEvent(event) {
+            const data = await request('/events', {
+                method: 'POST',
+                body: JSON.stringify(event),
+            });
+            return mapEvent(data);
+        },
+        async updateEvent(id, patch) {
+            const data = await request(`/events/${id}`, {
+                method: 'PATCH',
+                body: JSON.stringify(patch),
+            });
+            return mapEvent(data);
+        },
+        async deleteEvent(id) {
+            await request(`/events/${id}`, { method: 'DELETE' });
+        },
+    };
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * CalendarAdapter — the integration contract.
+ *
+ * Any data source (REST API, GraphQL, local storage, in-memory)
+ * implements this interface. The event store calls these methods
+ * and the adapter handles persistence.
+ */
+import type { TimelineEvent } from '../core/types.js';
+/** Simple date range for queries */
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
+export interface CalendarAdapter {
+    /** Fetch events that overlap the given date range */
+    fetchEvents(range: DateRange): Promise<TimelineEvent[]>;
+    /** Create a new event, return it with a server-assigned ID */
+    createEvent(event: Omit<TimelineEvent, 'id'>): Promise<TimelineEvent>;
+    /** Update an event, return the full updated event */
+    updateEvent(id: string, patch: Partial<TimelineEvent>): Promise<TimelineEvent>;
+    /** Delete an event by ID */
+    deleteEvent(id: string): Promise<void>;
+}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/assets/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="107" height="128" viewBox="0 0 107 128"><title>svelte-logo</title><path d="M94.157 22.819c-10.4-14.885-30.94-19.297-45.792-9.835L22.282 29.608A29.92 29.92 0 0 0 8.764 49.65a31.5 31.5 0 0 0 3.108 20.231 30 30 0 0 0-4.477 11.183 31.9 31.9 0 0 0 5.448 24.116c10.402 14.887 30.942 19.297 45.791 9.835l26.083-16.624A29.92 29.92 0 0 0 98.235 78.35a31.53 31.53 0 0 0-3.105-20.232 30 30 0 0 0 4.474-11.182 31.88 31.88 0 0 0-5.447-24.116" style="fill:#ff3e00"/><path d="M45.817 106.582a20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.503 18 18 0 0 1 .624-2.435l.49-1.498 1.337.981a33.6 33.6 0 0 0 10.203 5.098l.97.294-.09.968a5.85 5.85 0 0 0 1.052 3.878 6.24 6.24 0 0 0 6.695 2.485 5.8 5.8 0 0 0 1.603-.704L69.27 76.28a5.43 5.43 0 0 0 2.45-3.631 5.8 5.8 0 0 0-.987-4.371 6.24 6.24 0 0 0-6.698-2.487 5.7 5.7 0 0 0-1.6.704l-9.953 6.345a19 19 0 0 1-5.296 2.326 20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.502 17.99 17.99 0 0 1 8.13-12.052l26.081-16.623a19 19 0 0 1 5.3-2.329 20.72 20.72 0 0 1 22.237 8.243 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-.624 2.435l-.49 1.498-1.337-.98a33.6 33.6 0 0 0-10.203-5.1l-.97-.294.09-.968a5.86 5.86 0 0 0-1.052-3.878 6.24 6.24 0 0 0-6.696-2.485 5.8 5.8 0 0 0-1.602.704L37.73 51.72a5.42 5.42 0 0 0-2.449 3.63 5.79 5.79 0 0 0 .986 4.372 6.24 6.24 0 0 0 6.698 2.486 5.8 5.8 0 0 0 1.602-.704l9.952-6.342a19 19 0 0 1 5.295-2.328 20.72 20.72 0 0 1 22.237 8.242 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-8.13 12.053l-26.081 16.622a19 19 0 0 1-5.3 2.328" style="fill:#fff"/></svg>

package/dist/calendar/Calendar.svelte

@@ -0,0 +1,213 @@
+<!--
+  Calendar — the unified orchestrator.
+
+  Brings together: adapter → event store → view state + selection → toolbar + active view.
+  Provides context so any descendant view can read the store/state via getContext().
+
+  Usage:
+    <Calendar
+      adapter={myAdapter}
+      views={[
+        { id: 'week-terrain', label: 'Terrain', component: WeekTimelineV4 },
+        { id: 'week-agenda',  label: 'Agenda',  component: WeekTimelineV5 },
+        { id: 'day',          label: 'Day',     component: DayTimeline },
+      ]}
+      defaultView="week-terrain"
+      theme={presets.midnight}
+      height={600}
+      oneventclick={handleClick}
+      oneventcreate={handleCreate}
+    />
+-->
+<script lang="ts">
+	import { setContext, untrack, type Component } from 'svelte';
+	import type { CalendarAdapter } from '../adapters/types.js';
+	import type { CalendarViewId } from '../engine/view-state.svelte.js';
+	import { createEventStore, type EventStore } from '../engine/event-store.svelte.js';
+	import { createViewState, type ViewState } from '../engine/view-state.svelte.js';
+	import { createSelection, type Selection } from '../engine/selection.svelte.js';
+	import { createDragState, type DragState } from '../engine/drag.svelte.js';
+	import type { TimelineEvent } from '../core/types.js';
+	import Toolbar from './Toolbar.svelte';
+
+	/** One view registration */
+	export interface CalendarView {
+		id: CalendarViewId;
+		label: string;
+		/** day or week */
+		granularity: 'day' | 'week';
+		/** The Svelte component to render */
+		component: Component<Record<string, unknown>>;
+		/** Extra props to pass through (e.g. hourHeight, specialized settings) */
+		props?: Record<string, unknown>;
+	}
+
+	interface Props {
+		/** Data adapter (required) */
+		adapter: CalendarAdapter;
+		/** Registered views */
+		views?: CalendarView[];
+		/** Initial view */
+		defaultView?: CalendarViewId;
+		/** CSS theme string (--dt-* inline style) */
+		theme?: string;
+		/** Start week on Monday */
+		mondayStart?: boolean;
+		/** Total height */
+		height?: number;
+		/** Show toolbar */
+		showToolbar?: boolean;
+		/** Links to display in toolbar */
+		links?: { href: string; label: string }[];
+
+		// ── Callbacks ──
+		oneventclick?: (event: TimelineEvent) => void;
+		oneventcreate?: (range: { start: Date; end: Date }) => void;
+		oneventmove?: (event: TimelineEvent, newStart: Date, newEnd: Date) => void;
+	}
+
+	let {
+		adapter,
+		views = [],
+		defaultView = 'week-grid',
+		theme = '',
+		mondayStart = true,
+		height = 600,
+		showToolbar = true,
+		links = [],
+		oneventclick,
+		oneventcreate,
+		oneventmove,
+	}: Props = $props();
+
+	// ── Create reactive state ──
+	const store: EventStore = $derived(createEventStore(adapter));
+	const viewState: ViewState = createViewState(untrack(() => ({
+		defaultView,
+		mondayStart,
+	})));
+	const selection: Selection = createSelection();
+	const drag: DragState = createDragState();
+
+	// ── Drag commit handler ──
+	// Views call this on pointer-up to process drag results.
+	function commitDrag(): void {
+		const mode = drag.mode;
+		const payload = drag.commit();
+		if (!payload) return;
+
+		if ((mode === 'move' || mode === 'resize-start' || mode === 'resize-end') && payload.eventId) {
+			store.move(payload.eventId, payload.start, payload.end);
+			const ev = store.byId(payload.eventId);
+			if (ev) oneventmove?.(ev, payload.start, payload.end);
+		} else if (mode === 'create') {
+			oneventcreate?.({ start: payload.start, end: payload.end });
+		}
+	}
+
+	// Context is set once at mount; engine objects hold $state internally
+	// so consumers reading from them stay reactive automatically.
+	// Wrap store in a getter since it's $derived and may change when adapter changes.
+	setContext('calendar:store', { get current() { return store; } });
+	setContext('calendar:viewState', viewState);
+	setContext('calendar:selection', selection);
+	setContext('calendar:drag', drag);
+	setContext('calendar:commitDrag', commitDrag);
+	// Callbacks: provide a getter-based object so context consumers
+	// always see the latest callback references.
+	setContext('calendar:callbacks', {
+		get oneventclick() { return oneventclick; },
+		get oneventcreate() { return oneventcreate; },
+		get oneventmove() { return oneventmove; },
+	});
+
+	// ── Load events when range changes ──
+	$effect(() => {
+		const { start, end } = viewState.range;
+		store.load({ start, end });
+	});
+
+	// ── Resolve active view ──
+	const activeView = $derived(views.find((v) => v.id === viewState.view) ?? views[0]);
+
+	const toolbarViews = $derived(
+		views.map((v) => ({ id: v.id, label: v.label, granularity: v.granularity })),
+	);
+</script>
+
+<div class="cal" style="{theme}; --cal-h: {height}px">
+	{#if showToolbar}
+		<Toolbar {viewState} views={toolbarViews} {links} />
+	{/if}
+
+	<div class="cal-body">
+		{#if activeView}
+			{@const Comp = activeView.component}
+			<Comp
+				events={store.events}
+				style={theme}
+				height={height - (showToolbar ? 48 : 0)}
+				mondayStart={viewState.mondayStart}
+				focusDate={viewState.focusDate}
+				oneventclick={oneventclick}
+				oneventcreate={oneventcreate}
+				selectedEventId={selection.selectedId}
+				{...activeView.props ?? {}}
+			/>
+		{:else}
+			<div class="cal-empty">No views registered.</div>
+		{/if}
+	</div>
+
+	{#if store.loading}
+		<div class="cal-loading"></div>
+	{/if}
+</div>
+
+<style>
+	.cal {
+		position: relative;
+		height: var(--cal-h, 600px);
+		background: var(--dt-bg, #0b0e14);
+		border-radius: 12px;
+		overflow: hidden;
+		display: flex;
+		flex-direction: column;
+		border: 1px solid var(--dt-border, rgba(148, 163, 184, 0.07));
+	}
+
+	.cal-body {
+		flex: 1;
+		min-height: 0;
+		overflow: hidden;
+	}
+
+	.cal-empty {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		height: 100%;
+		font: 400 13px / 1 var(--dt-sans, 'Outfit', system-ui, sans-serif);
+		color: var(--dt-text-3, rgba(100, 116, 139, 0.55));
+	}
+
+	.cal-loading {
+		position: absolute;
+		top: 0;
+		left: 0;
+		right: 0;
+		height: 2px;
+		background: linear-gradient(
+			90deg,
+			transparent 0%,
+			var(--dt-accent, #ef4444) 50%,
+			transparent 100%
+		);
+		animation: cal-slide 1.2s ease-in-out infinite;
+	}
+
+	@keyframes cal-slide {
+		0% { transform: translateX(-100%); }
+		100% { transform: translateX(100%); }
+	}
+</style>

package/dist/calendar/Calendar.svelte.d.ts

@@ -0,0 +1,45 @@
+import { type Component } from 'svelte';
+import type { CalendarAdapter } from '../adapters/types.js';
+import type { CalendarViewId } from '../engine/view-state.svelte.js';
+import type { TimelineEvent } from '../core/types.js';
+/** One view registration */
+export interface CalendarView {
+    id: CalendarViewId;
+    label: string;
+    /** day or week */
+    granularity: 'day' | 'week';
+    /** The Svelte component to render */
+    component: Component<Record<string, unknown>>;
+    /** Extra props to pass through (e.g. hourHeight, specialized settings) */
+    props?: Record<string, unknown>;
+}
+interface Props {
+    /** Data adapter (required) */
+    adapter: CalendarAdapter;
+    /** Registered views */
+    views?: CalendarView[];
+    /** Initial view */
+    defaultView?: CalendarViewId;
+    /** CSS theme string (--dt-* inline style) */
+    theme?: string;
+    /** Start week on Monday */
+    mondayStart?: boolean;
+    /** Total height */
+    height?: number;
+    /** Show toolbar */
+    showToolbar?: boolean;
+    /** Links to display in toolbar */
+    links?: {
+        href: string;
+        label: string;
+    }[];
+    oneventclick?: (event: TimelineEvent) => void;
+    oneventcreate?: (range: {
+        start: Date;
+        end: Date;
+    }) => void;
+    oneventmove?: (event: TimelineEvent, newStart: Date, newEnd: Date) => void;
+}
+declare const Calendar: Component<Props, {}, "">;
+type Calendar = ReturnType<typeof Calendar>;
+export default Calendar;