@botiverse/raft-ui 0.51.0 → 0.52.0

package/dist/components/drag/drag-lists.mjs

@@ -0,0 +1,258 @@
+"use client";
+import { cn } from "../../cn.mjs";
+import { SILENT_DRAG_ANNOUNCEMENTS, dragInstructions, dragMessages } from "./drag-announcements.mjs";
+import { useDragAcrossLists } from "./drag-sensors.mjs";
+import { DropPlaceholder } from "./drop-placeholder.mjs";
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { arrayMove, verticalListSortingStrategy } from "@dnd-kit/sortable";
+//#region src/components/drag/drag-lists.tsx
+/** dnd-kit's vertical strategy, except that nothing moves while the hand is outside the list. */
+const dragListStrategy = (args) => args.overIndex < 0 ? null : verticalListSortingStrategy(args);
+/**
+* Items in one or more lists that can be reordered and moved between lists
+* (a sidebar's sections, a board's columns): the lists half of the drag
+* model (design/patterns/drag-and-drop.md#where-it-will-land). While dragging,
+* the item stands at its landing spot (its own slot is the place; siblings
+* slide apart), a list can refuse it, and every step is announced by name.
+* The keyboard is measured from the item's real place, so the arrows never
+* skip one after a move into another list.
+*
+* Spread `handlers`, `collisionDetection` and `accessibility` on the
+* `DndContext`, pass `coordinateGetter` to `useDragSensors`, and render
+* `DragRemeasure version={items}` inside it.
+*/
+function useDragLists({ lists, items, onItemsChange, listName, itemName, refuse, collisionDetection, announce, messages }) {
+	const say = useMemo(() => dragMessages(messages), [messages]);
+	const across = useDragAcrossLists(collisionDetection);
+	const itemsRef = useRef(items);
+	useLayoutEffect(() => {
+		itemsRef.current = items;
+	}, [items]);
+	const [activeId, setActiveId] = useState(null);
+	const [originList, setOriginList] = useState(null);
+	const [refusal, setRefusalState] = useState(null);
+	const refusalRef = useRef(refusal);
+	const setRefusal = (next) => {
+		refusalRef.current = next;
+		setRefusalState(next);
+	};
+	const origin = useRef(null);
+	const inserted = useRef(null);
+	const listOf = useCallback((state, id) => lists.includes(id) ? id : lists.find((list) => state[list].includes(String(id))) ?? null, [lists]);
+	const isList = (id) => lists.includes(id);
+	const where = (state, id) => {
+		const list = listOf(state, id);
+		return {
+			place: listName(list),
+			position: state[list].indexOf(id) + 1,
+			count: state[list].length
+		};
+	};
+	const update = (next) => {
+		itemsRef.current = next;
+		onItemsChange(next);
+	};
+	/** Still home: in its own list, at its own index (pass the sortable's projected index). */
+	const isHome = useCallback((id, index) => {
+		const start = origin.current;
+		return start != null && listOf(itemsRef.current, id) === start.list && index === start.index;
+	}, [listOf]);
+	const onDragStart = ({ active, activatorEvent }) => {
+		const id = String(active.id);
+		const list = listOf(items, id);
+		if (!list) return;
+		origin.current = {
+			list,
+			index: items[list].indexOf(id),
+			snapshot: items,
+			keyboard: typeof KeyboardEvent !== "undefined" && activatorEvent instanceof KeyboardEvent
+		};
+		inserted.current = null;
+		setActiveId(id);
+		setOriginList(list);
+		announce(say.pickedUp({
+			name: itemName(id),
+			...where(items, id)
+		}));
+	};
+	const onDragOver = ({ active, over }) => {
+		const start = origin.current;
+		if (!start) return;
+		const id = String(active.id);
+		if (!over) {
+			if (refusalRef.current) setRefusal(null);
+			announce(say.notOver({ name: itemName(id) }));
+			return;
+		}
+		const current = itemsRef.current;
+		const from = listOf(current, id);
+		const to = listOf(current, over.id);
+		if (!from || !to) return;
+		const reason = refuse?.(start.list, to, id) ?? null;
+		if (reason) {
+			setRefusal({
+				list: to,
+				reason
+			});
+			update(start.snapshot);
+			inserted.current = null;
+			announce(say.refused({
+				name: itemName(id),
+				place: listName(to),
+				reason
+			}));
+			return;
+		}
+		if (refusalRef.current) setRefusal(null);
+		if (from !== to) {
+			const fromList = current[from].filter((item) => item !== id);
+			const toList = [...current[to]];
+			let at = toList.indexOf(String(over.id));
+			if (at < 0) at = toList.length;
+			else if (start.keyboard) {
+				if (lists.indexOf(from) > lists.indexOf(to)) at += 1;
+			} else {
+				const rect = active.rect.current.translated;
+				if (rect && rect.top + rect.height / 2 > over.rect.top + over.rect.height / 2) at += 1;
+			}
+			toList.splice(at, 0, id);
+			const next = {
+				...current,
+				[from]: fromList,
+				[to]: toList
+			};
+			across.moved(start.keyboard);
+			update(next);
+			inserted.current = isList(over.id) ? null : over.id;
+			announce(say.over({
+				name: itemName(id),
+				...where(next, id)
+			}));
+			return;
+		}
+		if (over.id === id) {
+			inserted.current = null;
+			return;
+		}
+		const list = current[to];
+		if (inserted.current === over.id) {
+			announce(say.over({
+				name: itemName(id),
+				...where(current, id)
+			}));
+			return;
+		}
+		inserted.current = null;
+		const overIndex = isList(over.id) ? list.length - 1 : list.indexOf(String(over.id));
+		announce(say.over({
+			name: itemName(id),
+			place: listName(to),
+			position: overIndex + 1,
+			count: list.length
+		}));
+	};
+	const finish = (dropped, overId) => {
+		const start = origin.current;
+		const id = activeId;
+		const refused = refusalRef.current;
+		origin.current = null;
+		across.reset();
+		setActiveId(null);
+		setOriginList(null);
+		setRefusal(null);
+		if (!start || !id) return;
+		if (!dropped || overId == null || refused) {
+			update(start.snapshot);
+			const home = {
+				name: itemName(id),
+				...where(start.snapshot, id)
+			};
+			announce(refused && dropped ? say.refusedDrop({
+				...home,
+				reason: refused.reason
+			}) : say.cancelled(home));
+			return;
+		}
+		const current = itemsRef.current;
+		const list = listOf(current, id);
+		const ids = current[list];
+		const fromIndex = ids.indexOf(id);
+		const toIndex = inserted.current === overId ? fromIndex : isList(overId) ? ids.length - 1 : ids.indexOf(String(overId));
+		const next = toIndex >= 0 && toIndex !== fromIndex ? {
+			...current,
+			[list]: arrayMove([...ids], fromIndex, toIndex)
+		} : current;
+		update(next);
+		announce(say.dropped({
+			name: itemName(id),
+			...where(next, id)
+		}));
+	};
+	const accessibility = useMemo(() => ({
+		announcements: SILENT_DRAG_ANNOUNCEMENTS,
+		screenReaderInstructions: dragInstructions(messages)
+	}), [messages]);
+	return {
+		/** The dragged item's id, or null. */
+		activeId,
+		/** The list that refuses the item under the hand, and why. */
+		refusal,
+		/** The list the drag started in, while dragging. */
+		originList,
+		isHome,
+		listOf,
+		collisionDetection: across.collisionDetection,
+		coordinateGetter: across.coordinateGetter,
+		accessibility,
+		handlers: {
+			onDragStart,
+			onDragOver,
+			onDragEnd: ({ over }) => finish(true, over?.id ?? null),
+			onDragCancel: () => finish(false, null)
+		}
+	};
+}
+/**
+* Wraps each item's content in a list. The dragged item's own node is at 40%
+* while it is still home, and the dashed place (its size, its radius) once it
+* stands anywhere else. Every other item renders as it is: the wrapper stays
+* the same, so the item keeps focus when its drag starts.
+*/
+function DraggedSlot({ dragging = false, home, radius, className, children }) {
+	const place = dragging && !home;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "drag-slot",
+		className: "relative",
+		children: [/* @__PURE__ */ jsx("div", {
+			"data-drag-origin": dragging && home ? "" : void 0,
+			className: place ? "invisible" : void 0,
+			children
+		}), place ? /* @__PURE__ */ jsx(DropPlaceholder, { className: cn("absolute inset-0", radius, className) }) : null]
+	});
+}
+/** The last announcement, for a polite live region (`DragLiveRegion`). Repeats are dropped. */
+function useDragAnnouncer() {
+	const [message, setMessage] = useState("");
+	const last = useRef("");
+	return {
+		message,
+		announce: useCallback((text) => {
+			if (text === last.current) return;
+			last.current = text;
+			setMessage(text);
+		}, [])
+	};
+}
+/** A polite, visually hidden live region for drag announcements. */
+function DragLiveRegion({ message }) {
+	return /* @__PURE__ */ jsx("span", {
+		className: "sr-only",
+		role: "status",
+		"aria-live": "polite",
+		"aria-atomic": "true",
+		children: message
+	});
+}
+//#endregion
+export { DragLiveRegion, DraggedSlot, dragListStrategy, useDragAnnouncer, useDragLists };

