@torpor/ui 0.4.0 → 1.0.1

package/dist/motion/index.js

@@ -1,97 +1,79 @@
-// src/motion/fade.ts
+//#region src/motion/fade.ts
 function fade(_el, options) {
-  const keyframes = [
-    {
-      opacity: 0
-    },
-    {
-      opacity: 1
-    }
-  ];
-  return { keyframes, options };
+	return {
+		keyframes: [{ opacity: 0 }, { opacity: 1 }],
+		options
+	};
 }
-
-// src/motion/measure.ts
+//#endregion
+//#region src/motion/measure.ts
+/**
+* Measures an element before it is added to the DOM
+* @param el The element to measure
+* @param fn The function to use to get the desired measurement (e.g. el.offsetHeight)
+*/
 function measure(el, fn) {
-  let oldVisibility = el.style.visibility;
-  let oldPosition = el.style.position;
-  let oldParent = el.parentNode;
-  let oldBefore = el.nextSibling;
-  el.style.visibility = "hidden";
-  el.style.position = "absolute";
-  document.body.appendChild(el);
-  let result = fn(el);
-  el.parentNode.removeChild(el);
-  if (oldParent !== null) {
-    oldParent.insertBefore(el, oldBefore);
-    el.style.visibility = oldVisibility;
-    el.style.position = oldPosition;
-  }
-  return result;
+	let oldVisibility = el.style.visibility;
+	let oldPosition = el.style.position;
+	let oldParent = el.parentNode;
+	let oldBefore = el.nextSibling;
+	el.style.visibility = "hidden";
+	el.style.position = "absolute";
+	document.body.appendChild(el);
+	let result = fn(el);
+	el.parentNode.removeChild(el);
+	el.style.visibility = oldVisibility;
+	el.style.position = oldPosition;
+	if (oldParent !== null) oldParent.insertBefore(el, oldBefore);
+	return result;
 }
-
-// src/motion/grow.ts
+//#endregion
+//#region src/motion/grow.ts
 function grow(el, options) {
-  const height = measure(el, (el2) => el2.clientHeight);
-  const keyframes = [
-    {
-      height: "0px",
-      overflow: "hidden",
-      paddingTop: "0px",
-      paddingBottom: "0px",
-      marginTop: "0px",
-      marginBottom: "0px"
-    },
-    {
-      height: height + "px"
-    }
-  ];
-  return { keyframes, options };
+	return {
+		keyframes: [{
+			height: "0px",
+			overflow: "hidden",
+			paddingTop: "0px",
+			paddingBottom: "0px",
+			marginTop: "0px",
+			marginBottom: "0px"
+		}, { height: measure(el, (el) => el.clientHeight) + "px" }],
+		options
+	};
 }
-
-// src/motion/slide.ts
+//#endregion
+//#region src/motion/slide.ts
 function slide(el, options) {
-  let position = options?.side ?? "left";
-  switch (position) {
-    case "left": {
-      el.style.left = "0px";
-      const width = measure(el, (el2) => el2.offsetWidth);
-      const keyframes = [
-        { transform: `translateX(-${width}px)` },
-        { transform: "translateX(0px)" }
-      ];
-      return { keyframes, options };
-    }
-    case "top": {
-      el.style.top = "0px";
-      const height = measure(el, (el2) => el2.offsetHeight);
-      const keyframes = [
-        { transform: `translateY(-${height}px)` },
-        { transform: "translateY(0px)" }
-      ];
-      return { keyframes, options };
-    }
-    case "right": {
-      el.style.right = "0px";
-      const width = measure(el, (el2) => el2.offsetWidth);
-      const keyframes = [{ transform: `translateX(${width}px)` }, { transform: "translateX(0px)" }];
-      return { keyframes, options };
-    }
-    case "bottom": {
-      el.style.bottom = "0px";
-      const height = measure(el, (el2) => el2.offsetHeight);
-      const keyframes = [
-        { transform: `translateY(${height}px)` },
-        { transform: "translateY(0px)" }
-      ];
-      return { keyframes, options };
-    }
-  }
+	el.style.position = "fixed";
+	switch (options?.side ?? "left") {
+		case "left":
+			el.style.left = "0px";
+			return {
+				keyframes: [{ transform: `translateX(-${measure(el, (el) => el.offsetWidth)}px)` }, { transform: "translateX(0px)" }],
+				options
+			};
+		case "top":
+			el.style.top = "0px";
+			return {
+				keyframes: [{ transform: `translateY(-${measure(el, (el) => el.offsetHeight)}px)` }, { transform: "translateY(0px)" }],
+				options
+			};
+		case "right":
+			el.style.right = "0px";
+			return {
+				keyframes: [{ transform: `translateX(${measure(el, (el) => el.offsetWidth)}px)` }, { transform: "translateX(0px)" }],
+				options
+			};
+		case "bottom":
+			el.style.bottom = "0px";
+			return {
+				keyframes: [{ transform: `translateY(${measure(el, (el) => el.offsetHeight)}px)` }, { transform: "translateY(0px)" }],
+				options
+			};
+	}
 }
