@ahrowe/ui 0.39.0 → 0.40.0

package/README.md

@@ -127,6 +127,7 @@ runs where `@ahrowe/ui` is installed.
 | `Breadcrumb` | A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page |
 | `Button`, `ButtonStyleType`, `ButtonSize`, `ButtonType` | Primary interactive action trigger |
 | `ButtonGroup`, `ButtonGroupOrientation` | Joins a row (or column) of buttons into a single seamless control, merging their borders and rounding only the outer corners |
+| `Calendar`, `CalendarView` | Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments, a team schedule |
 | `Card`, `CardStyleType`, `CardHeader`, `CardMedia`, `CardContent`, `CardActions` | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
 | `Carousel` | A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay |
 | `Checkbox` | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
@@ -136,7 +137,7 @@ runs where `@ahrowe/ui` is installed.
 | `ConfigProvider` | Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance |
 | `ConfirmModal` | Confirmation dialog before destructive or irreversible actions — delete, archive, send, overwrite |
 | `CopyButton` | Icon-only button that copies a value to the clipboard: an invoice number, an ID in a table row, an API key or share link inside an `Input` |
-| `DatePicker`, `dateToDay`, `dayToDate` | Date selection input — booking forms, birth date fields, date range pickers, deadline selectors |
+| `DatePicker`, `dateToDay`, `dayToDate`, `dateToTime`, `dayTimeToDate` | Date selection input — booking forms, birth date fields, date range pickers, deadline selectors |
 | `Divider`, `DividerTextPosition`, `DividerOrientation` | A rule that separates sections of content — horizontal by default, filling the width of its parent |
 | `Drawer` | Inline horizontal panel that collapses and expands by animating its width — side panels, navigation rails, detail/filter panes that slide open beside the main content |
 | `DropZone`, `DropZoneReturnType`, `DropZoneStatus` | Drag-and-drop file upload area, optionally click-to-open the native picker |

package/dist/cjs-types/common/calendar/calendar.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { CalendarEvent, CalendarProps } from './calendar.types.js';
+declare function Calendar<E extends CalendarEvent = CalendarEvent>(props: CalendarProps<E>): ReactElement;
+export default Calendar;

package/dist/cjs-types/common/calendar/calendar.types.d.ts