package/dist/components/drag/drag-sensors.d.mts

@@ -0,0 +1,87 @@
+import { HoldThenMoveOptions } from "../../lib/touch-drag.mjs";
+import { CollisionDetection, KeyboardCoordinateGetter, KeyboardSensorOptions } from "@dnd-kit/core";
+//#region src/components/drag/drag-sensors.d.ts
+/**
+ * A mouse or a pen picks an item up once it has moved this far, so a click
+ * never moves anything (design/patterns/drag-and-drop.md#starting-a-drag).
+ */
+export declare const MOUSE_DRAG_DISTANCE_PX = 6;
+/**
+ * Space picks up and drops, Escape puts back, the arrow keys move. Enter
+ * never starts a drag: on an item that can also be opened or activated, Enter
+ * does that.
+ */
+export declare const DRAG_KEYBOARD_CODES: NonNullable<KeyboardSensorOptions["keyboardCodes"]>;
+export type DragSensorsOptions = {
+  /**
+   * How the arrow keys move a lifted item. Defaults to
+   * `listKeyboardCoordinates`, which steps through a sortable list.
+   */
+  coordinateGetter?: KeyboardCoordinateGetter;
+  /** Leave the keyboard out, for a surface whose keyboard path is a button. */
+  keyboard?: boolean;
+  /** The touch hold, distance and tolerance; the defaults are the system's. */
+  touch?: HoldThenMoveOptions;
+};
+/**
+ * The one sensor set for everything that can be dragged
+ * (design/patterns/drag-and-drop.md#starting-a-drag):
+ *
+ * - a mouse or a pen: after 6px of movement;
+ * - a finger: hold still 500ms, then move 10px (`useHoldThenMoveTouchSensor`);
+ * - the keyboard: Space picks up, the arrows move, Space drops, Escape puts
+ *   back. Enter never starts a drag.
+ *
+ * However the drag started, Escape during it only puts the item back: it is
+ * taken in the capture phase on the window and stopped, so no app handler
+ * (a dialog, a panel, a popover that closes on Escape) hears it. Once the drag
+ * is over, Escape reaches the app again.
+ *
+ * Pass the options, or only the keyboard's `coordinateGetter`.
+ */
+export declare function useDragSensors(options?: DragSensorsOptions | KeyboardCoordinateGetter): import("@dnd-kit/core").SensorDescriptor<import("@dnd-kit/core").SensorOptions>[];
+/**
+ * dnd-kit's sortable keyboard steps, measured from where the item's place
+ * actually is (its own node, slid into the landing spot) rather than from the
+ * lifted copy. After an item moves into another list the two differ, and the
+ * arrows would skip a place. Use it for lists inside one `DndContext`.
+ */
+export declare const listKeyboardCoordinates: KeyboardCoordinateGetter;
+export type DragAcrossLists = {
+  /** The caller's collision detection, holding the item over itself right after it moves list. */
+  collisionDetection: CollisionDetection;
+  /** Pass to `useDragSensors({ coordinateGetter })`. */
+  coordinateGetter: KeyboardCoordinateGetter;
+  /**
+   * Call when the item has just been moved into another list. By keyboard it
+   * then stays over itself until the next arrow; by pointer, for one frame.
+   */
+  moved: (viaKeyboard: boolean) => void;
+  /** Call when the drag ends or is cancelled. */
+  reset: () => void;
+};
+/**
+ * The keyboard fix for an item that moves between lists while it is dragged
+ * (a sidebar's sections, a board's columns). Without it, dnd-kit still counts
+ * the row the item was put next to as the place under it, projects one more
+ * move, and the next arrow skips a place: what is announced and where the item
+ * drops disagree. With it:
+ *
+ * - right after it moves list, the item is over itself (by keyboard until the
+ *   next arrow, by pointer for one frame);
+ * - the arrows are measured from the item's real place (`listKeyboardCoordinates`).
+ *
+ * Render `DragRemeasure` too, so the lists are measured again after the move.
+ */
+export declare function useDragAcrossLists(collisionDetection: CollisionDetection): DragAcrossLists;
+export type DragRemeasureProps = {
+  /** Anything that changes when an item moves list, such as the lists' items. */
+  version: unknown;
+};
+/**
+ * Measures every drop target again once an item's move into another list has
+ * rendered. dnd-kit's own observers skip targets whose size didn't change,
+ * even when they moved. Render it inside the `DndContext`.
+ */
+export declare function DragRemeasure({ version }: DragRemeasureProps): null;
+//#endregion