-export {
-  fade,
-  grow,
-  measure,
-  slide
-};
+//#endregion
+export { fade, grow, measure, slide };
+
 //# sourceMappingURL=index.js.map

package/dist/motion/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/motion/fade.ts","../../src/motion/measure.ts","../../src/motion/grow.ts","../../src/motion/slide.ts"],"sourcesContent":["import { type Animation } from \"@torpor/view\";\n\nexport default function fade(\n\t_el: HTMLElement,\n\toptions?: number | KeyframeAnimationOptions,\n): Animation {\n\tconst keyframes = [\n\t\t{\n\t\t\topacity: 0,\n\t\t},\n\t\t{\n\t\t\topacity: 1,\n\t\t},\n\t];\n\treturn { keyframes, options };\n}\n","/**\n * Measures an element before it is added to the DOM\n * @param el The element to measure\n * @param fn The function to use to get the desired measurement (e.g. el.offsetHeight)\n */\nexport default function measure(el: HTMLElement, fn: (_: HTMLElement) => number): number {\n\t// From https://stackoverflow.com/a/46707458\n\tlet oldVisibility = el.style.visibility;\n\tlet oldPosition = el.style.position;\n\n\tlet oldParent = el.parentNode;\n\tlet oldBefore = el.nextSibling;\n\n\tel.style.visibility = \"hidden\";\n\tel.style.position = \"absolute\";\n\n\tdocument.body.appendChild(el);\n\tlet result = fn(el);\n\tel.parentNode!.removeChild(el);\n\n\tif (oldParent !== null) {\n\t\toldParent.insertBefore(el, oldBefore);\n\t\tel.style.visibility = oldVisibility;\n\t\tel.style.position = oldPosition;\n\t}\n\n\treturn result;\n}\n","import { type Animation } from \"@torpor/view\";\nimport measure from \"./measure\";\n\nexport default function grow(\n\tel: HTMLElement,\n\toptions?: number | KeyframeAnimationOptions,\n): Animation {\n\tconst height = measure(el, (el) => el.clientHeight);\n\tconst keyframes = [\n\t\t{\n\t\t\theight: \"0px\",\n\t\t\toverflow: \"hidden\",\n\t\t\tpaddingTop: \"0px\",\n\t\t\tpaddingBottom: \"0px\",\n\t\t\tmarginTop: \"0px\",\n\t\t\tmarginBottom: \"0px\",\n\t\t},\n\t\t{\n\t\t\theight: height + \"px\",\n\t\t},\n\t];\n\treturn { keyframes, options };\n}\n","import { type Animation } from \"@torpor/view\";\nimport measure from \"./measure\";\n\ninterface Options extends KeyframeAnimationOptions {\n\tside: \"left\" | \"right\" | \"top\" | \"bottom\";\n}\n\nexport default function slide(el: HTMLElement, options?: Options): Animation {\n\tlet position = options?.side ?? \"left\";\n\tswitch (position) {\n\t\tcase \"left\": {\n\t\t\tel.style.left = \"0px\";\n\t\t\tconst width = measure(el, (el) => el.offsetWidth);\n\t\t\tconst keyframes = [\n\t\t\t\t{ transform: `translateX(-${width}px)` },\n\t\t\t\t{ transform: \"translateX(0px)\" },\n\t\t\t];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t\tcase \"top\": {\n\t\t\tel.style.top = \"0px\";\n\t\t\tconst height = measure(el, (el) => el.offsetHeight);\n\t\t\tconst keyframes = [\n\t\t\t\t{ transform: `translateY(-${height}px)` },\n\t\t\t\t{ transform: \"translateY(0px)\" },\n\t\t\t];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t\tcase \"right\": {\n\t\t\tel.style.right = \"0px\";\n\t\t\tconst width = measure(el, (el) => el.offsetWidth);\n\t\t\tconst keyframes = [{ transform: `translateX(${width}px)` }, { transform: \"translateX(0px)\" }];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t\tcase \"bottom\": {\n\t\t\tel.style.bottom = \"0px\";\n\t\t\tconst height = measure(el, (el) => el.offsetHeight);\n\t\t\tconst keyframes = [\n\t\t\t\t{ transform: `translateY(${height}px)` },\n\t\t\t\t{ transform: \"translateY(0px)\" },\n\t\t\t];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t}\n}\n"],"mappings":";AAEe,SAAR,KACN,KACA,SACY;AACZ,QAAM,YAAY;AAAA,IACjB;AAAA,MACC,SAAS;AAAA,IACV;AAAA,IACA;AAAA,MACC,SAAS;AAAA,IACV;AAAA,EACD;AACA,SAAO,EAAE,WAAW,QAAQ;AAC7B;;;ACVe,SAAR,QAAyB,IAAiB,IAAwC;AAExF,MAAI,gBAAgB,GAAG,MAAM;AAC7B,MAAI,cAAc,GAAG,MAAM;AAE3B,MAAI,YAAY,GAAG;AACnB,MAAI,YAAY,GAAG;AAEnB,KAAG,MAAM,aAAa;AACtB,KAAG,MAAM,WAAW;AAEpB,WAAS,KAAK,YAAY,EAAE;AAC5B,MAAI,SAAS,GAAG,EAAE;AAClB,KAAG,WAAY,YAAY,EAAE;AAE7B,MAAI,cAAc,MAAM;AACvB,cAAU,aAAa,IAAI,SAAS;AACpC,OAAG,MAAM,aAAa;AACtB,OAAG,MAAM,WAAW;AAAA,EACrB;AAEA,SAAO;AACR;;;ACxBe,SAAR,KACN,IACA,SACY;AACZ,QAAM,SAAS,QAAQ,IAAI,CAACA,QAAOA,IAAG,YAAY;AAClD,QAAM,YAAY;AAAA,IACjB;AAAA,MACC,QAAQ;AAAA,MACR,UAAU;AAAA,MACV,YAAY;AAAA,MACZ,eAAe;AAAA,MACf,WAAW;AAAA,MACX,cAAc;AAAA,IACf;AAAA,IACA;AAAA,MACC,QAAQ,SAAS;AAAA,IAClB;AAAA,EACD;AACA,SAAO,EAAE,WAAW,QAAQ;AAC7B;;;ACfe,SAAR,MAAuB,IAAiB,SAA8B;AAC5E,MAAI,WAAW,SAAS,QAAQ;AAChC,UAAQ,UAAU;AAAA,IACjB,KAAK,QAAQ;AACZ,SAAG,MAAM,OAAO;AAChB,YAAM,QAAQ,QAAQ,IAAI,CAACC,QAAOA,IAAG,WAAW;AAChD,YAAM,YAAY;AAAA,QACjB,EAAE,WAAW,eAAe,KAAK,MAAM;AAAA,QACvC,EAAE,WAAW,kBAAkB;AAAA,MAChC;AACA,aAAO,EAAE,WAAW,QAAQ;AAAA,IAC7B;AAAA,IACA,KAAK,OAAO;AACX,SAAG,MAAM,MAAM;AACf,YAAM,SAAS,QAAQ,IAAI,CAACA,QAAOA,IAAG,YAAY;AAClD,YAAM,YAAY;AAAA,QACjB,EAAE,WAAW,eAAe,MAAM,MAAM;AAAA,QACxC,EAAE,WAAW,kBAAkB;AAAA,MAChC;AACA,aAAO,EAAE,WAAW,QAAQ;AAAA,IAC7B;AAAA,IACA,KAAK,SAAS;AACb,SAAG,MAAM,QAAQ;AACjB,YAAM,QAAQ,QAAQ,IAAI,CAACA,QAAOA,IAAG,WAAW;AAChD,YAAM,YAAY,CAAC,EAAE,WAAW,cAAc,KAAK,MAAM,GAAG,EAAE,WAAW,kBAAkB,CAAC;AAC5F,aAAO,EAAE,WAAW,QAAQ;AAAA,IAC7B;AAAA,IACA,KAAK,UAAU;AACd,SAAG,MAAM,SAAS;AAClB,YAAM,SAAS,QAAQ,IAAI,CAACA,QAAOA,IAAG,YAAY;AAClD,YAAM,YAAY;AAAA,QACjB,EAAE,WAAW,cAAc,MAAM,MAAM;AAAA,QACvC,EAAE,WAAW,kBAAkB;AAAA,MAChC;AACA,aAAO,EAAE,WAAW,QAAQ;AAAA,IAC7B;AAAA,EACD;AACD;","names":["el","el"]}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/motion/fade.ts","../../src/motion/measure.ts","../../src/motion/grow.ts","../../src/motion/slide.ts"],"sourcesContent":["import { type Animation } from \"@torpor/view\";\n\nexport default function fade(\n\t_el: HTMLElement,\n\toptions?: number | KeyframeAnimationOptions,\n): Animation {\n\tconst keyframes = [\n\t\t{\n\t\t\topacity: 0,\n\t\t},\n\t\t{\n\t\t\topacity: 1,\n\t\t},\n\t];\n\treturn { keyframes, options };\n}\n","/**\n * Measures an element before it is added to the DOM\n * @param el The element to measure\n * @param fn The function to use to get the desired measurement (e.g. el.offsetHeight)\n */\nexport default function measure(el: HTMLElement, fn: (_el: HTMLElement) => number): number {\n\t// From https://stackoverflow.com/a/46707458\n\tlet oldVisibility = el.style.visibility;\n\tlet oldPosition = el.style.position;\n\n\tlet oldParent = el.parentNode;\n\tlet oldBefore = el.nextSibling;\n\n\tel.style.visibility = \"hidden\";\n\tel.style.position = \"absolute\";\n\n\tdocument.body.appendChild(el);\n\tlet result = fn(el);\n\tel.parentNode!.removeChild(el);\n\n\t// Restore the styles unconditionally: transition functions call this with\n\t// a newly created element that isn't attached yet (oldParent is null), and\n\t// leaving the measuring styles on it would render it invisible\n\tel.style.visibility = oldVisibility;\n\tel.style.position = oldPosition;\n\n\tif (oldParent !== null) {\n\t\toldParent.insertBefore(el, oldBefore);\n\t}\n\n\treturn result;\n}\n","import { type Animation } from \"@torpor/view\";\nimport measure from \"./measure\";\n\nexport default function grow(\n\tel: HTMLElement,\n\toptions?: number | KeyframeAnimationOptions,\n): Animation {\n\tconst height = measure(el, (el) => el.clientHeight);\n\tconst keyframes = [\n\t\t{\n\t\t\theight: \"0px\",\n\t\t\toverflow: \"hidden\",\n\t\t\tpaddingTop: \"0px\",\n\t\t\tpaddingBottom: \"0px\",\n\t\t\tmarginTop: \"0px\",\n\t\t\tmarginBottom: \"0px\",\n\t\t},\n\t\t{\n\t\t\theight: height + \"px\",\n\t\t},\n\t];\n\treturn { keyframes, options };\n}\n","import { type Animation } from \"@torpor/view\";\nimport measure from \"./measure\";\n\ninterface Options extends KeyframeAnimationOptions {\n\tside: \"left\" | \"right\" | \"top\" | \"bottom\";\n}\n\nexport default function slide(el: HTMLElement, options?: Options): Animation {\n\tel.style.position = \"fixed\";\n\tswitch (options?.side ?? \"left\") {\n\t\tcase \"left\": {\n\t\t\tel.style.left = \"0px\";\n\t\t\tconst width = measure(el, (el) => el.offsetWidth);\n\t\t\tconst keyframes = [\n\t\t\t\t{ transform: `translateX(-${width}px)` },\n\t\t\t\t{ transform: \"translateX(0px)\" },\n\t\t\t];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t\tcase \"top\": {\n\t\t\tel.style.top = \"0px\";\n\t\t\tconst height = measure(el, (el) => el.offsetHeight);\n\t\t\tconst keyframes = [\n\t\t\t\t{ transform: `translateY(-${height}px)` },\n\t\t\t\t{ transform: \"translateY(0px)\" },\n\t\t\t];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t\tcase \"right\": {\n\t\t\tel.style.right = \"0px\";\n\t\t\tconst width = measure(el, (el) => el.offsetWidth);\n\t\t\tconst keyframes = [{ transform: `translateX(${width}px)` }, { transform: \"translateX(0px)\" }];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t\tcase \"bottom\": {\n\t\t\tel.style.bottom = \"0px\";\n\t\t\tconst height = measure(el, (el) => el.offsetHeight);\n\t\t\tconst keyframes = [\n\t\t\t\t{ transform: `translateY(${height}px)` },\n\t\t\t\t{ transform: \"translateY(0px)\" },\n\t\t\t];\n\t\t\treturn { keyframes, options };\n\t\t}\n\t}\n}\n"],"mappings":";AAEA,SAAwB,KACvB,KACA,SACY;CASZ,OAAO;EAAE,WAAA,CAPR,EACC,SAAS,EACV,GACA,EACC,SAAS,EACV,CAEgB;EAAG;CAAQ;AAC7B;;;;;;;;ACVA,SAAwB,QAAQ,IAAiB,IAA0C;CAE1F,IAAI,gBAAgB,GAAG,MAAM;CAC7B,IAAI,cAAc,GAAG,MAAM;CAE3B,IAAI,YAAY,GAAG;CACnB,IAAI,YAAY,GAAG;CAEnB,GAAG,MAAM,aAAa;CACtB,GAAG,MAAM,WAAW;CAEpB,SAAS,KAAK,YAAY,EAAE;CAC5B,IAAI,SAAS,GAAG,EAAE;CAClB,GAAG,WAAY,YAAY,EAAE;CAK7B,GAAG,MAAM,aAAa;CACtB,GAAG,MAAM,WAAW;CAEpB,IAAI,cAAc,MACjB,UAAU,aAAa,IAAI,SAAS;CAGrC,OAAO;AACR;;;AC5BA,SAAwB,KACvB,IACA,SACY;CAeZ,OAAO;EAAE,WAAA,CAZR;GACC,QAAQ;GACR,UAAU;GACV,YAAY;GACZ,eAAe;GACf,WAAW;GACX,cAAc;EACf,GACA,EACC,QAXa,QAAQ,KAAK,OAAO,GAAG,YAWvB,IAAI,KAClB,CAEgB;EAAG;CAAQ;AAC7B;;;ACfA,SAAwB,MAAM,IAAiB,SAA8B;CAC5E,GAAG,MAAM,WAAW;CACpB,QAAQ,SAAS,QAAQ,QAAzB;EACC,KAAK;GACJ,GAAG,MAAM,OAAO;GAMhB,OAAO;IAAE,WAAA,CAHR,EAAE,WAAW,eAFA,QAAQ,KAAK,OAAO,GAAG,WAEJ,EAAE,KAAK,GACvC,EAAE,WAAW,kBAAkB,CAEf;IAAG;GAAQ;EAE7B,KAAK;GACJ,GAAG,MAAM,MAAM;GAMf,OAAO;IAAE,WAAA,CAHR,EAAE,WAAW,eAFC,QAAQ,KAAK,OAAO,GAAG,YAEJ,EAAE,KAAK,GACxC,EAAE,WAAW,kBAAkB,CAEf;IAAG;GAAQ;EAE7B,KAAK;GACJ,GAAG,MAAM,QAAQ;GAGjB,OAAO;IAAE,WAAA,CADU,EAAE,WAAW,cADlB,QAAQ,KAAK,OAAO,GAAG,WACa,EAAE,KAAK,GAAG,EAAE,WAAW,kBAAkB,CAC1E;IAAG;GAAQ;EAE7B,KAAK;GACJ,GAAG,MAAM,SAAS;GAMlB,OAAO;IAAE,WAAA,CAHR,EAAE,WAAW,cAFC,QAAQ,KAAK,OAAO,GAAG,YAEL,EAAE,KAAK,GACvC,EAAE,WAAW,kBAAkB,CAEf;IAAG;GAAQ;CAE9B;AACD"}

