@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/lib/dnd/session.d.ts

@@ -0,0 +1,124 @@
+import type { ContainerRegistration, CrossDrop, DragId, DragMode, DragSessionCallbacks, DragState, GroupRegistration, ItemRegistration, LayoutSnapshot, Point } from "./types";
+export interface StartArgs {
+    id: DragId;
+    mode: DragMode;
+    /** Pointer position at pickup. Omitted for keyboard sessions. */
+    point?: Point;
+    /**
+     * `true` for a pointer that is down but has not passed its activation
+     * constraint yet. The session holds `pending` until the sensor calls
+     * `activate()` — see `DragPhase` in `types.ts` for why that gap exists.
+     */
+    pending?: boolean;
+}
+export declare class DragSession {
+    private state;
+    private listeners;
+    private items;
+    private containers;
+    private groups;
+    private layout;
+    private callbacks;
+    private observers;
+    constructor(callbacks?: DragSessionCallbacks);
+    /**
+     * The OWNING consumer's callbacks — the one that renders the board and writes
+     * the reorder. Replaced rather than passed per-call because a React consumer
+     * re-creates its handlers on every render and the session must not be rebuilt;
+     * rebuilding it mid-gesture drops the drag.
+     */
+    setCallbacks(callbacks: DragSessionCallbacks): void;
+    /**
+     * Register an ADDITIONAL listener. Returns its teardown.
+     *
+     * `setCallbacks` is a single slot owned by whoever renders the board, so a
+     * second interested party — the live-region announcer, an analytics hook, a
+     * test — could not be told anything without clobbering it. And `subscribe`
+     * is not a substitute: a drop and a cancel both end at the same idle state,
+     * so a state subscriber sees ONE identical transition for two outcomes that
+     * must be announced differently.
+     *
+     * That gap was not theoretical. The announcer worked around it by inferring
+     * the cause from whichever DOM event was mid-dispatch — about ninety lines of
+     * genuinely careful machinery, defeated once by the microtask checkpoint the
+     * HTML spec runs BETWEEN listeners of the same event, so that every cancel
+     * announced itself as a drop. Nothing that reads the session should have to
+     * guess what the session just did.
+     */
+    addObserver(callbacks: DragSessionCallbacks): () => void;
+    /**
+     * Owner first, then observers, in registration order.
+     *
+     * The owner goes first because it is the one that mutates the list, and an
+     * observer that reads the consumer's state — an announcer reporting "3 of 7"
+     * — must see the world after the write, not before.
+     */
+    private fan;
+    getState: () => DragState;
+    subscribe: (fn: () => void) => (() => void);
+    private emit;
+    registerItem(reg: ItemRegistration): () => void;
+    /** DX-5522 / DX-5521: a group box's piece, keyed by its piece id (unique in the document; a box drawn as several pieces registers each). */
+    registerGroup(reg: GroupRegistration): () => void;
+    registerContainer(reg: ContainerRegistration): () => void;
+    /**
+     * Document order, used by keyboard container stepping.
+     *
+     * DX-4590: NOT registration order. A container re-registers whenever its
+     * `total`, `offset` or `axis` changes (a delete + re-add, which moves it to the
+     * end of the Map), and a lane or toggle that mounts later registers later, so
+     * registration order drifts away from the screen and ArrowLeft/Right skip lanes
+     * or reach them out of order. Document order is what the user sees.
+     */
+    containerIds(): string[];
+    /**
+     * Re-measure. Called at pickup, and by the sensors on scroll, resize and
+     * every auto-scroll frame — the three things that move a box while a drag is
+     * in flight without the drag having caused it.
+     */
+    remeasure(): LayoutSnapshot;
+    getLayout(): LayoutSnapshot | null;
+    start(args: StartArgs): boolean;
+    /** Promote a `pending` pointer into a real drag once its constraint is met. */
+    activate(): void;
+    /** Pointer moved. Cheap when the target has not changed, which is most frames. */
+    moveTo(point: Point): void;
+    /**
+     * Step the insertion point within the current container. The keyboard's
+     * along-axis movement.
+     *
+     * Clamped rather than wrapping: wrapping from the bottom of a list to the top
+     * is indistinguishable from a missed keypress when you cannot see the list.
+     */
+    moveIndex(delta: number): void;
+    /**
+     * Move to the previous or next container. The keyboard's cross-axis movement.
+     *
+     * Lands at the index nearest the item's current one rather than at the top,
+     * because a card carried sideways across a board should stay roughly where it
+     * was vertically — the same thing the pointer does for free.
+     */
+    moveContainer(delta: number): void;
+    /** Release. Emits `onDragEnd` even for a no-op so consumers can announce it. */
+    commit(): void;
+    /** Esc, `pointercancel`, or an unmount mid-gesture. Never writes. */
+    cancel(): void;
+    /** The container the pointer is over right now, or null. */
+    containerAtPoint(point: Point): string | null;
+    /**
+     * Where a drop target sits, as a person is told it: 1-based, in the WHOLE
+     * container, with the whole container's length counted with the carried item
+     * in it. A container that renders every item is its own whole (the items
+     * registered under it); a windowed one says so at registration (`offset`,
+     * `total`) and the answer follows. `index` counts the container with the
+     * carried item already removed — the engine's one index rule.
+     */
+    spokenPosition(container: string, index: number, carried: DragId): {
+        position: number;
+        total: number;
+    };
+    /** What a card carried in from another container means here — see `ContainerRegistration.crossDrop`. */
+    crossDropOf(container: string): CrossDrop | undefined;
+    /** How many items a container holds once the carried one is taken out. */
+    slotCount(container: string): number;
+}

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

