@columenlabs/lumen-ui 0.1.159 → 0.1.161

package/README.md

@@ -61,11 +61,11 @@ Use `createDeskQueryClient()` for the app's TanStack Query client: data stays fr
 
 **Frame.** `LumenShell` (sidebar with icons-only collapse and a drawer on phone, header, status bar, Settings, profile menu, ⌘K Find), `LumenAppSwitcher` and `LumenSuiteSwitcher` (groups, apps on other sites, a list read from an address), `WhatsNew` (release notes in a drawer), `TasksButton` and `TasksProvider` (background work in the header), `NotificationsSettings`, `McpSettings`, sign-in screens (`LumenAuthStage`, `LumenSecondStep`, `LumenSignInMethods`, `LumenBackupCodes`, `LumenBotCheck` for Cloudflare Turnstile, `authErrorText` for errors in plain words), `StatusHealth`, `LumenBoundary` (keeps a crash inside its card), `LumenPageState` (loading, empty and error), `lumenToast`.
 
-**Pages and views.** `LumenLayout` (a page of cards from one view config: filter, tiles, widgets; Edit layout and Edit widget when you pass `onConfigChange`; a card with `header: false` is its body alone), `LumenGrid` (the 6-column grid under it), `LumenView` and `LumenViewCard` (a table that filters, groups, pivots and totals the rows you load), `LumenTable`, `LumenTokenizedFilter`, `LumenWidget` and `LumenSavedWidget` (the frame every card sits in, with its link square and controls), `LumenCard` (one number and its lines), `LumenPager`, `DetailsTable`, `LumenTree`, `useAppView` (a page whose layout each person can change and reset).
+**Pages and views.** `LumenLayout` (a page of cards from one view config: filter, tiles, widgets; Edit layout and Edit widget when you pass `onConfigChange`; a card with `header: false` is its body alone), `LumenGrid` (the 6-column grid under it), `LumenView` and `LumenViewCard` (a table that filters, groups, pivots and totals the rows you load), `LumenTable`, `LumenTokenizedFilter`, `LumenWidget` and `LumenSavedWidget` (the frame every card sits in, with its link square and controls), `LumenCard` (one number and its lines), `LumenPager`, `DetailsTable`, `LumenTree`, `LumenCalendar` (events by month, week or agenda, in a time zone), `LumenBoard` (items in columns by stage), `useAppView` (a page whose layout each person can change and reset).
 
 **Charts.** `LumenChart` (one or more symbols' prices, with indicators), `LumenEChart`, `LumenGeoMap`, growth and price charts, `StackedBars`, `StackedColumns`, `TimeLines` (lines over time, with an optional right axis), `RankedBars` (with each bar's share of the total or of the first bar, and an empty state).
 
-**Pickers and panels.** `LumenSelector` (every picker), `LumenDrawer` with `DrawerSection` (a side panel on desktop, a sheet on phone), `LumenTabs`, `LumenConfirm` (destructive confirms), `LumenForm`, `LumenDateInput`, `LumenChoice`, `LumenSecret`, `LumenFileField` (drop or pick a file), `RenameField`, `ResetButton`, `SaveButton` with `FormIssue` (a Save that says why it can't), `IconPicker`.
+**Pickers and panels.** `LumenSelector` (every picker), `LumenDrawer` with `DrawerSection` (a side panel on desktop, a sheet on phone), `LumenTabs`, `LumenConfirm` (destructive confirms), `LumenForm`, `LumenDateInput`, `LumenChoice`, `LumenSecret`, `LumenFileField` (drop or pick a file), `RenameField`, `ResetButton`, `SaveButton` with `FormIssue` (a Save that says why it can't), `IconPicker`, `LumenPlayer` (video, audio, or slides over audio, with chapters, a following transcript and resume).
 
 **Primitives.** The shadcn parts under `@columenlabs/lumen-ui/ui/*` (`ui/button`, `ui/badge`, `ui/input`, ...) and `theme.css` (light and dark tokens).
 

package/dist/hooks/use-narrow.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+/** Under this width (px) a part lays itself out for a phone. */
+export declare const NARROW = 640;
+/**
+ * Whether a part's own box is narrower than `below` px: a phone, or a narrow drawer on a desktop.
+ * Before the box is measured it reads the window, so the first paint already fits.
+ */
+export declare function useNarrow(ref: RefObject<HTMLElement | null>, below?: number): boolean;

package/dist/hooks/use-narrow.js

@@ -0,0 +1,25 @@
+import { useLayoutEffect, useState } from 'react';
+/** Under this width (px) a part lays itself out for a phone. */
+export const NARROW = 640;
+/**
+ * Whether a part's own box is narrower than `below` px: a phone, or a narrow drawer on a desktop.
+ * Before the box is measured it reads the window, so the first paint already fits.
+ */
+export function useNarrow(ref, below = NARROW) {
+    const [narrow, setNarrow] = useState(() => typeof window === 'undefined' ? false : window.innerWidth < below);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const measure = () => {
+            const w = el.clientWidth;
+            if (w > 0)
+                setNarrow(w < below);
+        };
+        measure();
+        const seen = new ResizeObserver(measure);
+        seen.observe(el);
+        return () => seen.disconnect();
+    }, [ref, below]);
+    return narrow;
+}

package/dist/index.d.ts

