@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/lib/board/position.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ==== COLUMN POSITION ====
+ *
+ * Two facts about a column that three callers each need and must not each work
+ * out for themselves (DX-4540): how long the column really is, and where in the
+ * whole column a loaded card sits. A windowed column holds only a few pages of
+ * a longer list, so the cards loaded are not the column.
+ *
+ * `buildBoardModel` decides the length once (the model's `count`); `resolveMove`
+ * works from the column DEFINITIONS before any model exists and must decide
+ * "is this card already at that edge" with the same rule; and the move menu
+ * decides what to offer from a card's place in the column. All three read these.
+ */
+import type { BoardColumnDef } from "./types";
+/**
+ * The column's length: its `total` when the definition gave a number, otherwise
+ * the cards loaded (`total` absent means every card is loaded; `null` means the
+ * length is still being read, so the loaded cards are all that is known).
+ */
+export declare function columnLength(def: Pick<BoardColumnDef, "total"> | undefined, loaded: number): number;
+/** The place in the whole column of the loaded card at `index`: the window's offset plus the index. */
+export declare function positionInColumn(def: Pick<BoardColumnDef, "offset"> | undefined, index: number): number;

package/dist/types/lib/board/rejection.d.ts

@@ -0,0 +1,8 @@
+import type { UiStrings } from "../i18n";
+import type { BoardMoveRejection } from "./types";
+/**
+ * DX-4740: the sentence a person reads for a refused move. The core answers with values
+ * (`BoardMoveRejection`); the provider's `moveRejected` strings word them. A consumer's own
+ * sentence passes through untouched.
+ */
+export declare function describeMoveRejection(strings: UiStrings["moveRejected"], locale: string, reason: BoardMoveRejection): string;

package/dist/types/lib/board/types.d.ts

@@ -0,0 +1,294 @@
+/**
+ * The board contract. One model shape, one movement pipeline, read by the
+ * headless core and by the React slot layer above it.
+ *
+ * WHAT A BOARD IS HERE. Columns of items, where the items are OPAQUE to us. The
+ * board never learns what an item means — no `title`, no `priority`, no
+ * `assignee`, no status vocabulary. It knows an item's identity, which column
+ * holds it, and nothing else; everything visible is rendered by the consumer.
+ * That is not squeamishness about coupling, it is the only way the same
+ * component serves a second application: the moment a named prop describes a
+ * domain field, every consumer whose domain differs has to fight it.
+ *
+ * WHY ACCESSORS RATHER THAN A REQUIRED ITEM SHAPE. Demanding
+ * `{id, columnId}` forces every consumer to map their data into our shape and
+ * back out again, and that mapping is where identity gets lost — a remap that
+ * regenerates ids breaks drag mid-gesture, and it breaks silently. Reading the
+ * consumer's own objects through accessor functions means their array IS the
+ * source of truth and no copy exists to drift.
+ *
+ * THE MOVEMENT PIPELINE IS SINGULAR, AND THAT IS THE LOAD-BEARING RULE.
+ * Pointer drag, keyboard, the action menu and a bulk move all terminate in the
+ * SAME validated `onMove`. The alternative — a code path per input — is exactly
+ * how the accessible paths rot: the drag path gets exercised daily and the menu
+ * path silently stops agreeing with it, taking the WCAG 2.5.7 alternative
+ * (below) down with it. There is one funnel, so a fix or a bug reaches every
+ * input at once.
+ *
+ * WCAG 2.2 SC 2.5.7 IS WHY A MENU PATH EXISTS AT ALL, AND KEYBOARD DOES NOT
+ * SATISFY IT. Verbatim from the W3C's own understanding document: "achieving
+ * keyboard equivalence for a dragging operation does not automatically meet
+ * this success criterion, unless that equivalent keyboard operation also
+ * provides controls that can be clicked or tapped with a pointer." A touchscreen
+ * user may have no keyboard at all. So a single-pointer, non-dragging route to
+ * every drag outcome is mandatory rather than a courtesy, and `"menu"` is a
+ * first-class `BoardMoveSource` for that reason.
+ *
+ * INDICES COUNT THE LIST WITH THE MOVED ITEM ALREADY REMOVED. Inherited
+ * deliberately from `lib/dnd`'s `DropTarget` (see its header): it makes
+ * same-column and cross-column moves arithmetically identical and removes the
+ * whole off-by-one class. Every index in this file means that. Restating it
+ * here rather than assuming it, because a board that re-derives its own
+ * convention alongside the engine's is how the two drift.
+ */
+import type { ContainerId, DragId } from "../dnd";
+/**
+ * Identities are the engine's, not parallel types. A board column IS a drag
+ * container and a board item IS a draggable, so aliasing them keeps a value
+ * from having to be cast on its way between the two layers — the kind of cast
+ * that compiles forever and is wrong once.
+ */
+export type BoardColumnId = ContainerId;
+export type BoardItemId = DragId;
+/**
+ * How the board reads the consumer's own objects. `getId` and `getColumnId` are
+ * required because they are the two facts a board cannot function without;
+ * everything else about an item is the consumer's business.
+ */
+export interface BoardAccessors<T> {
+    /** Stable across renders. Never an array index — see the engine's `DragId`. */
+    getId: (item: T) => BoardItemId;
+    getColumnId: (item: T) => BoardColumnId;
+}
+export interface BoardColumnDef {
+    id: BoardColumnId;
+    /**
+     * Spoken in every announcement about this column and shown in the move menu.
+     * Required, unlike the engine's optional `label`: a column whose accessible
+     * name falls back to an id reads as "column c-3-todo" to a screen reader,
+     * which is speakable and useless. The board always has a real name available
+     * because the consumer had to name the column to render its header anyway.
+     */
+    label: string;
+    /**
+     * Soft cap on item count. Exceeding it is a VISUAL event, not a blocked move
+     * — a WIP limit exists to interrupt a human, and a board that refuses the
+     * drop instead just teaches people to work around the board. The core reports
+     * `overWip`; the view layer is responsible for making it loud. The limit is
+     * judged against the column's real length (`total`), not what is loaded.
+     */
+    wipLimit?: number;
+    /**
+     * DX-4540: the column's real length when `items` holds only the cards loaded so
+     * far (a windowed lane). The model's `count` is this number, and `overWip`,
+     * the move menu's "is there anything above/below" and the drag announcements
+     * all read it. `null` means the length is still being read: the column is
+     * neither empty nor over its limit, and `count` falls back to the loaded
+     * cards. Omitted, every card of the column is loaded and the count is theirs.
+     */
+    total?: number | null;
+    /**
+     * DX-4540: the position in the whole column of the first loaded card, so a
+     * card at index 0 of `items` is spoken as "position 221", not "position 1".
+     * Only meaningful with `total`; the loaded cards must be one contiguous run
+     * of the column. @default 0
+     */
+    offset?: number;
+    /**
+     * DX-4575: turns OFF reordering inside this column, and is the sentence shown
+     * in it while a card from it is dragged over it. Moves to and from OTHER
+     * columns are untouched. Text, not a boolean: supplying it is what turns the
+     * rule on, and the consumer owns the words (a column sorted by something its
+     * order cannot express, say, would tell the person what to sort by first).
+     * Enforced in `resolveMove`, so the drag, the keyboard, the menu and a bulk
+     * move all obey it, and the menu stops offering the within-column items.
+     */
+    reorderLocked?: string;
+    /**
+     * DX-4589: the words for THIS column's card-menu items that move a card to
+     * the column's visual top and bottom, replacing the Board's `reorderLabels`
+     * (then the defaults) for this column only. Partial, so a column renames one
+     * and inherits the other. The items stay positional: `toTop` moves to the
+     * visual top (`index` 0, `edge: "top"`), whatever order the column is sorted
+     * in, so a column sorted lowest-priority-first words `toTop` as the move that
+     * LOWERS the card.
+     */
+    reorderLabels?: Partial<BoardReorderLabels>;
+}
+/** The card menu's within-column items. DX-4575: a consumer that calls moving inside a list something else renames them. */
+export interface BoardReorderLabels {
+    toTop: string;
+    toBottom: string;
+}
+/**
+ * Where a move lands beyond what is loaded. In a windowed column `to.index` can
+ * only name a position among the LOADED cards, so a move to "the very top" or
+ * "the very bottom" of the column says so here and the consumer sends that
+ * intent to its server (see `moveAnchor`). In a column with every card loaded
+ * the edge is the same place as `index` 0 / the end, so a consumer that ignores
+ * it is still right.
+ */
+export type BoardEdge = "top" | "bottom";
+/**
+ * One item's move. `to.index` counts the destination list without this item —
+ * the LOADED list, in a windowed column. `to.edge`, when present, is the
+ * intent the index cannot carry; the index is then the nearest loaded position
+ * (0 for `"top"`, one past the last loaded card for `"bottom"`).
+ */
+export interface BoardMove {
+    itemId: BoardItemId;
+    from: {
+        columnId: BoardColumnId;
+        index: number;
+    };
+    to: BoardMoveTarget;
+}
+/**
+ * Where a move lands: a place in the destination (`index`, and optionally the
+ * `edge` it stands for), or only the destination (`lane: true`).
+ *
+ * DX-4583: a lane move names no position, so it has no `index` to be wrong
+ * about. It is what a board produces when a card is carried into another lane
+ * and the consumer decided that a lane change is not also a reorder (`Board`'s
+ * `crossLaneDrop="lane"`): the card keeps whatever rank it already has in the
+ * consumer's data, and `applyBoardMoves` leaves it where the consumer's order holds it. Narrow on `to.lane` before reading `to.index`, so a consumer
+ * that turns the option on cannot miss that there is no position to write.
+ */
+export type BoardMoveTarget = {
+    columnId: BoardColumnId;
+    index: number;
+    edge?: BoardEdge;
+    lane?: never;
+} | {
+    columnId: BoardColumnId;
+    lane: true;
+    index?: never;
+    edge?: never;
+};
+/**
+ * Which input produced the move. Kept on the request rather than inferred
+ * downstream because the three that are not `"pointer"` are the ones with no
+ * visible symptom when they break: a consumer's telemetry, and our own tests,
+ * need to assert that all four routes actually reach the funnel.
+ */
+export type BoardMoveSource = "pointer" | "keyboard" | "menu" | "bulk";
+/**
+ * `moves.length > 1` only for `"bulk"`, and then it is ALL-OR-NOTHING.
+ * Partially applying a multi-select move — accepting the first two cards and
+ * rejecting the rest — leaves the operator with a board state they did not ask
+ * for and cannot infer, which is worse than a clean refusal.
+ */
+export interface BoardMoveRequest {
+    moves: readonly BoardMove[];
+    source: BoardMoveSource;
+}
+/**
+ * A rejection MUST carry a reason, and that is why this is a verdict object
+ * rather than a boolean. A bare refusal is the failure mode GitHub Actions is
+ * still generating support threads over — a job sits in "queued" and the UI
+ * cannot say whether it is a concurrency limit, an approval or capacity. The
+ * reason is surfaced to the user and to the live-region announcer, so it is
+ * written for a person to read, not logged.
+ */
+export type BoardMoveVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * DX-4740: WHY THE CORE REFUSED A MOVE, AS VALUES, NEVER AS A SENTENCE. The core
+ * (`resolveMove`) has no language; the component that shows the refusal words it
+ * through the provider's `moveRejected` strings. Only the refusals a person can
+ * reach are listed: a stale request (the card was moved or removed under them) and
+ * a consumer's own sentence. A column that is no longer declared is the same kind of
+ * stale request (a live update removed it during the drag). A malformed request (a negative
+ * index, a duplicate item, a multi-move request that is not `"bulk"`) is the
+ * caller's bug and throws an English `Error` from `resolveMove` instead.
+ */
+export type BoardMoveRejection = {
+    code: "unknownItem";
+    itemId: BoardItemId;
+} | {
+    code: "unknownColumn";
+    columnId: BoardColumnId;
+} | {
+    code: "wrongColumn";
+    itemId: BoardItemId;
+    actualColumnId: BoardColumnId;
+    claimedColumnId: BoardColumnId;
+} | {
+    code: "fromIndexPastEnd";
+    itemId: BoardItemId;
+    index: number;
+    columnId: BoardColumnId;
+    count: number;
+} | {
+    code: "toIndexPastEnd";
+    itemId: BoardItemId;
+    index: number;
+    columnId: BoardColumnId;
+    max: number;
+}
+/** The consumer's own sentence (`reorderLocked`, `validateMove`), already in their language: shown as is. */
+ | {
+    code: "consumer";
+    message: string;
+};
+/** What `resolveMove` and `useBoard().requestMove` answer: `BoardMoveVerdict`, with a structured reason. */
+export type BoardMoveOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: BoardMoveRejection;
+};
+/** A column as the core computes it, ready to render. */
+export interface BoardColumnModel<T> {
+    id: BoardColumnId;
+    label: string;
+    /** The cards loaded. All of the column's cards unless the column is windowed. */
+    items: readonly T[];
+    /**
+     * The column's length: its `total` when the definition gave one, else the
+     * loaded cards. Count is on the model because the view needs it before it
+     * renders rows — and because it is computed ONCE here: the badge, the empty
+     * state, the WIP verdict, the move menu and the announcements all read this
+     * number, never their own.
+     */
+    count: number;
+    /** `true` while a windowed column's length is still being read (`total: null`). `count` is then the loaded cards. */
+    counting: boolean;
+    /** Position in the whole column of `items[0]`; 0 unless the column is windowed. */
+    offset: number;
+    wipLimit: number | undefined;
+    /** `true` when `count` exceeds `wipLimit`. Always false with no limit set, and while `counting`. */
+    overWip: boolean;
+    /** The definition's `reorderLocked` sentence; `undefined` when the column can be reordered. */
+    reorderLocked: string | undefined;
+    /** The definition's `reorderLabels`; `undefined` when the column words the items as the Board does. */
+    reorderLabels: Partial<BoardReorderLabels> | undefined;
+}
+export interface UseBoardOptions<T> {
+    items: readonly T[];
+    columns: readonly BoardColumnDef[];
+    accessors: BoardAccessors<T>;
+    /**
+     * Consulted before ANY move commits, from any of the four sources. Absent
+     * means every move is allowed — the common case, and not something a consumer
+     * should have to write boilerplate to say.
+     */
+    validateMove?: (request: BoardMoveRequest) => BoardMoveVerdict;
+    /**
+     * The single commit point. Fires only for a move that is both valid and not a
+     * no-op: the engine's `DragEndEvent.moved` exists because the previous board
+     * wrote its ordering field on every release that landed where it started, and
+     * a write that changes nothing still costs a request, a re-render and an audit
+     * row. That filtering happens in the core so no consumer has to remember it.
+     */
+    onMove: (request: BoardMoveRequest) => void;
+    /** Selection is board state because bulk atomicity is a board concern. */
+    selection?: {
+        selected: readonly BoardItemId[];
+        onChange: (selected: readonly BoardItemId[]) => void;
+    };
+}