package/dist/mount/draggable.ts

@@ -0,0 +1,63 @@
+import { beginDrag, endDrag, writeDragType } from "../utils/dragState";
+
+interface DraggableOptions {
+	/** High-level kind for drop targets to filter on */
+	kind?: string;
+	/** Payload handed to the drop target that receives this drag */
+	data?: any;
+	/**
+	 * Called when a drag starts; returning false cancels the drag entirely
+	 * (useful for drags-in-progress controls, readonly flags etc)
+	 */
+	onstart?: (e: DragEvent) => boolean | void;
+	/** Called when the drag finishes, whether it was dropped or cancelled */
+	onend?: (e: DragEvent) => void;
+}
+
+/**
+ * Makes an element draggable via the native HTML5 drag & drop API.
+ *
+ * ```
+ * <li onmount={(el) => draggable(el, { kind: "list-item", data: item })}>
+ * ```
+ *
+ * Pairs with dropTarget, which receives `{ kind, data }` for accepted
+ * drops. The tracked drag is always cleaned up on dragend, so handlers
+ * don't leak between drags.
+ */
+export default function draggable(node: HTMLElement, options: DraggableOptions): () => void {
+	let started = false;
+
+	function handleStart(e: DragEvent) {
+		if (options.onstart?.(e) === false) {
+			e.preventDefault();
+			return;
+		}
+		const info = beginDrag(options.kind ?? "", options.data);
+		writeDragType(e, info.id);
+		if (e.dataTransfer) {
+			e.dataTransfer.effectAllowed = "move";
+		}
+		started = true;
+	}
+
+	function handleEnd(e: DragEvent) {
+		if (started) {
+			started = false;
+			endDrag();
+			options.onend?.(e);
+		}
+	}
+
+	node.addEventListener("dragstart", handleStart);
+	node.addEventListener("dragend", handleEnd);
+
+	return () => {
+		node.removeEventListener("dragstart", handleStart);
+		node.removeEventListener("dragend", handleEnd);
+		if (started) {
+			started = false;
+			endDrag();
+		}
+	};
+}