@@ -0,0 +1,141 @@
+import { CSSProperties, ReactNode, Ref } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+export declare enum CalendarView {
+    Month = "month",
+    Week = "week",
+    Day = "day",
+    Agenda = "agenda"
+}
+/** A day of the week, as `Date#getDay()` counts: 0 is Sunday, 1 is Monday. */
+export type CalendarWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** First day of the week, as `Date#getDay()` counts: 0 is Sunday, 1 is Monday. */
+export type CalendarWeekStart = CalendarWeekday;
+export interface CalendarEvent {
+    id: string | number;
+    title: string;
+    /** Local time. */
+    start: Date;
+    /** Local time, exclusive. An all-day event on the 26th ends at midnight on the 27th. */
+    end: Date;
+    /** Shown in the all-day row instead of the time grid. Timed events of 24 hours or more are too. */
+    allDay?: boolean;
+    /** Any CSS colour. Falls back to `--primary-color`. */
+    color?: string;
+    /** Can be clicked but not moved or resized. */
+    readOnly?: boolean;
+}
+/** A span of local time. `end` is exclusive. */
+export interface CalendarRange {
+    start: Date;
+    end: Date;
+}
+export interface CalendarEventChange<E extends CalendarEvent = CalendarEvent> {
+    event: E;
+    start: Date;
+    end: Date;
+}
+export interface CalendarSlot {
+    start: Date;
+    end: Date;
+    allDay: boolean;
+}
+/** Where `renderEvent` draws an event. */
+export interface CalendarEventContext {
+    /**
+     * The event has one line: an event under 45 minutes in the week and day views, an all-day bar,
+     * or a row of the month view. The day and agenda lists have room for more.
+     */
+    singleLine: boolean;
+}
+export type CalendarSlots = 'root' | 'header' | 'dayHeader' | 'cell' | 'event';
+/** Text Calendar renders of its own, for translating it. Dates and times come from `locale`. */
+export interface CalendarLabels {
+    /** Previous period button (default `Previous`). */
+    previous?: string;
+    /** Next period button (default `Next`). */
+    next?: string;
+    /** Jump to today (default `Today`). */
+    today?: string;
+    /** Name of the view switcher, read out by screen readers (default `Calendar view`). */
+    viewSwitcher?: string;
+    month?: string;
+    week?: string;
+    day?: string;
+    agenda?: string;
+    /** All-day row and all-day events (default `All day`). */
+    allDay?: string;
+    /** Overflow button in a month cell (default `+3 more`). */
+    more?: (count: number) => string;
+    /** Appended to a day's name for screen readers (default `3 events`). */
+    eventCount?: (count: number) => string;
+    /** A day or period without events (default `No events`). */
+    noEvents?: string;
+    /** Create button in a day's event list, shown when `onSlotCreate` is set (default `New event`). */
+    newEvent?: string;
+}
+export interface CalendarProps<E extends CalendarEvent = CalendarEvent> extends HtmlProps<HTMLDivElement> {
+    /** The events to show. Only the ones inside the range `onRangeChange` reports are needed. */
+    events: E[];
+    /** Controlled: the selected day, `'YYYY-MM-DD'`, whose period is shown. Omit for uncontrolled. */
+    date?: string;
+    /** Day shown initially when uncontrolled, `'YYYY-MM-DD'` (default today). */
+    defaultDate?: string;
+    /** Called with the new day, `'YYYY-MM-DD'`: the value a DatePicker holds. */
+    onDateChange?: (day: string) => void;
+    /** Controlled view. Omit for uncontrolled. */
+    view?: CalendarView;
+    /** View shown initially when uncontrolled (default `CalendarView.Month`). */
+    defaultView?: CalendarView;
+    onViewChange?: (view: CalendarView) => void;
+    /** Views offered in the switcher, in order. The switcher is hidden when there is only one (default all four). */
+    views?: CalendarView[];
+    /** BCP 47 tag for dates, times and the week start (default the browser's locale). */
+    locale?: string;
+    /** Overrides the locale's first day of the week. */
+    weekStartsOn?: CalendarWeekStart;
+    /** Minutes that creating, moving and resizing snap to (default `15`). */
+    slotMinutes?: number;
+    /** Days of the week left out of every view: `[0, 6]` hides the weekend. */
+    hiddenDays?: CalendarWeekday[];
+    /**
+     * Hour the week and day views open at, such as `6` for 06:00 (default an hour before now while
+     * today is shown, otherwise 07:00).
+     */
+    scrollToHour?: number;
+    /**
+     * Called on mount and whenever the shown period changes, with the period and one either side of
+     * it, so the neighbours are already filled while swiping. Fetch events and expand recurring
+     * series for this range.
+     */
+    onRangeChange?: (range: CalendarRange) => void;
+    /** An event was clicked or tapped. `anchor` is its element, for positioning a popover. */
+    onEventClick?: (event: E, anchor: HTMLElement) => void;
+    /**
+     * An event was moved or resized. Setting it is what makes events draggable. Update `events`
+     * in the same render, or return a promise: the event then stays where it was dropped until the
+     * promise settles, and is drawn from `events` again after that, back in place if it rejected.
+     */
+    onEventChange?: (change: CalendarEventChange<E>) => void | Promise<unknown>;
+    /**
+     * Empty time was clicked or dragged over. Setting it is what enables creating: a click creates
+     * an hour, or an all-day slot in the month view. `anchor` marks the slot on screen, for a
+     * popover's `anchor`: the day's cell in the month view, an invisible box over the slot in the
+     * week and day views.
+     */
+    onSlotCreate?: (slot: CalendarSlot, anchor: HTMLElement) => void;
+    /**
+     * Content of an event, in place of its title. Must not contain interactive elements. Keep to the
+     * title where `context.singleLine` is set: further lines have no room there.
+     */
+    renderEvent?: (event: E, context: CalendarEventContext) => ReactNode;
+    /** The root element. */
+    ref?: Ref<HTMLDivElement>;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<CalendarSlots>;
+    styles?: SlotStyles<CalendarSlots>;
+    /** Overrides the text Calendar renders of its own. Merged per key. */
+    labels?: CalendarLabels;
+}
+/** The props `ConfigProvider` can set for every Calendar. The rest depend on the event type. */
+export type CalendarDefaults = Pick<CalendarProps, 'labels' | 'locale' | 'weekStartsOn' | 'slotMinutes' | 'views' | 'hiddenDays' | 'scrollToHour'>;

package/dist/cjs-types/common/calendar/components/agendaList/agendaList.d.ts