@@ -61,6 +61,9 @@ export { type ClientPoint, type ClientPointKind, type LumenTelemetryOptions, api
 export { refreshHeaders, withRefreshToken } from './refresh.js';
 export { type LumenLoad, LumenError, LumenLazy, LumenLoadFooter, LumenLoadTime, LumenProgress, LumenRefresh, LumenSkeleton, LumenStates, marketTrades, useLumenLoad, useLumenSource, useLiveLoad, } from './lumen-source.js';
 export { LumenBoundary } from './lumen-boundary.js';
+export { type CalendarCategory, type CalendarEvent, type CalendarRange, type CalendarView, LumenCalendar, type LumenCalendarProps, } from './lumen-calendar.js';
+export { type BoardColumn, type BoardItem, LumenBoard, type LumenBoardProps } from './lumen-board.js';
+export { LumenPlayer, type LumenPlayerProps, type PlayerChapter, type PlayerLine, type PlayerSlide, type PlayerSource, type PlayerTrack, playerClock, } from './lumen-player.js';
 export { LumenPageState } from './lumen-page-state.js';
 export { type FormIssue, goToIssue, SaveButton } from './form-issues.js';
 export { LumenForm, type LumenFormField, lumenFormIssues, type LumenFormValue, type LumenFormValues, } from './lumen-form.js';
@@ -89,7 +92,8 @@ export { type ConnectedDomain, ConnectOffer, connectionFields, linkGroupId } fro
 export { FRESHNESS, type Freshness, FreshnessIcon, FreshnessMark, freshnessLine, freshnessOf, } from './freshness.js';
 export { SourcesLine, useSourceHealth } from './source-health.js';
 export { TILE_WIDTH, Tile, TileChip, type TileOption, TileRow, TileSpark, TileToggleGroup, } from './tile.js';
-export { type FilterField, type FilterToken, LumenTokenizedFilter, type LumenFilterState, useLumenFilter, } from './lumen-filter.js';
+export { type FacetCounts, type FilterField, type FilterToken, LumenTokenizedFilter, type LumenFilterState, countsShown, useFacetCounts, useLumenFilter, } from './lumen-filter.js';
+export { LumenFilterPanel, LumenFilterPanelButton, type LumenFilterPanelProps, useFilterPanel, } from './lumen-filter-panel.js';
 export { useIsMobile } from './hooks/use-mobile.js';
 export { useBackClose } from './hooks/use-back-close.js';
 export { VIEW_ICONS, iconOf, viewIcon } from './view-icons.js';

package/dist/index.js

@@ -68,6 +68,9 @@ export { apiRoute, reportClient, reportClientError, reportFailedFetch, stackFing
 export { refreshHeaders, withRefreshToken } from './refresh.js';
 export { LumenError, LumenLazy, LumenLoadFooter, LumenLoadTime, LumenProgress, LumenRefresh, LumenSkeleton, LumenStates, marketTrades, useLumenLoad, useLumenSource, useLiveLoad, } from './lumen-source.js';
 export { LumenBoundary } from './lumen-boundary.js';
+export { LumenCalendar, } from './lumen-calendar.js';
+export { LumenBoard } from './lumen-board.js';
+export { LumenPlayer, playerClock, } from './lumen-player.js';
 export { LumenPageState } from './lumen-page-state.js';
 export { goToIssue, SaveButton } from './form-issues.js';
 export { LumenForm, lumenFormIssues, } from './lumen-form.js';
@@ -96,7 +99,8 @@ export { ConnectOffer, connectionFields, linkGroupId } from './connections.js';
 export { FRESHNESS, FreshnessIcon, FreshnessMark, freshnessLine, freshnessOf, } from './freshness.js';
 export { SourcesLine, useSourceHealth } from './source-health.js';
 export { TILE_WIDTH, Tile, TileChip, TileRow, TileSpark, TileToggleGroup, } from './tile.js';
-export { LumenTokenizedFilter, useLumenFilter, } from './lumen-filter.js';
+export { LumenTokenizedFilter, countsShown, useFacetCounts, useLumenFilter, } from './lumen-filter.js';
+export { LumenFilterPanel, LumenFilterPanelButton, useFilterPanel, } from './lumen-filter-panel.js';
 export { useIsMobile } from './hooks/use-mobile.js';
 export { useBackClose } from './hooks/use-back-close.js';
 export { VIEW_ICONS, iconOf, viewIcon } from './view-icons.js';

package/dist/lumen-board.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from 'react';
+export interface BoardColumn {
+    id: string;
+    label: string;
+    /** The count in the header; the number of its items by default. */
+    count?: number;
+}
+export interface BoardItem {
+    id: string;
+    /** The `BoardColumn` id it sits in. */
+    column: string;
+    title: string;
+    /** One muted line after the title: a due date, an owner. */
+    meta?: ReactNode;
+    /** Small marks at the card's end (`Badge`, `ColorChip`). */
+    badges?: ReactNode;
+}
+export interface LumenBoardProps<T extends BoardItem = BoardItem> {
+    columns: readonly BoardColumn[];
+    items: readonly T[];
+    /** A card was opened: show the app's drawer. */
+    onOpen?: (item: T) => void;
+    /** Moves a card; with it each card offers a Move to menu (hover, focus or tap on a phone). */
+    onMove?: (item: T, toColumn: string) => void;
+    /** Draws a card's body in place of the title, meta and badges. Keep it to one line. */
+    renderCard?: (item: T) => ReactNode;
+    /** A slot before the title: a done tick (a `Checkbox`). */
+    tick?: (item: T) => ReactNode;
+    /** An empty column's line. */
+    empty?: ReactNode;
+    /** How tall a column's list may grow before it scrolls (any CSS length). */
+    maxHeight?: string;
+    className?: string;
+}
+export declare function LumenBoard<T extends BoardItem>({ columns, items, onOpen, onMove, renderCard, tick, empty, maxHeight, className, }: LumenBoardProps<T>): import("react").JSX.Element;

package/dist/lumen-board.js

@@ -0,0 +1,62 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenBoard: items in columns by stage (a plan's checkpoints, a pipeline's steps). Each column
+// scrolls on its own; the board scrolls sideways inside its own box, never the page. On a narrow
+// box the columns become a snap scroller, one column a screen, with a LumenSelector to jump to one.
+// A card is one line: an optional tick slot, the title (it truncates, the whole of it on hover),
+// then a muted meta and badges. Moving a card is a menu of columns, so it works by keyboard and
+// needs no drag library.
+import { ArrowRightLeftIcon, KanbanIcon } from 'lucide-react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useNarrow } from './hooks/use-narrow.js';
+import { cn } from './lib/utils.js';
+import { LumenBoundary } from './lumen-boundary.js';
+import { LumenSelector } from './lumen-selector.js';
+import { IconButton } from './page.js';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuTrigger, } from './ui/dropdown-menu.js';
+export function LumenBoard({ columns, items, onOpen, onMove, renderCard, tick, empty = 'Nothing here', maxHeight = '70vh', className, }) {
+    const box = useRef(null);
+    const strip = useRef(null);
+    const narrow = useNarrow(box);
+    const [shown, setShown] = useState(columns[0]?.id ?? '');
+    const byColumn = useMemo(() => {
+        const map = new Map(columns.map((c) => [c.id, []]));
+        for (const it of items)
+            map.get(it.column)?.push(it);
+        return map;
+    }, [columns, items]);
+    // On a phone the picker follows the swipe, and a pick scrolls to its column.
+    const onScroll = () => {
+        const el = strip.current;
+        if (!narrow || !el || !el.clientWidth)
+            return;
+        const i = Math.round(el.scrollLeft / el.clientWidth);
+        const id = columns[i]?.id;
+        if (id && id !== shown)
+            setShown(id);
+    };
+    const jump = (id) => {
+        setShown(id);
+        const el = strip.current;
+        const i = columns.findIndex((c) => c.id === id);
+        if (el && i >= 0)
+            el.scrollTo({ left: i * el.clientWidth, behavior: 'smooth' });
+    };
+    // A column that goes away leaves the picker on the first.
+    useEffect(() => {
+        if (!columns.some((c) => c.id === shown))
+            setShown(columns[0]?.id ?? '');
+    }, [columns, shown]);
+    const countOf = (c) => c.count ?? byColumn.get(c.id)?.length ?? 0;
+    return (_jsxs("div", { ref: box, className: cn('flex min-w-0 flex-col gap-2', className), children: [narrow && columns.length > 1 ? (_jsx(LumenSelector, { label: "Column", icon: KanbanIcon, value: shown, onChange: jump, options: columns.map((c) => ({
+                    value: c.id,
+                    label: c.label,
+                    detail: String(countOf(c)),
+                })), className: "w-full" })) : null, _jsx("div", { ref: strip, onScroll: onScroll, className: cn('flex min-w-0 overflow-x-auto overscroll-x-contain', narrow ? 'snap-x snap-mandatory' : 'gap-3 pb-1'), children: columns.map((c) => {
+                    const list = byColumn.get(c.id) ?? [];
+                    return (_jsxs("section", { "aria-label": c.label, className: cn('flex shrink-0 flex-col rounded-lg border bg-muted/30', narrow ? 'w-full snap-start' : 'w-72'), children: [_jsxs("header", { className: "flex min-w-0 items-center gap-2 border-b px-3 py-2", children: [_jsx("h3", { className: "min-w-0 flex-1 truncate text-sm font-medium", title: c.label, children: c.label }), _jsx("span", { className: "num shrink-0 text-xs text-muted-foreground", children: countOf(c) })] }), _jsx("div", { className: "overflow-y-auto p-2", style: { maxHeight }, children: _jsx(LumenBoundary, { where: `board:${c.id}`, children: list.length ? (_jsx("ul", { className: "flex flex-col gap-1.5", children: list.map((it) => (_jsx("li", { children: _jsx(BoardCard, { item: it, columns: columns, onOpen: onOpen, onMove: onMove, renderCard: renderCard, tick: tick }) }, it.id))) })) : (_jsx("p", { className: "px-1 py-6 text-center text-sm text-muted-foreground", children: empty })) }) })] }, c.id));
+                }) })] }));
+}
+function BoardCard({ item, columns, onOpen, onMove, renderCard, tick, }) {
+    const [menu, setMenu] = useState(false);
+    return (_jsxs("div", { className: cn('group/card flex min-w-0 items-center gap-2 rounded-md border bg-card px-2 py-1.5 text-sm shadow-xs hover:bg-muted/60 focus-within:ring-3 focus-within:ring-ring/30', menu && 'bg-muted/60'), children: [tick ? _jsx("span", { className: "flex shrink-0 items-center", children: tick(item) }) : null, _jsx("button", { type: "button", onClick: () => onOpen?.(item), title: item.title, className: "flex min-w-0 flex-1 items-center gap-2 text-left focus-visible:outline-none", children: renderCard ? (renderCard(item)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "min-w-0 flex-1 truncate", children: item.title }), item.meta ? (_jsx("span", { className: "max-w-24 shrink-0 truncate text-xs text-muted-foreground", children: item.meta })) : null, item.badges ? (_jsx("span", { className: "flex shrink-0 items-center gap-1 whitespace-nowrap", children: item.badges })) : null] })) }), onMove ? (_jsxs(DropdownMenu, { open: menu, onOpenChange: setMenu, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx(IconButton, { icon: ArrowRightLeftIcon, label: "Move to", size: "icon-xs", className: cn('shrink-0 opacity-0 group-hover/card:opacity-100 group-focus-within/card:opacity-100 [@media(hover:none)]:opacity-100', menu && 'opacity-100') }) }), _jsxs(DropdownMenuContent, { align: "end", className: "min-w-44", children: [_jsx(DropdownMenuLabel, { children: "Move to" }), _jsx(DropdownMenuRadioGroup, { value: item.column, onValueChange: (to) => to !== item.column && onMove(item, to), children: columns.map((c) => (_jsx(DropdownMenuRadioItem, { value: c.id, children: _jsx("span", { className: "truncate", children: c.label }) }, c.id))) })] })] })) : null] }));
+}

