@nomideusz/svelte-calendar 0.3.1 → 0.5.1

package/dist/calendar/Calendar.svelte

@@ -1,18 +1,18 @@
 <!--
   Calendar — the unified orchestrator.
 
-  Brings together: adapter → event store → view state + selection → toolbar + active view.
+  Brings together: adapter → event store → view state + selection → 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 },
+        { id: 'week-planner', label: 'Planner', component: Planner, props: { mode: 'week' } },
+        { id: 'week-agenda',   label: 'Agenda',  component: Agenda },
+        { id: 'day-planner',   label: 'Planner', component: Planner, props: { mode: 'day' } },
       ]}
-      defaultView="week-terrain"
+      defaultView="week-planner"
       theme={presets.midnight}
       height={600}
       oneventclick={handleClick}
@@ -20,7 +20,7 @@
     />
 -->
 <script lang="ts">
-	import { setContext, untrack, type Component } from 'svelte';
+	import { setContext, untrack, type Component, type Snippet } 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';
@@ -28,7 +28,7 @@
 	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';
+	import { getLabels } from '../core/locale.js';
 
 	/** One view registration */
 	export interface CalendarView {
@@ -55,10 +55,6 @@
 		mondayStart?: boolean;
 		/** Total height */
 		height?: number;
-		/** Show toolbar */
-		showToolbar?: boolean;
-		/** Links to display in toolbar */
-		links?: { href: string; label: string }[];
 		/** Text direction: 'ltr' (default), 'rtl', or 'auto' */
 		dir?: 'ltr' | 'rtl' | 'auto';
 		/** BCP 47 locale tag (e.g. 'en-US', 'ar-SA') — sets lang and locale for formatting */
@@ -67,47 +63,56 @@
 		readOnly?: boolean;
 		/** Visible hour range: [startHour, endHour). Crops the grid to these hours. */
 		visibleHours?: [number, number];
+		/** Initial date to focus on (defaults to today) */
+		initialDate?: Date;
+		/** Drag snap interval in minutes (default: 15) */
+		snapInterval?: number;
+
+		// ── Snippets ──
+		/** Custom event rendering snippet */
+		event?: Snippet<[TimelineEvent]>;
+		/** Content to show when no events are loaded */
+		empty?: Snippet;
 
 		// ── Callbacks ──
 		oneventclick?: (event: TimelineEvent) => void;
 		oneventcreate?: (range: { start: Date; end: Date }) => void;
 		oneventmove?: (event: TimelineEvent, newStart: Date, newEnd: Date) => void;
+		onviewchange?: (viewId: CalendarViewId) => void;
 	}
 
 	let {
 		adapter,
 		views = [],
-		defaultView = 'week-grid',
+		defaultView = 'week-planner',
 		theme = '',
 		mondayStart = true,
 		height = 600,
-		showToolbar = true,
-		links = [],
 		dir,
 		locale,
 		readOnly = false,
 		visibleHours,
+		initialDate,
+		snapInterval = 15,
+		event: eventSnippet,
+		empty: emptySnippet,
 		oneventclick,
 		oneventcreate,
 		oneventmove,
+		onviewchange,
 	}: Props = $props();
 
 	// In readOnly mode, suppress mutation callbacks
 	const effectiveCreate = $derived(readOnly ? undefined : oneventcreate);
 	const effectiveMove = $derived(readOnly ? undefined : oneventmove);
 
-	import { setDefaultLocale } from '../core/locale.js';
-
-	// ── Set locale when provided ──
-	$effect(() => {
-		if (locale) setDefaultLocale(locale);
-	});
-
 	// ── Create reactive state ──
 	const store: EventStore = $derived(createEventStore(adapter));
 	const viewState: ViewState = createViewState(untrack(() => ({
 		defaultView,
 		mondayStart,
+		initialDate,
+		granularityForView: (viewId) => views.find((v) => v.id === viewId)?.granularity,
 	})));
 	const selection: Selection = createSelection();
 	const drag: DragState = createDragState();
@@ -146,6 +151,9 @@
 	});
 	setContext('calendar:readOnly', { get current() { return readOnly; } });
 	setContext('calendar:visibleHours', { get current() { return visibleHours; } });
+	setContext('calendar:snapInterval', { get current() { return snapInterval; } });
+	setContext('calendar:eventSnippet', { get current() { return eventSnippet; } });
+	setContext('calendar:emptySnippet', { get current() { return emptySnippet; } });
 
 	// ── Load events when range changes ──
 	$effect(() => {
@@ -153,24 +161,78 @@
 		store.load({ start, end });
 	});
 