@@ -0,0 +1,5 @@
+import { ReactElement } from 'react';
+import { CalendarEvent } from '../../calendar.types.js';
+import { AgendaListProps } from './agendaList.types.js';
+declare function AgendaList<E extends CalendarEvent>({ events, start, days, hidden, scrollTo, showDayHeaders, locale, text, onEventClick, renderEvent, className, classNames, slotStyles, }: AgendaListProps<E>): ReactElement;
+export default AgendaList;

package/dist/cjs-types/common/calendar/components/agendaList/agendaList.types.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from 'react';
+import { SlotClassNames, SlotStyles } from '../../../types/slots.types.js';
+import { CalendarEvent, CalendarEventContext, CalendarLabels, CalendarSlots } from '../../calendar.types.js';
+export interface AgendaListProps<E extends CalendarEvent = CalendarEvent> {
+    events: readonly E[];
+    /** First day listed. */
+    start: Date;
+    /** Days listed from `start`. */
+    days: number;
+    /** Weekdays left out of the list, as `Date#getDay()` counts. */
+    hidden?: ReadonlySet<number>;
+    /** Scrolled to on mount and whenever it changes: the first listed day on or after it. */
+    scrollTo?: Date;
+    /** A dated heading over each day. The list of a single, already named day leaves them out. */
+    showDayHeaders: boolean;
+    locale: string | undefined;
+    text: Required<CalendarLabels>;
+    onEventClick: ((event: E, anchor: HTMLElement) => void) | undefined;
+    renderEvent: ((event: E, context: CalendarEventContext) => ReactNode) | undefined;
+    className?: string;
+    classNames: SlotClassNames<CalendarSlots> | undefined;
+    slotStyles: SlotStyles<CalendarSlots> | undefined;
+}

package/dist/cjs-types/common/calendar/components/agendaList/index.d.ts

@@ -0,0 +1 @@
+export { default } from './agendaList.js';

package/dist/cjs-types/common/calendar/components/calendarHeader/calendarHeader.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { CalendarHeaderProps } from './calendarHeader.types.js';
+declare function CalendarHeader({ title, compact, direction, view, views, text, onStep, onToday, onViewChange, className, style, }: CalendarHeaderProps): ReactElement;
+export default CalendarHeader;

package/dist/cjs-types/common/calendar/components/calendarHeader/calendarHeader.types.d.ts

@@ -0,0 +1,17 @@
+import { CSSProperties } from 'react';
+import { CalendarLabels, CalendarView } from '../../calendar.types.js';
+export interface CalendarHeaderProps {
+    title: string;
+    /** Narrow: the view switcher takes a row of its own. */
+    compact: boolean;
+    /** `1` after paging forwards, `-1` back: the direction the title slides in from. */
+    direction: 1 | -1;
+    view: CalendarView;
+    views: CalendarView[];
+    text: Required<CalendarLabels>;
+    onStep: (step: 1 | -1) => void;
+    onToday: () => void;
+    onViewChange: (view: CalendarView) => void;
+    className?: string;
+    style?: CSSProperties;
+}

package/dist/cjs-types/common/calendar/components/calendarHeader/index.d.ts

@@ -0,0 +1 @@
+export { default } from './calendarHeader.js';

package/dist/cjs-types/common/calendar/components/compactMonth/compactMonth.d.ts

@@ -0,0 +1,9 @@
+import { ReactElement } from 'react';
+import { CalendarEvent } from '../../calendar.types.js';
+import { CompactMonthProps } from './compactMonth.types.js';
+/**
+ * The month view of a narrow calendar: a grid of days with event dots over the selected day's
+ * events. Scrolling that list folds the month up into the selected week, iOS-style.
+ */
+declare function CompactMonth<E extends CalendarEvent>({ events, date, locale, weekStartsOn, hidden, text, onDateChange, onEventClick, onSlotCreate, renderEvent, classNames, slotStyles, }: CompactMonthProps<E>): ReactElement;
+export default CompactMonth;

package/dist/cjs-types/common/calendar/components/compactMonth/compactMonth.types.d.ts

@@ -0,0 +1 @@
+export type { CalendarViewProps as CompactMonthProps } from '../../view.types.js';

package/dist/cjs-types/common/calendar/components/compactMonth/index.d.ts

@@ -0,0 +1 @@
+export { default } from './compactMonth.js';

package/dist/cjs-types/common/calendar/components/monthView/index.d.ts

@@ -0,0 +1 @@
+export { default } from './monthView.js';

package/dist/cjs-types/common/calendar/components/monthView/monthView.d.ts

