@joewinke/jatui 0.41.1 → 0.42.0

package/dist/components/EventCalendar.svelte.d.ts

@@ -0,0 +1,101 @@
+/**
+     * EventCalendar — month / week / day / agenda event calendar.
+     *
+     * The engine is upstreamed from MOS `CalendarGrid` (jatui-lfxyy): one lane
+     * allocator (`monthPacking`) places every bar and chip in a month row so they
+     * can't collide, lane capacity is measured from the row height, and timed
+     * events in week/day view split concurrent blocks side by side (`dayOverlap`).
+     * The skin takes clean-room ideas from BoardUI Pro's public calendar page:
+     * per-hue event token triplets (`--jatui-event-N{,-bg,-fg}`), a "+N more" that
+     * expands the week in place instead of navigating, a month-switcher pill that
+     * reuses the date-picker panel, and an agenda list.
+     *
+     * The host owns the events. Callbacks are all optional; each one switches a
+     * behaviour on (click to create, drag to move, drag/Shift-select a range).
+     * `onRangeChange` reports the visible range so a host can load just that.
+     *
+     * Keyboard (month): one tab stop on the grid; arrows / Home / End move the day,
+     * PageUp/PageDown change month (Shift = year), Enter creates (or opens the
+     * day), Shift+arrows extend a range when `onRangeSelect` is set. Event chips
+     * are buttons; Escape closes the details popover.
+     */
+import type { Snippet } from 'svelte';
+import { type Weekday } from './calendar/calendarGrid';
+import { type CalendarEventItem, type EventCalendarView } from './calendar/eventCalendar';
+import { type HourCycle } from './calendar/timeSlots';
+declare function $$render<E extends CalendarEventItem = CalendarEventItem>(): {
+    props: {
+        events: E[];
+        /** Current view (bindable). */
+        view?: EventCalendarView;
+        /** The focus date — which month / week / day is shown (bindable). */
+        date?: Date;
+        /** Views offered in the toolbar switcher. */
+        views?: EventCalendarView[];
+        weekStart?: Weekday | "locale";
+        locale?: string;
+        hourCycle?: HourCycle;
+        /** First and last (exclusive) hour of the week/day time grid. */
+        dayStartHour?: number;
+        dayEndHour?: number;
+        /** Pixel height of one hour in week/day view. */
+        hourHeight?: number;
+        /** Hour the time grid scrolls to on first show. */
+        scrollToHour?: number;
+        /** CSS height of the calendar body. */
+        height?: string;
+        toolbar?: boolean;
+        /** Extra toolbar content (filters, a "New event" button). */
+        toolbarEnd?: Snippet;
+        /** Custom chip content. */
+        eventContent?: Snippet<[E, {
+            view: EventCalendarView;
+            time: string;
+        }]>;
+        /** Details popover content, opened by clicking a chip. Gets the event and a close fn. */
+        eventDetails?: Snippet<[E, () => void]>;
+        /** `expand` (default): "+N more" grows the week in place. `day`: open day view. */
+        moreAction?: "expand" | "day";
+        onEventClick?: (ev: E, e: MouseEvent) => void;
+        /** Day number clicked. Defaults to opening day view when it is offered. */
+        onDayClick?: (date: Date) => void;
+        /** Empty cell / hour slot activated — the host opens its create flow. */
+        onCreate?: (date: Date, hour: number | undefined, e: MouseEvent | KeyboardEvent) => void;
+        /** Chip dropped on a day (and hour, in week/day view). Turns drag-to-move on. */
+        onEventMove?: (ev: E, target: {
+            date: Date;
+            hour?: number;
+            allDay: boolean;
+        }) => void;
+        /** Month cells dragged (or Shift+arrowed) across. */
+        onRangeSelect?: (start: Date, end: Date) => void;
+        /** The visible range changed — load events for it. */
+        onRangeChange?: (range: {
+            start: Date;
+            end: Date;
+        }, view: EventCalendarView) => void;
+        ariaLabel?: string;
+        class?: string;
+    };
+    exports: {};
+    bindings: "date" | "view";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<E extends CalendarEventItem = CalendarEventItem> {
+    props(): ReturnType<typeof $$render<E>>['props'];
+    events(): ReturnType<typeof $$render<E>>['events'];
+    slots(): ReturnType<typeof $$render<E>>['slots'];
+    bindings(): "date" | "view";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <E extends CalendarEventItem = CalendarEventItem>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<E>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<E>['props']>, ReturnType<__sveltets_Render<E>['events']>, ReturnType<__sveltets_Render<E>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<E>['bindings']>;
+    } & ReturnType<__sveltets_Render<E>['exports']>;
+    <E extends CalendarEventItem = CalendarEventItem>(internal: unknown, props: ReturnType<__sveltets_Render<E>['props']> & {}): ReturnType<__sveltets_Render<E>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const EventCalendar: $$IsomorphicComponent;
+type EventCalendar<E extends CalendarEventItem = CalendarEventItem> = InstanceType<typeof EventCalendar<E>>;
+export default EventCalendar;

package/dist/components/TimeSlotPicker.svelte

@@ -4,9 +4,31 @@
 	 *
 	 * Accepts an array of TimeSlot objects with `start` (Date), `end` (Date), and `available` (boolean).
 	 * Grouped automatically by hour: morning (<12), afternoon (<17), evening (17+).
+	 *
+	 * jatui-lfxyy upgrades (all additive):
+	 * - One `role="radiogroup"`; each slot is a `role="radio"` with `aria-checked`
+	 *   and a full accessible name ("Wednesday, March 4, 9:30 AM"). Roving focus:
+	 *   arrows move between available slots (Up/Down jump a visual row), Home/End,
+	 *   Space/Enter choose. `selectOnFocus` makes arrows choose too (radio
+	 *   default) — off by default because choosing usually advances a booking flow.
+	 * - `hourCycle` ('h12' | 'h23') and `timeZone` (IANA): times and the
+	 *   morning/afternoon/evening grouping follow the zone's wall clock.
+	 * - `timezone` snippet: a row above the slots for a zone picker / 12-24h toggle.
+	 * - The accent comes from a static token map (the old interpolated
+	 *   `bg-${accentColor}` classes were never generated by Tailwind).
 	 */
 
+	import type { Snippet } from 'svelte';
 	import type { TimeSlot } from '../types/booking';
+	import {
+		formatSlotLabel,
+		formatSlotTime,
+		groupSlotsByDayPart,
+		nextSlotIndex,
+		type DayPart,
+		type HourCycle
+	} from './calendar/timeSlots';
+	import { calendarAccentStyle } from './calendar/calendarGrid';
 
 	export type { TimeSlot };
 
@@ -16,6 +38,14 @@
 		onSelect,
 		selectedSlot = null,
 		accentColor = 'primary',
+		hourCycle = 'h12',
+		timeZone,
+		locale = 'en-US',
+		selectOnFocus = false,
+		ariaLabel = 'Available times',
+		emptyTitle = 'No Available Times',
+		emptyMessage = 'Please select a different date.',
+		timezone
 	}: {
 		slots: TimeSlot[];
 		loading?: boolean;
@@ -24,153 +54,189 @@
 		 * Compared by start-time value (not object identity) so a re-fetched
 		 * slots array still matches the selection. */
 		selectedSlot?: TimeSlot | null;
+		/** primary | secondary | accent | info | success | warning | error | neutral */
 		accentColor?: string;
+		/** 'h12' → "9:30 AM", 'h23' → "09:30". */
+		hourCycle?: HourCycle;
+		/** IANA zone the times (and their grouping) are shown in. Defaults to the runtime zone. */
+		timeZone?: string;
+		locale?: string;
+		/** Arrow keys also choose the slot they land on (strict radio behaviour). */
+		selectOnFocus?: boolean;
+		ariaLabel?: string;
+		emptyTitle?: string;
+		emptyMessage?: string;
+		/** Rendered above the slot list — a time-zone row or a 12/24h toggle. */
+		timezone?: Snippet;
 	} = $props();
 
