@stll/ui 0.57.0 → 0.59.0

package/dist/calendar/day-calendar.d.ts

@@ -0,0 +1,85 @@
+import { DayCalendarGranularity, DayCalendarRange } from "./day-calendar.logic.js";
+import { ReactElement, ReactNode } from "react";
+//#region src/calendar/day-calendar.d.ts
+/** A block paints in its matter's colour, or in the neutral surface tone. */
+export type DayCalendarTone = {
+  color: string | null;
+  matterId: string;
+  type: "matter";
+} | {
+  type: "neutral";
+};
+/** Whether an entry is still provisional (drawn dashed) or final. */
+export type DayCalendarEntryState = "draft" | "final";
+type DayCalendarBlockFields = DayCalendarRange & {
+  accessibleLabel: string;
+  detail?: ReactNode;
+  id: string;
+  title: ReactNode;
+  tone: DayCalendarTone;
+};
+export type DayCalendarBlock = (DayCalendarBlockFields & {
+  kind: "entry";
+  state: DayCalendarEntryState;
+}) | (DayCalendarBlockFields & {
+  kind: "mixed";
+}) | (DayCalendarBlockFields & {
+  kind: "segment";
+});
+export type DayCalendarRangeSelection = {
+  label: string;
+  type: "enabled";
+} | {
+  type: "disabled";
+};
+type DayCalendarColumnHeader = {
+  badge?: ReactNode;
+  id: string;
+  label: ReactNode;
+};
+/**
+ * A `locked` column has no blocks field, so caller data cannot reach it: it
+ * paints synthetic placeholder bars behind the caller's `action`.
+ */
+export type DayCalendarColumn = (DayCalendarColumnHeader & {
+  blocks: readonly DayCalendarBlock[];
+  rangeSelection: DayCalendarRangeSelection;
+  type: "blocks";
+}) | (DayCalendarColumnHeader & {
+  action: ReactNode;
+  type: "locked";
+});
+/**
+ * The committed range the caller is acting on. `panel` anchors caller content
+ * (an entry form) at the range's start, in the column it names.
+ */
+export type DayCalendarSelection = {
+  columnId: string;
+  panel?: {
+    columnId: string;
+    content: ReactNode;
+  };
+  range: DayCalendarRange;
+};
+type DayCalendarProps = {
+  ariaLabel: string;
+  columns: readonly DayCalendarColumn[];
+  /** The calendar day, `YYYY-MM-DD`, in `timeZone`. */
+  date: string;
+  granularity: DayCalendarGranularity;
+  /** Whole wall-clock hours the view covers, `0 <= startHour < endHour <= 24`. */
+  hours: {
+    endHour: number;
+    startHour: number;
+  };
+  /** The reader's formatting locale; it decides 12- or 24-hour labels. */
+  locale: string;
+  /** The current instant; the now-line shows only while it falls inside the day. */
+  nowMs: number;
+  onSelectRange: (columnId: string, range: DayCalendarRange) => void;
+  selection: DayCalendarSelection | null;
+  timeZone: string;
+};
+export declare const DayCalendar: ({ ariaLabel, columns, date, granularity, hours, locale, nowMs, onSelectRange, selection, timeZone }: DayCalendarProps) => ReactElement;
+//#endregion
+export {};

package/dist/calendar/day-calendar.js