@@ -0,0 +1,5 @@
+import { ReactElement } from 'react';
+import { CalendarEvent } from '../../calendar.types.js';
+import { MonthViewProps } from './monthView.types.js';
+declare function MonthView<E extends CalendarEvent>({ events, date, locale, weekStartsOn, hidden, text, onDateChange, onOpenDay, onEventClick, onEventChange, onSlotCreate, renderEvent, classNames, slotStyles, }: MonthViewProps<E>): ReactElement;
+export default MonthView;

package/dist/cjs-types/common/calendar/components/monthView/monthView.types.d.ts

@@ -0,0 +1,10 @@
+import { CalendarEvent } from '../../calendar.types.js';
+/** An event picked up in the month view, and how many days it has been dragged. */
+export interface MonthDrag<E extends CalendarEvent = CalendarEvent> {
+    event: E;
+    /** The day under the pointer when it was picked up. */
+    grabbed: Date;
+    /** Days it has been dragged by. */
+    offset: number;
+}
+export type { CalendarViewProps as MonthViewProps } from '../../view.types.js';

package/dist/cjs-types/common/calendar/components/timeGrid/index.d.ts

@@ -0,0 +1 @@
+export { default } from './timeGrid.js';

package/dist/cjs-types/common/calendar/components/timeGrid/timeGrid.d.ts

@@ -0,0 +1,5 @@
+import { ReactElement } from 'react';
+import { CalendarEvent } from '../../calendar.types.js';
+import { TimeGridProps } from './timeGrid.types.js';
+declare function TimeGrid<E extends CalendarEvent>({ events, date, view, locale, weekStartsOn, slotMinutes, hidden, scrollToHour, text, onDateChange, onOpenDay, onEventClick, onEventChange, onSlotCreate, renderEvent, classNames, slotStyles, zoomRef, }: TimeGridProps<E>): ReactElement;
+export default TimeGrid;

package/dist/cjs-types/common/calendar/components/timeGrid/timeGrid.types.d.ts

@@ -0,0 +1,40 @@
+import { RefObject } from 'react';
+import { CalendarEvent } from '../../calendar.types.js';
+import { CalendarViewProps } from '../../view.types.js';
+export interface TimeGridZoom {
+    /** Hour height in px. */
+    hour: number;
+    /** The theme's hour height in px, measured before the first zoom: the scale the limits are set in. */
+    base: number;
+}
+export interface TimeGridProps<E extends CalendarEvent = CalendarEvent> extends CalendarViewProps<E> {
+    /**
+     * The zoom set by pinching, or `null` for the theme's hour height. Owned by Calendar so the
+     * zoom survives switching between Week and Day, or out to Month and back.
+     */
+    zoomRef: RefObject<TimeGridZoom | null>;
+}
+interface DragBase {
+    /** The time the preview shows, recomputed on every move. */
+    start: Date;
+    end: Date;
+}
+export interface CreateDrag extends DragBase {
+    kind: 'create';
+    /** Days from the period's first day to the one the drag started on. Creating stays on it. */
+    day: number;
+    /** Wall-clock minutes of the press. */
+    anchor: number;
+}
+export interface MoveDrag<E extends CalendarEvent = CalendarEvent> extends DragBase {
+    kind: 'move';
+    event: E;
+    /** Minutes from the event's start to the press, so the event does not jump under the finger. */
+    grab: number;
+}
+export interface ResizeDrag<E extends CalendarEvent = CalendarEvent> extends DragBase {
+    kind: 'resize';
+    event: E;
+}
+export type TimeDrag<E extends CalendarEvent = CalendarEvent> = CreateDrag | MoveDrag<E> | ResizeDrag<E>;
+export {};

package/dist/cjs-types/common/calendar/dates.d.ts