@@ -0,0 +1,226 @@
+/**
+ * The drag-and-drop contract. One session shape, produced by every input
+ * source, read by everything downstream.
+ *
+ * WHY NOT HTML5 DRAG-AND-DROP. The obvious design — and the one the danxbot
+ * dashboard's Kanban board uses today — is `draggable="true"` plus
+ * `dragstart`/`dragover`/`drop`. It cannot do three of the four things this
+ * component exists to deliver:
+ *
+ *   1. TOUCH. Mobile browsers do not fire drag events for touch input at all.
+ *      Not throttled, not partial — absent. A board built on that API is inert
+ *      on every phone, and nothing inside the API can fix it.
+ *   2. KEYBOARD. There is no keyboard path into a drag session; the events only
+ *      exist as a consequence of a pointer gesture.
+ *   3. EDGE AUTO-SCROLL. `dragover` is throttled and the browser owns the
+ *      gesture, so a scroll ramp driven from it stutters.
+ *
+ * Pointer Events give one code path for mouse, touch and pen, and leave the
+ * gesture under our control — so keyboard becomes a second SENSOR feeding the
+ * same session rather than a parallel implementation that has to be kept in
+ * agreement with the first one.
+ *
+ * The invariant that removes the entire off-by-one bug class, asserted by the
+ * geometry tests: `DropTarget.index` is the insertion index in the container's
+ * item list WITH THE DRAGGED ITEM ALREADY REMOVED. Same-container and
+ * cross-container drops are then arithmetically identical, and a consumer never
+ * has to ask "does this index account for the hole the item left behind".
+ */
+/** Client-space point. Always viewport coordinates, never page. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A draggable item's identity. Stable across renders — never an array index. */
+export type DragId = string;
+/** A container that holds draggable items: a column, a list, a board lane. */
+export type ContainerId = string;
+/**
+ * The reorder axis of a container. `"y"` is a vertical list, `"x"` a row of
+ * columns. The axis decides which coordinate the midpoint rule reads and which
+ * arrow keys move within the container rather than between containers.
+ */
+export type DragAxis = "x" | "y";
+/**
+ * Where the dragged item lands if released now.
+ *
+ * `index` counts the container's items WITHOUT the dragged item — see the file
+ * header. `0` is before every remaining item, `length` is after all of them.
+ */
+export interface DropTarget {
+    container: ContainerId;
+    index: number;
+}
+/**
+ * Which sensor started the session. Downstream behaviour genuinely differs:
+ * the floating clone follows a pointer but snaps to the target in keyboard
+ * mode, and announcements are only worth emitting for a session a screen-reader
+ * user could be driving.
+ */
+export type DragMode = "pointer" | "keyboard";
+/**
+ * `pending` is a pointer that is down on a handle but has not yet passed its
+ * activation constraint. It exists so a tap stays a tap and a swipe stays a
+ * scroll — the single most common way a drag list becomes unusable on a phone
+ * is starting the drag on `pointerdown`.
+ */
+export type DragPhase = "idle" | "pending" | "dragging";
+export interface DragState {
+    phase: DragPhase;
+    /** The item being carried. Non-null in `pending` and `dragging`. */
+    id: DragId | null;
+    /** Where it came from, captured at pickup so cancel can restore it. */
+    from: DropTarget | null;
+    /** Where it would land now. Never null while `dragging`. */
+    over: DropTarget | null;
+    mode: DragMode | null;
+    /** Live pointer position. Null in keyboard mode — there is no pointer. */
+    point: Point | null;
+    /**
+     * The cursor's offset inside the item at pickup, so the floating clone tracks
+     * the exact point that was grabbed rather than snapping a corner to the
+     * cursor. Null in keyboard mode.
+     */
+    grab: Point | null;
+}
+/** A registered draggable item. Registration is what makes it measurable. */
+export interface ItemRegistration {
+    id: DragId;
+    container: ContainerId;
+    /** Position within its container, as the consumer's data currently orders it. */
+    index: number;
+    element: HTMLElement;
+    /**
+     * DX-5522: the group this item is drawn in (a `DragDropGroup`), or absent for an item drawn on its own. Items of one
+     * group are consecutive in their container; the group's box is drawn around them by the consumer, so the drag
+     * needs to know which items it holds to keep a sibling shift inside its own box.
+     */
+    group?: GroupId;
+    /** DX-5521: the piece of that group's box this item is drawn in (see `PieceId`). Set exactly when `group` is. */
+    piece?: PieceId;
+}
+/** A group's identity within one container: unique among that container's groups, the same on every render. */
+export type GroupId = string;
+/**
+ * DX-5521: one element of a group's box. A box is usually ONE element (one piece), but a list that draws its pages as
+ * separate blocks (a windowed board lane) draws a box whose cards sit on two pages as one piece per page, each holding
+ * that page's cards, joined edge to edge so they read as one box. The group (`GroupId`) says which cards belong together;
+ * the piece says which element frames which of them. Unique in the document, the same on every render.
+ */
+export type PieceId = string;
+/** A group box's piece (`DragDropGroup`), registered so it can be measured. */
+export interface GroupRegistration {
+    id: GroupId;
+    piece: PieceId;
+    container: ContainerId;
+    element: HTMLElement;
+}
+export interface ContainerRegistration {
+    id: ContainerId;
+    element: HTMLElement;
+    axis: DragAxis;
+    /**
+     * DX-4540: for a container that renders only a window of a longer list. The
+     * position in the whole list of its first registered item, so a drop spoken
+     * as "position 221 of 500" is true. Absent for a container that holds every
+     * item.
+     */
+    offset?: number;
+    /** The whole list's length, the carried item counted in it when it lives here. See `offset`. */
+    total?: number;
+    /**
+     * DX-4583: what a card carried in from ANOTHER container means here. Absent or
+     * `"position"`, it lands at an index: siblings part and a marker shows where.
+     * `"lane"`, it lands in the container as a whole and no index is meant: no gap
+     * opens, no marker shows, and the consumer decides what the drop writes. A
+     * card carried inside its own container is always positional.
+     */
+    crossDrop?: CrossDrop;
+}
+/** See `ContainerRegistration.crossDrop`. */
+export type CrossDrop = "position" | "lane";
+/** One item's measured box, taken at snapshot time. */
+export interface ItemRect {
+    id: DragId;
+    container: ContainerId;
+    index: number;
+    rect: DOMRect;
+    /** Copied from the registration — see `ItemRegistration.group`. */
+    group?: GroupId;
+    /** Copied from the registration — see `ItemRegistration.piece`. */
+    piece?: PieceId;
+    /**
+     * DX-5522: the space the item leaves after itself on the container's axis (its trailing margin), measured. Absent in a
+     * hand-written layout, which reads as "the container's usual spacing". The last item of a group box has none, and the
+     * insertion marker drawn after it has to make up the difference.
+     */
+    marginEnd?: number;
+}
+/** A group box's piece measured at snapshot time. */
+export interface GroupRect {
+    id: GroupId;
+    piece: PieceId;
+    container: ContainerId;
+    rect: DOMRect;
+}
+export interface ContainerRect {
+    id: ContainerId;
+    axis: DragAxis;
+    /** Copied from the registration — see `ContainerRegistration.crossDrop`. */
+    crossDrop?: CrossDrop;
+    rect: DOMRect;
+}
+/**
+ * Every box measured once, at pickup.
+ *
+ * WHY A SNAPSHOT. `getBoundingClientRect` forces layout, and a drag reads every
+ * candidate box on every move. Measuring per `pointermove` costs a forced
+ * reflow per frame of the one gesture that must never drop a frame — and it
+ * measures boxes that are MID-ANIMATION, so the midpoint rule reads a moving
+ * target and the insertion point oscillates. The snapshot is invalidated by
+ * scroll and resize, which are the only two things that move a box the drag
+ * itself did not.
+ */
+export interface LayoutSnapshot {
+    items: ItemRect[];
+    containers: ContainerRect[];
+    /** DX-5522: the group boxes, empty for a board that draws none. */
+    groups: GroupRect[];
+}
+/** Emitted once per completed drag. `from` and `to` may be equal — see `moved`. */
+export interface DragEndEvent {
+    id: DragId;
+    from: DropTarget;
+    to: DropTarget;
+    mode: DragMode;
+    /**
+     * `false` when the release lands the item exactly where it started. Consumers
+     * MUST skip their write in that case: the dashboard's implementation churned
+     * its ordering field on every no-op release, and a write that changes nothing
+     * still costs a request, a re-render and an audit-log row.
+     */
+    moved: boolean;
+}
+/** Emitted at pickup, before any movement. */
+export interface DragStartEvent {
+    id: DragId;
+    from: DropTarget;
+    mode: DragMode;
+}
+/** Emitted when a session ends without committing — Esc, or a cancelled pointer. */
+export interface DragCancelEvent {
+    id: DragId;
+    from: DropTarget;
+    mode: DragMode;
+}
+export interface DragSessionCallbacks {
+    onDragStart?: (e: DragStartEvent) => void;
+    /** Fires on every change of `over`, never on mere pointer movement. */
+    onDragOver?: (e: {
+        id: DragId;
+        from: DropTarget;
+        over: DropTarget;
+    }) => void;
+    onDragEnd?: (e: DragEndEvent) => void;
+    onDragCancel?: (e: DragCancelEvent) => void;
+}