package/dist/mount/dropTarget.ts

@@ -0,0 +1,108 @@
+import { type DragInfo, resolveDrag } from "../utils/dragState";
+
+interface DropTargetOptions {
+	/** Filters incoming drags; only accepted kinds receive over/drop calls */
+	accepts?: (info: DragInfo) => boolean;
+	/** The cursor effect shown while hovering (default "move") */
+	effect?: "move" | "copy" | "link";
+	/** Called continuously while an accepted drag hovers the target */
+	onover?: (info: DragInfo, e: DragEvent) => void;
+	/** Called once when hovering starts */
+	onenter?: (info: DragInfo, e: DragEvent) => void;
+	/** Called once when hovering ends */
+	onleave?: () => void;
+	/** Called when an accepted drag is dropped; returning false rejects it */
+	ondrop?: (info: DragInfo, e: DragEvent) => boolean | void;
+	/** Class applied while an accepted drag hovers the target */
+	dragClass?: string;
+}
+
+/**
+ * Turns an element into a drop target for native HTML5 drags.
+ *
+ * ```
+ * <div
+ * 	class="panel"
+ * 	onmount={(el) =>
+ * 		dropTarget(el, {
+ * 			accepts: (info) => info.kind === "list-item",
+ * 			dragClass: "dropping",
+ * 			ondrop: (info) => addItem(info.data),
+ * 		})
+ * 	}
+ * />
+ * ```
+ *
+ * Handles the tedious parts of the platform API -- preventing the browser's
+ * default navigation, resolving the tracked drag, effect negotiation --
+ * so components only express what they accept and what happens on drop.
+ */
+export default function dropTarget(node: HTMLElement, options: DropTargetOptions): () => void {
+	let hoverClassApplied = false;
+
+	function accepts(info: DragInfo | undefined): info is DragInfo {
+		return !!info && (!options.accepts || options.accepts(info));
+	}
+
+	function applyHover() {
+		if (!hoverClassApplied && options.dragClass) {
+			hoverClassApplied = true;
+			node.classList.add(options.dragClass);
+		}
+	}
+
+	function removeHover() {
+		if (hoverClassApplied) {
+			hoverClassApplied = false;
+			node.classList.remove(options.dragClass!);
+		}
+	}
+
+	function handleOver(e: DragEvent) {
+		const info = resolveDrag(e);
+		if (!accepts(info)) return;
+
+		e.preventDefault();
+		if (e.dataTransfer) {
+			e.dataTransfer.dropEffect = options.effect ?? "move";
+		}
+		applyHover();
+		options.onover?.(info!, e);
+	}
+
+	function handleEnter(e: DragEvent) {
+		const info = resolveDrag(e);
+		if (!accepts(info)) return;
+		applyHover();
+		options.onenter?.(info!, e);
+	}
+
+	function handleLeave(e: DragEvent) {
+		const related = e.relatedTarget as Node | null;
+		if (related && node.contains(related)) return;
+		removeHover();
+		options.onleave?.();
+	}
+
+	function handleDrop(e: DragEvent) {
+		e.preventDefault();
+		removeHover();
+
+		const info = resolveDrag(e);
+		if (!accepts(info)) return;
+		options.ondrop?.(info!, e);
+	}
+
+	node.addEventListener("dragover", handleOver);
+	node.addEventListener("dragenter", handleEnter);
+	node.addEventListener("dragleave", handleLeave);
+	node.addEventListener("drop", handleDrop);
+
+	return () => {
+		removeHover();
+		node.removeEventListener("dragover", handleOver);
+		node.removeEventListener("dragenter", handleEnter);
+		node.removeEventListener("dragleave", handleLeave);
+		node.removeEventListener("drop", handleDrop);
+	};
+}

