@happyvertical/smrt-ui 0.51.39 → 0.52.0

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

@@ -0,0 +1,66 @@
+/**
+ * CalendarView — a generic month calendar with a phone agenda.
+ *
+ * - `month` mode: a month grid (`role="grid"`, roving focus, arrow keys).
+ *   All-day and multi-day items render as bands across the days they cover;
+ *   a day that has more than fits shows "+N more", which opens the day in a
+ *   panel under the grid (never a modal) or follows `dayHref`.
+ * - `agenda` mode: a scrollable strip of the month's days above a day-by-day
+ *   list. `auto` (default) uses the agenda below 48rem, the grid above.
+ *
+ * Every day is computed in `timeZone` (IANA) and every name comes from
+ * `Intl` in `locale`, so the browser's own zone and language never leak in.
+ * The visible month and selected day can be controlled (`year`/`month`,
+ * `selectedDate`) and are reported through `onNavigate` / `onSelectDate`,
+ * so a page can keep them in its URL.
+ */
+import type { Snippet } from 'svelte';
+import { type CalendarItem, type CalendarMode, type CalendarMonth } from './calendar-model.js';
+export interface Props {
+    /** Items to show. */
+    items?: CalendarItem[];
+    /** Visible year (controlled together with `month`). */
+    year?: number;
+    /** Visible month, 1-12 (controlled together with `year`). */
+    month?: number;
+    /** Selected day as `YYYY-MM-DD` (controlled). */
+    selectedDate?: string | null;
+    /** IANA time zone every day is computed in. Defaults to the browser's. */
+    timeZone?: string;
+    /** BCP 47 locale for month/day names and times. Defaults to the i18n locale. */
+    locale?: string;
+    /** First weekday column, 0 = Sunday. Defaults to the locale's. */
+    weekStartsOn?: number;
+    /** `auto` switches to the agenda below 48rem. */
+    mode?: CalendarMode;
+    /** Rows per day in the month grid, including band rows. */
+    maxPerDay?: number;
+    /** Heading level of the month title. */
+    headingLevel?: 2 | 3 | 4;
+    /**
+     * "Now", for today highlighting (tests, server rendering). Without it the
+     * calendar reads the clock after mount and moves "today" at midnight in
+     * `timeZone`; before mount (server rendering) nothing is highlighted as
+     * today. Server-rendered pages should pass `timeZone` and `year`/`month`
+     * (or `now`) so the server and the browser pick the same month.
+     */
+    now?: Date;
+    /** Called when the visible month changes (prev/next/today/keyboard). */
+    onNavigate?: (month: CalendarMonth) => void;
+    /** Called when a day is selected. */
+    onSelectDate?: (date: string) => void;
+    /** Called when an item is activated (also for items with `href`). */
+    onItemSelect?: (item: CalendarItem) => void;
+    /** Link for a day; days become links and "+N more" follows it. */
+    dayHref?: (date: string) => string | undefined;
+    /** Custom row content for an item in the day panel and agenda. */
+    itemContent?: Snippet<[CalendarItem, {
+        time: string;
+    }]>;
+    /** Extra class on the root. */
+    class?: string;
+}
+declare const CalendarView: import("svelte").Component<Props, {}, "">;
+type CalendarView = ReturnType<typeof CalendarView>;
+export default CalendarView;
+//# sourceMappingURL=CalendarView.svelte.d.ts.map

package/dist/components/calendar/CalendarView.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CalendarView.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/calendar/CalendarView.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAItC,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAgBnB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,KAAK;IACpB,qBAAqB;IACrB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,wEAAwE;IACxE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,qCAAqC;IACrC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5C,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,kEAAkE;IAClE,WAAW,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACxD,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyiBD,QAAA,MAAM,YAAY,2CAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/calendar/DayView.svelte

@@ -2,6 +2,11 @@
 /**
  * DayView Component
  * Full event list for a specific day with optional weather
+ *
+ * @deprecated Use `CalendarView` (its day panel, agenda mode, or `dayHref`
+ * to a page of your own). This component formats dates as `en-US` in the
+ * browser zone and hard-codes game/meeting routes. See the smrt-ui README,
+ * "Calendar", for the migration.
  */
 
 import { M } from '../../i18n/strings.ui.js';