package/dist/types/lib/dnd/use-drag.d.ts

@@ -0,0 +1,82 @@
+import { DragSession } from "./session";
+import type { PointerActivation } from "./sensors/pointer";
+import type { ContainerId, CrossDrop, DragAxis, DragId, DragSessionCallbacks, DragState, GroupId, PieceId } from "./types";
+export declare const DragSessionProvider: import("react").Provider<DragSession | null>;
+export declare function useDragSession(component: string): DragSession;
+/**
+ * Create the session a `<DragDrop>` owns.
+ *
+ * Built ONCE, with its callbacks swapped on every render. Rebuilding it when a
+ * consumer's `onDragEnd` identity changes — which it does on every render
+ * unless they memoize, and they will not — would destroy the machine mid-gesture
+ * and drop the drag.
+ */
+export declare function useCreateDragSession(callbacks: DragSessionCallbacks): DragSession;
+/** Subscribe to the session. */
+export declare function useDragState(session: DragSession): DragState;
+/**
+ * True while a card is being carried in the enclosing `<DragDrop>`, and false
+ * outside one — it never throws, because the callers that ask (a windowed list
+ * deciding whether it may drop a page) are ordinary components that are
+ * sometimes inside a board and sometimes not.
+ *
+ * Reads only `phase === "dragging"`, so it re-renders its caller when a drag
+ * starts or ends and not on every pointer move, which `useDragState` would.
+ */
+export declare function useDragLive(): boolean;
+export interface UseDraggableOptions {
+    id: DragId;
+    container: ContainerId;
+    /** Position in the consumer's data. Re-registers when it changes. */
+    index: number;
+    /**
+     * The reorder axis of this item's container. Decides which arrow pair steps
+     * within the container and which moves between containers.
+     *
+     * @default "y"
+     */
+    axis?: DragAxis;
+    /** DX-5522: the group box this item is drawn in — see `ItemRegistration.group`. */
+    group?: GroupId;
+    /** DX-5521: the piece of that box it is drawn in — see `ItemRegistration.piece`. Given exactly when `group` is. */
+    piece?: PieceId;
+    disabled?: boolean;
+    activation?: PointerActivation;
+}
+export interface UseDraggableResult {
+    /** The item's own element — this is what gets measured. */
+    setItemRef: (el: HTMLElement | null) => void;
+    /**
+     * The drag handle. Pass the same element as `setItemRef` to make the whole
+     * item draggable, or a grip inside it to make only the grip draggable. They
+     * are deliberately separate: a card full of buttons must not start a drag
+     * from every one of them.
+     */
+    setHandleRef: (el: HTMLElement | null) => void;
+    isDragging: boolean;
+}
+export declare function useDraggable(session: DragSession, options: UseDraggableOptions): UseDraggableResult;
+/** DX-5522: register a group box's piece so the engine can measure it. The container is the enclosing one, passed by the caller. */
+export declare function useGroupBox(session: DragSession, options: {
+    id: GroupId;
+    piece: PieceId;
+    container: ContainerId;
+}): (el: HTMLElement | null) => void;
+export interface UseDropContainerOptions {
+    id: ContainerId;
+    axis?: DragAxis;
+    /** See `ContainerRegistration.offset` — a windowed container's first item's place in the whole list. */
+    offset?: number;
+    /** See `ContainerRegistration.total` — a windowed container's whole length. */
+    total?: number;
+    /** See `ContainerRegistration.crossDrop`. */
+    crossDrop?: CrossDrop;
+}
+export interface UseDropContainerResult {
+    setContainerRef: (el: HTMLElement | null) => void;
+    /** True while the carried item would land in this container. */
+    isOver: boolean;
+    /** Insertion index within this container, or null when it is not the target. */
+    overIndex: number | null;
+}
+export declare function useDropContainer(session: DragSession, options: UseDropContainerOptions): UseDropContainerResult;