package/dist/types/lib/board/use-board.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ==== USE BOARD ====
+ *
+ * The React binding over the two pure modules. Deliberately thin: every claim
+ * this hook makes has already been proven in model.ts and move.ts without a
+ * browser, so the only thing left for React-specific code to get wrong is
+ * memoisation and the selection wiring — logic that lived INSIDE a hook
+ * instead of a pure function would be logic no test in board-core.test.ts
+ * could reach without mounting a component. `renderHook` here exists only to
+ * prove the composition wires up, not to re-prove validation or bulk
+ * atomicity, which are already pinned in the pure-module tests.
+ *
+ * `requestMove` IS THE SINGLE FUNNEL. Pointer drag's `onDragEnd`, a keyboard
+ * handler, the mandatory "Move to…" menu (WCAG 2.5.7 — see `types.ts`), and a
+ * bulk-selection action all construct a `BoardMoveRequest` and call this ONE
+ * function. It never mutates `items` itself — `UseBoardOptions.onMove` returns
+ * `void` by contract, so the actual next `items` array is the CONSUMER's to
+ * produce, typically via `applyBoardMoves` from `./move`. `requestMove` only
+ * decides whether that consumer callback fires at all, and returns the verdict
+ * synchronously so the caller (e.g. the menu) can show a rejection reason
+ * immediately rather than guessing from a UI that just didn't change.
+ *
+ * SELECTION IS FULLY CONTROLLED, NOT A SECOND SOURCE OF TRUTH. `selection` on
+ * `UseBoardOptions` supplies BOTH `selected` and `onChange` — this hook never
+ * keeps its own copy of which ids are selected, for the same reason `items`
+ * is never copied: a second copy is a copy that can drift. What this hook
+ * "owns" is the BEHAVIOUR built on top of that controlled pair (toggle one,
+ * replace the set, clear) so every input source computes a selection change
+ * the same way, mirroring why `requestMove` exists as a single funnel for
+ * moves rather than one per source.
+ */
+import type { BoardColumnModel, BoardItemId, BoardMoveRequest, BoardMoveOutcome, UseBoardOptions } from "./types";
+export interface UseBoardResult<T> {
+    /** One entry per declared column, in `columns` order, ready to render. */
+    columns: readonly BoardColumnModel<T>[];
+    /** Items whose `getColumnId` matched no declared column. See model.ts. */
+    unassigned: readonly T[];
+    /** The current controlled selection, or `[]` when `selection` was not supplied. */
+    selected: readonly BoardItemId[];
+    /** No-ops when `selection` was not supplied — see the file header. */
+    toggleSelected: (id: BoardItemId) => void;
+    setSelected: (ids: readonly BoardItemId[]) => void;
+    clearSelection: () => void;
+    /** The single funnel every input source calls. See the file header. */
+    requestMove: (request: BoardMoveRequest) => BoardMoveOutcome;
+}
+export declare function useBoard<T>(options: UseBoardOptions<T>): UseBoardResult<T>;