@@ -0,0 +1,465 @@
+import { cn } from "../lib/utils.js";
+import { DAY_CALENDAR_SLOT_HEIGHT_PX, boundsHeight, extendRange, getDayBounds, getHourTicks, isRepeatedWallTime, layoutOverlaps, moveRange, offsetToTime, rangeFromDrag, slotAt, timeToOffset } from "./day-calendar.logic.js";
+import { resolveMatterColor } from "../lib/matter-colors.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { panic } from "better-result";
+import { Temporal } from "temporal-polyfill/full";
+//#region src/calendar/day-calendar.tsx
+const isSameDraftView = (left, right) => left.date === right.date && left.endHour === right.endHour && left.granularity === right.granularity && left.startHour === right.startHour && left.timeZone === right.timeZone;
+/**
+* A draft's range belongs to the day and grid it was made on; once they
+* change, committing it would select a stale range, so it is discarded.
+*/
+const useDraftSelection = (view) => {
+	const [stored, setDraft] = useState(null);
+	const draft = stored !== null && isSameDraftView(stored.view, view) ? stored : null;
+	if (stored !== null && draft === null) setDraft(null);
+	return [draft, setDraft];
+};
+const GUTTER_WIDTH = "4rem";
+/**
+* Two instants on different days. They differ in a field a time-only format
+* lacks, so formatting them as a range falls back to the locale's generic
+* interval pattern ("{0} – {1}", "{0}～{1}"), whose only shared part is the
+* separator.
+*/
+const SEPARATOR_PROBE = {
+	endMs: Temporal.Instant.from("2000-01-03T00:00:00Z").epochMilliseconds,
+	startMs: Temporal.Instant.from("2000-01-01T00:00:00Z").epochMilliseconds
+};
+/**
+* A range touching a fall-back day's repeated hour labels its ends with
+* their UTC offsets, or the two runs of that hour read the same. Interval
+* formats drop the zone name, so each end is formatted on its own.
+*/
+const createTimeLabels = ({ locale, timeZone }) => {
+	const options = {
+		hour: "numeric",
+		minute: "2-digit",
+		timeZone
+	};
+	const formatTime = new Intl.DateTimeFormat(locale, options);
+	const formatOffsetTime = new Intl.DateTimeFormat(locale, {
+		...options,
+		timeZoneName: "shortOffset"
+	});
+	const touchesRepeatedHour = (range) => isRepeatedWallTime(range.startMs, timeZone) || isRepeatedWallTime(range.endMs, timeZone);
+	const rangeSeparator = () => formatTime.formatRangeToParts(SEPARATOR_PROBE.startMs, SEPARATOR_PROBE.endMs).filter(({ source }) => source === "shared").map(({ value }) => value).join("");
+	return {
+		formatRange: (range) => touchesRepeatedHour(range) ? [formatOffsetTime.format(range.startMs), formatOffsetTime.format(range.endMs)].join(rangeSeparator()) : formatTime.formatRange(range.startMs, range.endMs),
+		formatTime,
+		timeFormatFor: (range) => touchesRepeatedHour(range) ? formatOffsetTime : formatTime
+	};
+};
+const DayCalendar = ({ ariaLabel, columns, date, granularity, hours, locale, nowMs, onSelectRange, selection, timeZone }) => {
+	assertDayCalendarContract(columns);
+	const view = {
+		date,
+		endHour: hours.endHour,
+		granularity,
+		startHour: hours.startHour,
+		timeZone
+	};
+	const [draft, setDraft] = useDraftSelection(view);
+	const bounds = getDayBounds({
+		date,
+		...hours,
+		timeZone
+	});
+	const grid = {
+		granularity,
+		bounds
+	};
+	const height = boundsHeight(grid);
+	const { formatRange, formatTime, timeFormatFor } = createTimeLabels({
+		locale,
+		timeZone
+	});
+	const minutesFromStart = (ms) => Math.round((ms - bounds.startMs) / 6e4);
+	const nowVisible = nowMs >= bounds.startMs && nowMs < bounds.endMs;
+	const timeAt = (event) => offsetToTime(event.clientY - event.currentTarget.getBoundingClientRect().top, grid);
+	const handlePointerDown = (columnId, event) => {
+		if (event.button !== 0) return;
+		event.currentTarget.setPointerCapture(event.pointerId);
+		const anchorMs = timeAt(event);
+		setDraft({
+			anchorMs,
+			columnId,
+			pointerId: event.pointerId,
+			range: rangeFromDrag({
+				anchorMs,
+				pointerMs: anchorMs
+			}, grid),
+			type: "pointer",
+			view
+		});
+	};
+	const handlePointerMove = (event) => {
+		if (draft?.type !== "pointer" || draft.pointerId !== event.pointerId) return;
+		setDraft({
+			anchorMs: draft.anchorMs,
+			columnId: draft.columnId,
+			pointerId: draft.pointerId,
+			range: rangeFromDrag({
+				anchorMs: draft.anchorMs,
+				pointerMs: timeAt(event)
+			}, grid),
+			type: "pointer",
+			view
+		});
+	};
+	const handlePointerUp = (event) => {
+		if (draft?.type !== "pointer" || draft.pointerId !== event.pointerId) return;
+		const range = rangeFromDrag({
+			anchorMs: draft.anchorMs,
+			pointerMs: timeAt(event)
+		}, grid);
+		setDraft(null);
+		onSelectRange(draft.columnId, range);
+	};
+	const handlePointerCancel = (event) => {
+		if (draft?.type === "pointer" && draft.pointerId === event.pointerId) setDraft(null);
+	};
+	const initialKeyboardRange = (columnId) => {
+		if (selection?.columnId === columnId) return selection.range;
+		return slotAt(nowVisible ? nowMs : bounds.startMs, grid);
+	};
+	const handleKeyDown = (columnId, event) => {
+		const current = draft?.columnId === columnId ? draft : null;
+		switch (event.key) {
+			case "ArrowDown":
+			case "ArrowUp": {
+				event.preventDefault();
+				const slots = event.key === "ArrowDown" ? 1 : -1;
+				if (current === null) {
+					setDraft({
+						columnId,
+						range: initialKeyboardRange(columnId),
+						type: "keyboard",
+						view
+					});
+					return;
+				}
+				setDraft({
+					columnId,
+					range: event.shiftKey ? extendRange(current.range, slots, grid) : moveRange(current.range, slots, grid),
+					type: "keyboard",
+					view
+				});
+				return;
+			}
+			case "Enter":
+				if (current === null) return;
+				event.preventDefault();
+				setDraft(null);
+				onSelectRange(columnId, current.range);
+				return;
+			case "Escape":
+				if (current === null) return;
+				event.preventDefault();
+				event.stopPropagation();
+				setDraft(null);
+				return;
+		}
+	};
+	const gridStyle = { gridTemplateColumns: `${GUTTER_WIDTH} repeat(${String(columns.length)}, minmax(0, 1fr))` };
+	const bodyStyle = { blockSize: height };
+	const slotHeight = DAY_CALENDAR_SLOT_HEIGHT_PX[granularity];
+	const slotLinesStyle = {
+		backgroundImage: ["linear-gradient(to bottom, var(--border) 1px, transparent 1px)", "linear-gradient(to bottom, color-mix(in srgb, var(--border) 45%, transparent) 1px, transparent 1px)"].join(", "),
+		backgroundSize: `100% ${String(slotHeight * 60 / granularity)}px, 100% ${String(slotHeight)}px`
+	};
+	const hourTicks = getHourTicks(bounds);
+	return /* @__PURE__ */ jsxs("section", {
+		"aria-label": ariaLabel,
+		className: "bg-card border-border grid rounded-xl border",
+		"data-granularity": granularity,
+		"data-slot": "day-calendar",
+		style: gridStyle,
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				"aria-hidden": "true",
+				className: "bg-card border-border sticky top-0 z-30 rounded-ss-xl border-b"
+			}),
+			columns.map((column, index) => /* @__PURE__ */ jsxs("header", {
+				className: cn("bg-card border-border text-muted-foreground sticky top-0 z-30 flex min-w-0 items-center gap-2 border-s border-b px-3 py-2.5 text-xs font-medium", index === columns.length - 1 && "rounded-se-xl"),
+				"data-slot": "day-calendar-column-header",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "min-w-0 shrink-0 truncate",
+					children: column.label
+				}), column.badge === void 0 ? null : /* @__PURE__ */ jsx("span", {
+					className: "bg-muted text-muted-foreground text-2xs min-w-0 truncate rounded-full px-2 py-0.5",
+					children: column.badge
+				})]
+			}, column.id)),
+			/* @__PURE__ */ jsx("div", {
+				"aria-hidden": "true",
+				className: "text-muted-foreground text-2xs relative tabular-nums",
+				style: bodyStyle,
+				children: hourTicks.map((tick) => /* @__PURE__ */ jsx("span", {
+					className: "absolute end-2 pt-0.5",
+					"data-slot": "day-calendar-hour",
+					style: { insetBlockStart: timeToOffset(tick, grid) },
+					children: formatTime.format(tick)
+				}, tick))
+			}),
+			columns.map((column) => {
+				const columnSelection = selection?.columnId === column.id ? selection.range : null;
+				const columnDraft = draft?.columnId === column.id ? draft.range : null;
+				const panel = selection?.panel?.columnId === column.id ? {
+					content: selection.panel.content,
+					range: selection.range
+				} : null;
+				return /* @__PURE__ */ jsxs("div", {
+					className: "border-border relative min-w-0 border-s",
+					"data-column-id": column.id,
+					"data-slot": "day-calendar-column",
+					"data-type": column.type,
+					style: bodyStyle,
+					children: [
+						column.type === "locked" ? /* @__PURE__ */ jsx(LockedColumnBody, { action: column.action }) : null,
+						column.type === "blocks" && column.rangeSelection.type === "enabled" ? /* @__PURE__ */ jsxs("div", {
+							"aria-keyshortcuts": "ArrowUp ArrowDown Shift+ArrowUp Shift+ArrowDown Enter Escape",
+							"aria-label": column.rangeSelection.label,
+							"aria-orientation": "vertical",
+							"aria-valuemax": minutesFromStart(bounds.endMs),
+							"aria-valuemin": 0,
+							"aria-valuenow": minutesFromStart((columnDraft ?? initialKeyboardRange(column.id)).startMs),
+							"aria-valuetext": formatRange(columnDraft ?? initialKeyboardRange(column.id)),
+							className: "focus-visible:ring-ring absolute inset-0 touch-none outline-none select-none focus-visible:ring-2 focus-visible:ring-inset",
+							"data-slot": "day-calendar-surface",
+							onKeyDown: (event) => handleKeyDown(column.id, event),
+							onPointerCancel: handlePointerCancel,
+							onPointerDown: (event) => handlePointerDown(column.id, event),
+							onPointerMove: handlePointerMove,
+							onPointerUp: handlePointerUp,
+							role: "slider",
+							style: slotLinesStyle,
+							tabIndex: 0,
+							children: [/* @__PURE__ */ jsx(ColumnBlocks, {
+								blocks: column.blocks,
+								grid
+							}), /* @__PURE__ */ jsx(RangeOutline, {
+								committed: columnSelection,
+								draft: columnDraft,
+								grid,
+								timeFormatFor
+							})]
+						}) : null,
+						column.type === "blocks" && column.rangeSelection.type === "disabled" ? /* @__PURE__ */ jsxs("div", {
+							className: "absolute inset-0",
+							"data-slot": "day-calendar-surface",
+							style: slotLinesStyle,
+							children: [/* @__PURE__ */ jsx(ColumnBlocks, {
+								blocks: column.blocks,
+								grid
+							}), /* @__PURE__ */ jsx(RangeOutline, {
+								committed: columnSelection,
+								draft: null,
+								grid,
+								timeFormatFor
+							})]
+						}) : null,
+						nowVisible && column.type === "blocks" ? /* @__PURE__ */ jsx("div", {
+							"aria-hidden": "true",
+							className: "bg-destructive pointer-events-none absolute inset-x-0 z-20 h-0.5",
+							"data-slot": "day-calendar-now",
+							style: { insetBlockStart: timeToOffset(nowMs, grid) }
+						}) : null,
+						panel === null ? null : /* @__PURE__ */ jsx("div", {
+							className: "absolute inset-x-2 z-40",
+							"data-slot": "day-calendar-panel",
+							style: { insetBlockStart: timeToOffset(panel.range.startMs, grid) },
+							children: panel.content
+						})
+					]
+				}, column.id);
+			})
+		]
+	});
+};
+const ColumnBlocks = ({ blocks, grid }) => {
+	const visible = blocks.flatMap((block) => {
+		const startMs = Math.max(block.startMs, grid.bounds.startMs);
+		const endMs = Math.min(block.endMs, grid.bounds.endMs);
+		return endMs > startMs ? [{
+			block,
+			endMs,
+			id: block.id,
+			startMs
+		}] : [];
+	});
+	const lanes = layoutOverlaps(visible);
+	return visible.map(({ block, endMs, startMs }) => {
+		const lane = lanes.get(block.id);
+		if (lane === void 0) panic(`Day calendar layout lost block ${block.id}`);
+		return /* @__PURE__ */ jsx(DayCalendarBlockView, {
+			block,
+			lane,
+			range: {
+				endMs,
+				startMs
+			},
+			grid
+		}, block.id);
+	});
+};
+/** Below this height a block puts its title and detail on one line. */
+const TWO_LINE_BLOCK_MIN_PX = 40;
+/** A brief block paints at least this tall, unless the grid ends sooner. */
+const BLOCK_MIN_PX = 6;
+const BLOCK_KIND_CLASSES = {
+	entry: "font-medium",
+	mixed: "text-muted-foreground",
+	segment: ""
+};
+const ENTRY_STATE_CLASSES = {
+	draft: "border border-dashed border-current/40",
+	final: ""
+};
+const DayCalendarBlockView = ({ block, grid, lane, range }) => {
+	const top = timeToOffset(range.startMs, grid);
+	const blockSize = Math.min(Math.max(timeToOffset(range.endMs, grid) - top, BLOCK_MIN_PX), boundsHeight(grid) - top);
+	const placement = {
+		blockSize,
+		inlineSize: `${String(100 / lane.laneCount)}%`,
+		insetBlockStart: top,
+		insetInlineStart: `${String(lane.lane * 100 / lane.laneCount)}%`
+	};
+	return /* @__PURE__ */ jsx("div", {
+		className: "pointer-events-none absolute px-1.5 py-px",
+		style: placement,
+		children: /* @__PURE__ */ jsxs("article", {
+			"aria-label": block.accessibleLabel,
+			className: cn("text-foreground flex h-full min-w-0 overflow-hidden rounded-md px-2.5 text-start text-xs", blockSize < TWO_LINE_BLOCK_MIN_PX ? "flex-row items-center gap-2" : "flex-col gap-0.5 py-1", BLOCK_KIND_CLASSES[block.kind], block.kind === "entry" && ENTRY_STATE_CLASSES[block.state], block.tone.type === "matter" && "border-s-[3px]", block.tone.type === "neutral" && "bg-muted"),
+			"data-kind": block.kind,
+			"data-slot": "day-calendar-block",
+			style: blockSurfaceStyle(block),
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "min-w-0 shrink-0 truncate font-medium",
+				children: block.title
+			}), block.detail === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				className: "text-muted-foreground min-w-0 truncate tabular-nums",
+				children: block.detail
+			})]
+		})
+	});
+};
+const MIXED_STRIPES = "repeating-linear-gradient(135deg, var(--muted) 0 6px, transparent 6px 12px)";
+function blockSurfaceStyle(block) {
+	const tone = block.tone;
+	const stripes = block.kind === "mixed" ? MIXED_STRIPES : void 0;
+	switch (tone.type) {
+		case "neutral": return { backgroundImage: stripes };
+		case "matter": {
+			const color = resolveMatterColor(tone.matterId, tone.color);
+			return {
+				backgroundColor: `color-mix(in srgb, ${color} 16%, var(--card))`,
+				backgroundImage: stripes,
+				borderInlineStartColor: color
+			};
+		}
+		default: return panic("Unhandled day calendar tone");
+	}
+}
+const RangeOutline = ({ committed, draft, grid, timeFormatFor }) => {
+	const range = draft ?? committed;
+	if (range === null) return null;
+	const formatTime = timeFormatFor(range);
+	const top = timeToOffset(range.startMs, grid);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "border-info bg-info/10 pointer-events-none absolute inset-x-1 z-10 rounded-lg border-2",
+		"data-slot": "day-calendar-selection",
+		"data-state": draft === null ? "committed" : "draft",
+		style: {
+			blockSize: timeToOffset(range.endMs, grid) - top,
+			insetBlockStart: top
+		},
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "text-info-foreground text-2xs absolute end-1 bottom-full mb-0.5 tabular-nums",
+			children: formatTime.format(range.startMs)
+		}), /* @__PURE__ */ jsx("span", {
+			className: "text-info-foreground text-2xs absolute end-1 top-full mt-0.5 tabular-nums",
+			children: formatTime.format(range.endMs)
+		})]
+	});
+};
+/**
+* Placeholder geometry for a locked column, as fractions of the column. It is
+* fixed so that nothing about the hidden data (count, timing, length) leaks.
+*/
+const LOCKED_PLACEHOLDER_BARS = [
+	{
+		blockSize: "7%",
+		inlineEnd: "30%",
+		start: "1%",
+		tone: "tinted"
+	},
+	{
+		blockSize: "5%",
+		inlineEnd: "12%",
+		start: "9%",
+		tone: "neutral"
+	},
+	{
+		blockSize: "5%",
+		inlineEnd: "40%",
+		start: "15%",
+		tone: "neutral"
+	},
+	{
+		blockSize: "8%",
+		inlineEnd: "18%",
+		start: "21%",
+		tone: "tinted"
+	},
+	{
+		blockSize: "7%",
+		inlineEnd: "25%",
+		start: "30%",
+		tone: "neutral"
+	},
+	{
+		blockSize: "8%",
+		inlineEnd: "35%",
+		start: "42%",
+		tone: "tinted"
+	},
+	{
+		blockSize: "6%",
+		inlineEnd: "22%",
+		start: "55%",
+		tone: "neutral"
+	}
+];
+const LOCKED_BAR_TONES = {
+	neutral: "bg-muted-foreground/15",
+	tinted: "bg-muted-foreground/25"
+};
+const LockedColumnBody = ({ action }) => /* @__PURE__ */ jsxs("div", {
+	className: "absolute inset-0 overflow-hidden",
+	children: [/* @__PURE__ */ jsx("div", {
+		"aria-hidden": "true",
+		className: "absolute inset-0 opacity-70 blur-sm",
+		"data-slot": "day-calendar-locked-placeholder",
+		inert: true,
+		children: LOCKED_PLACEHOLDER_BARS.map((bar) => /* @__PURE__ */ jsx("div", {
+			className: cn("absolute start-2.5 rounded-lg", LOCKED_BAR_TONES[bar.tone]),
+			style: {
+				blockSize: bar.blockSize,
+				insetBlockStart: bar.start,
+				insetInlineEnd: bar.inlineEnd
+			}
+		}, bar.start))
+	}), /* @__PURE__ */ jsx("div", {
+		className: "absolute inset-x-3 top-16 flex justify-center",
+		"data-slot": "day-calendar-locked-action",
+		children: action
+	})]
+});
+function assertDayCalendarContract(columns) {
+	if (new Set(columns.map(({ id }) => id)).size !== columns.length) panic("Day calendar column ids must be unique");
+}
+//#endregion
+export { DayCalendar };