package/dist/components/drag/drag-sensors.mjs

@@ -0,0 +1,169 @@
+"use client";
+import { eventWindow, holdEscape, releaseEscape } from "../../lib/drag-escape.mjs";
+import { useHoldThenMoveTouchSensor, useMouseOnlyPointerSensor } from "../../lib/touch-drag.mjs";
+import { useLayoutEffect, useMemo, useRef } from "react";
+import { KeyboardSensor, useDndContext, useSensor, useSensors } from "@dnd-kit/core";
+import { sortableKeyboardCoordinates } from "@dnd-kit/sortable";
+//#region src/components/drag/drag-sensors.ts
+/**
+* A mouse or a pen picks an item up once it has moved this far, so a click
+* never moves anything (design/patterns/drag-and-drop.md#starting-a-drag).
+*/
+const MOUSE_DRAG_DISTANCE_PX = 6;
+/**
+* Space picks up and drops, Escape puts back, the arrow keys move. Enter
+* never starts a drag: on an item that can also be opened or activated, Enter
+* does that.
+*/
+const DRAG_KEYBOARD_CODES = {
+	start: ["Space"],
+	cancel: ["Escape"],
+	end: ["Space"]
+};
+var DragKeyboardSensorImpl = class extends KeyboardSensor {
+	static activators = KeyboardSensor.activators;
+	attach() {
+		super.attach();
+		holdEscape(eventWindow(this.props.event), this, (event) => this.handleCancel(event));
+	}
+	detach() {
+		releaseEscape(eventWindow(this.props.event), this);
+		super.detach();
+	}
+};
+/**
+* dnd-kit's KeyboardSensor, but Escape during the drag puts the item back and
+* reaches nothing else: no dialog, panel or popover that closes on Escape
+* hears it (`drag-escape.ts`). The pointer sensors of `useDragSensors` do the
+* same.
+*/
+const DragKeyboardSensor = DragKeyboardSensorImpl;
+const NO_TOUCH = {};
+/**
+* The one sensor set for everything that can be dragged
+* (design/patterns/drag-and-drop.md#starting-a-drag):
+*
+* - a mouse or a pen: after 6px of movement;
+* - a finger: hold still 500ms, then move 10px (`useHoldThenMoveTouchSensor`);
+* - the keyboard: Space picks up, the arrows move, Space drops, Escape puts
+*   back. Enter never starts a drag.
+*
+* However the drag started, Escape during it only puts the item back: it is
+* taken in the capture phase on the window and stopped, so no app handler
+* (a dialog, a panel, a popover that closes on Escape) hears it. Once the drag
+* is over, Escape reaches the app again.
+*
+* Pass the options, or only the keyboard's `coordinateGetter`.
+*/
+function useDragSensors(options = {}) {
+	const { coordinateGetter = listKeyboardCoordinates, keyboard = true, touch = NO_TOUCH } = typeof options === "function" ? { coordinateGetter: options } : options;
+	const keyboardOptions = useMemo(() => ({
+		keyboardCodes: DRAG_KEYBOARD_CODES,
+		coordinateGetter
+	}), [coordinateGetter]);
+	const mouse = useMouseOnlyPointerSensor(6);
+	const finger = useHoldThenMoveTouchSensor(touch);
+	const keys = useSensor(DragKeyboardSensor, keyboardOptions);
+	return useSensors(mouse, finger, keyboard ? keys : null);
+}
+/**
+* dnd-kit's sortable keyboard steps, measured from where the item's place
+* actually is (its own node, slid into the landing spot) rather than from the
+* lifted copy. After an item moves into another list the two differ, and the
+* arrows would skip a place. Use it for lists inside one `DndContext`.
+*/
+const listKeyboardCoordinates = (event, args) => {
+	const { context } = args;
+	const node = context.active == null ? null : context.draggableNodes.get(context.active.id)?.node.current;
+	if (!node) return sortableKeyboardCoordinates(event, args);
+	const rect = node.getBoundingClientRect();
+	const collisionRect = {
+		top: rect.top,
+		left: rect.left,
+		width: rect.width,
+		height: rect.height,
+		bottom: rect.bottom,
+		right: rect.right
+	};
+	return sortableKeyboardCoordinates(event, {
+		...args,
+		context: {
+			...context,
+			collisionRect
+		}
+	});
+};
+/**
+* The keyboard fix for an item that moves between lists while it is dragged
+* (a sidebar's sections, a board's columns). Without it, dnd-kit still counts
+* the row the item was put next to as the place under it, projects one more
+* move, and the next arrow skips a place: what is announced and where the item
+* drops disagree. With it:
+*
+* - right after it moves list, the item is over itself (by keyboard until the
+*   next arrow, by pointer for one frame);
+* - the arrows are measured from the item's real place (`listKeyboardCoordinates`).
+*
+* Render `DragRemeasure` too, so the lists are measured again after the move.
+*/
+function useDragAcrossLists(collisionDetection) {
+	const box = useRef({
+		overSelf: false,
+		justMoved: false,
+		frame: 0
+	});
+	return useMemo(() => {
+		const clearFrame = () => {
+			const state = box.current;
+			if (state.frame && typeof cancelAnimationFrame !== "undefined") cancelAnimationFrame(state.frame);
+			state.frame = 0;
+		};
+		return {
+			collisionDetection: (args) => (box.current.justMoved || box.current.overSelf) && args.active ? [{ id: args.active.id }] : collisionDetection(args),
+			coordinateGetter: (event, args) => {
+				box.current.overSelf = false;
+				return listKeyboardCoordinates(event, args);
+			},
+			moved: (viaKeyboard) => {
+				const state = box.current;
+				state.justMoved = true;
+				if (viaKeyboard) state.overSelf = true;
+				clearFrame();
+				if (typeof requestAnimationFrame === "undefined") {
+					state.justMoved = false;
+					return;
+				}
+				state.frame = requestAnimationFrame(() => {
+					state.frame = requestAnimationFrame(() => {
+						state.justMoved = false;
+						state.frame = 0;
+					});
+				});
+			},
+			reset: () => {
+				clearFrame();
+				box.current.overSelf = false;
+				box.current.justMoved = false;
+			}
+		};
+	}, [collisionDetection]);
+}
+/**
+* Measures every drop target again once an item's move into another list has
+* rendered. dnd-kit's own observers skip targets whose size didn't change,
+* even when they moved. Render it inside the `DndContext`.
+*/
+function DragRemeasure({ version }) {
+	const context = useDndContext();
+	const latest = useRef(context);
+	useLayoutEffect(() => {
+		latest.current = context;
+	});
+	useLayoutEffect(() => {
+		const { active, droppableContainers } = latest.current;
+		if (active) latest.current.measureDroppableContainers([...droppableContainers.keys()]);
+	}, [version]);
+	return null;
+}
+//#endregion
+export { DRAG_KEYBOARD_CODES, DragRemeasure, MOUSE_DRAG_DISTANCE_PX, listKeyboardCoordinates, useDragAcrossLists, useDragSensors };