package/dist/types/lib/calendar/band-packer.d.ts

@@ -0,0 +1,53 @@
+/** A contiguous run of columns within one row of the grid. Both ends inclusive. */
+export interface BandInput {
+    readonly key: string;
+    readonly startColumn: number;
+    readonly endColumn: number;
+    /**
+     * Ordering weight. Lower sorts earlier, so pinned items keep their place as
+     * neighbours come and go. Ties fall through to span length, then key.
+     */
+    readonly priority?: number;
+}
+export interface BandPlacement extends BandInput {
+    /** 0-based row within the band. */
+    readonly row: number;
+}
+export interface BandResult {
+    /** Everything that fits, in row order. */
+    readonly placed: readonly BandPlacement[];
+    /** Everything pushed past the limit, in the same order it would have had. */
+    readonly hidden: readonly BandInput[];
+    /** Per column, how many hidden items cover it — the "+N more" count. */
+    readonly overflow: readonly number[];
+    /** Rows actually used by `placed`. */
+    readonly rows: number;
+}
+export interface BandOptions {
+    /** How many columns the row has. Required — it sizes the overflow tally. */
+    readonly columns: number;
+    /**
+     * Most rows the band may occupy, INCLUDING the row the "+N more" affordance
+     * takes.
+     *
+     * Counting the affordance is what stops the classic off-by-one where the
+     * overflow link is drawn on top of the last event. When items do not fit,
+     * events get `maxRows - 1` rows and the last is reserved — which is
+     * FullCalendar's `dayMaxEventRows` semantics, and the only version that
+     * leaves room for the thing it just decided to draw.
+     *
+     * Omit for no limit. The all-day band MUST pass one: an uncapped band eats
+     * the container and makes the time grid unreachable — an open FullCalendar
+     * bug, and react-big-calendar's default is literally `Infinity`.
+     */
+    readonly maxRows?: number;
+}
+/**
+ * Assign each item the first row where every column it covers is free.
+ *
+ * Greedy first-fit. Not optimal in the sense of minimising rows — that is
+ * NP-hard and nobody wants it anyway, because the optimal packing reshuffles
+ * every event's row whenever one is added, and a calendar whose events jump
+ * rows as you type is worse than one that uses an extra row.
+ */
+export declare function packBand(inputs: readonly BandInput[], options: BandOptions): BandResult;