@@ -0,0 +1,50 @@
+import { CalendarView, CalendarRange, CalendarWeekStart } from './calendar.types.js';
+export declare const MINUTES_PER_DAY = 1440;
+export declare function startOfDay(date: Date): Date;
+/** Midnight, `days` calendar days away. */
+export declare function addDays(date: Date, days: number): Date;
+/** The same wall-clock time, `days` calendar days away. */
+export declare function shiftDays(date: Date, days: number): Date;
+export declare function daysInMonth(year: number, month: number): number;
+/** Midnight, `months` months away. The day is clamped, so 31 January plus one month is the end of February. */
+export declare function addMonths(date: Date, months: number): Date;
+export declare function startOfMonth(date: Date): Date;
+export declare function startOfWeek(date: Date, weekStartsOn: CalendarWeekStart): Date;
+/** Calendar days from `a` to `b`, whatever their times of day. */
+export declare function dayDiff(a: Date, b: Date): number;
+export declare function isSameDay(a: Date, b: Date): boolean;
+export { dateToDay } from '../utils/day.js';
+/** Wall-clock minutes since midnight. On a 25-hour day the repeated hour maps onto itself. */
+export declare function minutesOfDay(date: Date): number;
+/**
+ * The wall-clock time `minutes` after the start of `day`; 1440 is the next midnight. A time the
+ * clock skips resolves forwards (02:30 becomes 03:30) and a repeated one to its first occurrence.
+ */
+export declare function atMinutes(day: Date, minutes: number): Date;
+/**
+ * `end`, unless a clock change turned the range around: where one end lands in the hour the
+ * clocks skip, a wall-clock end can fall on or before its start. Then `minutes` of real time
+ * after the start instead.
+ */
+export declare function endAfter(start: Date, end: Date, minutes: number): Date;
+/** Midnight of the first day of the period `date` is in. */
+export declare function periodStart(view: CalendarView, date: Date, weekStartsOn: CalendarWeekStart): Date;
+/** The days a view shows for `date`. The month view is always six full weeks. */
+export declare function periodRange(view: CalendarView, date: Date, weekStartsOn: CalendarWeekStart): CalendarRange;
+/** `hiddenDays` as a lookup. A list that leaves no day of the week hides nothing. */
+export declare function hiddenDaySet(hiddenDays: readonly number[] | undefined): ReadonlySet<number>;
+/** `date`, or the first shown day from it on in `direction`. */
+export declare function shownDay(date: Date, hidden: ReadonlySet<number>, direction?: 1 | -1): Date;
+/** `date` moved by `steps` periods, keeping its place in the period where it can. */
+export declare function stepDate(view: CalendarView, date: Date, steps: number, hidden?: ReadonlySet<number>): Date;
+/** The shown period plus one on either side: what the swipe pager can reveal. */
+export declare function rangeWithNeighbours(view: CalendarView, date: Date, weekStartsOn: CalendarWeekStart, hidden?: ReadonlySet<number>): CalendarRange;
+/** Midnight of each of `count` days from `start`. */
+export declare function daysFrom(start: Date, count: number): Date[];
+/** The days of `count` from `start` that are not hidden: the columns a row of them draws. */
+export declare function shownDays(start: Date, count: number, hidden?: ReadonlySet<number>): Date[];
+/**
+ * The day a month grid moves to for `key`, or `null` for a key it does not handle. A hidden day
+ * gives way to the next shown one in the direction the key points, so the focus stays on a cell.
+ */
+export declare function gridKeyTarget(key: string, day: Date, weekStartsOn: CalendarWeekStart, hidden?: ReadonlySet<number>): Date | null;

package/dist/cjs-types/common/calendar/format.d.ts