package/dist/components/drag/drag.recipe.d.mts

@@ -0,0 +1,7 @@
+//#region src/components/drag/drag.recipe.d.ts
+/**
+ * The lift look, for a copy drawn outside `DragLift`: an opaque popover
+ * surface, `shadow-float` and the `line-seam` ring. No scale, no tilt.
+ */
+export declare const LIFT_CLASS = "bg-layer-popover shadow-float ring-1 ring-line-seam";
+//#endregion

package/dist/components/drag/drag.recipe.mjs

@@ -0,0 +1,30 @@
+import { tv } from "../../lib/tv.mjs";
+//#region src/components/drag/drag.recipe.ts
+/**
+* The lift look, for a copy drawn outside `DragLift`: an opaque popover
+* surface, `shadow-float` and the `line-seam` ring. No scale, no tilt.
+*/
+const LIFT_CLASS = "bg-layer-popover shadow-float ring-1 ring-line-seam";
+const drag = tv({
+	slots: {
+		lift: [
+			"pointer-events-none size-full",
+			"rounded-control",
+			LIFT_CLASS
+		],
+		placeholder: [
+			"pointer-events-none box-border",
+			"rounded-control",
+			"border-[1.5px] border-dashed border-line-strong bg-fill-subtle"
+		],
+		hint: [
+			"pointer-events-none fixed top-0 left-0 z-70 max-w-80",
+			"rounded-chip px-2 py-1",
+			"font-sans text-caption",
+			"bg-layer-hud text-foreground-on-hud shadow-float ring-1 ring-line-seam"
+		]
+	},
+	variants: { opaque: { true: { placeholder: ["bg-layer-canvas", "bg-[linear-gradient(var(--fill-subtle),var(--fill-subtle))]"] } } }
+});
+//#endregion
+export { LIFT_CLASS, drag };