package/dist/components/calendar/DayView.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DayView.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/calendar/DayView.svelte.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvE,MAAM,WAAW,KAAK;IACpB,+CAA+C;IAC/C,IAAI,EAAE,IAAI,CAAC;IACX,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D;AA6JD,QAAA,MAAM,OAAO,2CAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}
+{"version":3,"file":"DayView.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/calendar/DayView.svelte.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvE,MAAM,WAAW,KAAK;IACpB,+CAA+C;IAC/C,IAAI,EAAE,IAAI,CAAC;IACX,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D;AA6JD,QAAA,MAAM,OAAO,2CAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/components/calendar/__tests__/CalendarView.test.js

@@ -0,0 +1,226 @@
+import { act, render, screen, within } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import { expectNoA11yViolations } from '../../../test-support/a11y';
+import CalendarView from '../CalendarView.svelte';
+const tz = 'America/Edmonton';
+const now = new Date('2026-09-29T18:00:00Z');
+const items = [
+    { id: 'fair', title: 'Fall Fair', start: '2026-09-05', end: '2026-09-07' },
+    {
+        id: 'council',
+        title: 'Council meeting',
+        start: new Date('2026-09-15T01:00:00Z'),
+        label: 'Council',
+        href: '/meetings/sept',
+    },
+    { id: 'a', title: 'Game A', start: new Date('2026-09-20T18:00:00Z') },
+    { id: 'b', title: 'Game B', start: new Date('2026-09-20T19:00:00Z') },
+    { id: 'c', title: 'Game C', start: new Date('2026-09-20T20:00:00Z') },
+    { id: 'd', title: 'Game D', start: new Date('2026-09-20T21:00:00Z') },
+];
+function renderMonth(props = {}) {
+    return render(CalendarView, {
+        props: {
+            items,
+            timeZone: tz,
+            locale: 'en-US',
+            weekStartsOn: 0,
+            mode: 'month',
+            now,
+            year: 2026,
+            month: 9,
+            ...props,
+        },
+    });
+}
+describe('CalendarView (month)', () => {
+    it('renders a localized grid in the given zone', () => {
+        renderMonth();
+        expect(screen.getByRole('heading', { name: 'September 2026' })).toBeTruthy();
+        expect(screen.getByRole('grid')).toBeTruthy();
+        expect(screen.getAllByRole('columnheader')).toHaveLength(7);
+        // 19:00 MDT on the 14th, not the 15th (UTC)
+        expect(screen.getByRole('button', {
+            name: 'Monday, September 14, 2026, 1 item',
+        })).toBeTruthy();
+        expect(screen
+            .getByRole('button', { name: 'Tuesday, September 29, 2026' })
+            .getAttribute('aria-current')).toBe('date');
+    });
+    it('renders month names in the requested locale', () => {
+        renderMonth({ locale: 'fr-FR' });
+        expect(screen.getByRole('heading').textContent?.trim()).toBe('septembre 2026');
+    });
+    it('renders all-day spans as bands and overflow as +N more', async () => {
+        const onSelectDate = vi.fn();
+        const { container } = renderMonth({ onSelectDate });
+        // Sat Sep 5 - Mon Sep 7 wraps: one segment per week row.
+        const bands = [...container.querySelectorAll('.cv-band')];
+        expect(bands.map((b) => b.textContent?.trim())).toEqual([
+            'Fall Fair',
+            'Fall Fair',
+        ]);
+        expect(bands[0].style.gridColumn).toBe('7 / span 1');
+        expect(bands[0].classList.contains('cv-band--after')).toBe(true);
+        expect(bands[1].style.gridColumn).toBe('1 / span 2');
+        expect(bands[1].classList.contains('cv-band--before')).toBe(true);
+        const more = screen.getByText('+2 more');
+        await userEvent.click(more);
+        expect(onSelectDate).toHaveBeenCalledWith('2026-09-20');
+        const panel = screen.getByRole('region', {
+            name: 'Sunday, September 20, 2026',
+        });
+        expect(within(panel).getAllByRole('button', { name: /Game/ })).toHaveLength(4);
+        await userEvent.click(within(panel).getByRole('button', {
+            name: 'Close Sunday, September 20, 2026',
+        }));
+        expect(screen.queryByRole('region')).toBeNull();
+    });
+    it('navigates with prev/next/today and reports the month', async () => {
+        const onNavigate = vi.fn();
+        render(CalendarView, {
+            props: {
+                items,
+                timeZone: tz,
+                locale: 'en-US',
+                mode: 'month',
+                now,
+                onNavigate,
+            },
+        });
+        await userEvent.click(screen.getByRole('button', { name: 'Next month' }));
+        expect(onNavigate).toHaveBeenLastCalledWith({ year: 2026, month: 10 });
+        expect(screen.getByRole('heading').textContent?.trim()).toBe('October 2026');
+        await userEvent.click(screen.getByRole('button', { name: 'Today' }));
+        expect(onNavigate).toHaveBeenLastCalledWith({ year: 2026, month: 9 });
+    });
+    it('moves focus with arrow keys and crosses months', async () => {
+        const onNavigate = vi.fn();
+        renderMonth({ onNavigate, year: undefined, month: undefined });
+        const today = screen.getByRole('button', {
+            name: 'Tuesday, September 29, 2026',
+        });
+        expect(today.tabIndex).toBe(0);
+        today.focus();
+        await userEvent.keyboard('{ArrowRight}');
+        expect(document.activeElement.dataset.cvDay).toBe('2026-09-30');
+        await userEvent.keyboard('{ArrowRight}');
+        expect(onNavigate).toHaveBeenLastCalledWith({ year: 2026, month: 10 });
+        expect(document.activeElement.dataset.cvDay).toBe('2026-10-01');
+        await userEvent.keyboard('{ArrowUp}');
+        expect(document.activeElement.dataset.cvDay).toBe('2026-09-24');
+        await userEvent.keyboard('{Home}');
+        expect(document.activeElement.dataset.cvDay).toBe('2026-09-20');
+    });
+    it('turns days into links with dayHref', () => {
+        renderMonth({ dayHref: (d) => `/events/${d}` });
+        const link = screen.getByRole('link', {
+            name: 'Monday, September 14, 2026, 1 item',
+        });
+        expect(link.getAttribute('href')).toBe('/events/2026-09-14');
+    });
+});
+describe('CalendarView accessibility', () => {
+    it('is axe-clean in month mode with an open day', async () => {
+        const { container } = renderMonth({ selectedDate: '2026-09-20' });
+        await expectNoA11yViolations(container);
+    });
+    it('is axe-clean in agenda mode', async () => {
+        const { container } = renderMonth({ mode: 'agenda' });
+        await expectNoA11yViolations(container);
+    });
+});
+describe('CalendarView (agenda)', () => {
+    it('lists days with items and a day strip', async () => {
+        const onItemSelect = vi.fn();
+        render(CalendarView, {
+            props: {
+                items,
+                timeZone: tz,
+                locale: 'en-US',
+                mode: 'agenda',
+                now,
+                year: 2026,
+                month: 9,
+                onItemSelect,
+            },
+        });
+        const strip = screen.getByRole('toolbar', {
+            name: 'Days in September 2026',
+        });
+        expect(within(strip).getAllByRole('button')).toHaveLength(30);
+        const headings = screen
+            .getAllByRole('heading', { level: 3 })
+            .map((h) => h.textContent?.trim());
+        expect(headings).toEqual([
+            'Saturday, September 5, 2026',
+            'Sunday, September 6, 2026',
+            'Monday, September 7, 2026',
+            'Monday, September 14, 2026',
+            'Sunday, September 20, 2026',
+        ]);
+        const link = screen.getByRole('link', { name: /Council meeting/ });
+        expect(link.getAttribute('href')).toBe('/meetings/sept');
+        expect(link.textContent).toContain('7:00 PM');
+        expect(link.textContent).toContain('Council');
+        expect(screen.getAllByText('Until Sep 7').length).toBeGreaterThan(0);
+        await userEvent.click(within(strip).getByRole('button', {
+            name: 'Thursday, September 10, 2026',
+        }));
+        expect(screen.getByRole('heading', { name: 'Thursday, September 10, 2026' })).toBeTruthy();
+        expect(screen.getAllByText('Nothing scheduled').length).toBe(1);
+    });
+    it('switches to the agenda on phones in auto mode', async () => {
+        const matchMedia = vi.fn().mockImplementation((query) => ({
+            matches: query === '(max-width: 48rem)',
+            media: query,
+            addEventListener: vi.fn(),
+            removeEventListener: vi.fn(),
+        }));
+        vi.stubGlobal('matchMedia', matchMedia);
+        try {
+            const { container } = render(CalendarView, {
+                props: { items, timeZone: tz, locale: 'en-US', now },
+            });
+            await Promise.resolve();
+            expect(container.querySelector('[data-view]')?.getAttribute('data-view')).toBe('agenda');
+            expect(screen.queryByRole('grid')).toBeNull();
+        }
+        finally {
+            vi.unstubAllGlobals();
+        }
+    });
+});
+describe('CalendarView robustness', () => {
+    it('falls back instead of throwing on an invalid time zone', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            expect(() => renderMonth({ timeZone: 'Mars/Olympus_Mons' })).not.toThrow();
+            expect(screen.getByRole('heading', { name: 'September 2026' })).toBeTruthy();
+            expect(warn).toHaveBeenCalledWith(expect.stringContaining('Mars/Olympus_Mons'));
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('moves the today highlight after midnight without a now prop', async () => {
+        vi.useFakeTimers({ toFake: ['Date', 'setInterval', 'clearInterval'] });
+        try {
+            // 23:59 on Sep 29 in Edmonton (05:59Z on the 30th).
+            vi.setSystemTime(new Date('2026-09-30T05:59:00Z'));
+            renderMonth({ now: undefined });
+            const day = (name) => screen.getByRole('button', { name });
+            await act(() => { });
+            expect(day('Tuesday, September 29, 2026').getAttribute('aria-current')).toBe('date');
+            await act(() => {
+                vi.advanceTimersByTime(2 * 60_000);
+            });
+            expect(day('Wednesday, September 30, 2026').getAttribute('aria-current')).toBe('date');
+            expect(day('Tuesday, September 29, 2026').getAttribute('aria-current')).toBeNull();
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});

package/dist/components/calendar/__tests__/calendar-model.test.js

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { addMonthsToKey, dateKeyInZone, defaultWeekStart, layoutMonth, monthWeeks, shiftMonth, toEntries, toneFor, } from '../calendar-model.js';
+describe('calendar model', () => {
+    it('computes days in the given zone, not the host zone', () => {
+        const instant = new Date('2026-09-29T03:30:00Z');
+        expect(dateKeyInZone(instant, 'America/Edmonton')).toBe('2026-09-28');
+        expect(dateKeyInZone(instant, 'Pacific/Auckland')).toBe('2026-09-29');
+    });
+    it('builds full weeks for any first weekday', () => {
+        const sunday = monthWeeks({ year: 2026, month: 9 }, 0);
+        expect(sunday[0][0]).toBe('2026-08-30');
+        expect(sunday.at(-1)?.[6]).toBe('2026-10-03');
+        const monday = monthWeeks({ year: 2026, month: 9 }, 1);
+        expect(monday[0][0]).toBe('2026-08-31');
+        expect(monday).toHaveLength(5);
+    });
+    it('shifts months and clamps days', () => {
+        expect(shiftMonth({ year: 2026, month: 12 }, 1)).toEqual({
+            year: 2027,
+            month: 1,
+        });
+        expect(shiftMonth({ year: 2026, month: 1 }, -1)).toEqual({
+            year: 2025,
+            month: 12,
+        });
+        expect(addMonthsToKey('2026-01-31', 1)).toBe('2026-02-28');
+    });
+    it('reads the locale week start when the runtime knows it', () => {
+        const start = defaultWeekStart('en-GB');
+        expect([0, 1]).toContain(start);
+        expect(defaultWeekStart('not a locale!')).toBe(0);
+    });
+    it('normalizes all-day dates, exclusive midnights, and timed spans', () => {
+        const tz = 'America/Edmonton';
+        const entries = toEntries([
+            { id: 'a', title: 'Fair', start: '2026-09-05', end: '2026-09-07' },
+            {
+                id: 'b',
+                title: 'Exclusive',
+                allDay: true,
+                start: new Date('2026-09-10T06:00:00Z'),
+                end: new Date('2026-09-12T06:00:00Z'),
+            },
+            {
+                id: 'c',
+                title: 'Late meeting',
+                start: new Date('2026-09-15T01:00:00Z'),
+                end: new Date('2026-09-15T03:00:00Z'),
+            },
+            {
+                id: 'd',
+                title: 'Overnight',
+                start: new Date('2026-09-20T04:00:00Z'),
+                end: new Date('2026-09-20T16:00:00Z'),
+            },
+            { id: 'bad', title: 'Bad', start: 'not a date' },
+        ], tz);
+        const byId = Object.fromEntries(entries.map((e) => [e.item.id, e]));
+        expect(byId.a).toMatchObject({
+            startKey: '2026-09-05',
+            endKey: '2026-09-07',
+            allDay: true,
+            band: true,
+        });
+        expect(byId.b).toMatchObject({
+            startKey: '2026-09-10',
+            endKey: '2026-09-11',
+        });
+        // 19:00-21:00 MDT on the 14th
+        expect(byId.c).toMatchObject({
+            startKey: '2026-09-14',
+            endKey: '2026-09-14',
+            band: false,
+        });
+        // 22:00 on the 19th to 10:00 on the 20th spans two days
+        expect(byId.d).toMatchObject({
+            startKey: '2026-09-19',
+            endKey: '2026-09-20',
+            band: true,
+        });
+        expect(byId.bad).toBeUndefined();
+    });
+    it('lays out bands in lanes and counts overflow as "+N more"', () => {
+        const entries = toEntries([
+            { id: 'span', title: 'Span', start: '2026-09-01', end: '2026-09-09' },
+            { id: 'one', title: 'One', start: '2026-09-02' },
+            {
+                id: 't1',
+                title: 'T1',
+                start: new Date('2026-09-02T15:00:00Z'),
+            },
+            {
+                id: 't2',
+                title: 'T2',
+                start: new Date('2026-09-02T16:00:00Z'),
+            },
+        ], 'UTC');
+        const weeks = layoutMonth({ year: 2026, month: 9 }, entries, {
+            weekStartsOn: 0,
+            maxPerDay: 3,
+        });
+        const first = weeks[0];
+        // Span continues into the next week; "One" takes a second lane.
+        const span = first.bands.find((b) => b.entry.item.id === 'span');
+        expect(span).toMatchObject({ column: 2, span: 5, lane: 0 });
+        expect(span?.continuesAfter).toBe(true);
+        expect(first.lanes).toBe(2);
+        const sep2 = first.days.find((d) => d.key === '2026-09-02');
+        // One row left for timed items; two don't fit, so show none + "+2 more".
+        expect(sep2?.visible).toHaveLength(0);
+        expect(sep2?.hiddenCount).toBe(2);
+        expect(sep2?.all.map((e) => e.item.id)).toEqual([
+            'span',
+            'one',
+            't1',
+            't2',
+        ]);
+        const second = weeks[1];
+        const cont = second.bands.find((b) => b.entry.item.id === 'span');
+        expect(cont).toMatchObject({ column: 0, span: 4, continuesBefore: true });
+    });
+    it('derives a stable tone from the group', () => {
+        const a = toneFor({
+            id: '1',
+            title: 'x',
+            start: '2026-01-01',
+            group: 'council',
+        });
+        const b = toneFor({
+            id: '2',
+            title: 'y',
+            start: '2026-01-01',
+            group: 'council',
+        });
+        expect(a).toBe(b);
+        expect(toneFor({ id: '3', title: 'z', start: '2026-01-01', tone: 'error' })).toBe('error');
+    });
+});

package/dist/components/calendar/calendar-model.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Pure, Svelte-free date model for `CalendarView`.
+ *
+ * Every calendar day is a `YYYY-MM-DD` key in the view's IANA time zone.
+ * Instants are projected into that zone through `Intl` exactly once; all
+ * further math (grids, spans, lanes) runs on keys, so the browser's own zone
+ * never leaks into what a day contains.
+ */
+/** Color tone of a calendar item, mapped to the theme's color roles. */
+export type CalendarTone = 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'error' | 'neutral';
+/** A generic item on the calendar (an event, a meeting, a game, a deadline). */
+export interface CalendarItem {
+    /** Stable identity, used as the render key. */
+    id: string;
+    /** Visible title. */
+    title: string;
+    /**
+     * Start: a `Date`, an ISO date-time string, or a `YYYY-MM-DD` date (which
+     * makes the item all-day unless `allDay` says otherwise).
+     */
+    start: Date | string;
+    /**
+     * End. Timed items: the exclusive end instant. All-day items: a
+     * `YYYY-MM-DD` date is the inclusive last day; an instant at local
+     * midnight is the exclusive end (the day after the last day).
+     */
+    end?: Date | string | null;
+    /** Occupies whole days; rendered as a band in the month grid. */
+    allDay?: boolean;
+    /** Color role. Defaults to one derived from `group`, else `primary`. */
+    tone?: CalendarTone;
+    /** Explicit CSS color; overrides `tone`. */
+    color?: string;
+    /** Short category text shown next to the title in lists (e.g. "Council"). */
+    label?: string;
+    /** Stable grouping key (e.g. a content type); picks a tone when none is set. */
+    group?: string;
+    /** Link target. Without it the item is a button that calls `onItemSelect`. */
+    href?: string;
+}
+/** A visible month; `month` is 1-12 (calendar numbering, not `Date#getMonth`). */
+export interface CalendarMonth {
+    year: number;
+    month: number;
+}
+/** Month grid, agenda list, or month grid above 48rem and agenda below. */
+export type CalendarMode = 'auto' | 'month' | 'agenda';
+/** An item projected onto calendar day keys. */
+export interface CalendarEntry {
+    item: CalendarItem;
+    /** First day (inclusive). */
+    startKey: string;
+    /** Last day (inclusive). */
+    endKey: string;
+    allDay: boolean;
+    /** Rendered as a band: all-day, or spans more than one day. */
+    band: boolean;
+    /** Start instant for timed items; start-of-day ordering for all-day. */
+    startMs: number;
+}
+/** A band segment inside one week row. */
+export interface CalendarBandSegment {
+    entry: CalendarEntry;
+    /** 0-6 column in the week. */
+    column: number;
+    /** Number of columns covered. */
+    span: number;
+    /** 0-based lane (row) inside the week's band area. */
+    lane: number;
+    /** The item started before this week. */
+    continuesBefore: boolean;
+    /** The item ends after this week. */
+    continuesAfter: boolean;
+}
+/** A single day cell in a laid-out week. */
+export interface CalendarDayCell {
+    key: string;
+    day: number;
+    inMonth: boolean;
+    /** Timed single-day items shown in the cell. */
+    visible: CalendarEntry[];
+    /** Items (bands and timed) on this day that did not fit. */
+    hiddenCount: number;
+    /** Every item on this day (bands first, then by start). */
+    all: CalendarEntry[];
+}
+/** One week row of the month grid. */
+export interface CalendarWeek {
+    days: CalendarDayCell[];
+    bands: CalendarBandSegment[];
+    /** Number of band lanes rendered in this week. */
+    lanes: number;
+}
+/** The browser's resolved IANA zone (`UTC` when unavailable). */
+export declare function defaultTimeZone(): string;
+/** Whether `timeZone` is an IANA zone this runtime's `Intl` accepts. */
+export declare function isValidTimeZone(timeZone: unknown): timeZone is string;
+/**
+ * `timeZone` when valid, otherwise the runtime default. `onInvalid` hears
+ * about a rejected non-empty zone (a typo, a zone this runtime lacks), so a
+ * view can warn instead of throwing from its render.
+ */
+export declare function resolveTimeZone(timeZone: string | undefined, onInvalid?: (timeZone: string) => void): string;
+/**
+ * The calendar day of an instant in a time zone.
+ *
+ * @param instant - Instant to project
+ * @param timeZone - IANA time zone
+ * @returns `YYYY-MM-DD`
+ */
+export declare function dateKeyInZone(instant: Date, timeZone: string): string;
+/** Today's `YYYY-MM-DD` in a time zone. */
+export declare function todayKey(timeZone: string, now?: Date): string;
+/** Whether a string is a `YYYY-MM-DD` date key. */
+export declare function isDateKey(value: unknown): value is string;
+/** Build a `YYYY-MM-DD` key (month 1-12). */
+export declare function formatKey(year: number, month: number, day: number): string;
+/** Split a key into numbers (month 1-12). */
+export declare function parseKey(key: string): {
+    year: number;
+    month: number;
+    day: number;
+};
+/** Add days to a key. */
+export declare function addDays(key: string, days: number): string;
+/** Day of week of a key (0 = Sunday). */
+export declare function weekdayOfKey(key: string): number;
+/** The month a key falls in. */
+export declare function monthOfKey(key: string): CalendarMonth;
+/** Shift a month by `delta` months. */
+export declare function shiftMonth(value: CalendarMonth, delta: number): CalendarMonth;
+/** Days in a month. */
+export declare function daysInMonth(value: CalendarMonth): number;
+/** Move a key by whole months, clamping the day (Jan 31 + 1 month = Feb 28). */
+export declare function addMonthsToKey(key: string, delta: number): string;
+/** Every key of a month, in order. */
+export declare function monthKeys(value: CalendarMonth): string[];
+/**
+ * Full weeks covering a month.
+ *
+ * @param value - Month to cover
+ * @param weekStartsOn - First column (0 = Sunday, 1 = Monday, …)
+ * @returns Week rows of seven keys each
+ */
+export declare function monthWeeks(value: CalendarMonth, weekStartsOn: number): string[][];
+/**
+ * First day of the week for a locale (0 = Sunday), from `Intl.Locale` week
+ * info where the runtime provides it; Sunday otherwise.
+ */
+export declare function defaultWeekStart(locale: string | undefined): number;
+/** Tone for an item: explicit tone, else a stable tone for its group. */
+export declare function toneFor(item: CalendarItem): CalendarTone;
+/**
+ * Project items onto day keys. Items with unparseable dates are dropped and
+ * reported through `onInvalid`.
+ *
+ * @param items - Calendar items
+ * @param timeZone - IANA zone the calendar shows
+ * @param onInvalid - Called for each dropped item
+ * @returns Entries sorted by start
+ */
+export declare function toEntries(items: readonly CalendarItem[], timeZone: string, onInvalid?: (item: CalendarItem) => void): CalendarEntry[];
+/** Every entry on a day: bands covering it first, then timed items by start. */
+export declare function entriesOnDay(entries: readonly CalendarEntry[], key: string): CalendarEntry[];
+/**
+ * Lay out a month grid: bands get lanes per week, each day shows what fits in
+ * `maxPerDay` rows, and the rest is counted for a "+N more" control.
+ *
+ * @param value - Visible month
+ * @param entries - Entries from {@link toEntries}
+ * @param options - First weekday and per-day row budget
+ * @returns Week rows
+ */
+export declare function layoutMonth(value: CalendarMonth, entries: readonly CalendarEntry[], options: {
+    weekStartsOn: number;
+    maxPerDay: number;
+}): CalendarWeek[];
+//# sourceMappingURL=calendar-model.d.ts.map

package/dist/components/calendar/calendar-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar-model.d.ts","sourceRoot":"","sources":["../../../src/components/calendar/calendar-model.ts"],"names":[],"mappings":"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"}