package/dist/types/lib/dom/scroll-ancestor.d.ts

@@ -0,0 +1,15 @@
+export type ScrollAxis = "x" | "y";
+export interface ScrollBoxOptions {
+    /** The axes that count; a box scrolling along any of them qualifies. @default ["y"] */
+    axes?: readonly ScrollAxis[];
+    /** Also require the content to overflow the box on that axis, not merely allow scrolling. @default false */
+    mustOverflow?: boolean;
+}
+export interface ScrollAncestorOptions extends ScrollBoxOptions {
+    /** Whether `from` itself may be the answer. Required: it is a statement about the caller. */
+    includeSelf: boolean;
+}
+/** Does `el` scroll along any of the given axes? */
+export declare function isScrollBox(el: HTMLElement, { axes, mustOverflow }?: ScrollBoxOptions): boolean;
+/** The nearest box that scrolls, walking up from `from`; null when none does. */
+export declare function nearestScrollAncestor(from: Element | null, { includeSelf, ...box }: ScrollAncestorOptions): HTMLElement | null;

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

@@ -0,0 +1,33 @@
+/** Binary units, because these are file sizes and every OS reports them this way. */
+export declare function formatBytes(bytes: number, locale: string): string;
+/**
+ * 241_600 → "241.6K". A thin, token-domain-named wrapper — see
+ * `formatCompactNumber` below for the shared algorithm and its own reasoning.
+ * Kept as its own function (rather than every call site switching to the
+ * generic one directly) because "tokens" is a real vocabulary word in this
+ * package's chat components, and renaming every call site to the generic name
+ * would cost real diff for zero behavioral gain.
+ */
+export declare function formatTokens(tokens: number, locale: string): string;
+/**
+ * A GENERIC large count, abbreviated the way the locale writes it: in en-US
+ * `850` → `"850"`, `1_100` → `"1.1K"`, `3_400_000` → `"3.4M"`,
+ * `4_400_000_000` → `"4.4B"`. `null` / `undefined` / non-finite → `"—"`.
+ *
+ * DX-4740: THE SUFFIXES COME FROM `Intl` (`notation: "compact"`), NOT FROM A
+ * TABLE HERE. A hand-written T/B/M/k ladder is English: "B" for 10^9 reads as
+ * "billón" (10^12) to an es-AR reader, and every other language has its own
+ * words for thousand and million. en-US now writes an uppercase "K".
+ *
+ * One decimal at most, trimmed of a trailing ".0" (`1_000_000` → `"1M"`, not
+ * `"1.0M"`), and exact below 1,000 — a count small enough to read digit-by-digit
+ * gets no abbreviation at all, since "850" is not improved by becoming "0.9K".
+ * `formatTokens` is the token-budget's name for the same thing; this one is for
+ * any large count a screen needs to abbreviate — a field tally, a donut's
+ * fraction, a record count.
+ *
+ * NEGATIVE VALUES keep their sign (`-1_100` → `"-1.1K"`) rather than being
+ * treated as absent — a generic count utility cannot assume its caller's
+ * domain never has one.
+ */
+export declare function formatCompactNumber(value: number | null | undefined, locale: string): string;