package/dist/components/drag/drop-placeholder.d.mts

@@ -0,0 +1,41 @@
+import { ComponentPropsWithRef } from "react";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/components/drag/drop-placeholder.d.ts
+export type DropPlaceholderProps = useRender.ComponentProps<"div"> & {
+  /**
+   * In a layout (the gap a column makes, a new column's strip): an opaque
+   * `layer-canvas` under the `fill-subtle` wash, so the column behind the gap
+   * doesn't show through while its sections reflow. Nothing is drawn over
+   * live content (design/patterns/drag-and-drop.md#where-it-will-land).
+   */
+  opaque?: boolean;
+};
+/**
+ * Where a dragged item will land (design/patterns/drag-and-drop.md#where-it-will-land):
+ * a 1.5px dashed `line-strong` outline on `fill-subtle`, with the item's
+ * radius and size. One look for every place. The control radius is the
+ * default; pass the item's own (`rounded-container` for a card). Hidden from
+ * assistive technology: the announcements say where the item is.
+ */
+export declare function DropPlaceholder({ opaque, className, render, ...props }: DropPlaceholderProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type DragRefusalHintProps = Omit<ComponentPropsWithRef<"div">, "children" | "ref"> & {
+  /** Why the place under the hand won't take the item, such as "Can't move from Todo to Done". */
+  children: string;
+  /** Render the hint in another element; by default it renders in `document.body`. */
+  container?: Element | DocumentFragment | null;
+};
+/**
+ * Shown while the hand is over a place that refuses the item
+ * (design/patterns/drag-and-drop.md#refused-places): the reason, in a HUD
+ * chip by the pointer (by the lifted copy in a keyboard drag), and the
+ * not-allowed cursor. Render it only while the place is refused, inside the
+ * `DndContext`, with no placeholder anywhere. Announce the reason as well:
+ * the chip is not read out.
+ *
+ * The chip sits right of and below the pointer. Near the window's right edge
+ * it goes left of the pointer and of the lifted copy, near the bottom edge
+ * above the pointer; it never sits under the copy, and always stays 8px inside
+ * the window. Its size is measured when its content changes, not every frame.
+ */
+export declare function DragRefusalHint({ children, container, className, style, ...props }: DragRefusalHintProps): import("react").ReactPortal | null;
+//#endregion