package/dist/lumen-calendar.d.ts

@@ -0,0 +1,50 @@
+export interface CalendarEvent {
+    id: string;
+    title: string;
+    /** An instant (`Date` or ISO string), or a plain `YYYY-MM-DD` for a whole day. */
+    start: Date | string;
+    /** Inclusive for a plain `YYYY-MM-DD`; an end at midnight does not reach the next day. */
+    end?: Date | string;
+    allDay?: boolean;
+    /** A `categories` id: its colour and filter chip. */
+    category?: string;
+    /** Any CSS colour; the category's colour by default. */
+    color?: string;
+}
+export interface CalendarCategory {
+    id: string;
+    label: string;
+    color: string;
+}
+export type CalendarView = 'month' | 'week' | 'agenda';
+export interface CalendarRange {
+    /** The first instant on screen (midnight of the first day in `timeZone`). */
+    start: Date;
+    /** The instant after the last day on screen. */
+    end: Date;
+    view: CalendarView;
+}
+export interface LumenCalendarProps<E extends CalendarEvent = CalendarEvent> {
+    events: readonly E[];
+    categories?: readonly CalendarCategory[];
+    /** The open view, controlled; or `defaultView` (Agenda on a narrow box, else Month). */
+    view?: CalendarView;
+    defaultView?: CalendarView;
+    onViewChange?: (view: CalendarView) => void;
+    /** A day in the period shown, controlled; or `defaultDate` (today). */
+    date?: Date;
+    defaultDate?: Date;
+    onDateChange?: (date: Date) => void;
+    /** An event was clicked: open the app's drawer. */
+    onSelect?: (event: E) => void;
+    /** The days on screen changed (and once at first): fetch by range. */
+    onRangeChange?: (range: CalendarRange) => void;
+    /** An IANA zone every day and time is shown in; the browser's by default. */
+    timeZone?: string;
+    /** 0 Sunday (default) or 1 Monday. */
+    weekStartsOn?: 0 | 1;
+    /** Shown when the period has no events. */
+    empty?: string;
+    className?: string;
+}
+export declare function LumenCalendar<E extends CalendarEvent>({ events, categories, view: viewProp, defaultView, onViewChange, date: dateProp, defaultDate, onDateChange, onSelect, onRangeChange, timeZone, weekStartsOn, empty, className, }: LumenCalendarProps<E>): import("react").JSX.Element;