package/dist/types/lib/group-in-order.d.ts

@@ -0,0 +1,13 @@
+export interface OrderedSection<T> {
+    /** `undefined` when nothing in the set names a group. */
+    label: string | undefined;
+    items: T[];
+}
+/**
+ * Buckets items by their group, preserving first-seen order.
+ *
+ * Grouping is opt-in as a WHOLE, not per item: if not one item names a group this returns one ungrouped section rather than inventing
+ * an "Uncategorised" heading nobody asked to see. When some items name a group and others do not, the rest go under `otherLabel`,
+ * because at that point the absence of a group on a few items is itself information worth a heading.
+ */
+export declare function groupInOrder<T>(items: readonly T[], groupOf: (item: T) => string | undefined, otherLabel: string): OrderedSection<T>[];

package/dist/types/lib/header-fold.d.ts

@@ -0,0 +1,10 @@
+/** The measured width of the `AppShell` header in CSS pixels; `0` until measured. */
+export declare const HeaderWidthContext: import("react").Context<number>;
+/**
+ * True when the `AppShell` header is narrower than `minWidth` CSS pixels, i.e. the
+ * control that asked no longer fits and should live in the account menu instead.
+ * Call it from inside the shell's `header` or `sidebarFooter` subtree (a
+ * component the consumer renders there), never from the component that renders
+ * `<AppShell>` itself: the width is provided by the shell, below it.
+ */
+export declare function useHeaderFold(minWidth: number): boolean;