package/dist/types/lib/calendar/drag.d.ts

@@ -0,0 +1,125 @@
+import { type Instant, type PlainDate, type TimeZone } from "@/lib/time";
+import type { CalendarDuration } from "@/lib/time";
+import type { DragKind, TimedEvent } from "./types";
+/** A day column, as the view measured it. */
+export interface ColumnRect {
+    readonly day: PlainDate;
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+    readonly bottom: number;
+}
+/** Where a pointer is, in calendar terms. */
+export interface CalendarTarget {
+    readonly dayIndex: number;
+    readonly day: PlainDate;
+    /** Snapped to `snapMinutes`, measured from that day's own first instant. */
+    readonly instant: Instant;
+}
+export interface ResolveOptions {
+    readonly zone: TimeZone;
+    readonly columns: readonly ColumnRect[];
+    readonly snapMinutes: number;
+}
+/**
+ * Which day and which time a point is over.
+ *
+ * `null` outside every column — and the caller KEEPS THE LAST NON-NULL TARGET
+ * rather than treating that as "no drop". A pointer leaves the columns
+ * constantly while dragging toward the edge of the grid, and an event that
+ * snapped back to its origin every time the finger crossed the gutter would be
+ * unusable.
+ */
+export declare function resolveCalendarTarget(point: {
+    x: number;
+    y: number;
+}, options: ResolveOptions): CalendarTarget | null;
+/**
+ * Snap an instant to the nearest `snapMinutes`, measured from the DAY'S OWN
+ * first instant.
+ *
+ * Not from midnight and not from the epoch. On a day that begins at 01:00 —
+ * Havana in March — snapping to the epoch puts every slot boundary an hour away
+ * from the rails the grid drew, in exactly the zones where a user is least able
+ * to explain what they are seeing.
+ */
+export declare function snapInstant(zone: TimeZone, day: PlainDate, instant: Instant, snapMinutes: number): Instant;
+export interface CalendarDragOrigin {
+    readonly event: TimedEvent;
+    readonly kind: DragKind;
+    /** The target under the pointer when the gesture activated. */
+    readonly from: CalendarTarget;
+}
+export interface CalendarDragResult {
+    /**
+     * The change, as a CALENDAR duration — never milliseconds.
+     *
+     * "One day later" is 23 hours across a spring-forward boundary and 25 across
+     * a fall-back. A user dragging an event from Saturday to Sunday expects it to
+     * keep its wall-clock time, and a millisecond delta cannot express that. It
+     * is the bug in every library surveyed.
+     */
+    readonly delta: CalendarDuration;
+    /** False when the gesture would leave the event exactly where it was. */
+    readonly moved: boolean;
+    /**
+     * Set when a resize would produce a zero or negative duration.
+     *
+     * REJECTED, NOT CLAMPED. FullCalendar returns no mutation at all;
+     * react-big-calendar clamps, and asymmetrically — its bottom-edge rule can
+     * produce a ZERO-DURATION event, which then renders as an invisible sliver
+     * the user cannot grab to fix. Refusing the gesture leaves the event where it
+     * was, which the user can see and try again from.
+     */
+    readonly invalid?: "too-short";
+}
+/**
+ * The minimum an event may be resized to, in minutes.
+ *
+ * One snap step. Anything smaller cannot be expressed by the gesture that made
+ * it, so it could never be undone by the same gesture.
+ */
+export declare const MIN_DURATION_MINUTES = 15;
+/**
+ * What a gesture from `origin` to `target` means.
+ *
+ * DAYS AND MINUTES SEPARATELY, and that separation is the whole point. The day
+ * component is a CALENDAR move — re-anchored to the same wall-clock time on the
+ * new day. The minute component is EXACT elapsed time — dragging down two hours
+ * means two hours. Both are true at once, and collapsing them into one number
+ * loses whichever property the collapse did not preserve.
+ */
+export declare function calendarDragResult(origin: CalendarDragOrigin, target: CalendarTarget, zone: TimeZone, minDurationMinutes?: number): CalendarDragResult;
+/**
+ * The event as it would be after `delta`, for the live preview.
+ *
+ * COMPOSED ONTO THE EVENT AT CALL TIME, never onto a snapshot taken at
+ * pointer-down. Two real failures from other calendars' trackers: a re-render
+ * replaces the event store mid-drag and the drag is left holding an instance
+ * from the dead one; and a concurrent server update during a drag DUPLICATES
+ * the times, because a snapshot was composited on top of data that had moved
+ * underneath it. Recomputing from whatever the event says now makes a change
+ * arriving mid-gesture compose rather than clobber.
+ */
+export declare function applyCalendarDelta(event: TimedEvent, kind: DragKind, delta: CalendarDuration, zone: TimeZone): TimedEvent;
+/**
+ * The event a drag-to-create gesture would produce.
+ *
+ * The two ends are ordered, so dragging upward creates the same event as
+ * dragging downward across the same span — which is what every calendar does
+ * and what a user expects from a rubber-band gesture.
+ */
+export declare function createdEvent(anchor: CalendarTarget, target: CalendarTarget, minDurationMinutes?: number): {
+    start: Instant;
+    endExclusive: Instant;
+    day: PlainDate;
+};
+/**
+ * A human description of the position, for the live region.
+ *
+ * "Moved to 2:30 PM, Wednesday" — the SLOT, not the fact that something moved.
+ * "Moved" alone tells a screen-reader user nothing they can act on.
+ */
+export declare function describeTarget(target: CalendarTarget, zone: TimeZone, locale: string): string;
+/** Where in the grid a fraction sits, for the preview. Inverse of the resolve. */
+export declare function fractionOf(zone: TimeZone, day: PlainDate, instant: Instant): number;