+	// Keep active view in sync when external defaultView changes after mount.
+	$effect(() => {
+		viewState.setView(defaultView);
+	});
+
+	// Keep view state's week-start rule in sync with incoming prop changes.
+	$effect(() => {
+		if (viewState.mondayStart !== mondayStart) {
+			viewState.setMondayStart(mondayStart);
+		}
+	});
+
+	// Notify host when active view changes (e.g. via granularity toggles).
+	$effect(() => {
+		onviewchange?.(viewState.view);
+	});
+
 	// ── 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 })),
-	);
+	// ── Date label (always visible, centered over views) ──
+	const dateLabel = $derived.by(() => {
+		if (viewState.granularity === 'day') {
+			return viewState.focusDate.toLocaleDateString(locale, {
+				weekday: 'long',
+				month: 'short',
+				day: 'numeric',
+			});
+		}
+		return viewState.focusDate.toLocaleDateString(locale, {
+			month: 'long',
+			year: 'numeric',
+		});
+	});
+
+	// Which granularities are available?
+	const granularities = $derived.by(() => {
+		const g = new Set(views.map((v) => v.granularity));
+		return (['day', 'week'] as const).filter((key) => g.has(key));
+	});
+
+	const L = $derived(getLabels());
 </script>
 
 <div
 	class="cal"
 	style="{theme}; --cal-h: {height}px"
 	role="region"
-	aria-label="Calendar"
+	aria-label={L.calendar}
 	dir={dir}
 	lang={locale}
 >