@@ -0,0 +1,32 @@
+import { CalendarView, CalendarRange, CalendarWeekStart } from './calendar.types.js';
+/**
+ * Cached, since building one costs about fifty times more than using it. A formatter keeps the
+ * time zone it was built in while `Date` follows the current one, so the key carries the zone: a
+ * zone change (the device's, or `process.env.TZ` between tests) then builds a new formatter
+ * instead of labelling days in the old zone.
+ */
+export declare function formatter(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+/**
+ * The locale's first day of the week, falling back to Monday where `getWeekInfo` is missing:
+ * it is Baseline only since July 2026 (Chrome 130, Firefox 153, Safari 17).
+ */
+export declare function localeWeekStart(locale: string | undefined): CalendarWeekStart;
+export declare function formatTime(date: Date, locale: string | undefined): string;
+/** A time span, with the dates added by Intl where the two ends fall on different days. */
+export declare function formatTimeRange(start: Date, end: Date, locale: string | undefined): string;
+/**
+ * The clock times alone, `10:00 PM to 2:00 AM` as the locale writes it, where `formatTimeRange` would add both dates for
+ * an event that crosses midnight. Both ends are moved onto one day for it. The first spec of
+ * `formatRange` threw a RangeError for an end earlier than the start; an engine still doing that
+ * gets the start time alone.
+ */
+export declare function formatClockRange(start: Date, end: Date, locale: string | undefined): string;
+/** `9 AM` where the locale counts to twelve, `09:00` where it counts to 24. */
+export declare function formatHour(hour: number, locale: string | undefined): string;
+export declare function formatWeekday(date: Date, locale: string | undefined, width: 'long' | 'short' | 'narrow'): string;
+/** The day of the month in the locale's own digits. */
+export declare function formatDayNumber(date: Date, locale: string | undefined): string;
+export declare function formatLongDate(date: Date, locale: string | undefined): string;
+export declare function formatShortDate(date: Date, locale: string | undefined): string;
+export declare function formatMonthTitle(date: Date, locale: string | undefined): string;
+export declare function formatPeriodTitle(view: CalendarView, date: Date, range: CalendarRange, locale: string | undefined): string;

package/dist/cjs-types/common/calendar/gesture.d.ts

@@ -0,0 +1,32 @@
+/** Touch movement before a press is read as a swipe or a scroll (carousel.tsx, useSwipeDismiss.ts). */
+export declare const LOCK_DISTANCE = 10;
+/** Mouse movement before a press becomes a drag. */
+export declare const MOUSE_DRAG_DISTANCE = 4;
+/** Hold before a touch picks something up (VirtualList's `longPressDelay`). */
+export declare const LONG_PRESS_MS = 400;
+/** A touch this soon after a scroll is stopping momentum, not picking something up. */
+export declare const RECENT_SCROLL_MS = 150;
+/** Share of the width a swipe must travel to page (carousel.tsx). */
+export declare const COMMIT_RATIO = 0.2;
+/** px/ms a shorter flick must reach to page anyway (useSwipeDismiss.ts). */
+export declare const COMMIT_VELOCITY = 0.5;
+/** How far back the flick velocity is measured. */
+export declare const VELOCITY_WINDOW_MS = 100;
+/** Distance from a scroller's edge where a drag starts scrolling it (useRowDrag.ts). */
+export declare const EDGE_ZONE = 48;
+/** px per frame at the very edge. */
+export declare const EDGE_SPEED = 18;
+/** How long after a gesture the click it ends in is swallowed (useRowDrag.ts). */
+export declare const CLICK_SUPPRESS_MS = 350;
+/** `1` to page forwards, `-1` back, `0` to return. A swipe to the left reveals the next period. */
+export declare function pageStep(dx: number, width: number, velocity: number): -1 | 0 | 1;
+/** Scroll speed for a pointer at `y` in a scroller spanning `top` to `bottom`: negative scrolls up. */
+export declare function edgeSpeed(y: number, top: number, bottom: number): number;
+export declare function snap(minutes: number, step: number): number;
+export declare function clamp(value: number, min: number, max: number): number;
+export interface VelocitySample {
+    time: number;
+    x: number;
+}
+/** px/ms over the samples of the last `VELOCITY_WINDOW_MS`. */
+export declare function velocityOf(samples: readonly VelocitySample[], now: number): number;

package/dist/cjs-types/common/calendar/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './calendar.js';
+export * from './calendar.types.js';

package/dist/cjs-types/common/calendar/layout.d.ts

@@ -0,0 +1,74 @@
+import { CalendarEvent } from './calendar.types.js';
+/**
+ * Below this an event has no room for a line of text at the default hour height. It is drawn as a
+ * bar of its real length with its label beneath, and packed with room for that label.
+ */
+export declare const BRIEF_EVENT_MINUTES = 15;
+/** `end`, clamped so an event that ends before it starts is treated as having no length. */
+export declare function eventEnd(event: CalendarEvent): Date;
+/** Drawn in the all-day row rather than the time grid. */
+export declare function isAllDayLike(event: CalendarEvent): boolean;
+/** First and last day (both midnight, both inclusive) the event appears on. */
+export declare function eventDays(event: CalendarEvent): {
+    first: Date;
+    last: Date;
+};
+/** All-day events first, then by start, then the longer first, so a day reads the same everywhere. */
+export declare function compareEvents(a: CalendarEvent, b: CalendarEvent): number;
+/** The events on each of `dates`, sorted with `compareEvents`. */
+export declare function eventsByDay<E extends CalendarEvent>(events: readonly E[], dates: readonly Date[]): E[][];
+export interface TimedBox<E extends CalendarEvent = CalendarEvent> {
+    event: E;
+    /** Wall-clock minutes from the column's midnight. */
+    top: number;
+    bottom: number;
+    /** Where the next event in its column may start: below the label of a brief event. */
+    reach: number;
+    /** Left edge, as a column of `columns`. */
+    column: number;
+    columns: number;
+    /** Columns it can widen into to its right without covering another event. */
+    span: number;
+    continuesBefore: boolean;
+    continuesAfter: boolean;
+}
+/**
+ * Lays out one day column of the time grid: events that overlap share the width in columns, and
+ * each one widens right into columns that are free for its whole height.
+ *
+ * Positions are wall-clock minutes, never milliseconds from midnight. Drawing and packing have
+ * to agree on that: on a 25-hour day two events in the repeated hour occupy the same rows, and
+ * packing them by real time would put them in one column, drawn over each other.
+ */
+export declare function packDay<E extends CalendarEvent>(events: readonly E[], day: Date): TimedBox<E>[];
+export interface LaneBar<E extends CalendarEvent = CalendarEvent> {
+    event: E;
+    /** First column of the row it covers, 0-based. */
+    start: number;
+    /** Columns it covers within the row. */
+    span: number;
+    lane: number;
+    /** It starts before its first column: in an earlier row, or on a hidden day. */
+    continuesBefore: boolean;
+    continuesAfter: boolean;
+}
+/**
+ * Stacks the events of one row of days into lanes, as the month view and the all-day row draw
+ * them: longer bars first, so a multi-day event keeps one lane across the week. `dates` are the
+ * row's columns, so a hidden day between two of them is simply not drawn.
+ */
+export declare function packLanes<E extends CalendarEvent>(events: readonly E[], dates: readonly Date[], include?: (event: E) => boolean): LaneBar<E>[];
+export interface LimitedLanes<E extends CalendarEvent = CalendarEvent> {
+    visible: LaneBar<E>[];
+    /** Lane the `+N` buttons go in, on the days that have one. */
+    moreLane: number;
+    /** Events hidden on each day of the row. */
+    hidden: number[];
+}
+/**
+ * Fits the bars into `capacity` lanes. A day that needs more gives its last lane to a `+N`
+ * button; a day that does not keeps every bar. Decided per day, so one crowded day does not
+ * hide events on the quiet days next to it. A bar crossing into a crowded day's `+N` lane is
+ * hidden along its whole length and counted on each day it covers.
+ */
+export declare function limitLanes<E extends CalendarEvent>(bars: LaneBar<E>[], days: number, capacity: number): LimitedLanes<E>;

package/dist/cjs-types/common/calendar/useGestures.d.ts

@@ -0,0 +1,37 @@
+import { RefObject } from 'react';
+export interface GesturePoint {
+    x: number;
+    y: number;
+}
+export interface GestureHandlers<D> {
+    /** Every press that starts a gesture, before anything else: where a running settle is finished. */
+    onPress?: () => void;
+    /** Whether a horizontal swipe may page right now. */
+    canSwipe?: () => boolean;
+    onSwipeMove?: (dx: number) => void;
+    /** Also called with `(0, 0)` when the browser takes the gesture over. */
+    onSwipeEnd?: (dx: number, velocity: number) => void;
+    /** What a press on `target` would pick up, or `null` where nothing can be dragged. */
+    dragFrom?: (target: Element, point: GesturePoint) => D | null;
+    onDragStart?: (drag: D, point: GesturePoint) => void;
+    onDragMove?: (point: GesturePoint) => void;
+    onDragEnd?: (point: GesturePoint) => void;
+    onDragCancel?: () => void;
+    onPinchStart?: (center: GesturePoint, distance: number) => void;
+    onPinchMove?: (center: GesturePoint, distance: number) => void;
+    onPinchEnd?: () => void;
+    /** The element a drag scrolls near its edges, and the band of the viewport that counts as its inside. */
+    autoScroll?: () => {
+        element: HTMLElement;
+        top: number;
+        bottom: number;
+    } | null;
+}
+/**
+ * One owner for every pointer gesture inside `ref`, so a swipe, a long-press drag, a pinch and
+ * the browser's own scrolling can never both act on the same touch.
+ *
+ * Mouse or touch rules are chosen per event from `pointerType`, not once from a media query,
+ * which answers wrongly on a laptop with a touch screen.
+ */
+export declare function useGestures<D>(ref: RefObject<HTMLElement | null>, handlers: GestureHandlers<D>): void;

package/dist/cjs-types/common/calendar/usePager.d.ts

@@ -0,0 +1,20 @@
+export interface Pager {
+    /** Ref for each element that slides. The time grid has two, its head and its body. */
+    trackRef: (element: HTMLElement | null) => void;
+    /** Width of one pane. */
+    width: () => number;
+    /** Offset every track by `dx` px, following the finger. */
+    move: (dx: number) => void;
+    /** Animate to the next (`1`) or previous (`-1`) pane and page, or back (`0`). */
+    settle: (step: -1 | 0 | 1) => void;
+    /** Jump to the end of a running settle: a new press arrived before it finished. */
+    finish: () => void;
+}
+/**
+ * Drives the three panes a pageable view renders: previous, current and next, keyed by period, so
+ * after paging the pane that slid in is the same DOM node as the one now current. The track is
+ * reset in the same commit that swaps them, which is why nothing flashes.
+ *
+ * `focusFallback` receives focus when it would otherwise be left inside a pane that just went inert.
+ */
+export declare function usePager(periodKey: string, onPage: (step: 1 | -1) => void, focusFallback: () => HTMLElement | null): Pager;

package/dist/cjs-types/common/calendar/view.types.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode } from 'react';
+import { SlotClassNames, SlotStyles } from '../types/slots.types.js';
+import { CalendarEvent, CalendarEventChange, CalendarEventContext, CalendarLabels, CalendarSlot, CalendarSlots, CalendarView, CalendarWeekStart } from './calendar.types.js';
+/** What Calendar hands each of its views. Internal, so it stays out of the published types. */
+export interface CalendarViewProps<E extends CalendarEvent = CalendarEvent> {
+    events: readonly E[];
+    /** Local midnight of the selected day. */
+    date: Date;
+    view: CalendarView;
+    locale: string | undefined;
+    weekStartsOn: CalendarWeekStart;
+    slotMinutes: number;
+    /** Weekdays left out, as `Date#getDay()` counts. `date` is never one of them. */
+    hidden: ReadonlySet<number>;
+    scrollToHour: number | undefined;
+    text: Required<CalendarLabels>;
+    onDateChange: (date: Date) => void;
+    /** Opens a day in the Day view, or `undefined` where the Day view is not offered. */
+    onOpenDay: ((date: Date) => void) | undefined;
+    onEventClick: ((event: E, anchor: HTMLElement) => void) | undefined;
+    onEventChange: ((change: CalendarEventChange<E>) => void) | undefined;
+    onSlotCreate: ((slot: CalendarSlot, anchor: HTMLElement) => void) | undefined;
+    renderEvent: ((event: E, context: CalendarEventContext) => ReactNode) | undefined;
+    classNames: SlotClassNames<CalendarSlots> | undefined;
+    slotStyles: SlotStyles<CalendarSlots> | undefined;
+}