package/dist/mount/hoverTrigger.ts

@@ -10,7 +10,7 @@ export default function hoverTrigger(node: HTMLElement, options: HoverTriggerOpt
 	const hoverDelay = options.hoverDelay || 1000;
 	const touchDelay = options.touchDelay || 1000;
 
-	let interval: NodeJS.Timeout | undefined;
+	let interval: ReturnType<typeof setTimeout> | undefined;
 
 	// Add click event handlers to the node
 	node.addEventListener("mouseenter", handleMouseEnter);

package/dist/utils/$handle.ts

@@ -0,0 +1,23 @@
+import { $run } from "@torpor/view";
+
+/**
+ * Runs a function once on subscription and re-runs it whenever any reactive
+ * state it read changes. The callback receives a `first` flag that is `true`
+ * on the initial run and `false` on every subsequent (change-driven) run, so
+ * callers can distinguish setup from "react to a change" without maintaining
+ * their own `firstChange` flag.
+ *
+ * This is a small helper over `$run` kept in @torpor/ui for its components;
+ * library authors can copy it if they need the same pattern.
+ *
+ * @param fn The function to run, receiving a `first` flag. May return a
+ *   cleanup function.
+ */
+export default function $handle(fn: (first: boolean) => void | (() => void)): void {
+	let firstRun = true;
+	$run(() => {
+		const first = firstRun;
+		firstRun = false;
+		return fn(first);
+	});
+}

package/dist/utils/LoadedItems.torp

@@ -0,0 +1,47 @@
+import { ListBox, ListBoxItem } from "../ListBox/index";
+
+interface LoadedItemsProps {
+	/** The items to render */
+	items: any[];
+	/** The selected value(s), bound through to the internal ListBox */
+	value: any;
+	/** Whether multiple items can be selected */
+	multiple?: boolean;
+	/** Extracts the display text for an item (defaults to label ?? text ?? item) */
+	getItemLabel?: (item: any) => any;
+	/** Extracts the value for an item (defaults to value ?? id) */
+	getItemValue?: (item: any) => any;
+}
+
+function defaultLabel(item: any): string {
+	const label = item?.label ?? item?.text ?? item;
+	return typeof label === "string" ? label : String(label);
+}
+
+function defaultValue(item: any): any {
+	return item?.value ?? item?.id;
+}
+
+/**
+ * The internally rendered list of options for components that load their
+ * items from a network loader (ComboBox auto-complete etc). Used as the
+ * fallback content when a consumer doesn't slot their own ListBox.
+ */
+export default function LoadedItems($props: LoadedItemsProps) {
+	const getLabel = $props.getItemLabel ?? defaultLabel;
+	const getValue = $props.getItemValue ?? defaultValue;
+
+	@render {
+		<ListBox type={$props.multiple ? "multiple" : "single"} value={$props.value}>
+			@for (let item of $props.items) {
+				@key = getValue(item)
+				<ListBoxItem value={getValue(item)}>
+					{getLabel(item)}
+				</ListBoxItem>
+			}
+		</ListBox>
+		@if ($props.items.length === 0) {
+			<span class="torp-loaded-items-empty">No results.</span>
+		}
+	}
+}

package/dist/utils/PopoutClickTrigger.torp

@@ -0,0 +1,99 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import getId from "./getId";
+import { type PopoutContext } from "./PopoutTypes";
+
+interface PopoutClickTriggerProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** The element to render: a button, or a div for right-click regions */
+	tag?: "button" | "div";
+	/** The event that activates the popout */
+	event?: "click" | "contextmenu";
+	/** The containing popout's context (the family-specific one, not PopoutContext) */
+	context: PopoutContext;
+	/**
+	 * Called with the activating event before visibility is toggled, for
+	 * triggers that track a position (right-click coordinates etc)
+	 */
+	onactivate?: (node: HTMLElement, e: MouseEvent) => void;
+}
+
+/**
+ * The shared primitive behind PopoverTrigger, ContextualTrigger and
+ * ModalTrigger: it publishes the trigger id, renders the standard trigger
+ * attributes (aria-haspopup / aria-expanded / aria-controls), anchors the
+ * popout to itself and toggles visibility on the configured event.
+ *
+ * Hover activation deliberately lives in PopoverHover / ContextualHover,
+ * whose open/close semantics (intent delay, exit grace) differ enough from
+ * a press to warrant their own component.
+ */
+export default function PopoutClickTrigger($props?: PopoutClickTriggerProps) {
+	let defaultId = getId();
+
+	const context = $props!.context;
+	const $state = context.state;
+
+	// Set the trigger ID so that it can be used with aria-labelledby
+	$state.triggerId = $props?.id ?? defaultId;
+
+	const tag = $props?.tag ?? "button";
+	const event = $props?.event ?? "click";
+
+	function handleEvent(node: HTMLElement, e: MouseEvent) {
+		if (event === "contextmenu") {
+			e.preventDefault();
+		}
+		$props?.onactivate?.(node, e);
+		$state.visible = !$state.visible;
+	}
+
+	function handleClick(e: MouseEvent) {
+		if (event !== "click") return;
+		handleEvent(e.currentTarget as HTMLElement, e);
+	}
+
+	function handleContextMenu(e: MouseEvent) {
+		if (event !== "contextmenu") return;
+		handleEvent(e.currentTarget as HTMLElement, e);
+	}
+
+	function handleMount(el: HTMLElement) {
+		context.anchorElement = el;
+	}
+
+	@render {
+		@if (tag === "button") {
+			<button
+				type="button"
+				id={$props?.id ?? defaultId}
+				class={["torp-popout-trigger", $props?.class]}
+				{$props?.style}
+				aria-haspopup={$state.contentRole ?? "true"}
+				aria-expanded={$state.visible ? "true" : "false"}
+				aria-controls={$state.contentId}
+				onclick={handleClick}
+				onmount={handleMount}
+			>
+				<slot />
+			</button>
+		} else {
+			<div
+				id={$props?.id ?? defaultId}
+				class={["torp-popout-trigger", $props?.class]}
+				{$props?.style}
+				aria-haspopup={$state.contentRole ?? "true"}
+				aria-expanded={$state.visible ? "true" : "false"}
+				aria-controls={$state.contentId}
+				oncontextmenu={handleContextMenu}
+				onmount={handleMount}
+			>
+				<slot />
+			</div>
+		}
+	}
+}