package/dist/calendar/day-calendar.logic.d.ts

@@ -0,0 +1,113 @@
+//#region src/calendar/day-calendar.logic.d.ts
+export declare const DAY_CALENDAR_GRANULARITIES: readonly [15, 30, 60];
+export type DayCalendarGranularity = (typeof DAY_CALENDAR_GRANULARITIES)[number];
+/**
+ * Height of one grid slot. Coarser grids get taller slots, but not
+ * proportionally: an hour stays tall enough for a two-line block.
+ */
+export declare const DAY_CALENDAR_SLOT_HEIGHT_PX: {
+  readonly 15: 22;
+  readonly 30: 32;
+  readonly 60: 44;
+};
+/** A half-open instant range, `[startMs, endMs)`, in epoch milliseconds. */
+export type DayCalendarRange = {
+  endMs: number;
+  startMs: number;
+};
+export declare const granularityMs: (granularity: DayCalendarGranularity) => number;
+type DayBoundsOptions = {
+  date: string;
+  endHour: number;
+  startHour: number;
+  timeZone: string;
+};
+/**
+ * The instants a day view covers, from `startHour` to `endHour` wall-clock
+ * time in `timeZone`. A daylight-saving day is an hour shorter or longer;
+ * the view stays linear in real time. Hours wholly inside a daylight-saving
+ * gap resolve both ends to the same instant; the view then covers the hour
+ * after the gap rather than collapsing to zero height.
+ */
+export declare const getDayBounds: ({ date, endHour, startHour, timeZone }: DayBoundsOptions) => DayCalendarRange;
+/**
+ * Whether the wall-clock time at `ms` occurs twice in `timeZone`, as in the
+ * repeated hour of a fall-back day; only its UTC offset tells it apart from
+ * its twin. A wall time read from an instant is never in a gap, so the two
+ * resolutions differ only for a repeated one.
+ */
+export declare const isRepeatedWallTime: (ms: number, timeZone: string) => boolean;
+/** One instant per elapsed hour from the day's start, for hour labels. */
+export declare const getHourTicks: (bounds: DayCalendarRange) => number[];
+type OffsetOptions = {
+  granularity: DayCalendarGranularity;
+  bounds: DayCalendarRange;
+};
+export declare const timeToOffset: (ms: number, { granularity, bounds }: OffsetOptions) => number;
+export declare const offsetToTime: (offsetPx: number, { granularity, bounds }: OffsetOptions) => number;
+export declare const boundsHeight: (options: OffsetOptions) => number;
+export declare const clampToBounds: (ms: number, bounds: DayCalendarRange) => number;
+export type SnapDirection = "ceil" | "floor" | "nearest";
+/**
+ * Snaps to the slot grid, which starts at the day's first hour (a whole
+ * wall-clock hour), then clamps into the day. Idempotent: a snapped
+ * instant is a grid point or a day edge, and both snap to themselves.
+ */
+export declare const snapToGrid: (ms: number, { direction, granularity, bounds }: OffsetOptions & {
+  direction: SnapDirection;
+}) => number;
+/**
+ * The snapped range between a drag's anchor and the pointer, in either
+ * order: the start floors and the end ceils, so the range always covers
+ * both instants.
+ */
+export declare const rangeFromDrag: ({ anchorMs, pointerMs }: {
+  anchorMs: number;
+  pointerMs: number;
+}, options: OffsetOptions) => DayCalendarRange;
+/** Moves a range by whole slots, keeping its duration inside the day. */
+export declare const moveRange: (range: DayCalendarRange, slots: number, { granularity, bounds }: OffsetOptions) => DayCalendarRange;
+/** Grows or shrinks a range's end by whole slots; it never drops below one slot. */
+export declare const extendRange: (range: DayCalendarRange, slots: number, options: OffsetOptions) => DayCalendarRange;
+/** A one-slot range at the snapped instant, used to start a keyboard selection. */
+export declare const slotAt: (ms: number, options: OffsetOptions) => DayCalendarRange;
+export type DayCalendarLanePlacement = {
+  lane: number;
+  laneCount: number;
+};
+/**
+ * Places overlapping ranges side by side. Ranges that overlap transitively
+ * form a cluster; each takes the first lane free at its start, and every
+ * member of a cluster shares the cluster's lane count, so their widths match.
+ */
+export declare const layoutOverlaps: (ranges: readonly (DayCalendarRange & {
+  id: string;
+})[]) => Map<string, DayCalendarLanePlacement>;
+export type MergedSegment<Segment extends DayCalendarRange & {
+  id: string;
+}> = {
+  segment: Segment;
+  type: "single";
+} | {
+  endMs: number;
+  id: string;
+  sources: Segment[];
+  startMs: number;
+  type: "mixed";
+};
+/**
+ * Collapses runs of rapid switching. Consecutive segments shorter than
+ * `thresholdMs` that touch or overlap form one `mixed` entry listing its
+ * sources in time order; a lone short segment stays as it is. Every input
+ * segment lands in exactly one output entry, and the time the output covers
+ * equals the time the input covers. Output ids are unique: a `mixed` id
+ * derives from its first source and takes a numeric suffix when an input or
+ * an earlier entry already uses it.
+ */
+export declare const mergeShortSegments: <Segment extends DayCalendarRange & {
+  id: string;
+}>(segments: readonly Segment[], { thresholdMs }: {
+  thresholdMs: number;
+}) => MergedSegment<Segment>[];
+//#endregion
+export {};