package/dist/cjs-types/common/configProvider/configProvider.types.d.ts

@@ -15,6 +15,7 @@ import { SearchInputLabels } from '../searchInput/searchInput.types.js';
 import { TooltipLabels } from '../tooltip/tooltip.types.js';
 import { VirtualListLabels } from '../virtualList/virtualList.types.js';
 import { ButtonProps } from '../button/button.types.js';
+import { CalendarDefaults } from '../calendar/calendar.types.js';
 import { CopyButtonProps } from '../copyButton/copyButton.types.js';
 import { CommandPaletteProps } from '../commandPalette/commandPalette.types.js';
 import { WeatherIconProps } from '../weatherIcon/weatherIcon.types.js';
@@ -84,6 +85,8 @@ export interface ComponentDefaults {
     VirtualList?: {
         labels?: VirtualListLabels;
     };
+    /** Not `Partial<CalendarProps>`: the rest of its props depend on the event type. */
+    Calendar?: CalendarDefaults;
     Input?: Partial<InputProps>;
     Textarea?: Partial<TextareaProps>;
     NumberInput?: Partial<NumberInputProps>;

package/dist/cjs-types/common/confirmModal/confirmModal.types.d.ts

@@ -14,7 +14,7 @@ export interface ConfirmModalProps extends Omit<HtmlProps<HTMLDivElement>, 'onCl
     style?: CSSProperties;
     onClose?: (didSubmit: boolean) => void;
     onConfirm?: () => void | Promise<void>;
-    title?: string;
+    title?: ReactNode;
     content?: ReactNode;
     isOpen?: boolean;
     isDelete?: boolean;

package/dist/cjs-types/common/datePicker/index.d.ts

@@ -1,3 +1,3 @@
 export { default } from './datePicker.js';
 export * from './datePicker.types.js';
-export { dateToDay, dayToDate } from '../utils/day.js';
+export { dateToDay, dayToDate, dateToTime, dayTimeToDate } from '../utils/day.js';