package/dist/utils/PopoutTypes.ts

@@ -3,30 +3,77 @@ export const PopoutContextName: unique symbol = Symbol.for("torp.Popout");
 // TODO: Use this type in more places
 export type HandleButtonPress = (type: "confirm" | "cancel" | undefined, value?: any) => void;
 
+/**
+ * The shared focus API for popout-style contexts: content can focus its
+ * first/last item after being shown.
+ *
+ * HACK: Deferring the focus call is necessary because if we focus the first
+ * element e.g. in a Dialog's onMount, it will scroll the page to the focused
+ * element and mess up our careful positioning. We need to be able to manually
+ * set the order to
+ * 1. set visible (so we have an element with content)
+ * 2. set position (so the element is in the right place)
+ * 3. set focus (for accessibility)
+ * There may be a more elegant way to accomplish this!
+ */
+export interface FocusApi {
+	focusFirstElement?: () => void;
+	focusLastElement?: () => void;
+}
+
 /** The shared context for popout components */
-export interface PopoutContext {
+export interface PopoutContext extends FocusApi {
 	handleButton: HandleButtonPress;
 	// HACK: We need to be able to let children (i.e. Dialogs) override the click outside functionality
 	// There may be a more elegant way to accomplish this too
-	handleClickOutside?: (e: MouseEvent) => void;
+	handleClickOutside?: (e: MouseEvent | KeyboardEvent) => void;
 	state: PopoutState;
 	//modal: boolean;
 	anchorElement?: HTMLElement;
-	// HACK: focusFirstElement is necessary because if we focus the first element e.g. in a Dialog's
-	// onMount, it will scroll the page to the focused element and mess up our careful positioning
-	// We need to be able to manually set the order to
-	// 1. set visible (so we have an element with content)
-	// 2. set position (so the element is in the right place)
-	// 3. set focus (for accessibility)
-	// There may be a more elegant way to accomplish this!
-	focusFirstElement?: () => void;
-	focusLastElement?: () => void;
+
+	/**
+	 * Called from menu content when an arrow key should move to an adjacent item
+	 * in a containing MenuBar, opening its menu. Only set by MenuBarItem.
+	 */
+	navigateMenuBar?: (target: "previous" | "next") => void;
+
+	markElement?: (id: string) => void;
+	selectMarkedElement?: () => void;
+	searchText?: string;
+	searchItems?: (searchText: string) => { id: string; setFocused: () => void } | undefined;
 }
 
 export interface PopoutState {
 	visible: boolean;
-	//position: Point;
 	contentId?: string;
+	triggerId?: string;
+	/**
+	 * The role of this popout's content ("menu", "listbox", "tree", "grid" or
+	 * "dialog"), set by the content component so that triggers can use it for
+	 * their aria-haspopup attribute.
+	 */
+	contentRole?: string;
+	/** Whether the popout is modal (e.g. it has an overlay) */
+	modal?: boolean;
+	/** The ID of the active descendant element, for aria-activedescendant */
+	activeDescendant?: string;
+}
+
+/**
+ * The state that a submenu trigger registers with its containing group
+ * (Menu, MenuBar, ToolBar or NavMenu). Passed to `registerItem`; the group
+ * assigns `index`, and the trigger assigns `text` from its label on mount.
+ */
+export interface SubmenuItemState {
+	/** Assigned by the group on registration */
+	index?: number;
+	/** The item's label, set from its text content on mount; used for type-ahead */
+	text?: string;
+	setFocused: () => void;
+	/** Shows or hides the item's submenu */
+	setVisible?: (visible: boolean) => void;
+	/** Whether the item is disabled; disabled items are skipped by keyboard navigation */
+	disabled?: boolean;
 }
 
 export interface Point {