-	{#if showToolbar}
-		<Toolbar {viewState} views={toolbarViews} {links} />
+	<!-- Floating granularity pills (hidden for Agenda views) -->
+	{#if granularities.length > 1 && activeView?.label !== 'Agenda'}
+		<div class="cal-pills" role="group" aria-label={L.viewMode}>
+			{#each granularities as g}
+				<button
+					class="cal-pill"
+					class:cal-pill--active={viewState.granularity === g}
+					aria-pressed={viewState.granularity === g}
+					onclick={() => {
+						const currentLabel = views.find((v) => v.id === viewState.view)?.label;
+						const match = views.find((v) => v.granularity === g && v.label === currentLabel);
+						const fallback = views.find((v) => v.granularity === g);
+						const target = match ?? fallback;
+						if (target) viewState.setView(target.id);
+					}}
+				>
+					{g === 'day' ? L.day : L.week}
+				</button>
+			{/each}
+		</div>
 	{/if}
 
 	<div class="cal-body">
@@ -179,8 +241,9 @@
 			<Comp
 				events={store.events}
 				style={theme}
-				height={height - (showToolbar ? 48 : 0)}
+				height={null}
 				mondayStart={viewState.mondayStart}
+				{locale}
 				focusDate={viewState.focusDate}
 				oneventclick={oneventclick}
 				oneventcreate={effectiveCreate}
@@ -205,15 +268,60 @@
 		height: var(--cal-h, 600px);
 		background: var(--dt-bg, #0b0e14);
 		border-radius: 12px;
-		overflow: hidden;
+		overflow: clip;
 		display: flex;
 		flex-direction: column;
 		border: 1px solid var(--dt-border, rgba(148, 163, 184, 0.07));
 	}
 
+	/* ── Floating pills ── */
+	.cal-pills {
+		position: absolute;
+		top: 22px;
+		bottom: auto;
+		left: 10px;
+		z-index: 20;
+		display: flex;
+		gap: 2px;
+		background: color-mix(in srgb, var(--dt-surface, #10141c) 85%, transparent);
+		backdrop-filter: blur(6px);
+		-webkit-backdrop-filter: blur(6px);
+		border-radius: 8px;
+		padding: 2px;
+		border: 1px solid var(--dt-border, rgba(148, 163, 184, 0.07));
+	}
+
+	.cal-pill {
+		border: none;
+		background: transparent;
+		color: var(--dt-text-2, rgba(148, 163, 184, 0.55));
+		cursor: pointer;
+		font: 600 11px / 1 var(--dt-sans, 'Outfit', system-ui, sans-serif);
+		padding: 6px 12px;
+		border-radius: 6px;
+		letter-spacing: 0.04em;
+		text-transform: uppercase;
+		transition: background 100ms, color 100ms;
+	}
+
+	.cal-pill:hover {
+		color: var(--dt-text, rgba(226, 232, 240, 0.85));
+	}
+
+	.cal-pill--active {
+		background: var(--dt-accent, #ef4444);
+		color: var(--dt-btn-text, #fff);
+	}
+
+	.cal-pill:focus-visible {
+		outline: 2px solid color-mix(in srgb, var(--dt-accent, #ef4444) 55%, transparent);
+		outline-offset: 2px;
+	}
+
 	.cal-body {
 		flex: 1;
 		min-height: 0;
+		position: relative;
 		overflow: hidden;
 	}
 

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

@@ -1,4 +1,4 @@
-import { type Component } from 'svelte';
+import { type Component, type Snippet } 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';
@@ -26,13 +26,6 @@ interface Props {
     mondayStart?: boolean;
     /** Total height */
     height?: number;
-    /** Show toolbar */
-    showToolbar?: boolean;
-    /** Links to display in toolbar */
-    links?: {
-        href: string;
-        label: string;
-    }[];
     /** Text direction: 'ltr' (default), 'rtl', or 'auto' */
     dir?: 'ltr' | 'rtl' | 'auto';
     /** BCP 47 locale tag (e.g. 'en-US', 'ar-SA') — sets lang and locale for formatting */
@@ -41,12 +34,21 @@ interface Props {
     readOnly?: boolean;
     /** Visible hour range: [startHour, endHour). Crops the grid to these hours. */
     visibleHours?: [number, number];
+    /** Initial date to focus on (defaults to today) */
+    initialDate?: Date;
+    /** Drag snap interval in minutes (default: 15) */
+    snapInterval?: number;
+    /** Custom event rendering snippet */
+    event?: Snippet<[TimelineEvent]>;
+    /** Content to show when no events are loaded */
+    empty?: Snippet;
     oneventclick?: (event: TimelineEvent) => void;
     oneventcreate?: (range: {
         start: Date;
         end: Date;
     }) => void;
     oneventmove?: (event: TimelineEvent, newStart: Date, newEnd: Date) => void;
+    onviewchange?: (viewId: CalendarViewId) => void;
 }
 declare const Calendar: Component<Props, {}, "">;
 type Calendar = ReturnType<typeof Calendar>;

package/dist/calendar/index.d.ts

@@ -1,3 +1,2 @@
 export { default as Calendar } from './Calendar.svelte';
-export { default as Toolbar } from './Toolbar.svelte';
 export type { CalendarView } from './Calendar.svelte';

package/dist/calendar/index.js

@@ -1,3 +1,2 @@
 // ─── Calendar shell barrel export ───────────────────────
 export { default as Calendar } from './Calendar.svelte';
-export { default as Toolbar } from './Toolbar.svelte';

package/dist/core/index.d.ts

@@ -1,8 +1,9 @@
 export { createClock } from './clock.svelte.js';
 export type { Clock } from './clock.svelte.js';
-export { DAY_MS, HOUR_MS, HOURS, sod, startOfWeek, addDaysMs, diffDays, pad, fractionalHour, fmtHM, fmtS, dayNum, dayOfWeek, } from './time.js';
-export { setDefaultLocale, getDefaultLocale, is24HourLocale, fmtH, weekdayShort, weekdayLong, monthShort, monthLong, dateShort, dateWithWeekday, fmtDay, fmtWeekRange, } from './locale.js';
+export { DAY_MS, HOUR_MS, HOURS, sod, startOfWeek, addDaysMs, diffDays, pad, fractionalHour, fmtHM, fmtS, dayNum, dayOfWeek, isMultiDay, isAllDay, segmentForDay, } from './time.js';
+export type { DaySegment } from './time.js';
+export { setDefaultLocale, getDefaultLocale, is24HourLocale, fmtH, fmtTime, fmtDuration, weekdayShort, weekdayLong, monthShort, monthLong, dateShort, dateWithWeekday, fmtDay, fmtWeekRange, defaultLabels, setLabels, resetLabels, getLabels, } from './locale.js';
+export type { CalendarLabels } from './locale.js';
 export { toZonedTime, fromZonedTime, nowInZone, formatInTimeZone, } from './timezone.js';
-export type { TimelineEvent, WeekTimelineProps, DayTimelineProps, } from './types.js';
-export { timeToX } from './types.js';
+export type { TimelineEvent, } from './types.js';
 export { generatePalette, VIVID_PALETTE } from './palette.js';

package/dist/core/index.js

@@ -2,11 +2,10 @@
 // Clock
 export { createClock } from './clock.svelte.js';
 // Time constants & math
-export { DAY_MS, HOUR_MS, HOURS, sod, startOfWeek, addDaysMs, diffDays, pad, fractionalHour, fmtHM, fmtS, dayNum, dayOfWeek, } from './time.js';
+export { DAY_MS, HOUR_MS, HOURS, sod, startOfWeek, addDaysMs, diffDays, pad, fractionalHour, fmtHM, fmtS, dayNum, dayOfWeek, isMultiDay, isAllDay, segmentForDay, } from './time.js';
 // Locale-aware formatting
-export { setDefaultLocale, getDefaultLocale, is24HourLocale, fmtH, weekdayShort, weekdayLong, monthShort, monthLong, dateShort, dateWithWeekday, fmtDay, fmtWeekRange, } from './locale.js';
+export { setDefaultLocale, getDefaultLocale, is24HourLocale, fmtH, fmtTime, fmtDuration, weekdayShort, weekdayLong, monthShort, monthLong, dateShort, dateWithWeekday, fmtDay, fmtWeekRange, defaultLabels, setLabels, resetLabels, getLabels, } from './locale.js';
 // Timezone utilities
 export { toZonedTime, fromZonedTime, nowInZone, formatInTimeZone, } from './timezone.js';
-export { timeToX } from './types.js';
 // Palette
 export { generatePalette, VIVID_PALETTE } from './palette.js';

package/dist/core/locale.d.ts

@@ -7,6 +7,68 @@
  * For date-fns locale integration later, this module can import from
  * `date-fns/locale/*` and pass to `format()`.
  */
+/**
+ * All user-visible text in the calendar UI.
+ * Override via `setLabels()` for full localisation.
+ */
+export interface CalendarLabels {
+    today: string;
+    yesterday: string;
+    tomorrow: string;
+    day: string;
+    week: string;
+    planner: string;
+    agenda: string;
+    now: string;
+    free: string;
+    allDay: string;
+    done: string;
+    upNext: string;
+    until: string;
+    noEvents: string;
+    nothingScheduled: string;
+    nothingScheduledYet: string;
+    nothingWasScheduled: string;
+    allDoneForToday: string;
+    goToToday: string;
+    previousDay: string;
+    nextDay: string;
+    previousWeek: string;
+    nextWeek: string;
+    calendar: string;
+    viewMode: string;
+    dayNavigation: string;
+    weekNavigation: string;
+    dayPlanner: string;
+    scrollableDayPlanner: string;
+    todaysLineup: string;
+    weekAhead: string;
+    multiWeekGrid: string;
+    currentTime: string;
+    createEvent: string;
+    happeningNow: string;
+    past: string;
+    completed: string;
+    inProgress: string;
+    /** e.g. "+3 more" */
+    nMore: (n: number) => string;
+    /** e.g. "5 events" */
+    nEvents: (n: number) => string;
+    /** e.g. "3 completed" */
+    nCompleted: (n: number) => string;
+    /** e.g. "day 2 of 4" */
+    dayNOfTotal: (current: number, total: number) => string;
+    /** e.g. "75% complete" */
+    percentComplete: (pct: number) => string;
+}
+/** English defaults — used unless overridden via `setLabels()`. */
+export declare const defaultLabels: CalendarLabels;
+/** Replace one or more UI labels. Merges with current labels. */
+export declare function setLabels(overrides: Partial<CalendarLabels>): void;
+/** Reset all labels to English defaults. */
+export declare function resetLabels(): void;
+/** Get the currently active labels. */
+export declare function getLabels(): Readonly<CalendarLabels>;
 /** Change the default locale for all formatting functions */
 export declare function setDefaultLocale(tag: string): void;
 /** Get the current default locale */
@@ -37,3 +99,15 @@ export declare function fmtDay(ms: number, todayMs: number, opts?: {
  * Format a week range label: "Feb 17 – 23, 2026" or "Jan 27 – Feb 2, 2026"
  */
 export declare function fmtWeekRange(weekStartMs: number, locale?: string): string;
+/**
+ * Format a Date as a compact time string.
+ *
+ * 12-hour locales → "9a", "12:30p"
+ * 24-hour locales → "9:00", "14:30"
+ */
+export declare function fmtTime(d: Date, locale?: string): string;
+/**
+ * Format the duration between two Dates as a compact string.
+ * e.g. "45m", "1h", "1h 30m"
+ */
+export declare function fmtDuration(start: Date, end: Date): string;

package/dist/core/locale.js

@@ -7,6 +7,67 @@
  * For date-fns locale integration later, this module can import from
  * `date-fns/locale/*` and pass to `format()`.
  */
+import { DAY_MS } from './time.js';
+/** English defaults — used unless overridden via `setLabels()`. */
+export const defaultLabels = {
+    today: 'Today',
+    yesterday: 'Yesterday',
+    tomorrow: 'Tomorrow',
+    day: 'Day',
+    week: 'Week',
+    planner: 'Planner',
+    agenda: 'Agenda',
+    now: 'now',
+    free: 'free',
+    allDay: 'All day',
+    done: 'Done',
+    upNext: 'Up next',
+    until: 'until',
+    noEvents: 'No events',
+    nothingScheduled: 'Nothing scheduled',
+    nothingScheduledYet: 'Nothing scheduled yet',
+    nothingWasScheduled: 'Nothing was scheduled',
+    allDoneForToday: 'All done for today',
+    goToToday: 'Go to today',
+    previousDay: 'Previous day',
+    nextDay: 'Next day',
+    previousWeek: 'Previous week',
+    nextWeek: 'Next week',
+    calendar: 'Calendar',
+    viewMode: 'View mode',
+    dayNavigation: 'Day navigation',
+    weekNavigation: 'Week navigation',
+    dayPlanner: 'Day planner',
+    scrollableDayPlanner: 'Scrollable day planner',
+    todaysLineup: "Today's lineup",
+    weekAhead: 'Week ahead',
+    multiWeekGrid: 'Multi-week calendar grid',
+    currentTime: 'Current time',
+    createEvent: 'Create event',
+    happeningNow: 'happening now',
+    past: 'past',
+    completed: 'completed',
+    inProgress: 'in progress',
+    nMore: (n) => `+${n} more`,
+    nEvents: (n) => `${n} event${n === 1 ? '' : 's'}`,
+    nCompleted: (n) => `${n} completed`,
+    dayNOfTotal: (current, total) => `day ${current} of ${total}`,
+    percentComplete: (pct) => `${pct}% complete`,
+};
+let _labels = { ...defaultLabels };
+/** Replace one or more UI labels. Merges with current labels. */
+export function setLabels(overrides) {
+    _labels = { ..._labels, ...overrides };
+}
+/** Reset all labels to English defaults. */
+export function resetLabels() {
+    _labels = { ...defaultLabels };
+}
+/** Get the currently active labels. */
+export function getLabels() {
+    return _labels;
+}
+// ─── Default locale ─────────────────────────────────────
 /** Module-level default locale — consumers can override via setDefaultLocale() */
 let defaultLocale = 'en-US';
 /** Change the default locale for all formatting functions */
@@ -73,7 +134,6 @@ export function dateWithWeekday(ms, locale) {
         day: 'numeric',
     });
 }
-import { DAY_MS } from './time.js';
 /**
  * Format a timestamp as a smart day label:
  *   "Today · Feb 21", "Yesterday · Feb 20", "Mon, Feb 17", etc.
@@ -81,12 +141,13 @@ import { DAY_MS } from './time.js';
 export function fmtDay(ms, todayMs, opts, locale) {
     const loc = locale ?? defaultLocale;
     const short = new Date(ms).toLocaleDateString(loc, { month: 'short', day: 'numeric' });
+    const L = _labels;
     if (ms === todayMs)
-        return opts?.short ? 'Today' : `Today · ${short}`;
+        return opts?.short ? L.today : `${L.today} · ${short}`;
     if (ms === todayMs - DAY_MS)
-        return opts?.short ? 'Yesterday' : `Yesterday · ${short}`;
+        return opts?.short ? L.yesterday : `${L.yesterday} · ${short}`;
     if (ms === todayMs + DAY_MS)
-        return opts?.short ? 'Tomorrow' : `Tomorrow · ${short}`;
+        return opts?.short ? L.tomorrow : `${L.tomorrow} · ${short}`;
     if (opts?.short) {
         return new Date(ms).toLocaleDateString(loc, { weekday: 'short', day: 'numeric' });
     }
@@ -111,3 +172,34 @@ export function fmtWeekRange(weekStartMs, locale) {
     }
     return `${sm} ${s.getDate()} – ${e.getDate()}, ${ey}`;
 }
+// ─── Shared time / duration formatting ──────────────────
+/**
+ * Format a Date as a compact time string.
+ *
+ * 12-hour locales → "9a", "12:30p"
+ * 24-hour locales → "9:00", "14:30"
+ */
+export function fmtTime(d, locale) {
+    if (is24HourLocale(locale)) {
+        const h = d.getHours();
+        const m = d.getMinutes();
+        return m === 0 ? String(h) : `${h}:${String(m).padStart(2, '0')}`;
+    }
+    const h = d.getHours();
+    const m = d.getMinutes();
+    const suffix = h >= 12 ? 'p' : 'a';
+    const h12 = h === 0 ? 12 : h > 12 ? h - 12 : h;
+    return m === 0 ? `${h12}${suffix}` : `${h12}:${String(m).padStart(2, '0')}${suffix}`;
+}
+/**
+ * Format the duration between two Dates as a compact string.
+ * e.g. "45m", "1h", "1h 30m"
+ */
+export function fmtDuration(start, end) {
+    const mins = Math.round((end.getTime() - start.getTime()) / 60_000);
+    if (mins < 60)
+        return `${mins}m`;
+    const h = Math.floor(mins / 60);
+    const m = mins % 60;
+    return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}

package/dist/core/time.d.ts

@@ -35,3 +35,33 @@ export declare function fmtS(ms: number): string;
 export declare function dayNum(ms: number): number;
 /** Day-of-week index (0 = Sun … 6 = Sat) */
 export declare function dayOfWeek(ms: number): number;
+import type { TimelineEvent } from './types.js';
+/** Does an event span more than one calendar day? */
+export declare function isMultiDay(ev: TimelineEvent): boolean;
+/** Is an event effectively all-day? (allDay flag, or spans ≥24h with midnight boundaries) */
+export declare function isAllDay(ev: TimelineEvent): boolean;
+/**
+ * Describes how an event appears on a specific day.
+ */
+export interface DaySegment {
+    ev: TimelineEvent;
+    /** Effective start for this day (clamped to day start) */
+    start: Date;
+    /** Effective end for this day (clamped to day end) */
+    end: Date;
+    /** Is this the first day of the event? */
+    isStart: boolean;
+    /** Is this the last day of the event? */
+    isEnd: boolean;
+    /** 1-based day index within the span */
+    dayIndex: number;
+    /** Total number of days the event spans */
+    totalDays: number;
+    /** Is this an all-day event? */
+    allDay: boolean;
+}
+/**
+ * Compute how an event appears on a specific day.
+ * Returns null if the event doesn't overlap the day.
+ */
+export declare function segmentForDay(ev: TimelineEvent, dayMs: number): DaySegment | null;

package/dist/core/time.js

@@ -66,3 +66,45 @@ export function dayNum(ms) {
 export function dayOfWeek(ms) {
     return getDay(new Date(ms));
 }
+/** Does an event span more than one calendar day? */
+export function isMultiDay(ev) {
+    return sod(ev.start.getTime()) !== sod(ev.end.getTime() - 1);
+}
+/** Is an event effectively all-day? (allDay flag, or spans ≥24h with midnight boundaries) */
+export function isAllDay(ev) {
+    if (ev.allDay)
+        return true;
+    const duration = ev.end.getTime() - ev.start.getTime();
+    if (duration < DAY_MS)
+        return false;
+    const s = ev.start;
+    return s.getHours() === 0 && s.getMinutes() === 0 && s.getSeconds() === 0;
+}
+/**
+ * Compute how an event appears on a specific day.
+ * Returns null if the event doesn't overlap the day.
+ */
+export function segmentForDay(ev, dayMs) {
+    const dayStart = sod(dayMs);
+    const dayEnd = dayStart + DAY_MS;
+    const evStart = ev.start.getTime();
+    const evEnd = ev.end.getTime();
+    // No overlap
+    if (evStart >= dayEnd || evEnd <= dayStart)
+        return null;
+    const firstDayMs = sod(evStart);
+    // For end time: if event ends exactly at midnight, last day is the day before
+    const lastDayMs = sod(evEnd - 1);
+    const totalDays = Math.round((lastDayMs - firstDayMs) / DAY_MS) + 1;
+    const dayIndex = Math.round((dayStart - firstDayMs) / DAY_MS) + 1;
+    return {
+        ev,
+        start: new Date(Math.max(evStart, dayStart)),
+        end: new Date(Math.min(evEnd, dayEnd)),
+        isStart: dayStart === firstDayMs,
+        isEnd: dayStart === lastDayMs,
+        dayIndex,
+        totalDays,
+        allDay: isAllDay(ev),
+    };
+}