elements-kit 0.18.2 → 0.19.0

package/dist/ui/overlay/index.mjs

@@ -0,0 +1,1001 @@
+import { p as onCleanup, s as effect } from "../../lib-Dkc7cV5F.mjs";
+import "../../signals/index.mjs";
+import { createElementRect } from "../../utilities/element-rect.mjs";
+//#region src/ui/overlay/constrain.ts
+/**
+* Resolves a custom property holding a length to pixels. Plain `px` values
+* parse directly; anything else (`svh` / `calc()` / fractions of the
+* constraint) resolves natively by measuring a hidden probe.
+*/
+function resolveVarPx(overlay, name, axis) {
+	const raw = getComputedStyle(overlay).getPropertyValue(name).trim();
+	if (/^-?\d+(\.\d+)?px$/.test(raw)) return parseFloat(raw);
+	const probe = document.createElement("div");
+	probe.style.position = "absolute";
+	probe.style.visibility = "hidden";
+	probe.style[axis] = `var(${name})`;
+	overlay.appendChild(probe);
+	const px = probe.getBoundingClientRect()[axis];
+	probe.remove();
+	return px;
+}
+/** Resolves the constraint rect every gesture bound derives from. */
+function resolveConstraint(overlay) {
+	return {
+		top: resolveVarPx(overlay, "--overlay-constraint-top", "height"),
+		left: resolveVarPx(overlay, "--overlay-constraint-left", "width"),
+		width: resolveVarPx(overlay, "--overlay-constraint-width", "width"),
+		height: resolveVarPx(overlay, "--overlay-constraint-height", "height")
+	};
+}
+/**
+* Confines an overlay to a rect source by syncing it into the
+* `--overlay-constraint-*` variables. Pass an `Element` (observed via
+* `ResizeObserver` through `createElementRect`) or a custom
+* {@link ConstraintRect}. Every location clamp and gesture bound derives
+* from those variables, so the overlay re-clamps when the rect changes.
+*
+* Caveat: `ResizeObserver` fires on size changes — a container that moves
+* without resizing (e.g. page scroll) does not retrigger the sync.
+*
+* Registers its cleanup with the current scope (`onCleanup`) and also
+* returns it as `dispose` / `Symbol.dispose`; disposing removes the
+* variables, restoring the viewport constraint.
+*
+* @example
+* ```ts
+* import { constrainOverlay } from "elements-kit/ui/overlay";
+*
+* const panel = document.querySelector("dialog.x-overlay")!;
+* constrainOverlay(panel, document.querySelector("main")!);
+* ```
+*/
+function constrainOverlay(overlay, source) {
+	const owned = source instanceof Element;
+	const rect = owned ? createElementRect(source) : source;
+	const stop = effect(() => {
+		overlay.style.setProperty("--overlay-constraint-top", `${rect.top()}px`);
+		overlay.style.setProperty("--overlay-constraint-left", `${rect.left()}px`);
+		overlay.style.setProperty("--overlay-constraint-width", `${rect.width()}px`);
+		overlay.style.setProperty("--overlay-constraint-height", `${rect.height()}px`);
+	});
+	const dispose = () => {
+		stop();
+		if (owned) rect[Symbol.dispose]();
+		overlay.style.removeProperty("--overlay-constraint-top");
+		overlay.style.removeProperty("--overlay-constraint-left");
+		overlay.style.removeProperty("--overlay-constraint-width");
+		overlay.style.removeProperty("--overlay-constraint-height");
+	};
+	onCleanup(dispose);
+	return {
+		dispose,
+		[Symbol.dispose]: dispose
+	};
+}
+//#endregion
+//#region src/ui/overlay/resize-strategy.ts
+/**
+* Resize strategies — pluggable policy for a resize drag's live bounds
+* and resting size. Pure (no DOM); the gesture injects the context.
+* Built-ins: `freeResize` (default), `detents`.
+*/
+/** How far (ms) a release velocity is projected when picking a rest. */
+const PROJECTION_MS = 160;
+/** Clamp `value` into `[min, max]`. */
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+/**
+* Picks the index of the detent closest to the released size, projected
+* along the release velocity (px/ms, positive = shrinking). Returns `-1`
+* when the gesture should dismiss instead.
+*/
+function closestDetent(sizePx, detentsPx, velocityPxPerMs = 0, dismissible = false, velocityThreshold = .5) {
+	const projected = sizePx - velocityPxPerMs * 160;
+	if (dismissible) {
+		const smallest = detentsPx[0] ?? 0;
+		if (projected < smallest / 2) return -1;
+		if (sizePx < smallest && velocityPxPerMs > velocityThreshold) return -1;
+	}
+	let best = 0;
+	for (let i = 1; i < detentsPx.length; i++) if (Math.abs(detentsPx[i] - projected) < Math.abs(detentsPx[best] - projected)) best = i;
+	return best;
+}
+/**
+* Free resize: drag to any size within the room; a flick or shrink past
+* the minimum dismisses. The default strategy.
+*/
+function freeResize(opts) {
+	return {
+		bounds: (ctx) => [opts?.min ?? ctx.min, ctx.max],
+		rest: (ctx) => {
+			const lo = opts?.min ?? ctx.min;
+			const projected = ctx.size - ctx.velocity * 160;
+			if (ctx.dismissible && (projected < lo / 2 || ctx.size < lo && ctx.velocity > ctx.velocityThreshold)) return null;
+			return clamp(ctx.size, lo, ctx.max);
+		}
+	};
+}
+/**
+* Snap to discrete steps — each a fraction of the constraint along the
+* axis (number `0–1`) or a CSS length (string). Flick-aware; shrinking
+* past the smallest step dismisses.
+*/
+function detents(steps) {
+	const resolved = (ctx) => steps.map((s) => clamp(ctx.resolve(s), ctx.min, ctx.max)).sort((a, b) => a - b);
+	return {
+		bounds: (ctx) => {
+			const s = resolved(ctx);
+			return [s[0] ?? ctx.min, s[s.length - 1] ?? ctx.max];
+		},
+		rest: (ctx) => {
+			const s = resolved(ctx);
+			const i = closestDetent(ctx.size, s, ctx.velocity, ctx.dismissible, ctx.velocityThreshold);
+			return i === -1 ? null : s[i];
+		}
+	};
+}
+/** Clamp with rubber-band resistance past either bound. */
+function resist(value, min, max, resistance = 3) {
+	if (value > max) return max + (value - max) / resistance;
+	if (value < min) return min - (min - value) / resistance;
+	return value;
+}
+/**
+* The block / inline handle sides a `data-resize` value encodes. Edges
+* name one axis (`block-start`, `inline-end` → the other side `null`);
+* corners name both as a `start`/`end` pair, block side first
+* (`end-end`, `start-end`).
+*/
+function parseResize(resize) {
+	const value = resize.trim();
+	const corner = /^(start|end)-(start|end)$/.exec(value);
+	if (corner) return {
+		block: corner[1],
+		inline: corner[2]
+	};
+	const block = /^block-(start|end)$/.exec(value);
+	if (block) return {
+		block: block[1],
+		inline: null
+	};
+	const inline = /^inline-(start|end)$/.exec(value);
+	if (inline) return {
+		block: null,
+		inline: inline[1]
+	};
+	return {
+		block: null,
+		inline: null
+	};
+}
+/** New per-axis velocity (px/ms) from a move; keeps the prior value when
+* the timestamp doesn't advance (synthetic events). */
+function updateVelocity(prev, client, timeStamp) {
+	const dt = timeStamp - prev.lastTime;
+	if (dt > 0) return {
+		x: (client.x - prev.prev.x) / dt,
+		y: (client.y - prev.prev.y) / dt
+	};
+	return prev.velocity;
+}
+/**
+* Which gesture a pointerdown engages, by zone priority: corner grip →
+* move strip → whole-surface edge drag. Returns `null` when the pointer
+* misses every zone.
+*/
+function detectEngagement(args) {
+	const { block, inline, draggable, rect, pointer, dir } = args;
+	const corner = block !== null && inline !== null;
+	const handleRight = inline === "end" === (dir === 1);
+	if (corner && Math.abs(pointer.x - (handleRight ? rect.right : rect.left)) <= 28 && Math.abs(pointer.y - (block === "end" ? rect.bottom : rect.top)) <= 28) return "resize";
+	const topCenterResize = block === "start" && inline === null;
+	if (draggable && pointer.y - rect.top >= 0 && pointer.y - rect.top <= 28 && (!topCenterResize || Math.abs(pointer.x - (dir === 1 ? rect.left : rect.right)) <= 28)) return "move";
+	if (block !== null && inline === null) return "block";
+	if (inline !== null && block === null) return "inline";
+	return null;
+}
+/**
+* Edge-drag setup: the growth `sign` (handle grows toward the pointer),
+* the `anchorSign` for the location shift, and whether the handle-less
+* edge already sits flush against the constraint (`docked` → the CSS clamp
+* holds it, skip the shift).
+*/
+function edgeSetup(args) {
+	const { axis, side, rect, constraint, dir } = args;
+	if (axis === "block") {
+		const sign = side === "end" ? 1 : -1;
+		const anchorEdge = side === "start" ? rect.bottom : rect.top;
+		const constraintEdge = side === "start" ? constraint.top + constraint.height : constraint.top;
+		return {
+			sign,
+			anchorSign: sign,
+			docked: Math.abs(anchorEdge - constraintEdge) < 1
+		};
+	}
+	const handleRight = side === "end" === (dir === 1);
+	const anchorEdge = handleRight ? rect.left : rect.right;
+	const constraintEdge = handleRight ? constraint.left : constraint.left + constraint.width;
+	return {
+		sign: (side === "end" ? 1 : -1) * dir,
+		anchorSign: handleRight ? 1 : -1,
+		docked: Math.abs(anchorEdge - constraintEdge) < 1
+	};
+}
+/**
+* Edge-drag resolution: from a target size + soft bounds, the rendered
+* size and the slide offset (the value to write to `--overlay-dx/-dy`, or
+* `null` to remove it). Both bounds rubber-band, but in different channels:
+*
+* - Above `hi` the size grows with resistance, but only up to the hard `max`
+*   (the room from the anchored edge to the constraint). Past the room the
+*   box cannot grow — `max-width`/`-height` caps it and the location clamp
+*   would shove the *anchored* edge inward — so the size pins to `max` and
+*   the resisted overshoot rides the unclamped slide instead, translating
+*   the whole surface past the edge (handle-side rubber-band). On release the
+*   strategy rests at the room and the slide clears, snapping it back in.
+* - Below `lo` the size pins to `lo` and the surface slides toward its edge
+*   (the dismiss preview).
+*
+* With a soft `hi` below the room (e.g. a `detents` max) the size-band
+* between `hi` and `max` renders normally before the slide takes over.
+*/
+function edgeDrag(args) {
+	const { target, lo, hi, sign, max = Infinity } = args;
+	if (target > hi) return slidePastRoom(hi + (target - hi) / 3, max, sign);
+	if (target < lo) return {
+		size: lo,
+		slide: -sign * (lo - Math.max(target, 0))
+	};
+	return {
+		size: target,
+		slide: null
+	};
+}
+/**
+* Cap a resisted size at the room `max`; route the resisted overshoot beyond
+* it to the slide channel (translating the surface past the edge instead of
+* letting the CSS clamp shove the anchored edge). `null` slide within the room.
+* The handle-side rubber-band shared by the edge ({@link edgeDrag}) and corner
+* resizes — both can only grow until the handle reaches the constraint.
+*/
+function slidePastRoom(resisted, max, sign) {
+	if (resisted <= max) return {
+		size: resisted,
+		slide: null
+	};
+	return {
+		size: max,
+		slide: sign * (resisted - max)
+	};
+}
+/**
+* Pin the opposite edge along one axis: shift the center-anchored location
+* by half the size change. Returns the rect-relative center coordinate, or
+* `null` when docked (the CSS clamp already holds that edge). The single
+* source of anchoring truth for block, inline, and corner resizes.
+*/
+function anchor(args) {
+	const { axis, center0, constraint, anchorSign, startSize, size, docked } = args;
+	if (docked) return null;
+	const origin = axis === "width" ? constraint.left : constraint.top;
+	return (axis === "width" ? center0.x : center0.y) - origin + anchorSign * (size - startSize) / 2;
+}
+//#endregion
+//#region src/ui/overlay/move-session.ts
+/** Move bounds on the box center — the same clamp the stylesheet applies to
+* the persisted location point (center floor = half the box). */
+function moveBounds(args) {
+	const { rect, constraint } = args;
+	const minX = constraint.left + rect.width / 2;
+	const minY = constraint.top + rect.height / 2;
+	return {
+		minX,
+		minY,
+		maxX: Math.max(constraint.left + constraint.width - rect.width / 2, minX),
+		maxY: Math.max(constraint.top + constraint.height - rect.height / 2, minY)
+	};
+}
+/** Live move offset (`--overlay-dx/-dy`): 1:1 inside the bounds, rubber-band
+* resistance beyond them. */
+function moveOffset(args) {
+	const { center0, client, start, bounds } = args;
+	return {
+		dx: resist(center0.x + (client.x - start.x), bounds.minX, bounds.maxX) - center0.x,
+		dy: resist(center0.y + (client.y - start.y), bounds.minY, bounds.maxY) - center0.y
+	};
+}
+/** Rested move location (rect-relative), clamped inside the bounds. */
+function moveRest(args) {
+	const { center0, client, start, bounds, constraint } = args;
+	const cx = clamp(center0.x + (client.x - start.x), bounds.minX, bounds.maxX);
+	const cy = clamp(center0.y + (client.y - start.y), bounds.minY, bounds.maxY);
+	return {
+		x: cx - constraint.left,
+		y: cy - constraint.top
+	};
+}
+/** Whether a flicked move's projected center leaves the constraint (close). */
+function projectedOutOfBounds(args) {
+	const { rect, velocity, constraint } = args;
+	const px = rect.left + rect.width / 2 + velocity.x * 160;
+	const py = rect.top + rect.height / 2 + velocity.y * 160;
+	return px < constraint.left || px > constraint.left + constraint.width || py < constraint.top || py > constraint.top + constraint.height;
+}
+/**
+* Window move — x/y drag from the top strip, flick off the constraint to
+* dismiss. Doesn't resize: writes only `offset` live and the rested x/y on
+* release (so the I/O layer fires no `resizechange`).
+*/
+function moveSession(snap, deps, io) {
+	const bounds = moveBounds({
+		rect: snap.rect,
+		constraint: snap.constraint
+	});
+	return {
+		move(p) {
+			const { dx, dy } = moveOffset({
+				center0: snap.center0,
+				client: p.current,
+				start: p.start,
+				bounds
+			});
+			io.sync({ offset: {
+				dx,
+				dy
+			} });
+		},
+		release(p) {
+			if (deps.dismissible && projectedOutOfBounds({
+				rect: deps.liveRect(),
+				velocity: p.velocity,
+				constraint: snap.constraint
+			})) return io.dismiss();
+			const r = moveRest({
+				center0: snap.center0,
+				client: p.current,
+				start: p.start,
+				bounds,
+				constraint: snap.constraint
+			});
+			io.commit({
+				x: r.x,
+				y: r.y
+			});
+		},
+		cancel() {
+			io.revert([]);
+		}
+	};
+}
+//#endregion
+//#region src/ui/overlay/overlay-dom.ts
+/**
+* Overlay DOM — the only element-touching code. Two halves:
+*
+* - `createFrameIO`: reads the engage-time environment off the element
+*   (`engage`, turning layout into the plain-number {@link Snapshot} /
+*   {@link Resizer} / {@link MoveDeps} the pure modes consume) and renders
+*   their output back to the `--overlay-*` channels (`sync` / `commit`) or
+*   reverts/dismisses.
+* - `createGestureRecognizer`: generic single-pointer drag plumbing
+*   (capture, velocity, the touch-scroll block) that drives a {@link Session}.
+*
+* Everything between — the mode reducers and their math — stays pure and
+* element-free (`gesture-model` + the mode files).
+*/
+const CHANNEL = {
+	x: "--overlay-x",
+	y: "--overlay-y",
+	w: "--overlay-w",
+	h: "--overlay-h"
+};
+function createFrameIO(overlay, options) {
+	const { strategy, dismissible, velocityThreshold } = options;
+	const getProp = (name) => overlay.style.getPropertyValue(name);
+	const setLen = (name, px) => overlay.style.setProperty(name, `${px}px`);
+	/** Channels at engage — `revert`/`dismiss` restore these. */
+	let prev = {
+		x: "",
+		y: "",
+		w: "",
+		h: ""
+	};
+	const restoreChannel = (name, value) => {
+		if (value) overlay.style.setProperty(name, value);
+		else overlay.style.removeProperty(name);
+	};
+	const clearDrag = () => {
+		overlay.style.removeProperty("height");
+		overlay.style.removeProperty("width");
+		overlay.style.removeProperty("--overlay-dy");
+		overlay.style.removeProperty("--overlay-dx");
+		overlay.style.removeProperty("transition");
+		overlay.style.removeProperty("user-select");
+		overlay.style.removeProperty("-webkit-user-select");
+	};
+	const emitResize = () => {
+		overlay.dispatchEvent(new CustomEvent("resizechange", {
+			bubbles: true,
+			composed: true,
+			detail: {
+				width: getProp("--overlay-w") || void 0,
+				height: getProp("--overlay-h") || void 0
+			}
+		}));
+	};
+	/** Resolves a CSS length to px in the overlay's context (strategy steps). */
+	const probeLength = (value, axis) => {
+		const probe = document.createElement("div");
+		probe.style.position = "absolute";
+		probe.style.visibility = "hidden";
+		probe.style[axis] = value;
+		overlay.appendChild(probe);
+		const px = probe.getBoundingClientRect()[axis];
+		probe.remove();
+		return px;
+	};
+	const writeFrame = (frame) => {
+		for (const k of [
+			"x",
+			"y",
+			"w",
+			"h"
+		]) {
+			const v = frame[k];
+			if (v !== void 0) setLen(CHANNEL[k], v);
+		}
+	};
+	const applyOffset = (name, v) => {
+		if (v === void 0) return;
+		if (v === null) overlay.style.removeProperty(name);
+		else setLen(name, v);
+	};
+	return {
+		engage() {
+			const constraint = resolveConstraint(overlay);
+			const rect = overlay.getBoundingClientRect();
+			prev = {
+				x: getProp("--overlay-x"),
+				y: getProp("--overlay-y"),
+				w: getProp("--overlay-w"),
+				h: getProp("--overlay-h")
+			};
+			const dir = getComputedStyle(overlay).direction === "rtl" ? -1 : 1;
+			const ctx = (q) => ({
+				...q,
+				dismissible,
+				velocityThreshold,
+				resolve: (value) => typeof value === "number" ? value * (q.axis === "width" ? constraint.width : constraint.height) : probeLength(value, q.axis)
+			});
+			return {
+				snapshot: {
+					constraint,
+					rect,
+					center0: {
+						x: rect.left + rect.width / 2,
+						y: rect.top + rect.height / 2
+					},
+					dir
+				},
+				resizer: {
+					bounds: (a) => strategy.bounds ? strategy.bounds(ctx({
+						...a,
+						size: a.startSize,
+						velocity: 0
+					})) : [a.min, a.max],
+					rest: (a, drag) => strategy.rest(ctx({
+						...a,
+						...drag
+					}))
+				},
+				move: {
+					dismissible,
+					liveRect: () => overlay.getBoundingClientRect()
+				}
+			};
+		},
+		sync(patch) {
+			overlay.style.transition = "none";
+			if (patch.frame) {
+				const f = patch.frame;
+				if (f.w !== void 0) overlay.style.width = `${f.w}px`;
+				if (f.h !== void 0) overlay.style.height = `${f.h}px`;
+				if (f.x !== void 0) setLen("--overlay-x", f.x);
+				if (f.y !== void 0) setLen("--overlay-y", f.y);
+			}
+			if (patch.offset) {
+				applyOffset("--overlay-dx", patch.offset.dx);
+				applyOffset("--overlay-dy", patch.offset.dy);
+			}
+		},
+		commit(frame) {
+			clearDrag();
+			writeFrame(frame);
+			if (frame.w !== void 0 || frame.h !== void 0) emitResize();
+		},
+		dismiss() {
+			clearDrag();
+			restoreChannel("--overlay-x", prev.x);
+			restoreChannel("--overlay-y", prev.y);
+			restoreChannel("--overlay-w", prev.w);
+			restoreChannel("--overlay-h", prev.h);
+			if (overlay instanceof HTMLDialogElement && overlay.open) overlay.close();
+			else overlay.hidePopover?.();
+		},
+		revert(keys) {
+			clearDrag();
+			for (const k of keys) restoreChannel(CHANNEL[k], prev[k]);
+		}
+	};
+}
+/**
+* The pointer loop for `target`: single-pointer capture, velocity tracking,
+* text-selection suppression, and a non-passive `touchmove` block while a
+* drag is live. It owns the "is a drag active" state and drives the engaged
+* {@link Session} — `move`/`release`/`cancel` on pointermove/up/cancel. The
+* session owns the DOM writes (through the `io` it closed over); the
+* recognizer knows nothing about channels.
+*/
+function createGestureRecognizer(target, { canEngage, engage }) {
+	let active = null;
+	let pointer = null;
+	const onPointerDown = (event) => {
+		if (active) return;
+		if (!canEngage(event)) return;
+		const session = engage(event);
+		if (!session) return;
+		active = session;
+		const c = {
+			x: event.clientX,
+			y: event.clientY
+		};
+		pointer = {
+			start: { ...c },
+			prev: { ...c },
+			current: { ...c },
+			lastTime: event.timeStamp,
+			velocity: {
+				x: 0,
+				y: 0
+			}
+		};
+		target.style.userSelect = "none";
+		target.style.setProperty("-webkit-user-select", "none");
+		target.setPointerCapture?.(event.pointerId);
+	};
+	const onPointerMove = (event) => {
+		if (!active || !pointer) return;
+		const c = {
+			x: event.clientX,
+			y: event.clientY
+		};
+		pointer.velocity = updateVelocity(pointer, c, event.timeStamp);
+		pointer.prev = c;
+		pointer.lastTime = event.timeStamp;
+		pointer.current = c;
+		active.move(pointer);
+	};
+	const onPointerUp = (event) => {
+		if (!active || !pointer) return;
+		pointer.current = {
+			x: event.clientX,
+			y: event.clientY
+		};
+		const session = active;
+		active = null;
+		target.releasePointerCapture?.(event.pointerId);
+		session.release(pointer);
+		pointer = null;
+	};
+	const onPointerCancel = () => {
+		if (!active) return;
+		const session = active;
+		active = null;
+		pointer = null;
+		session.cancel();
+	};
+	const blockScroll = (event) => {
+		if (active) event.preventDefault();
+	};
+	target.addEventListener("pointerdown", onPointerDown);
+	target.addEventListener("pointermove", onPointerMove);
+	target.addEventListener("pointerup", onPointerUp);
+	target.addEventListener("pointercancel", onPointerCancel);
+	target.addEventListener("touchmove", blockScroll, { passive: false });
+	return { dispose() {
+		target.removeEventListener("pointerdown", onPointerDown);
+		target.removeEventListener("pointermove", onPointerMove);
+		target.removeEventListener("pointerup", onPointerUp);
+		target.removeEventListener("pointercancel", onPointerCancel);
+		target.removeEventListener("touchmove", blockScroll);
+	} };
+}
+//#endregion
+//#region src/ui/overlay/resize-height-session.ts
+/**
+* Height resize — the block-axis edge handle (sheets). One edge moves toward
+* the pointer; the opposite edge is pinned by the location shift, or held by
+* the CSS clamp when docked. Below the lower bound the surface slides away via
+* `--overlay-dy`. Self-contained: the height-axis wiring lives here.
+*/
+function resizeHeightSession(snap, resizer, io, side) {
+	const startSize = snap.rect.height;
+	const { sign, anchorSign, docked } = edgeSetup({
+		axis: "block",
+		side,
+		rect: snap.rect,
+		constraint: snap.constraint,
+		dir: snap.dir
+	});
+	const hardMax = anchorSign > 0 ? snap.constraint.top + snap.constraint.height - snap.rect.top : snap.rect.bottom - snap.constraint.top;
+	const ax = {
+		axis: "height",
+		startSize,
+		min: 0,
+		max: hardMax
+	};
+	const anchorAt = (size) => anchor({
+		axis: "height",
+		center0: snap.center0,
+		constraint: snap.constraint,
+		anchorSign,
+		startSize,
+		size,
+		docked
+	});
+	return {
+		move(p) {
+			const target = startSize + sign * (p.current.y - p.start.y);
+			const [lo, hi] = resizer.bounds(ax);
+			const { size, slide } = edgeDrag({
+				target,
+				lo,
+				hi,
+				sign,
+				max: hardMax
+			});
+			const a = anchorAt(size);
+			io.sync({
+				frame: {
+					h: size,
+					...a !== null ? { y: a } : {}
+				},
+				offset: { dy: slide }
+			});
+		},
+		release(p) {
+			const target = startSize + sign * (p.current.y - p.start.y);
+			const r = resizer.rest(ax, {
+				size: target,
+				velocity: -sign * p.velocity.y
+			});
+			if (r === null) return io.dismiss();
+			const a = anchorAt(r);
+			io.commit({
+				h: r,
+				...a !== null ? { y: a } : {}
+			});
+		},
+		cancel() {
+			io.revert(["x", "y"]);
+		}
+	};
+}
+//#endregion
+//#region src/ui/overlay/resize-session.ts
+/** Corner resize: minimum width / height (free mode). */
+const MIN_RESIZE_W = 240;
+const MIN_RESIZE_H = 160;
+/** Corner-resize signs + which physical corner the handle is on. */
+function cornerSetup(args) {
+	const { block, inline, dir } = args;
+	return {
+		signX: (inline === "end" ? 1 : -1) * dir,
+		signY: block === "end" ? 1 : -1,
+		handleRight: inline === "end" === (dir === 1)
+	};
+}
+/**
+* Corner-resize bounds: the opposite corner stays anchored, so the room
+* toward the handle-side constraint edges caps the size (the grip never
+* leaves the constraint). The strategy bounds the width; the height is a
+* free clamp.
+*/
+function cornerBounds(args) {
+	const { rect, constraint, block, handleRight } = args;
+	const maxW = handleRight ? constraint.left + constraint.width - rect.left : rect.right - constraint.left;
+	return {
+		maxW,
+		maxH: block === "end" ? constraint.top + constraint.height - rect.top : rect.bottom - constraint.top,
+		hardMin: MIN_RESIZE_W,
+		hardMax: maxW
+	};
+}
+/**
+* Corner grip — free 2D resize, opposite corner anchored. The two axes are
+* asymmetric: the width follows the strategy (and alone decides dismissal),
+* the height is a free clamp `[MIN_RESIZE_H, maxH]` that never dismisses.
+*/
+function resizeSession(snap, resizer, io, block, inline) {
+	const { signX, signY, handleRight } = cornerSetup({
+		block,
+		inline,
+		dir: snap.dir
+	});
+	const { maxH, hardMin, hardMax } = cornerBounds({
+		rect: snap.rect,
+		constraint: snap.constraint,
+		block,
+		handleRight
+	});
+	const startW = snap.rect.width;
+	const startH = snap.rect.height;
+	const ax = {
+		axis: "width",
+		startSize: startW,
+		min: hardMin,
+		max: hardMax
+	};
+	const frameFor = (w, h) => ({
+		w,
+		h,
+		x: anchor({
+			axis: "width",
+			center0: snap.center0,
+			constraint: snap.constraint,
+			anchorSign: signX,
+			startSize: startW,
+			size: w,
+			docked: false
+		}),
+		y: anchor({
+			axis: "height",
+			center0: snap.center0,
+			constraint: snap.constraint,
+			anchorSign: signY,
+			startSize: startH,
+			size: h,
+			docked: false
+		})
+	});
+	return {
+		move(p) {
+			const [lo, hi] = resizer.bounds(ax);
+			const { size: w, slide: dx } = slidePastRoom(resist(startW + signX * (p.current.x - p.start.x), lo, hi), hardMax, signX);
+			const { size: h, slide: dy } = slidePastRoom(resist(startH + signY * (p.current.y - p.start.y), MIN_RESIZE_H, maxH), maxH, signY);
+			io.sync({
+				frame: frameFor(w, h),
+				offset: {
+					dx,
+					dy
+				}
+			});
+		},
+		release(p) {
+			const w = resizer.rest(ax, {
+				size: startW + signX * (p.current.x - p.start.x),
+				velocity: -p.velocity.x * signX
+			});
+			if (w === null) return io.dismiss();
+			const h = clamp(startH + signY * (p.current.y - p.start.y), MIN_RESIZE_H, maxH);
+			io.commit(frameFor(w, h));
+		},
+		cancel() {
+			io.revert([
+				"x",
+				"y",
+				"w",
+				"h"
+			]);
+		}
+	};
+}
+//#endregion
+//#region src/ui/overlay/resize-width-session.ts
+/**
+* Width resize — the inline-axis edge handle (drawers). Mirror of
+* `resizeHeightSession` on the width axis (the RTL sign flip is folded into
+* `edgeSetup`); the opposite edge is pinned, and below the lower bound the
+* surface slides via `--overlay-dx`. Self-contained: the width-axis wiring.
+*/
+function resizeWidthSession(snap, resizer, io, side) {
+	const startSize = snap.rect.width;
+	const { sign, anchorSign, docked } = edgeSetup({
+		axis: "inline",
+		side,
+		rect: snap.rect,
+		constraint: snap.constraint,
+		dir: snap.dir
+	});
+	const hardMax = anchorSign > 0 ? snap.constraint.left + snap.constraint.width - snap.rect.left : snap.rect.right - snap.constraint.left;
+	const ax = {
+		axis: "width",
+		startSize,
+		min: 0,
+		max: hardMax
+	};
+	const anchorAt = (size) => anchor({
+		axis: "width",
+		center0: snap.center0,
+		constraint: snap.constraint,
+		anchorSign,
+		startSize,
+		size,
+		docked
+	});
+	return {
+		move(p) {
+			const target = startSize + sign * (p.current.x - p.start.x);
+			const [lo, hi] = resizer.bounds(ax);
+			const { size, slide } = edgeDrag({
+				target,
+				lo,
+				hi,
+				sign,
+				max: hardMax
+			});
+			const a = anchorAt(size);
+			io.sync({
+				frame: {
+					w: size,
+					...a !== null ? { x: a } : {}
+				},
+				offset: { dx: slide }
+			});
+		},
+		release(p) {
+			const target = startSize + sign * (p.current.x - p.start.x);
+			const r = resizer.rest(ax, {
+				size: target,
+				velocity: -sign * p.velocity.x
+			});
+			if (r === null) return io.dismiss();
+			const a = anchorAt(r);
+			io.commit({
+				w: r,
+				...a !== null ? { x: a } : {}
+			});
+		},
+		cancel() {
+			io.revert(["x", "y"]);
+		}
+	};
+}
+//#endregion
+//#region src/ui/overlay/gestures.ts
+/** The size a `data-resize` value persists: block edges drive the height,
+* everything else (inline edges, corners) the width. */
+const resizeKey = (parsed) => parsed.block !== null && parsed.inline === null ? "h" : "w";
+/** Build the drag session for an engaged zone. */
+function selectSession(key, parsed, snapshot, resizer, move, io) {
+	if (key === "block") return resizeHeightSession(snapshot, resizer, io, parsed.block);
+	if (key === "inline") return resizeWidthSession(snapshot, resizer, io, parsed.inline);
+	if (key === "resize") return resizeSession(snapshot, resizer, io, parsed.block, parsed.inline);
+	return moveSession(snapshot, move, io);
+}
+/**
+* Opt-in pointer gestures for `.x-overlay`, dispatched by the gesture
+* attributes (structure stays in markup; policy is options):
+*
+* - An edge word (`block-*` / `inline-*`) is a whole-surface size drag
+*   along that axis — block drags the height (sheets), inline the width
+*   (drawers), `:dir(rtl)` flips the inline sign. The side names the
+*   handle; the opposite edge stays put.
+* - A corner word (`start-start` / … — block side first) is a desktop-
+*   window resize from a square zone at that corner, anchored at the
+*   opposite corner so the surface never grows past the constraint. The
+*   width follows the `resize` strategy; the height is a free clamp.
+* - `data-draggable` moves the surface in x/y from the top strip,
+*   rubber-banding at the edges; flinging it off the constraint dismisses
+*   (when `dismissible`).
+*
+* Layered for testability: `gesture-model` owns the pure mode reducers +
+* math, and `overlay-dom` owns all DOM contact (pointer plumbing + channel
+* I/O). This function is the wiring — it picks a pure `Session` from
+* `detectEngagement` and adapts it to the recognizer through the io.
+* The `resize` strategy (`freeResize` by default, or `detents`) decides the
+* rested size, written to the public `--overlay-w`/`--overlay-h` channels;
+* CSS renders and animates them. JS never touches `translate`/`top`/`left`.
+*
+* Registers its cleanup with the current scope (`onCleanup`) and also
+* returns it as `dispose` / `Symbol.dispose`.
+*
+* @example
+* ```ts
+* import { createOverlayGestures, detents } from "elements-kit/ui/overlay";
+*
+* const el = document.querySelector("dialog.x-overlay")!;
+* createOverlayGestures(el, { resize: detents([0.25, 0.6, 0.9]) });
+* el.addEventListener("resizechange", (e) => console.log(e.detail));
+* ```
+*/
+function createOverlayGestures(overlay, options) {
+	const io = createFrameIO(overlay, {
+		strategy: options?.resize ?? freeResize(),
+		dismissible: options?.dismissible ?? true,
+		velocityThreshold: options?.velocityThreshold ?? .5
+	});
+	const canEngage = (event) => {
+		const resize = overlay.getAttribute("data-resize") ?? "";
+		const draggable = overlay.hasAttribute("data-draggable");
+		if (!resize && !draggable) return false;
+		if (overlay.getAttribute("data-anchor") === "element") return false;
+		const target = event.target;
+		if (target?.closest("button, a, label, input, select, textarea, [contenteditable]")) return false;
+		for (let el = target; el !== null && el !== overlay; el = el.parentElement) if (el.scrollTop > 0) return false;
+		return true;
+	};
+	const engage = (event) => {
+		const parsed = parseResize(overlay.getAttribute("data-resize") ?? "");
+		const draggable = overlay.hasAttribute("data-draggable");
+		const { snapshot, resizer, move } = io.engage();
+		const key = detectEngagement({
+			...parsed,
+			draggable,
+			rect: snapshot.rect,
+			pointer: {
+				x: event.clientX,
+				y: event.clientY
+			},
+			dir: snapshot.dir
+		});
+		if (!key) return null;
+		return selectSession(key, parsed, snapshot, resizer, move, io);
+	};
+	const recognizer = createGestureRecognizer(overlay, {
+		canEngage,
+		engage
+	});
+	const dispose = () => recognizer.dispose();
+	onCleanup(dispose);
+	return {
+		resize(size) {
+			const key = resizeKey(parseResize(overlay.getAttribute("data-resize") ?? ""));
+			io.commit({ [key]: size });
+		},
+		dispose,
+		[Symbol.dispose]: dispose
+	};
+}
+//#endregion
+//#region src/ui/overlay/overlay.ts
+/**
+* One-call wiring for an interactive `.x-overlay`: optional constraint
+* sync + pointer gestures, under a single disposable. Structure stays in
+* markup (`data-resize` / `data-draggable`); policy is config.
+*
+* Registers its cleanup with the current scope (`onCleanup`) and also
+* returns it as `dispose` / `Symbol.dispose`.
+*
+* @example
+* ```ts
+* import { overlay, detents } from "elements-kit/ui/overlay";
+*
+* const el = document.querySelector("dialog.x-overlay")!;
+* const o = overlay(el, {
+*   constrain: document.querySelector("main")!,
+*   resize: detents([0.25, 0.6, 0.9]),
+*   onResize: (size) => console.log(size),
+* });
+* ```
+*/
+function overlay(el, config) {
+	const { constrain, ...gestureOptions } = config ?? {};
+	let constraint = null;
+	if (constrain) constraint = constrainOverlay(el, constrain);
+	const gestures = createOverlayGestures(el, gestureOptions);
+	const dispose = () => {
+		gestures.dispose();
+		constraint?.dispose();
+	};
+	onCleanup(dispose);
+	return {
+		resize: (size) => gestures.resize(size),
+		dispose,
+		[Symbol.dispose]: dispose
+	};
+}
+//#endregion
+export { PROJECTION_MS, clamp, closestDetent, constrainOverlay, createOverlayGestures, detents, freeResize, overlay, resolveConstraint };