@columenlabs/lumen-ui 0.1.160 → 0.1.162

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/hooks/use-tell.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tells `tell` a value each time the value itself changes, never because `tell` is a new function.
+ * The view hears its sort, chips and grouping through these: an app's inline callback (a new
+ * function every render) used to re-run the effect, set the app's state, render, and so on without
+ * end, asking the server for the same page each time. The value is compared by its JSON, so an
+ * equal value in a new object is not a change either. A `tell` that appears later hears the value.
+ */
+export declare function useTell<V>(value: V, tell: ((value: V) => void) | undefined): void;

package/dist/hooks/use-tell.js

@@ -0,0 +1,24 @@
+import * as React from 'react';
+/**
+ * Tells `tell` a value each time the value itself changes, never because `tell` is a new function.
+ * The view hears its sort, chips and grouping through these: an app's inline callback (a new
+ * function every render) used to re-run the effect, set the app's state, render, and so on without
+ * end, asking the server for the same page each time. The value is compared by its JSON, so an
+ * equal value in a new object is not a change either. A `tell` that appears later hears the value.
+ */
+export function useTell(value, tell) {
+    const tellRef = React.useRef(tell);
+    tellRef.current = tell;
+    const valueRef = React.useRef(value);
+    valueRef.current = value;
+    const sent = React.useRef(null);
+    const key = JSON.stringify(value ?? null);
+    const has = !!tell;
+    React.useEffect(() => {
+        const mark = has ? key : null;
+        if (mark === null || sent.current === mark)
+            return;
+        sent.current = mark;
+        tellRef.current?.(valueRef.current);
+    }, [key, has]);
+}

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';
@@ -92,6 +95,7 @@ export { TILE_WIDTH, Tile, TileChip, type TileOption, TileRow, TileSpark, TileTo
 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 { useTell } from './hooks/use-tell.js';
 export { useBackClose } from './hooks/use-back-close.js';
 export { VIEW_ICONS, iconOf, viewIcon } from './view-icons.js';
 export { type AppViewState, useAppView } from './app-views.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';
@@ -99,6 +102,7 @@ export { TILE_WIDTH, Tile, TileChip, TileRow, TileSpark, TileToggleGroup, } from
 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 { useTell } from './hooks/use-tell.js';
 export { useBackClose } from './hooks/use-back-close.js';
 export { VIEW_ICONS, iconOf, viewIcon } from './view-icons.js';
 export { useAppView } from './app-views.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.js

@@ -89,7 +89,7 @@ export function LumenFilterPanel({ filter, open, onOpenChange, tips, order, titl
 /** One field: its values ticked in place, or a number field's range. */
 function Section({ field, filter, facets: { counts, empties }, tip, }) {
     const { tokens, setTokens } = filter;
-    const shown = countsShown(filter);
+    const shown = countsShown(filter, field.key);
     const mine = tokens.filter((t) => t.key === field.key);
     const not = mine.some((t) => t.not);
     const [more, setMore] = useState(false);

package/dist/lumen-filter.d.ts

@@ -36,10 +36,13 @@ export declare function filterByTokens<T>(rows: T[], fields: FilterField<T>[], t
 /** The row's text, for `contains` tokens. */
 text?: (row: T) => string[]): T[];
 /** A server's counts per field: each value's rows, and the rows with no value (`none`), over the
- *  rows every other field's tokens keep. */
+ *  rows every other field's tokens keep. `counted: false` gives a field's values to pick without
+ *  counts, for when the server could not count them without reading every row: the box and the
+ *  panel list the values and show no numbers. */
 export type FacetCounts = Record<string, {
     values: Record<string, number>;
     none?: number;
+    counted?: boolean;
 }>;
 /**
  * Each field's values with their counts, shared by the filter box and the filter panel. A field
@@ -50,11 +53,12 @@ export declare function useFacetCounts<T>(filter: LumenFilterState<T>): {
     counts: Map<string, Map<string, number>>;
     empties: Map<string, number>;
 };
-/** Whether a count means something: over a server's page only when the server counted. */
+/** Whether a count means something: over a server's page only when the server counted (that
+ *  field, when `key` is given). */
 export declare const countsShown: (filter: {
     partial: boolean;
     facets: FacetCounts | null;
-}) => boolean;
+}, key?: string) => boolean;
 /** Keeps the tokens and text, and filters `rows` by them. */
 export declare function useLumenFilter<T>(rows: T[], fields: FilterField<T>[], { text: textOf, initial, partial, facets, }?: {
     /** Free-text haystack per row (a name, an id), besides the field values. */

package/dist/lumen-filter.js

@@ -149,8 +149,9 @@ export function useFacetCounts(filter) {
         return { counts, empties };
     }, [fields, indexed, tokens, facets]);
 }
-/** Whether a count means something: over a server's page only when the server counted. */
-export const countsShown = (filter) => !filter.partial || !!filter.facets;
+/** Whether a count means something: over a server's page only when the server counted (that
+ *  field, when `key` is given). */
+export const countsShown = (filter, key) => (filter.facets ? key === undefined || filter.facets[key]?.counted !== false : !filter.partial);
 /** Keeps the tokens and text, and filters `rows` by them. */
 export function useLumenFilter(rows, fields, { text: textOf, initial = [], partial = false, facets, } = {}) {
     const [tokens, setRaw] = useState(() => onePerField(initial));
@@ -312,7 +313,7 @@ function NumberCondition({ label, current, tall, count, onSet, }) {
 export function LumenTokenizedFilter({ filter, placeholder = 'Filter…', label = 'Filter', className, saved, onSave, changed, link: given, }) {
     const { fields, indexed, tokens, setTokens, text, setText, hasText } = filter;
     // Over one page of a server's rows a count is not the real one: show none, unless the server counted.
-    const tally = (n) => (countsShown(filter) ? n : '');
+    const tally = (n, key) => (countsShown(filter, key) ? n : '');
     // Text counts are over the rows loaded: none over a server's page.
     const pageTally = (n) => (filter.partial ? '' : n);
     // A box its card passes no link takes the card's own (every card carries a square).
@@ -530,14 +531,14 @@ export function LumenTokenizedFilter({ filter, placeholder = 'Filter…', label
         return (_jsxs(CommandItem, { value: `${key}:${value}`, onSelect: () => toggle(key, value), className: tall, children: [_jsx(Checkbox, { checked: on, tabIndex: -1, "aria-hidden": true, className: "pointer-events-none" }), prefix && _jsx("span", { className: "shrink-0 text-muted-foreground", children: prefix }), _jsx("span", { className: "min-w-0 truncate", children: value }), _jsx(Button, { variant: "ghost", size: "xs", className: "-my-1 ml-auto h-6 px-1.5 font-normal text-muted-foreground opacity-0 group-data-selected/command-item:opacity-100 max-md:opacity-100", "aria-label": `Only ${value}`, onMouseDown: (e) => e.preventDefault(), onClick: (e) => {
                         e.stopPropagation();
                         only(key, value);
-                    }, children: "Only" }), _jsx(CommandShortcut, { className: cn('ml-0 w-8 text-right', shortcut), children: tally(count) })] }, `${key}:${value}`));
+                    }, children: "Only" }), _jsx(CommandShortcut, { className: cn('ml-0 w-8 text-right', shortcut), children: tally(count, key) })] }, `${key}:${value}`));
     };
     // A field's "No <field>" row, pinned above its values: the rows with no value (Exclude: any).
     const emptyRow = (f, include) => {
         const n = empties.get(f.key) ?? 0;
         if (!n && !hasEmpty(f.key))
             return null;
-        return (_jsxs(CommandItem, { value: `${f.key}:${EMPTY_VALUE}`, onSelect: () => toggleEmpty(f.key, include ? false : undefined), className: tall, children: [_jsx(Checkbox, { checked: hasEmpty(f.key), tabIndex: -1, "aria-hidden": true, className: "pointer-events-none" }), _jsx("span", { className: "min-w-0 truncate text-muted-foreground italic", children: noneOf(f.label) }), _jsx(CommandShortcut, { className: cn('ml-auto w-8 text-right', shortcut), children: tally(n) })] }, `${f.key}:${EMPTY_VALUE}`));
+        return (_jsxs(CommandItem, { value: `${f.key}:${EMPTY_VALUE}`, onSelect: () => toggleEmpty(f.key, include ? false : undefined), className: tall, children: [_jsx(Checkbox, { checked: hasEmpty(f.key), tabIndex: -1, "aria-hidden": true, className: "pointer-events-none" }), _jsx("span", { className: "min-w-0 truncate text-muted-foreground italic", children: noneOf(f.label) }), _jsx(CommandShortcut, { className: cn('ml-auto w-8 text-right', shortcut), children: tally(n, f.key) })] }, `${f.key}:${EMPTY_VALUE}`));
     };
     const summary = (c) => {
         const w = chipWords(c, fieldOf(c.key), 'full');

package/dist/lumen-layout.js

@@ -19,6 +19,7 @@ import { ConnectOffer } from './connections.js';
 import { usePageKey } from './fold.js';
 import { useGroup } from './group-button.js';
 import { useIsMobile } from './hooks/use-mobile.js';
+import { useTell } from './hooks/use-tell.js';
 import { SourceStatusItems, useJoins } from './joins.js';
 import { useYourData } from './joins.js';
 import { lazyPart } from './lazy-part.js';
@@ -249,7 +250,8 @@ function ViewLayout({ crumbs, actions, meta, status, intro, cards: extra, lead,
         savedFiltersRef.current = savedFilters;
         setTokens(config.filters.default);
     }, [savedFilters, config.filters.default, setTokens]);
-    useEffect(() => onTokens?.(filter.tokens), [onTokens, filter.tokens]);
+    // Told through a ref, so an app's inline callback never loops (useTell).
+    useTell(filter.tokens, onTokens);
     const group = useGroup(domain, config);
     // The sort the person set by a header click, held like the chips and grouping (rule C).
     const [heldSort, setHeldSort] = useState(config.sort);
@@ -262,8 +264,7 @@ function ViewLayout({ crumbs, actions, meta, status, intro, cards: extra, lead,
         setHeldSort(config.sort);
     }, [savedSort, config.sort]);
     // A server's page sorts on the server: it hears each sort held.
-    const onServerSort = paging?.onSort;
-    useEffect(() => onServerSort?.(heldSort ?? null), [onServerSort, heldSort]);
+    useTell(heldSort ?? null, paging?.onSort);
     const [details, setDetails] = useState(null);
     const onDetails = onOpen ?? (domain.details?.length ? setDetails : undefined);
     const openKey = onOpen ? (openedKey ?? null) : details === null ? null : domain.rowKey(details);

package/dist/lumen-player.d.ts

@@ -0,0 +1,58 @@
+export interface PlayerTrack {
+    /** A WebVTT file. */
+    src: string;
+    srcLang: string;
+    label: string;
+    default?: boolean;
+}
+export interface PlayerChapter {
+    /** Seconds from the start. */
+    at: number;
+    title: string;
+}
+export interface PlayerLine {
+    start: number;
+    end?: number;
+    text: string;
+    /** Who says it, before the line. */
+    who?: string;
+}
+export interface PlayerSlide {
+    /** Seconds into the audio when the slide shows. */
+    at: number;
+    image: string;
+    alt?: string;
+}
+export type PlayerSource = {
+    kind: 'slides';
+    slides: readonly PlayerSlide[];
+    audio: string;
+};
+export interface LumenPlayerProps {
+    /** The recording's address; or `source` for slides over audio. */
+    src?: string;
+    source?: PlayerSource;
+    /** `video` or `audio`; read from the address's extension by default (video when unsure). */
+    kind?: 'video' | 'audio';
+    /** The recording's name, for screen readers and full screen. */
+    title?: string;
+    poster?: string;
+    /** Captions (video). */
+    tracks?: readonly PlayerTrack[];
+    chapters?: readonly PlayerChapter[];
+    transcript?: readonly PlayerLine[];
+    /** Where to start, in seconds (a saved place, or a search hit's minute). */
+    start?: number;
+    /** The place, about every 10 s while playing, on pause and at the end. */
+    onProgress?: (seconds: number, info: {
+        duration: number | null;
+        ended: boolean;
+    }) => void;
+    onEnded?: () => void;
+    /** Plays as soon as it can (the next item of a series, after the last one ended). */
+    autoPlay?: boolean;
+    className?: string;
+}
+/** `1:02`, `1:02:03`. */
+export declare function playerClock(seconds: number): string;
+export declare function LumenPlayer({ src, source, kind, title, poster, tracks, chapters, transcript, start, onProgress, onEnded, autoPlay, className, }: LumenPlayerProps): import("react").JSX.Element;

package/dist/lumen-player.js

@@ -0,0 +1,244 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenPlayer: a recording, video or audio, on the browser's own <video>/<audio> (served with byte
+// ranges, so seeking reads only what it needs) with the kit's controls under it: play, back and
+// forward 15 s, the seek bar and its times, speed, captions and full screen. Chapters jump; a timed
+// transcript lights the line being said, keeps it in view inside its own box and plays from a
+// line on a tap. It starts at `start` and reports its place through `onProgress` about every 10 s
+// while it plays, on pause and at the end, so an app can save where it was left. A slides source
+// is pictures in step with an audio track: the slide shown is the last one whose `at` has passed.
+// Keys work only while the player has focus: space or k plays, j and l skip 15 s, ← and → 5 s,
+// f full screen, c captions.
+import { CaptionsIcon, GaugeIcon, MaximizeIcon, MinimizeIcon, PauseIcon, PlayIcon, RotateCcwIcon, RotateCwIcon, } from 'lucide-react';
+import { useEffect, useRef, useState, } from 'react';
+import { cn } from './lib/utils.js';
+import { LumenSelector } from './lumen-selector.js';
+import { IconButton } from './page.js';
+import { Slider } from './ui/slider.js';
+import { Spinner } from './ui/spinner.js';
+const SPEEDS = ['0.75', '1', '1.25', '1.5', '1.75', '2'];
+const SKIP = 15;
+const NUDGE = 5;
+const REPORT_MS = 10_000;
+/** After a person scrolls the transcript, it stops following for this long. */
+const HANDS_OFF_MS = 5_000;
+const AUDIO = /\.(mp3|m4a|aac|wav|ogg|oga|opus|flac)(\?|#|$)/i;
+/** `1:02`, `1:02:03`. */
+export function playerClock(seconds) {
+    const s = Math.max(0, Math.floor(Number.isFinite(seconds) ? seconds : 0));
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const ss = String(s % 60).padStart(2, '0');
+    return h ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`;
+}
+/** The last entry whose time has passed, by binary search over a list sorted by time. */
+function lastAt(list, time, now) {
+    let lo = 0;
+    let hi = list.length - 1;
+    let at = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (time(list[mid]) <= now) {
+            at = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    return at;
+}
+export function LumenPlayer({ src, source, kind, title, poster, tracks, chapters, transcript, start, onProgress, onEnded, autoPlay, className, }) {
+    const root = useRef(null);
+    const media = useRef(null);
+    const url = source?.kind === 'slides' ? source.audio : (src ?? '');
+    const slides = source?.kind === 'slides' ? source.slides : null;
+    const video = !slides && (kind ? kind === 'video' : !AUDIO.test(url));
+    const [now, setNow] = useState(start ?? 0);
+    const [duration, setDuration] = useState(null);
+    const [playing, setPlaying] = useState(false);
+    const [waiting, setWaiting] = useState(false);
+    const [failed, setFailed] = useState(false);
+    const [rate, setRate] = useState('1');
+    const [captions, setCaptions] = useState(() => !!tracks?.some((t) => t.default));
+    const [full, setFull] = useState(false);
+    const last = useRef(0);
+    const progress = useRef(onProgress);
+    progress.current = onProgress;
+    const report = (ended = false) => {
+        const el = media.current;
+        // Opening a recording and leaving it unplayed saves nothing.
+        if (!el || !Number.isFinite(el.currentTime) || (!ended && el.currentTime < 1))
+            return;
+        last.current = Date.now();
+        progress.current?.(Math.round(el.currentTime), {
+            duration: Number.isFinite(el.duration) ? Math.round(el.duration) : null,
+            ended,
+        });
+    };
+    // Leaving the player (closing its drawer) saves the place too.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: report reads refs only, once on leave
+    useEffect(() => {
+        const el = media.current;
+        return () => {
+            if (el && !el.ended && el.currentTime >= 1) {
+                progress.current?.(Math.round(el.currentTime), {
+                    duration: Number.isFinite(el.duration) ? Math.round(el.duration) : null,
+                    ended: false,
+                });
+            }
+        };
+    }, [url]);
+    useEffect(() => {
+        const on = () => setFull(document.fullscreenElement === root.current);
+        document.addEventListener('fullscreenchange', on);
+        return () => document.removeEventListener('fullscreenchange', on);
+    }, []);
+    // Captions follow the toggle once the tracks have loaded.
+    useEffect(() => {
+        const list = media.current?.textTracks;
+        if (!list)
+            return;
+        for (let i = 0; i < list.length; i++) {
+            const t = list[i];
+            if (t)
+                t.mode = captions && i === 0 ? 'showing' : 'hidden';
+        }
+    }, [captions]);
+    const seek = (s, play = false) => {
+        const el = media.current;
+        if (!el)
+            return;
+        const end = Number.isFinite(el.duration) ? el.duration : Number.POSITIVE_INFINITY;
+        el.currentTime = Math.min(Math.max(0, s), end);
+        setNow(el.currentTime);
+        if (play)
+            void el.play().catch(() => { });
+    };
+    const toggle = () => {
+        const el = media.current;
+        if (!el)
+            return;
+        if (el.paused)
+            void el.play().catch(() => { });
+        else
+            el.pause();
+    };
+    const fullscreen = () => {
+        if (document.fullscreenElement)
+            void document.exitFullscreen().catch(() => { });
+        else
+            void root.current?.requestFullscreen?.().catch(() => { });
+    };
+    const onKey = (e) => {
+        const t = e.target;
+        // Fields, menus and the seek bar keep their own keys.
+        if (t.closest('input, textarea, select, [role="slider"], [role="combobox"], [role="listbox"]'))
+            return;
+        const here = media.current?.currentTime ?? 0;
+        const keys = {
+            ' ': toggle,
+            k: toggle,
+            j: () => seek(here - SKIP),
+            l: () => seek(here + SKIP),
+            ArrowLeft: () => seek(here - NUDGE),
+            ArrowRight: () => seek(here + NUDGE),
+            ...(video ? { f: fullscreen } : {}),
+            ...(video && tracks?.length ? { c: () => setCaptions((c) => !c) } : {}),
+        };
+        const run = keys[e.key];
+        // Space on a focused button presses it; the player takes it only on itself or the media.
+        if (!run || e.metaKey || e.ctrlKey || e.altKey)
+            return;
+        if (e.key === ' ' && t.closest('button'))
+            return;
+        e.preventDefault();
+        run();
+    };
+    const events = {
+        ref: media,
+        src: url,
+        preload: 'metadata',
+        playsInline: true,
+        onLoadedMetadata: (e) => {
+            const el = e.currentTarget;
+            setFailed(false);
+            setDuration(Number.isFinite(el.duration) ? el.duration : null);
+            el.playbackRate = Number(rate);
+            if (start && start > 0 && (!Number.isFinite(el.duration) || start < el.duration - 1)) {
+                el.currentTime = start;
+                setNow(start);
+            }
+            if (autoPlay)
+                void el.play().catch(() => { });
+        },
+        onDurationChange: (e) => {
+            const d = e.currentTarget.duration;
+            setDuration(Number.isFinite(d) ? d : null);
+        },
+        onTimeUpdate: (e) => {
+            const el = e.currentTarget;
+            setNow(el.currentTime);
+            if (!el.paused && Date.now() - last.current >= REPORT_MS)
+                report();
+        },
+        onPlay: () => setPlaying(true),
+        onPause: () => {
+            setPlaying(false);
+            report();
+        },
+        onWaiting: () => setWaiting(true),
+        onPlaying: () => setWaiting(false),
+        onCanPlay: () => setWaiting(false),
+        onError: () => {
+            setWaiting(false);
+            setFailed(true);
+        },
+        onEnded: () => {
+            setPlaying(false);
+            report(true);
+            onEnded?.();
+        },
+    };
+    const slide = slides ? (slides[lastAt(slides, (s) => s.at, now)] ?? slides[0]) : null;
+    const chapter = chapters?.length ? lastAt(chapters, (c) => c.at, now) : -1;
+    const end = duration ?? 0;
+    return (_jsxs("section", { ref: root, 
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: the player takes its keys while focused
+        tabIndex: 0, onKeyDown: onKey, "aria-label": title ? `${title} player` : 'Player', className: cn('flex min-w-0 flex-col gap-3 rounded-md outline-none focus-visible:ring-3 focus-visible:ring-ring/50', full && 'justify-center bg-background p-4', className), children: [_jsxs("div", { className: cn('relative overflow-hidden rounded-md', (video || slides) && 'bg-black', full && 'min-h-0 flex-1'), children: [video ? (_jsx("video", { ...events, poster: poster, title: title, onClick: toggle, className: cn('w-full', full ? 'h-full object-contain' : 'aspect-video'), children: tracks?.map((t) => (_jsx("track", { kind: "captions", src: t.src, srcLang: t.srcLang, label: t.label, default: t.default }, t.src))) }, url)) : (_jsxs(_Fragment, { children: [_jsx("audio", { ...events, title: title, className: "hidden" }, url), slide ? (_jsx("img", { src: slide.image, alt: slide.alt ?? title ?? '', className: cn('w-full object-contain', full ? 'h-full' : 'aspect-video') })) : null] })), waiting && !failed ? (_jsx("span", { className: "absolute inset-0 flex items-center justify-center bg-black/20", children: _jsx(Spinner, { className: "size-6 text-white" }) })) : null, failed ? (_jsxs("div", { role: "alert", className: cn('flex items-center justify-center gap-2 p-4 text-sm', video || slides ? 'absolute inset-0 bg-black/70 text-white' : 'text-destructive'), children: [_jsx("span", { className: "truncate", children: "Could not load this recording" }), _jsx(IconButton, { icon: RotateCwIcon, label: "Try again", variant: "secondary", onClick: () => {
+                                    setFailed(false);
+                                    media.current?.load();
+                                } })] })) : null] }), _jsxs("div", { className: "flex flex-col gap-1", children: [_jsx(Slider, { "aria-label": "Seek", min: 0, max: end || 1, step: 1, value: [Math.min(now, end || 1)], disabled: !end, onValueChange: ([v]) => v !== undefined && seek(v), className: "py-2" }), _jsxs("div", { className: "flex min-w-0 items-center gap-1", children: [_jsx(IconButton, { icon: playing ? PauseIcon : PlayIcon, label: playing ? 'Pause' : 'Play', variant: "default", onClick: toggle, disabled: failed }), _jsx(IconButton, { icon: RotateCcwIcon, label: `Back ${SKIP} seconds`, onClick: () => seek(now - SKIP) }), _jsx(IconButton, { icon: RotateCwIcon, label: `Forward ${SKIP} seconds`, onClick: () => seek(now + SKIP) }), _jsxs("span", { className: "num ml-1 min-w-0 truncate text-xs text-muted-foreground", children: [playerClock(now), " / ", duration === null ? '–:––' : playerClock(duration)] }), _jsxs("span", { className: "ml-auto flex shrink-0 items-center gap-1", children: [_jsx(LumenSelector, { trigger: "chip", size: "sm", icon: GaugeIcon, label: "Speed", value: rate, display: _jsxs("span", { className: "num", children: [rate, "\u00D7"] }), options: SPEEDS.map((s) => ({ value: s, label: `${s}×` })), search: false, align: "end", onChange: (v) => {
+                                            setRate(v);
+                                            if (media.current)
+                                                media.current.playbackRate = Number(v);
+                                        } }), video && tracks?.length ? (_jsx(IconButton, { icon: CaptionsIcon, label: captions ? 'Hide captions' : 'Show captions', pressed: captions, onClick: () => setCaptions((c) => !c) })) : null, video ? (_jsx(IconButton, { icon: full ? MinimizeIcon : MaximizeIcon, label: full ? 'Exit full screen' : 'Full screen', onClick: fullscreen })) : null] })] })] }), !full && chapters?.length ? (_jsx(PlayerList, { label: "Chapters", children: chapters.map((c, i) => (_jsx(PlayerRow, { at: c.at, current: i === chapter, onPlay: () => seek(c.at, true), children: c.title }, `${c.at}:${c.title}`))) })) : null, !full && transcript?.length ? (_jsx(Transcript, { lines: transcript, now: now, playing: playing, onPlay: (s) => seek(s, true) })) : null] }));
+}
+function PlayerList({ label, children }) {
+    return (_jsxs("section", { "aria-label": label, className: "flex flex-col gap-1", children: [_jsx("h3", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsx("ol", { className: "flex flex-col", children: children })] }));
+}
+function PlayerRow({ at, current, onPlay, children, wrap, index, }) {
+    return (_jsx("li", { "data-line": index, children: _jsxs("button", { type: "button", onClick: onPlay, "aria-current": current || undefined, className: cn('flex w-full min-w-0 gap-3 rounded-md px-2 py-1 text-left text-sm hover:bg-muted focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50', wrap ? 'items-baseline' : 'items-center', current && 'bg-accent text-accent-foreground'), children: [_jsx("time", { className: "num w-14 shrink-0 text-xs text-muted-foreground", children: playerClock(at) }), _jsx("span", { className: cn('min-w-0 flex-1', wrap ? 'break-words' : 'truncate'), children: children })] }) }));
+}
+function Transcript({ lines, now, playing, onPlay, }) {
+    const box = useRef(null);
+    const touched = useRef(0);
+    const at = lastAt(lines, (l) => l.start, now);
+    const line = lines[at];
+    const current = line && (line.end === undefined || now < line.end) ? at : -1;
+    // While it plays, the line being said stays in view inside the box (never the page), unless the
+    // person has just scrolled it themselves.
+    useEffect(() => {
+        const el = box.current;
+        if (!playing || current < 0 || !el || Date.now() - touched.current < HANDS_OFF_MS)
+            return;
+        const row = el.querySelector(`[data-line="${current}"]`);
+        if (!row)
+            return;
+        const top = row.offsetTop - el.offsetTop;
+        if (top < el.scrollTop || top + row.offsetHeight > el.scrollTop + el.clientHeight)
+            el.scrollTo({ top: top - el.clientHeight / 3, behavior: 'smooth' });
+    }, [current, playing]);
+    const mark = () => {
+        touched.current = Date.now();
+    };
+    return (_jsxs("section", { "aria-label": "Transcript", className: "flex flex-col gap-1", children: [_jsx("h3", { className: "text-xs font-medium text-muted-foreground", children: "Transcript" }), _jsx("div", { ref: box, onWheel: mark, onTouchMove: mark, className: "relative max-h-[40vh] overflow-y-auto overscroll-contain", children: _jsx("ol", { className: "flex flex-col", children: lines.map((l, i) => (_jsxs(PlayerRow, { index: i, at: l.start, current: i === current, onPlay: () => onPlay(l.start), wrap: true, children: [l.who ? _jsxs("span", { className: "font-medium", children: [l.who, ": "] }) : null, l.text] }, `${l.start}:${i}`))) }) })] }));
+}

package/dist/lumen-view.js

@@ -15,6 +15,7 @@ import { DrawerSection } from './drawer-section.js';
 import { useFloatingHead } from './floating-head.js';
 import { FreshnessMark, freshnessLine, freshnessOf } from './freshness.js';
 import { useIsMobile } from './hooks/use-mobile.js';
+import { useTell } from './hooks/use-tell.js';
 import { IconButton } from './icon-button.js';
 import { lazyPart } from './lazy-part.js';
 import { cn } from './lib/utils.js';
@@ -236,8 +237,7 @@ export function LumenView({ domain, config, rows, total = rows.length, paging: s
     // server groups it.
     const groupBy = server && !server.groups ? null : pickedGroup;
     const served = server?.groups && groupBy ? server.groups : null;
-    const onGroup = server?.groups?.onGroup;
-    useEffect(() => onGroup?.(groupBy?.key ?? null), [onGroup, groupBy?.key]);
+    useTell(groupBy?.key ?? null, server?.groups?.onGroup);
     const pivot = server ? false : pickedPivot;
     // Live columns on screen keep their source reading while the market trades (#861).
     const load = useLiveLoad(sourceLoad, columns.some((c) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ui",
-  "version": "0.1.160",
+  "version": "0.1.162",
   "description": "Lumen: shared React components (frame, views, widgets, charts, drawers).",
   "license": "MIT",
   "type": "module",
@@ -49,7 +49,7 @@
     "@codemirror/lang-javascript": "6.2.5",
     "@codemirror/lang-json": "6.0.2",
     "@codemirror/lang-sql": "6.10.0",
-    "@columenlabs/lumen-ui-types": "0.1.160",
+    "@columenlabs/lumen-ui-types": "0.1.162",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/sortable": "10.0.0",
     "@dnd-kit/utilities": "3.2.2",