+	const uid = `tsp-${Math.random().toString(36).slice(2, 8)}`;
+	const PART_LABEL: Record<DayPart, string> = { morning: 'Morning', afternoon: 'Afternoon', evening: 'Evening' };
+
 	const isSelected = (slot: TimeSlot): boolean =>
 		selectedSlot != null && slot.start.getTime() === selectedSlot.start.getTime();
 
-	const groupedSlots = $derived(() => {
-		const morning: TimeSlot[] = [];
-		const afternoon: TimeSlot[] = [];
-		const evening: TimeSlot[] = [];
+	const groups = $derived(groupSlotsByDayPart(slots, timeZone));
+	/** Slots in visual order (group by group) — the roving-focus sequence. */
+	const ordered = $derived(groups.flatMap((g) => g.slots));
+	const availableCount = $derived(slots.filter((s) => s.available).length);
 
-		for (const slot of slots) {
-			const hour = slot.start.getHours();
-			if (hour < 12) {
-				morning.push(slot);
-			} else if (hour < 17) {
-				afternoon.push(slot);
-			} else {
-				evening.push(slot);
-			}
-		}
+	let rootEl = $state<HTMLDivElement | null>(null);
+	let focusIndex = $state(-1);
 
-		return { morning, afternoon, evening };
+	/** The one slot in the tab order: the focused one, else the selection, else the first available. */
+	const tabIndexSlot = $derived.by(() => {
+		if (focusIndex >= 0 && ordered[focusIndex]?.available) return focusIndex;
+		const sel = ordered.findIndex((s) => s.available && isSelected(s));
+		if (sel >= 0) return sel;
+		return ordered.findIndex((s) => s.available);
 	});
 
-	function formatTime(date: Date): string {
-		return date.toLocaleTimeString('en-US', {
-			hour: 'numeric',
-			minute: '2-digit',
-			hour12: true
-		});
+	function handleSlotClick(slot: TimeSlot, index: number) {
+		focusIndex = index;
+		if (slot.available) onSelect(slot);
+	}
+
+	/** Columns in the slot's own grid row, read from layout (3 on mobile, 4 from sm). */
+	function columnsAt(el: HTMLElement): number {
+		const grid = el.parentElement;
+		if (!grid) return 1;
+		const cols = getComputedStyle(grid).gridTemplateColumns.split(' ').filter(Boolean).length;
+		return cols || 1;
 	}
 
-	function handleSlotClick(slot: TimeSlot) {
-		if (slot.available) {
-			onSelect(slot);
+	function handleKeydown(e: KeyboardEvent, index: number) {
+		if (e.key === ' ' || e.key === 'Enter') {
+			e.preventDefault();
+			const slot = ordered[index];
+			if (slot?.available) onSelect(slot);
+			return;
 		}
+		const rtl = getComputedStyle(e.currentTarget as HTMLElement).direction === 'rtl';
+		const next = nextSlotIndex(ordered, index, e.key, { columns: columnsAt(e.currentTarget as HTMLElement), rtl });
+		if (next === null) return;
+		e.preventDefault();
+		focusIndex = next;
+		rootEl?.querySelector<HTMLElement>(`[data-slot-index="${next}"]`)?.focus();
+		if (selectOnFocus && ordered[next]?.available) onSelect(ordered[next]);
 	}
 </script>
 
-<div class="time-slot-picker">
+<div class="time-slot-picker" style={calendarAccentStyle(accentColor)} bind:this={rootEl}>
+	{#if timezone}
+		<div class="time-slot-picker__tz">{@render timezone()}</div>
+	{/if}
+
 	{#if loading}
-		<div class="flex justify-center py-12">
-			<span class="loading loading-spinner loading-lg text-{accentColor}"></span>
+		<div class="flex justify-center py-12" role="status" aria-label="Loading times">
+			<span class="loading loading-spinner loading-lg time-slot-picker__spinner"></span>
 		</div>
 	{:else if slots.length === 0}
 		<div class="text-center py-12">
 			<div class="w-16 h-16 mx-auto mb-4 rounded-full bg-base-200 flex items-center justify-center">
 				<!-- Clock icon -->
-				<svg class="w-8 h-8 text-base-content/40" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+				<svg class="w-8 h-8 text-base-content/40" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
 					<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
 				</svg>
 			</div>
-			<h3 class="text-lg font-semibold mb-2">No Available Times</h3>
-			<p class="text-base-content/60">Please select a different date.</p>
+			<h3 class="text-lg font-semibold mb-2">{emptyTitle}</h3>
+			<p class="text-base-content/60">{emptyMessage}</p>
 		</div>
 	{:else}
-		{@const { morning, afternoon, evening } = groupedSlots()}
-		{@const availableCount = slots.filter(s => s.available).length}
-
 		<p class="text-[0.8125rem] text-base-content/45 mb-4">
 			{availableCount} time{availableCount !== 1 ? 's' : ''} available
 		</p>
 
-		<div class="space-y-6">
-			{#if morning.length > 0}
-				<div>
-					<h4 class="text-[0.8125rem] text-base-content/45 mb-3 flex items-center gap-2 tracking-[0.005em]">
-						<!-- Sun icon -->
-						<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-							<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z" />
-						</svg>
-						Morning
+		<div class="space-y-6" role="radiogroup" aria-label={ariaLabel}>
+			{#each groups as group (group.part)}
+				{@const offset = ordered.indexOf(group.slots[0])}
+				<div role="group" aria-labelledby="{uid}-{group.part}">
+					<h4 id="{uid}-{group.part}" class="text-[0.8125rem] text-base-content/45 mb-3 flex items-center gap-2 tracking-[0.005em]">
+						{#if group.part === 'evening'}
+							<!-- Moon icon -->
+							<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+								<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z" />
+							</svg>
+						{:else}
+							<!-- Sun icon -->
+							<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+								<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z" />
+							</svg>
+						{/if}
+						{PART_LABEL[group.part]}
 					</h4>
 					<div class="grid grid-cols-3 sm:grid-cols-4 gap-2">
-						{#each morning as slot}
+						{#each group.slots as slot, j (slot.start.getTime())}
+							{@const index = offset + j}
 							<button
-								onclick={() => handleSlotClick(slot)}
-								disabled={!slot.available}
-								class="py-3 px-4 rounded-lg text-[0.9375rem] font-medium transition-all duration-200
-									{slot.available
-										? isSelected(slot)
-											? `bg-${accentColor} text-${accentColor}-content ring-2 ring-${accentColor} ring-offset-2 ring-offset-base-100 font-semibold`
-											: `bg-base-200/50 hover:bg-${accentColor} hover:text-${accentColor}-content`
-										: 'bg-base-200/20 text-base-content/30 cursor-not-allowed line-through'}"
+								type="button"
+								role="radio"
+								aria-checked={isSelected(slot)}
+								aria-disabled={!slot.available ? 'true' : undefined}
+								aria-label="{formatSlotLabel(slot.start, { hourCycle, timeZone, locale })}{slot.available ? '' : ', unavailable'}"
+								tabindex={index === tabIndexSlot ? 0 : -1}
+								data-slot-index={index}
+								onclick={() => handleSlotClick(slot, index)}
+								onkeydown={(e) => handleKeydown(e, index)}
+								onfocus={() => (focusIndex = index)}
+								class="time-slot-picker__slot py-3 px-4 rounded-lg text-[0.9375rem] font-medium tabular-nums"
+								class:is-selected={slot.available && isSelected(slot)}
+								class:is-unavailable={!slot.available}
 							>
-								{formatTime(slot.start)}
+								{formatSlotTime(slot.start, { hourCycle, timeZone, locale })}
 							</button>
 						{/each}
 					</div>
 				</div>
-			{/if}
-
-			{#if afternoon.length > 0}
-				<div>
-					<h4 class="text-[0.8125rem] text-base-content/45 mb-3 flex items-center gap-2 tracking-[0.005em]">
-						<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-							<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z" />
-						</svg>
-						Afternoon
-					</h4>
-					<div class="grid grid-cols-3 sm:grid-cols-4 gap-2">
-						{#each afternoon as slot}
-							<button
-								onclick={() => handleSlotClick(slot)}
-								disabled={!slot.available}
-								class="py-3 px-4 rounded-lg text-[0.9375rem] font-medium transition-all duration-200
-									{slot.available
-										? isSelected(slot)
-											? `bg-${accentColor} text-${accentColor}-content ring-2 ring-${accentColor} ring-offset-2 ring-offset-base-100 font-semibold`
-											: `bg-base-200/50 hover:bg-${accentColor} hover:text-${accentColor}-content`
-										: 'bg-base-200/20 text-base-content/30 cursor-not-allowed line-through'}"
-							>
-								{formatTime(slot.start)}
-							</button>
-						{/each}
-					</div>
-				</div>
-			{/if}
-
-			{#if evening.length > 0}
-				<div>
-					<h4 class="text-[0.8125rem] text-base-content/45 mb-3 flex items-center gap-2 tracking-[0.005em]">
-						<!-- Moon icon -->
-						<svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-							<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z" />
-						</svg>
-						Evening
-					</h4>
-					<div class="grid grid-cols-3 sm:grid-cols-4 gap-2">
-						{#each evening as slot}
-							<button
-								onclick={() => handleSlotClick(slot)}
-								disabled={!slot.available}
-								class="py-3 px-4 rounded-lg text-[0.9375rem] font-medium transition-all duration-200
-									{slot.available
-										? isSelected(slot)
-											? `bg-${accentColor} text-${accentColor}-content ring-2 ring-${accentColor} ring-offset-2 ring-offset-base-100 font-semibold`
-											: `bg-base-200/50 hover:bg-${accentColor} hover:text-${accentColor}-content`
-										: 'bg-base-200/20 text-base-content/30 cursor-not-allowed line-through'}"
-							>
-								{formatTime(slot.start)}
-							</button>
-						{/each}
-					</div>
-				</div>
-			{/if}
+			{/each}
 		</div>
 	{/if}
 </div>
+
+<style>
+	.time-slot-picker {
+		--_accent: var(--jatui-cal-accent, var(--jatui-selection-solid, var(--color-primary)));
+		--_accent-fg: var(--jatui-cal-accent-fg, var(--jatui-selection-solid-fg, var(--color-primary-content)));
+	}
+	.time-slot-picker__tz {
+		margin-block-end: 0.75rem;
+	}
+	.time-slot-picker__spinner {
+		color: var(--_accent);
+	}
+	.time-slot-picker__slot {
+		background: color-mix(in oklab, var(--color-base-200) 50%, transparent);
+		color: var(--color-base-content);
+		cursor: pointer;
+		transition:
+			background-color var(--motion-fast, 150ms) var(--motion-standard, ease),
+			color var(--motion-fast, 150ms) var(--motion-standard, ease);
+	}
+	.time-slot-picker__slot:hover:not(.is-unavailable):not(.is-selected) {
+		background: var(--_accent);
+		color: var(--_accent-fg);
+	}
+	.time-slot-picker__slot:focus-visible {
+		outline: var(--jatui-focus-ring-width, 2px) solid var(--jatui-focus-ring, var(--color-primary));
+		outline-offset: var(--jatui-focus-ring-offset, 2px);
+	}
+	.time-slot-picker__slot.is-selected {
+		background: var(--_accent);
+		color: var(--_accent-fg);
+		font-weight: 600;
+		box-shadow:
+			0 0 0 2px var(--color-base-100),
+			0 0 0 4px var(--_accent);
+	}
+	.time-slot-picker__slot.is-unavailable {
+		background: color-mix(in oklab, var(--color-base-200) 20%, transparent);
+		color: color-mix(in oklab, var(--color-base-content) 30%, transparent);
+		cursor: not-allowed;
+		text-decoration: line-through;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.time-slot-picker__slot {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/TimeSlotPicker.svelte.d.ts

@@ -3,8 +3,22 @@
      *
      * Accepts an array of TimeSlot objects with `start` (Date), `end` (Date), and `available` (boolean).
      * Grouped automatically by hour: morning (<12), afternoon (<17), evening (17+).
+     *
+     * jatui-lfxyy upgrades (all additive):
+     * - One `role="radiogroup"`; each slot is a `role="radio"` with `aria-checked`
+     *   and a full accessible name ("Wednesday, March 4, 9:30 AM"). Roving focus:
+     *   arrows move between available slots (Up/Down jump a visual row), Home/End,
+     *   Space/Enter choose. `selectOnFocus` makes arrows choose too (radio
+     *   default) — off by default because choosing usually advances a booking flow.
+     * - `hourCycle` ('h12' | 'h23') and `timeZone` (IANA): times and the
+     *   morning/afternoon/evening grouping follow the zone's wall clock.
+     * - `timezone` snippet: a row above the slots for a zone picker / 12-24h toggle.
+     * - The accent comes from a static token map (the old interpolated
+     *   `bg-${accentColor}` classes were never generated by Tailwind).
      */
+import type { Snippet } from 'svelte';
 import type { TimeSlot } from '../types/booking';
+import { type HourCycle } from './calendar/timeSlots';
 type $$ComponentProps = {
     slots: TimeSlot[];
     loading?: boolean;
@@ -13,7 +27,20 @@ type $$ComponentProps = {
      * Compared by start-time value (not object identity) so a re-fetched
      * slots array still matches the selection. */
     selectedSlot?: TimeSlot | null;
+    /** primary | secondary | accent | info | success | warning | error | neutral */
     accentColor?: string;
+    /** 'h12' → "9:30 AM", 'h23' → "09:30". */
+    hourCycle?: HourCycle;
+    /** IANA zone the times (and their grouping) are shown in. Defaults to the runtime zone. */
+    timeZone?: string;
+    locale?: string;
+    /** Arrow keys also choose the slot they land on (strict radio behaviour). */
+    selectOnFocus?: boolean;
+    ariaLabel?: string;
+    emptyTitle?: string;
+    emptyMessage?: string;
+    /** Rendered above the slot list — a time-zone row or a 12/24h toggle. */
+    timezone?: Snippet;
 };
 declare const TimeSlotPicker: import("svelte").Component<$$ComponentProps, {
     TimeSlot: typeof TimeSlot;

package/dist/components/calendar/CalendarHeader.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+	/**
+	 * CalendarHeader — previous/next month buttons around a live month title.
+	 * Shared by every month panel (CalendarPicker, DatePicker, DateRangePicker,
+	 * BookingScheduler). `title` replaces the plain heading (EventCalendar uses it
+	 * for its month-switcher pill).
+	 */
+	import type { Snippet } from 'svelte';
+	import IconButton from '../IconButton.svelte';
+
+	let {
+		label,
+		onPrev,
+		onNext,
+		canPrev = true,
+		canNext = true,
+		size = 'md',
+		hidePrev = false,
+		hideNext = false,
+		prevLabel = 'Previous month',
+		nextLabel = 'Next month',
+		title
+	}: {
+		label: string;
+		onPrev?: () => void;
+		onNext?: () => void;
+		canPrev?: boolean;
+		canNext?: boolean;
+		size?: 'sm' | 'md';
+		/** Hide one arrow (the inner edges of a two-month view). Keeps its space. */
+		hidePrev?: boolean;
+		hideNext?: boolean;
+		prevLabel?: string;
+		nextLabel?: string;
+		title?: Snippet;
+	} = $props();
+</script>
+
+<div class="jatui-cal-header">
+	<span class:jatui-cal-header__ghost={hidePrev}>
+		<IconButton
+			label={prevLabel}
+			size={size === 'sm' ? 'xs' : 'sm'}
+			shape="circle"
+			disabled={!canPrev || hidePrev}
+			onclick={() => onPrev?.()}
+		>
+			<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true" class="jatui-cal-header__chev">
+				<path stroke-linecap="round" stroke-linejoin="round" d="M15 19l-7-7 7-7" />
+			</svg>
+		</IconButton>
+	</span>
+	{#if title}
+		{@render title()}
+	{:else}
+		<h3 class="jatui-cal-header__title" class:is-sm={size === 'sm'} aria-live="polite">{label}</h3>
+	{/if}
+	<span class:jatui-cal-header__ghost={hideNext}>
+		<IconButton
+			label={nextLabel}
+			size={size === 'sm' ? 'xs' : 'sm'}
+			shape="circle"
+			disabled={!canNext || hideNext}
+			onclick={() => onNext?.()}
+		>
+			<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true" class="jatui-cal-header__chev">
+				<path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7" />
+			</svg>
+		</IconButton>
+	</span>
+</div>
+
+<style>
+	.jatui-cal-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.5rem;
+		margin-block-end: 0.5rem;
+	}
+	.jatui-cal-header__title {
+		margin: 0;
+		font-size: 1rem;
+		font-weight: 600;
+		text-align: center;
+		flex: 1;
+	}
+	.jatui-cal-header__title.is-sm {
+		font-size: 0.875rem;
+	}
+	.jatui-cal-header__ghost {
+		visibility: hidden;
+	}
+	/* Chevrons point the reading direction. */
+	:global([dir='rtl']) .jatui-cal-header__chev {
+		transform: scaleX(-1);
+	}
+</style>

package/dist/components/calendar/CalendarHeader.svelte.d.ts

@@ -0,0 +1,24 @@
+/**
+     * CalendarHeader — previous/next month buttons around a live month title.
+     * Shared by every month panel (CalendarPicker, DatePicker, DateRangePicker,
+     * BookingScheduler). `title` replaces the plain heading (EventCalendar uses it
+     * for its month-switcher pill).
+     */
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    label: string;
+    onPrev?: () => void;
+    onNext?: () => void;
+    canPrev?: boolean;
+    canNext?: boolean;
+    size?: 'sm' | 'md';
+    /** Hide one arrow (the inner edges of a two-month view). Keeps its space. */
+    hidePrev?: boolean;
+    hideNext?: boolean;
+    prevLabel?: string;
+    nextLabel?: string;
+    title?: Snippet;
+};
+declare const CalendarHeader: import("svelte").Component<$$ComponentProps, {}, "">;
+type CalendarHeader = ReturnType<typeof CalendarHeader>;
+export default CalendarHeader;