package/dist/lumen-calendar.js

@@ -0,0 +1,308 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenCalendar: an events calendar over plain data. Month, Week (with a time axis) and Agenda,
+// switched with LumenTabs; Today, previous and next as icon buttons; category chips that filter.
+// Every day is worked out in the passed time zone without a date library: an event's instant is
+// read into that zone's calendar day and minute with Intl, and the grid counts whole days.
+// On a narrow box (a phone, or a narrow drawer) Month shows dots with the picked day's list under
+// it, and Agenda is the view it opens on. Nothing here fetches: `onRangeChange` tells the app which
+// days are on screen, so it can read just those.
+import { CalendarCheckIcon, CalendarDaysIcon, CalendarRangeIcon, ChevronLeftIcon, ChevronRightIcon, ListIcon, } from 'lucide-react';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { ColorChip, ColorDot } from './color-dot.js';
+import { useNarrow } from './hooks/use-narrow.js';
+import { cn } from './lib/utils.js';
+import { LumenBoundary } from './lumen-boundary.js';
+import { LumenTabs } from './lumen-tabs.js';
+import { IconButton } from './page.js';
+import { Empty, EmptyHeader, EmptyTitle } from './ui/empty.js';
+import { ToggleGroup, ToggleGroupItem } from './ui/toggle-group.js';
+const DAY_MS = 86_400_000;
+/** Most days one event may cover on the grid, so a bad end date never loops for long. */
+const MAX_SPAN = 62;
+/** Events a month cell draws before "+N". */
+const CELL_EVENTS = 3;
+/** The hour the week's time axis opens at when nothing starts earlier. */
+const OPEN_HOUR = 7;
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+// ── Civil days ────────────────────────────────────────────────────────────────
+// A civil day is a whole number: days since 1970-01-01. Its Date at UTC midnight formats with
+// `timeZone: 'UTC'`, so labels never shift by the viewer's own zone.
+const dayOf = (y, m, d) => Date.UTC(y, m - 1, d) / DAY_MS;
+const asDate = (day, minute = 0) => new Date(day * DAY_MS + minute * 60_000);
+const weekday = (day) => (((day + 4) % 7) + 7) % 7;
+const ymd = (day) => {
+    const d = asDate(day);
+    return { y: d.getUTCFullYear(), m: d.getUTCMonth() + 1, d: d.getUTCDate() };
+};
+const daysIn = (y, m) => new Date(Date.UTC(y, m, 0)).getUTCDate();
+const addMonths = (day, n) => {
+    const c = ymd(day);
+    const t = new Date(Date.UTC(c.y, c.m - 1 + n, 1));
+    const y = t.getUTCFullYear();
+    const m = t.getUTCMonth() + 1;
+    return dayOf(y, m, Math.min(c.d, daysIn(y, m)));
+};
+const zoneParts = new Map();
+/** The instant's calendar day and minute of the day in `zone`. */
+function zoned(ms, zone) {
+    let f = zoneParts.get(zone);
+    if (!f) {
+        f = new Intl.DateTimeFormat('en-US', {
+            timeZone: zone,
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            hourCycle: 'h23',
+        });
+        zoneParts.set(zone, f);
+    }
+    const p = {};
+    for (const x of f.formatToParts(new Date(ms)))
+        if (x.type !== 'literal')
+            p[x.type] = +x.value;
+    return {
+        day: dayOf(p.year ?? 1970, p.month ?? 1, p.day ?? 1),
+        minute: ((p.hour ?? 0) % 24) * 60 + (p.minute ?? 0),
+    };
+}
+/** Midnight of a civil day in `zone`, as an instant. */
+function midnight(day, zone) {
+    const guess = day * DAY_MS;
+    const offset = (ms) => {
+        const z = zoned(ms, zone);
+        return z.day * DAY_MS + z.minute * 60_000 - Math.floor(ms / 60_000) * 60_000;
+    };
+    const first = guess - offset(guess);
+    return new Date(guess - offset(first));
+}
+function place(ev, zone, colors) {
+    const read = (v) => {
+        if (typeof v === 'string') {
+            const m = v.match(DATE_ONLY);
+            if (m)
+                return { day: dayOf(Number(m[1]), Number(m[2]), Number(m[3])), minute: 0, plain: true };
+        }
+        const ms = (v instanceof Date ? v : new Date(v)).getTime();
+        return Number.isFinite(ms) ? { ...zoned(ms, zone), plain: false } : null;
+    };
+    const s = read(ev.start);
+    if (!s)
+        return null;
+    const e = ev.end ? read(ev.end) : null;
+    const allDay = !!ev.allDay || s.plain;
+    let endDay = s.day;
+    let endMin = s.minute + 30;
+    if (e) {
+        endDay = e.day;
+        endMin = (e.day - s.day) * 1440 + e.minute;
+        // A timed end at midnight closes the day before.
+        if (!e.plain && e.minute === 0 && e.day > s.day)
+            endDay = e.day - 1;
+    }
+    endDay = Math.min(Math.max(endDay, s.day), s.day + MAX_SPAN);
+    return {
+        ev,
+        startDay: s.day,
+        endDay,
+        startMin: allDay ? 0 : s.minute,
+        endMin: allDay ? 1440 : Math.max(endMin, s.minute + 15),
+        allDay,
+        color: ev.color ?? (ev.category && colors.get(ev.category)) ?? 'var(--primary)',
+    };
+}
+/** Side-by-side lanes for one day's timed events that overlap. */
+function lanes(list) {
+    const out = [];
+    let group = [];
+    let ends = [];
+    let groupEnd = -1;
+    const close = () => {
+        for (const g of group)
+            g.of = ends.length;
+        out.push(...group);
+        group = [];
+        ends = [];
+    };
+    for (const p of [...list].sort((a, b) => a.startMin - b.startMin)) {
+        if (p.startMin >= groupEnd)
+            close();
+        let lane = ends.findIndex((end) => end <= p.startMin);
+        if (lane < 0)
+            lane = ends.push(0) - 1;
+        ends[lane] = p.endMin;
+        groupEnd = Math.max(groupEnd, p.endMin);
+        group.push({ p, lane, of: 0 });
+    }
+    close();
+    return out;
+}
+function useControlled(value, initial, onChange) {
+    const [own, setOwn] = useState(initial);
+    const set = (v) => {
+        if (value === undefined)
+            setOwn(v);
+        onChange?.(v);
+    };
+    return [value ?? own, set];
+}
+// ── The part ──────────────────────────────────────────────────────────────────
+export function LumenCalendar({ events, categories, view: viewProp, defaultView, onViewChange, date: dateProp, defaultDate, onDateChange, onSelect, onRangeChange, timeZone, weekStartsOn = 0, empty = 'No events', className, }) {
+    const box = useRef(null);
+    const narrow = useNarrow(box);
+    const zone = timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const [view, setView] = useControlled(viewProp, () => defaultView ??
+        (typeof window !== 'undefined' && window.innerWidth < 640 ? 'agenda' : 'month'), onViewChange);
+    const [date, setDate] = useControlled(dateProp, () => defaultDate ?? new Date(), onDateChange);
+    const anchor = zoned(date.getTime(), zone).day;
+    const today = zoned(Date.now(), zone).day;
+    const [picked, setPicked] = useState(null);
+    const [hidden, setHidden] = useState(new Set());
+    const colors = useMemo(() => new Map((categories ?? []).map((c) => [c.id, c.color])), [categories]);
+    const catLabel = useMemo(() => new Map((categories ?? []).map((c) => [c.id, c.label])), [categories]);
+    // Each event on every day it covers, whole days first, then by start.
+    const byDay = useMemo(() => {
+        const map = new Map();
+        for (const ev of events) {
+            if (ev.category && hidden.has(ev.category))
+                continue;
+            const p = place(ev, zone, colors);
+            if (!p)
+                continue;
+            for (let d = p.startDay; d <= p.endDay; d++) {
+                const list = map.get(d);
+                if (list)
+                    list.push(p);
+                else
+                    map.set(d, [p]);
+            }
+        }
+        for (const list of map.values())
+            list.sort((a, b) => Number(b.allDay) - Number(a.allDay) ||
+                a.startDay - b.startDay ||
+                a.startMin - b.startMin ||
+                a.ev.title.localeCompare(b.ev.title));
+        return map;
+    }, [events, hidden, zone, colors]);
+    // The days on screen: whole weeks around the month, one week, or the month as a list.
+    const { y, m } = ymd(anchor);
+    const first = dayOf(y, m, 1);
+    const lead = (d) => (weekday(d) - weekStartsOn + 7) % 7;
+    const [from, to] = view === 'week'
+        ? [anchor - lead(anchor), anchor - lead(anchor) + 7]
+        : view === 'month'
+            ? [
+                first - lead(first),
+                first - lead(first) + Math.ceil((lead(first) + daysIn(y, m)) / 7) * 7,
+            ]
+            : [first, first + daysIn(y, m)];
+    const ranged = useRef(onRangeChange);
+    ranged.current = onRangeChange;
+    useEffect(() => {
+        ranged.current?.({ start: midnight(from, zone), end: midnight(to, zone), view });
+    }, [from, to, zone, view]);
+    const fmt = useMemo(() => {
+        const f = (o) => new Intl.DateTimeFormat(undefined, { timeZone: 'UTC', ...o });
+        return {
+            month: f({ month: 'long', year: 'numeric' }),
+            range: f({ month: 'short', day: 'numeric', year: 'numeric' }),
+            weekday: f({ weekday: narrow ? 'narrow' : 'short' }),
+            dayLong: f({ weekday: 'short', month: 'short', day: 'numeric' }),
+            time: f({ hour: 'numeric', minute: '2-digit' }),
+            hour: f({ hour: 'numeric' }),
+        };
+    }, [narrow]);
+    const timeOf = (p, day) => p.allDay || day !== p.startDay ? 'All day' : fmt.time.format(asDate(p.startDay, p.startMin));
+    const title = view === 'week'
+        ? fmt.range.formatRange(asDate(from), asDate(to - 1))
+        : fmt.month.format(asDate(first));
+    const step = (n) => {
+        const next = view === 'week' ? anchor + n * 7 : addMonths(anchor, n);
+        setPicked(null);
+        setDate(midnight(next, zone));
+    };
+    const unit = view === 'week' ? 'week' : 'month';
+    const tabs = [
+        { value: 'month', label: 'Month', icon: CalendarDaysIcon },
+        { value: 'week', label: 'Week', icon: CalendarRangeIcon },
+        { value: 'agenda', label: 'Agenda', icon: ListIcon },
+    ];
+    // On a narrow month the picked day's list sits under the dots: today when it is on screen.
+    const listDay = picked ??
+        (view === 'month' && narrow
+            ? today >= first && today < first + daysIn(y, m)
+                ? today
+                : first
+            : null);
+    const row = (p, day) => (_jsx("li", { children: _jsxs("button", { type: "button", onClick: () => onSelect?.(p.ev), className: "flex w-full min-w-0 items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm hover:bg-muted focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50", children: [_jsx("time", { className: "w-16 shrink-0 truncate text-muted-foreground", children: timeOf(p, day) }), _jsx(ColorDot, { color: p.color }), _jsx("span", { className: "min-w-0 flex-1 truncate", title: p.ev.title, children: p.ev.title }), !narrow && p.ev.category && catLabel.has(p.ev.category) ? (_jsx("span", { className: "max-w-40 shrink truncate text-xs text-muted-foreground", children: catLabel.get(p.ev.category) })) : null] }) }, `${p.ev.id}:${day}`));
+    const dayList = (day, list) => (_jsxs("section", { "aria-label": fmt.dayLong.format(asDate(day)), children: [_jsxs("h3", { className: "sticky top-0 z-10 flex items-center gap-2 bg-background px-2 py-1 text-xs font-medium text-muted-foreground", children: [_jsx("span", { className: "truncate", children: fmt.dayLong.format(asDate(day)) }), day === today ? _jsx("span", { className: "text-primary", children: "Today" }) : null] }), _jsx("ul", { children: list.map((p) => row(p, day)) })] }, day));
+    const nothing = (_jsx(Empty, { className: "py-10", children: _jsx(EmptyHeader, { children: _jsx(EmptyTitle, { className: "text-sm font-normal text-muted-foreground", children: empty }) }) }));
+    let body;
+    if (view === 'agenda') {
+        const days = [];
+        for (let d = from; d < to; d++) {
+            const list = byDay.get(d);
+            if (list?.length)
+                days.push(dayList(d, list));
+        }
+        body = days.length ? _jsx("div", { className: "flex flex-col gap-2", children: days }) : nothing;
+    }
+    else if (view === 'month') {
+        const cells = [];
+        for (let d = from; d < to; d++) {
+            const list = byDay.get(d) ?? [];
+            const out = d < first || d >= first + daysIn(y, m);
+            const day = ymd(d).d;
+            const pick = () => setPicked(d === picked ? null : d);
+            cells.push(_jsxs("div", { className: cn('flex min-w-0 flex-col gap-0.5 border-t border-l p-1', narrow ? 'min-h-12 items-center' : 'min-h-24', out && 'bg-muted/40 text-muted-foreground', d === listDay && 'bg-accent'), children: [_jsx("button", { type: "button", onClick: pick, "aria-label": `${fmt.dayLong.format(asDate(d))}, ${list.length} events`, "aria-pressed": d === listDay, className: cn('num flex size-6 shrink-0 items-center justify-center rounded-full text-xs focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50', d === today ? 'bg-primary font-semibold text-primary-foreground' : 'hover:bg-muted'), children: day }), narrow ? (_jsx("span", { className: "flex h-2 items-center gap-0.5", "aria-hidden": true, children: list.slice(0, CELL_EVENTS).map((p) => (_jsx("span", { className: "size-1.5 rounded-full", style: { background: p.color } }, p.ev.id))) })) : (_jsxs(_Fragment, { children: [list.slice(0, CELL_EVENTS).map((p) => (_jsxs("button", { type: "button", onClick: () => onSelect?.(p.ev), title: p.ev.title, className: "flex w-full min-w-0 items-center gap-1 rounded-sm px-1 text-left text-xs hover:bg-muted focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50", children: [_jsx("span", { className: "size-2 shrink-0 rounded-full", style: { background: p.color } }), !p.allDay && d === p.startDay ? (_jsx("time", { className: "num shrink-0 text-muted-foreground", children: fmt.time.format(asDate(d, p.startMin)) })) : null, _jsx("span", { className: "min-w-0 truncate", children: p.ev.title })] }, p.ev.id))), list.length > CELL_EVENTS ? (_jsxs("button", { type: "button", onClick: pick, className: "num truncate rounded-sm px-1 text-left text-xs text-muted-foreground hover:bg-muted", children: ["+", list.length - CELL_EVENTS, " more"] })) : null] }))] }, d));
+        }
+        const heads = [];
+        for (let i = 0; i < 7; i++)
+            heads.push(_jsx("div", { className: "truncate px-1 py-1 text-center text-xs text-muted-foreground", children: fmt.weekday.format(asDate(from + i)) }, i));
+        const listed = listDay !== null ? (byDay.get(listDay) ?? []) : null;
+        body = (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsxs("div", { className: "overflow-hidden rounded-md border-r border-b", children: [_jsx("div", { className: "grid grid-cols-7", children: heads }), _jsx("div", { className: "grid grid-cols-7", children: cells })] }), listed !== null && listDay !== null ? (listed.length ? (dayList(listDay, listed)) : (_jsxs("p", { className: "px-2 text-sm text-muted-foreground", children: [fmt.dayLong.format(asDate(listDay)), ": ", empty] }))) : null] }));
+    }
+    else {
+        body = (_jsx(WeekGrid, { from: from, today: today, byDay: byDay, fmt: fmt, onSelect: onSelect, timeOf: timeOf }));
+    }
+    return (_jsxs("div", { ref: box, className: cn('flex min-w-0 flex-col gap-3', className), children: [_jsx(LumenTabs, { tabs: tabs, value: view, onChange: (v) => {
+                    setPicked(null);
+                    setView(v);
+                }, actions: _jsxs(_Fragment, { children: [_jsx(IconButton, { icon: CalendarCheckIcon, label: "Today", onClick: () => {
+                                setPicked(null);
+                                setDate(new Date());
+                            } }), _jsx(IconButton, { icon: ChevronLeftIcon, label: `Previous ${unit}`, onClick: () => step(-1) }), _jsx(IconButton, { icon: ChevronRightIcon, label: `Next ${unit}`, onClick: () => step(1) })] }) }), _jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-x-3 gap-y-2", children: [_jsx("h2", { className: "min-w-0 truncate text-sm font-semibold", "aria-live": "polite", children: title }), categories?.length ? (_jsx(ToggleGroup, { type: "multiple", size: "sm", "aria-label": "Categories", value: categories.filter((c) => !hidden.has(c.id)).map((c) => c.id), onValueChange: (on) => setHidden(new Set(categories.filter((c) => !on.includes(c.id)).map((c) => c.id))), className: "flex-wrap gap-1", children: categories.map((c) => (_jsx(ToggleGroupItem, { value: c.id, "aria-label": c.label, className: "h-auto rounded-sm p-0 data-[state=off]:opacity-50 data-[state=on]:bg-transparent", children: _jsx(ColorChip, { color: c.color, children: c.label }) }, c.id))) })) : null] }), _jsx(LumenBoundary, { where: "calendar", children: body })] }));
+}
+// ── Week ──────────────────────────────────────────────────────────────────────
+function WeekGrid({ from, today, byDay, fmt, onSelect, timeOf, }) {
+    const scroller = useRef(null);
+    const days = Array.from({ length: 7 }, (_, i) => from + i);
+    const timed = days.map((d) => (byDay.get(d) ?? []).filter((p) => !p.allDay && p.startDay === d));
+    const whole = days.map((d) => (byDay.get(d) ?? []).filter((p) => p.allDay || p.startDay !== d));
+    const earliest = Math.min(OPEN_HOUR, ...timed.flat().map((p) => Math.floor(p.startMin / 60)));
+    // Opening a week scrolls the axis to its first event, or to the morning.
+    useLayoutEffect(() => {
+        const el = scroller.current;
+        const hour = el?.querySelector('[data-hour]');
+        if (el && hour)
+            el.scrollTop = Math.max(0, (earliest - 0.25) * hour.offsetHeight);
+    }, [earliest]);
+    const cols = { gridTemplateColumns: '3rem repeat(7, minmax(0, 1fr))' };
+    const hours = Array.from({ length: 24 }, (_, h) => h);
+    return (_jsxs("div", { className: "flex flex-col rounded-md border", style: { ['--cal-hour']: '3rem' }, children: [_jsxs("div", { className: "grid border-b", style: cols, children: [_jsx("div", {}), days.map((d) => (_jsxs("div", { className: "flex min-w-0 flex-col items-center py-1 text-xs", children: [_jsx("span", { className: "truncate text-muted-foreground", children: fmt.weekday.format(asDate(d)) }), _jsx("span", { className: cn('num flex size-6 items-center justify-center rounded-full', d === today && 'bg-primary font-semibold text-primary-foreground'), children: ymd(d).d })] }, d)))] }), whole.some((l) => l.length) ? (_jsxs("div", { className: "grid border-b", style: cols, children: [_jsx("div", { className: "truncate px-1 py-1 text-right text-xs text-muted-foreground", children: "All day" }), whole.map((list, i) => (_jsx("div", { className: "flex min-w-0 flex-col gap-0.5 border-l p-0.5", children: list.map((p) => (_jsx(WeekEvent, { p: p, onSelect: onSelect, label: p.ev.title }, p.ev.id))) }, days[i])))] })) : null, _jsx("div", { ref: scroller, className: "max-h-[60vh] overflow-y-auto", children: _jsxs("div", { className: "relative grid", style: cols, children: [_jsx("div", { children: hours.map((h) => (_jsx("div", { "data-hour": true, className: "relative pr-1 text-right text-xs text-muted-foreground", style: { height: 'var(--cal-hour)' }, children: h ? (_jsx("span", { className: "num -translate-y-1/2 absolute right-1 whitespace-nowrap", children: fmt.hour.format(asDate(0, h * 60)) })) : null }, h))) }), days.map((d, i) => (_jsxs("div", { className: cn('relative border-l', d === today && 'bg-accent/40'), children: [hours.map((h) => (_jsx("div", { className: "border-t", style: { height: 'var(--cal-hour)' } }, h))), lanes(timed[i] ?? []).map(({ p, lane, of }) => (_jsx("div", { className: "absolute px-px", style: {
+                                        top: `calc(${p.startMin / 60} * var(--cal-hour))`,
+                                        height: `calc(${(Math.min(p.endMin, 1440) - p.startMin) / 60} * var(--cal-hour))`,
+                                        left: `${(lane / of) * 100}%`,
+                                        width: `${100 / of}%`,
+                                    }, children: _jsx(WeekEvent, { p: p, onSelect: onSelect, label: `${timeOf(p, d)} ${p.ev.title}`, tall: true, time: p.endMin - p.startMin >= 45
+                                            ? fmt.time.format(asDate(d, p.startMin))
+                                            : undefined }) }, p.ev.id)))] }, d)))] }) })] }));
+}
+function WeekEvent({ p, onSelect, label, tall, time, }) {
+    return (_jsxs("button", { type: "button", title: label, "aria-label": label, onClick: () => onSelect?.(p.ev), className: cn('flex w-full min-w-0 flex-col overflow-hidden rounded-sm border-l-2 px-1 text-left text-xs focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50', tall && 'h-full'), style: {
+            borderColor: p.color,
+            background: `color-mix(in oklab, ${p.color} 16%, var(--background))`,
+            color: `color-mix(in oklab, ${p.color} 45%, var(--foreground))`,
+        }, children: [_jsx("span", { className: "w-full truncate font-medium", children: p.ev.title }), time ? _jsx("time", { className: "num w-full truncate opacity-80", children: time }) : null] }));
+}

package/dist/lumen-filter-panel.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+import { type LumenFilterState } from './lumen-filter.js';
+export interface LumenFilterPanelProps<T> {
+    /** The filter's state, the same one the page's filter box draws. */
+    filter: LumenFilterState<T>;
+    /** Open (desktop: shown beside the page; phone: the sheet is up). */
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** A field's details, behind an (i) beside its name. Most fields need none. */
+    tips?: Record<string, ReactNode>;
+    /** The fields in the order shown (default: the filter's own order). Fields left out are not
+     *  shown here, but still filter from the box. */
+    order?: string[];
+    /** Its heading (default `Filters`). */
+    title?: string;
+    className?: string;
+}
+/**
+ * Remembers whether the panel is open on this device, per page (`id`). Desktop starts open,
+ * a phone closed (its sheet opens from the filter icon).
+ */
+export declare function useFilterPanel(id: string): {
+    open: boolean;
+    onOpenChange: (next: boolean) => void;
+};
+/** The filter icon that shows the panel (or opens its sheet on a phone), with how many fields
+ *  filter now. On a desktop it shows only while the panel is hidden. */
+export declare function LumenFilterPanelButton<T>({ filter, open, onOpenChange, }: Pick<LumenFilterPanelProps<T>, 'filter' | 'open' | 'onOpenChange'>): import("react").JSX.Element | null;
+/** The filter panel: a side panel on a desktop, a bottom sheet on a phone. */
+export declare function LumenFilterPanel<T>({ filter, open, onOpenChange, tips, order, title, className, }: LumenFilterPanelProps<T>): import("react").JSX.Element | null;