package/dist/types/lib/calendar/index.d.ts

@@ -0,0 +1,4 @@
+export { isAllDay, type AllDayEvent, type CalendarEvent, type CalendarEventId, type CalendarView, type DragKind, type EventDraft, type EventPalette, type PaletteEntry, type PaletteKey, type TimedEvent, type VisibleRange, } from "./types";
+export { packLanes, type LaneInput, type LaneOptions, type LanePlacement } from "./lane-packer";
+export { packBand, type BandInput, type BandOptions, type BandPlacement, type BandResult } from "./band-packer";
+export { allDayBandSegment, dayKey, daySlots, snapFractionToInstant, timeSegments, timedBandSegment, type BandSegment, type DaySlot, type TimeSegment, } from "./segments";

package/dist/types/lib/calendar/lane-packer.d.ts

@@ -0,0 +1,88 @@
+/** A half-open interval `[start, end)` in column fractions, with an identity. */
+export interface LaneInput {
+    readonly key: string;
+    readonly start: number;
+    readonly end: number;
+}
+export interface LanePlacement {
+    readonly key: string;
+    /** As laid out — possibly inflated past the input by `minSpan`. */
+    readonly start: number;
+    readonly end: number;
+    /** 0-based lane within this event's collision batch. */
+    readonly column: number;
+    /** Lanes in that batch. Uniform across every member of it — see below. */
+    readonly lanes: number;
+    /** Fraction of the container's width, from its leading edge. */
+    readonly left: number;
+    readonly width: number;
+    /** Later columns paint over earlier ones. Equal to `column`. */
+    readonly zIndex: number;
+}
+export interface LaneOptions {
+    /**
+     * `cascade` — every event runs to the container's trailing edge and later
+     * columns paint over earlier ones. **This is the Google look and the
+     * default.** `split` — the batch divides the width evenly and nothing
+     * overlaps.
+     *
+     * Three products, three different cascade multipliers: Schedule-X runs to the
+     * edge, FullCalendar doubles the lane width capped at 1, and
+     * react-big-calendar uses 1.7x — arbitrary and unexplained anywhere in its
+     * source. Running to the edge is the only one of the three that is a rule
+     * rather than a number someone liked.
+     */
+    readonly mode?: "cascade" | "split";
+    /**
+     * The smallest span an event may occupy, as a column fraction.
+     *
+     * A 5-minute event on a 12-hour column is 0.7% of it — unclickable, and
+     * unreadable long before that. So it is inflated to a floor.
+     *
+     * **THE INFLATED SPAN IS WHAT COLLISION USES TOO**, which is the part that is
+     * easy to get wrong. Two 5-minute events a minute apart do not overlap as
+     * intervals, but they overlap ON SCREEN once both are inflated to a clickable
+     * height — so laying them in the same lane stacks one on the other. Detecting
+     * collisions on the true interval and drawing the inflated one is how a
+     * calendar ends up with events sitting invisibly behind each other.
+     */
+    readonly minSpan?: number;
+    /**
+     * Cap on lanes per batch. Beyond it, events STACK in the last lane rather
+     * than disappear.
+     *
+     * A week column is around 120px; a fifth lane in it is 24px and unreadable.
+     * But hiding an event in a time grid is worse than overlapping one — the user
+     * can see and click something that overlaps, and cannot do either with
+     * something that is not there. So the cap limits the DIVISION, not the
+     * membership. Day view passes no cap.
+     */
+    readonly maxLanes?: number;
+    /**
+     * Floor on the rendered width, as a fraction.
+     *
+     * Guards the width-0 collapse — an open FullCalendar bug where enough
+     * concurrent events divide the column into nothing and the whole batch
+     * becomes invisible. A floor makes a crowded column ugly instead of empty.
+     */
+    readonly minWidth?: number;
+}
+/**
+ * Lay out overlapping events across lanes.
+ *
+ * Four steps, and the third is the colouring:
+ *
+ *   1. Sort by the total order above.
+ *   2. Sweep into COLLISION BATCHES — a batch closes when the next event starts
+ *      at or after the maximum end of everything accumulated so far. Two events
+ *      in different batches provably cannot overlap, so lane counts never leak
+ *      between them and one crowded hour does not narrow the whole day.
+ *   3. Within a batch, give each event the SMALLEST lane index not taken by an
+ *      earlier member it overlaps. That is greedy colouring of an interval
+ *      graph, and on interval graphs greedy in start order is OPTIMAL — it uses
+ *      exactly the number of lanes the maximum concurrency requires.
+ *   4. `lanes = maxColumn + 1`, computed ONCE PER BATCH and applied uniformly to
+ *      every member. Per-event lane counts are what make two side-by-side
+ *      events different widths for no visible reason.
+ */
+export declare function packLanes(inputs: readonly LaneInput[], options?: LaneOptions): LanePlacement[];