@getdom/studio 0.1.1 → 0.2.1

package/src/pages/designer/stage/DomDesignerStage.vue

@@ -0,0 +1,237 @@
+<script setup>
+import DesignerBounds from './DesignerBounds.vue';
+import { resizeBounds } from './resizeGeometry.js';
+import { createSnapIndex, snapResize } from './snapGeometry.js';
+import { createSpacingIndex } from './spacingGeometry.js';
+import { snapTranslation } from './snapPipeline.js';
+import SpacingGuides from './SpacingGuides.vue';
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+
+defineOptions({ __doc: { name: 'Designer stage', description: 'Beta HTML stage with controlled selection and opt-in absolute movement and resizing.' } });
+const props = defineProps({
+	modelValue: { type: String, default: '' },
+	positioning: { type: Boolean, default: false },
+	interactive: { type: Boolean, default: false },
+	snapping: { type: Boolean, default: false },
+	spacingSnapping: { type: Boolean, default: false, _edit: { description: 'Repeat horizontal and vertical layer gaps while dragging. Independent of alignment snapping; disabled by default.' } },
+	frameScoped: { type: Boolean, default: false, _edit: { description: 'Only move children of an absolute data-designer-frame. Snap to that frame and its direct children.' } },
+});
+const emit = defineEmits(['update:modelValue', 'style-change']);
+const root = ref(null);
+const box = ref(null);
+const viewScale = ref(1);
+const guides = ref({});
+const canPosition = ref(false);
+const guideClip = ref(null);
+let moveFrame;
+let pendingMove;
+let observer;
+let mutationObserver;
+let gesture;
+
+/** Finds a marked element without interpolating application identifiers into selectors. */
+function selectedElement() {
+	if (gesture?.element) return gesture.element;
+	return [...(root.value?.querySelectorAll('[data-designer-id]') || [])].find((el) => el.dataset.designerId === props.modelValue);
+}
+/** Resolves the nearest containing frame without changing legacy stage behaviour. */
+function containingFrame(element) {
+	return element?.parentElement?.closest('[data-designer-frame]');
+}
+/** Allows free movement only where the parent, rather than the selected frame, is absolute. */
+function permitsPositioning(element) {
+	const frame = containingFrame(element);
+	return props.positioning && (!props.frameScoped || (frame?.dataset.designerFrame === 'absolute' && element.parentElement === frame));
+}
+/** Measures the selection in the stage's CSS coordinates, including its scroll offset. */
+function measure() {
+	const el = selectedElement();
+	canPosition.value = permitsPositioning(el);
+	if (!el || !root.value) { box.value = null; return; }
+	const r = el.getBoundingClientRect();
+	const stage = root.value.getBoundingClientRect();
+	const scale = stage.width / root.value.offsetWidth || 1;
+	viewScale.value = scale;
+	box.value = { left: (r.left - stage.left) / scale - root.value.clientLeft + root.value.scrollLeft, top: (r.top - stage.top) / scale - root.value.clientTop + root.value.scrollTop, width: r.width / scale, height: r.height / scale };
+}
+/** Selects the innermost marked HTML layer and prevents preview controls from activating. */
+function select(event) {
+	if (props.interactive || event.target.closest('[data-designer-overlay]')) return;
+	const el = event.target.closest('[data-designer-id]');
+	if (!el || !root.value.contains(el)) return;
+	event.preventDefault();
+	event.stopPropagation();
+	emit('update:modelValue', el.dataset.designerId);
+}
+/** Begins a captured pointer gesture; conversion to absolute positioning occurs on movement. */
+function begin(event, resize = '') {
+	if (event.button !== 0) return;
+	const el = selectedElement();
+	if (!el || !permitsPositioning(el)) return;
+	if (!resize) {
+		const hit = el.ownerDocument.elementsFromPoint(event.clientX, event.clientY).find((item) => item.hasAttribute('data-designer-id') && root.value.contains(item));
+		if (hit && hit.dataset.designerId !== props.modelValue) {
+			emit('update:modelValue', hit.dataset.designerId);
+			return;
+		}
+	}
+	event.preventDefault();
+	event.currentTarget.focus();
+	const parent = el.offsetParent || root.value;
+	const rect = el.getBoundingClientRect();
+	const pr = parent.getBoundingClientRect();
+	const scale = pr.width / parent.offsetWidth || 1;
+	gesture = { id: props.modelValue, pointer: event.pointerId, handle: event.currentTarget, x: event.clientX, y: event.clientY, scale, resize, left: (rect.left - pr.left) / scale - parent.clientLeft + parent.scrollLeft, top: (rect.top - pr.top) / scale - parent.clientTop + parent.scrollTop, width: rect.width / scale, height: rect.height / scale };
+	gesture.element = el;
+	if (props.snapping || (props.spacingSnapping && !resize)) {
+		const stage = root.value.getBoundingClientRect();
+		const stageScale = stage.width / root.value.offsetWidth || 1;
+		const origin = { left: (rect.left - stage.left) / stageScale - root.value.clientLeft + root.value.scrollLeft, top: (rect.top - stage.top) / stageScale - root.value.clientTop + root.value.scrollTop };
+		const scope = props.frameScoped ? containingFrame(el) : null;
+		const scopeRect = scope?.getBoundingClientRect();
+		const rects = [scope ? { left: (scopeRect.left - stage.left) / stageScale - root.value.clientLeft + root.value.scrollLeft + scope.clientLeft, top: (scopeRect.top - stage.top) / stageScale - root.value.clientTop + root.value.scrollTop + scope.clientTop, width: scope.clientWidth, height: scope.clientHeight } : { left: 0, top: 0, width: root.value.clientWidth, height: root.value.clientHeight }];
+		const bounds = rects[0];
+		guideClip.value = scope ? `inset(${bounds.top}px ${Math.max(0, root.value.clientWidth - bounds.left - bounds.width)}px ${Math.max(0, root.value.clientHeight - bounds.top - bounds.height)}px ${bounds.left}px)` : null;
+		for (const target of root.value.querySelectorAll('[data-designer-id]')) {
+			if (target === el || el.contains(target) || target.contains(el)) continue;
+			if (scope && target.parentElement !== scope) continue;
+			const r = target.getBoundingClientRect();
+			const style = target.ownerDocument.defaultView.getComputedStyle(target);
+			if (!r.width || !r.height || style.visibility === 'hidden' || style.display === 'none') continue;
+			const left = (r.left - stage.left) / stageScale - root.value.clientLeft + root.value.scrollLeft;
+			const top = (r.top - stage.top) / stageScale - root.value.clientTop + root.value.scrollTop;
+			if (left + r.width / stageScale < 0 || top + r.height / stageScale < 0 || left > root.value.clientWidth || top > root.value.clientHeight) continue;
+			rects.push({ left, top, width: r.width / stageScale, height: r.height / stageScale });
+		}
+		gesture.snap = {
+			index: props.snapping ? createSnapIndex(rects) : null,
+			spacing: props.spacingSnapping && !resize ? createSpacingIndex(rects.slice(1)) : null,
+			origin, scale: stageScale, matches: {},
+		};
+	}
+	event.currentTarget.setPointerCapture(event.pointerId);
+}
+/** Coalesces pointer events to one geometry update per animation frame. */
+function move(event) {
+	if (!gesture || gesture.pointer !== event.pointerId) return;
+	pendingMove = { pointerId: event.pointerId, clientX: event.clientX, clientY: event.clientY, ctrlKey: event.ctrlKey };
+	if (!moveFrame) moveFrame = requestAnimationFrame(flushMove);
+}
+/** Applies the latest pointer sample without retaining browser event objects. */
+function flushMove() {
+	moveFrame = null;
+	const event = pendingMove;
+	pendingMove = null;
+	if (event) applyMove(event);
+}
+/** Emits CSS patches in parent coordinates after optional stage-coordinate snapping. */
+function applyMove(event) {
+	if (!gesture || gesture.pointer !== event.pointerId) return;
+	const g = gesture;
+	const dx = (event.clientX - g.x) / g.scale;
+	const dy = (event.clientY - g.y) / g.scale;
+	if (!g.moved && Math.abs(dx) + Math.abs(dy) < 2) return;
+	g.moved = true;
+	const proposed = g.resize ? resizeBounds(g, g.resize, dx, dy) : { left: g.left + dx, top: g.top + dy, width: g.width, height: g.height };
+	let { left, top, width, height } = proposed;
+	if (g.snap && (props.snapping || (props.spacingSnapping && !g.resize)) && !event.ctrlKey) {
+		const snap = g.snap;
+		const ratio = g.scale / snap.scale;
+		const result = g.resize
+			? snapResize({ left: snap.origin.left + (left - g.left) * ratio, top: snap.origin.top + (top - g.top) * ratio, width: width * ratio, height: height * ratio }, snap.index, snap.scale, snap.matches, 16 * ratio, g.resize)
+			: snapTranslation({ left: snap.origin.left + dx * ratio, top: snap.origin.top + dy * ratio, width: g.width * ratio, height: g.height * ratio }, { alignment: snap.index, spacing: snap.spacing }, snap.scale, snap.matches);
+		if (g.resize) {
+			width = result.width / ratio;
+			height = result.height / ratio;
+		}
+		left = g.left + (result.left - snap.origin.left) / ratio;
+		top = g.top + (result.top - snap.origin.top) / ratio;
+		snap.matches = result.matches;
+		guides.value = result.matches;
+	} else {
+		guides.value = {};
+		if (g.snap) g.snap.matches = {};
+	}
+	const style = { position: 'absolute', margin: '0px', boxSizing: 'border-box', left: `${Math.round(left)}px`, top: `${Math.round(top)}px`, width: `${Math.max(16, Math.round(width))}px`, height: `${Math.max(16, Math.round(height))}px` };
+	emit('style-change', { id: g.id, style });
+	nextTick(measure);
+}
+/** Flushes the last queued sample before a normal pointer release. */
+function finish() {
+	if (moveFrame) cancelAnimationFrame(moveFrame);
+	flushMove();
+	end();
+}
+/** Releases capture on completion, cancellation, selection change or unmount. */
+function end() {
+	if (moveFrame) cancelAnimationFrame(moveFrame);
+	moveFrame = null;
+	pendingMove = null;
+	guides.value = {};
+	guideClip.value = null;
+	const g = gesture;
+	gesture = null;
+	if (g?.handle.hasPointerCapture(g.pointer)) g.handle.releasePointerCapture(g.pointer);
+}
+/** Provides keyboard movement and resizing for the same selected HTML layer. */
+function nudge(event, handle = '') {
+	if (!props.positioning || !['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(event.key)) return;
+	const el = selectedElement();
+	if (!el || !permitsPositioning(el)) return;
+	event.preventDefault();
+	const step = event.shiftKey ? 10 : 1;
+	const horizontal = event.key === 'ArrowLeft' || event.key === 'ArrowRight';
+	const delta = ['ArrowLeft', 'ArrowUp'].includes(event.key) ? -step : step;
+	const key = event.altKey ? (horizontal ? 'width' : 'height') : (horizontal ? 'left' : 'top');
+	const parent = el.offsetParent || root.value;
+	const rect = el.getBoundingClientRect();
+	const pr = parent.getBoundingClientRect();
+	const scale = pr.width / parent.offsetWidth || 1;
+	const geometry = { left: (rect.left - pr.left) / scale - parent.clientLeft + parent.scrollLeft, top: (rect.top - pr.top) / scale - parent.clientTop + parent.scrollTop, width: rect.width / scale, height: rect.height / scale };
+	if (handle) Object.assign(geometry, resizeBounds(geometry, handle, horizontal ? delta : 0, horizontal ? 0 : delta));
+	else geometry[key] = event.altKey ? Math.max(16, geometry[key] + delta) : geometry[key] + delta;
+	emit('style-change', { id: props.modelValue, style: { position: 'absolute', margin: '0px', boxSizing: 'border-box', ...Object.fromEntries(Object.entries(geometry).map(([name, value]) => [name, `${Math.round(value)}px`])) } });
+}
+/** Installs observers for responsive HTML, font loading and application-owned edits. */
+function mount() {
+	observer = new ResizeObserver(measure);
+	observer.observe(root.value);
+	mutationObserver = new MutationObserver(refresh);
+	mutationObserver.observe(root.value, { childList: true, subtree: true, attributes: true, characterData: true });
+	window.addEventListener('resize', measure);
+	refresh();
+}
+/** Updates observed layer boxes while ignoring mutations to the editor overlay itself. */
+function refresh(records = []) {
+	if (records.length && records.every((r) => r.target.closest?.('[data-designer-overlay]'))) return;
+	if (gesture) { measure(); return; }
+	observer?.disconnect();
+	if (root.value) {
+		observer?.observe(root.value);
+		root.value.querySelectorAll('[data-designer-id]').forEach((el) => observer?.observe(el));
+	}
+	measure();
+}
+/** Tears down every observer, listener and pointer capture owned by this stage. */
+function cleanup() {
+	end();
+	observer?.disconnect();
+	mutationObserver?.disconnect();
+	window.removeEventListener('resize', measure);
+}
+watch(() => [props.modelValue, props.positioning, props.interactive, props.snapping, props.spacingSnapping, props.frameScoped], async () => { end(); await nextTick(); measure(); });
+onMounted(mount);
+onBeforeUnmount(cleanup);
+</script>
+
+<template>
+	<div ref="root" class="relative isolate" @click.capture="select" @scroll.capture="measure">
+		<slot />
+		<div data-designer-overlay aria-hidden="true" class="pointer-events-none absolute inset-0 z-[2147483647]" :style="{ clipPath: guideClip }">
+			<div v-if="guides.x && guides.x.kind !== 'spacing'" class="absolute inset-y-0 bg-primary" :style="{ left: `${guides.x.target}px`, width: `${1 / viewScale}px` }" />
+			<div v-if="guides.y && guides.y.kind !== 'spacing'" class="absolute inset-x-0 bg-primary" :style="{ top: `${guides.y.target}px`, height: `${1 / viewScale}px` }" />
+			<SpacingGuides :matches="guides" :scale="viewScale" />
+		</div>
+		<DesignerBounds v-if="box && !interactive" :box="box" :scale="viewScale" :positioning="canPosition" @begin="begin($event.event, $event.handle)" @move="move" @finish="finish" @cancel="end" @nudge="nudge($event.event, $event.handle)" />
+	</div>
+</template>

package/src/pages/designer/stage/SpacingGuides.vue

@@ -0,0 +1,33 @@
+<script setup>
+import { computed } from 'vue';
+const props = defineProps({ matches: { type: Object, default: () => ({}) }, scale: { type: Number, default: 1 } });
+const unit = computed(() => 1 / Math.max(props.scale, 0.001));
+const measures = computed(measurements);
+
+/** Projects the reference and repeated gaps into non-interactive stage-coordinate rulers. */
+function measurements() {
+	return ['x', 'y'].flatMap((axis) => {
+		const match = props.matches[axis];
+		if (match?.kind !== 'spacing') return [];
+		return [match.reference, [match.neighbour, match.target]].map(([from, to]) => ({
+			axis, from: Math.min(from, to), to: Math.max(from, to), cross: match.cross,
+			label: `${Math.round(match.gap * 100) / 100}px`,
+		}));
+	});
+}
+</script>
+
+<template>
+	<svg v-if="measures.length" class="absolute inset-0 h-full w-full overflow-visible text-primary" aria-hidden="true">
+		<g v-for="(measure, index) in measures" :key="index" :stroke-width="unit" stroke="currentColor" fill="none">
+			<template v-if="measure.axis === 'x'">
+				<path :d="`M${measure.from},${measure.cross}H${measure.to} M${measure.from},${measure.cross - 4 * unit}v${8 * unit} M${measure.to},${measure.cross - 4 * unit}v${8 * unit}`" />
+				<text :x="(measure.from + measure.to) / 2" :y="measure.cross - 7 * unit" text-anchor="middle" :font-size="11 * unit" :stroke-width="3 * unit" stroke="var(--canvas)" fill="currentColor" paint-order="stroke">{{ measure.label }}</text>
+			</template>
+			<template v-else>
+				<path :d="`M${measure.cross},${measure.from}V${measure.to} M${measure.cross - 4 * unit},${measure.from}h${8 * unit} M${measure.cross - 4 * unit},${measure.to}h${8 * unit}`" />
+				<text :x="measure.cross + 7 * unit" :y="(measure.from + measure.to) / 2" dominant-baseline="middle" :font-size="11 * unit" :stroke-width="3 * unit" stroke="var(--canvas)" fill="currentColor" paint-order="stroke">{{ measure.label }}</text>
+			</template>
+		</g>
+	</svg>
+</template>

package/src/pages/designer/stage/resizeGeometry.js

@@ -0,0 +1,15 @@
+/** Resizes only the handle's axes, preserving opposite edges and clamping before they cross. */
+export function resizeBounds(rect, handle, dx, dy, minimum = 16) {
+	const result = { ...rect };
+	if (handle.includes('e')) result.width = Math.max(minimum, rect.width + dx);
+	if (handle.includes('s')) result.height = Math.max(minimum, rect.height + dy);
+	if (handle.includes('w')) {
+		result.width = Math.max(minimum, rect.width - dx);
+		result.left = rect.left + rect.width - result.width;
+	}
+	if (handle.includes('n')) {
+		result.height = Math.max(minimum, rect.height - dy);
+		result.top = rect.top + rect.height - result.height;
+	}
+	return result;
+}

package/src/pages/designer/stage/snapGeometry.js

@@ -0,0 +1,69 @@
+import { resizeBounds } from './resizeGeometry.js';
+
+/** Builds sorted, deduplicated edge/centre indexes once per gesture in stage coordinates. */
+export function createSnapIndex(rects) {
+	return {
+		x: [...new Set(rects.flatMap((r) => [r.left, r.left + r.width / 2, r.left + r.width]))].sort((a, b) => a - b),
+		y: [...new Set(rects.flatMap((r) => [r.top, r.top + r.height / 2, r.top + r.height]))].sort((a, b) => a - b),
+	};
+}
+
+/** Finds a nearest coordinate in logarithmic time without scanning all alignment targets. */
+function nearest(values, value) {
+	let low = 0;
+	let high = values.length;
+	while (low < high) {
+		const middle = (low + high) >>> 1;
+		if (values[middle] < value) low = middle + 1;
+		else high = middle;
+	}
+	const before = values[low - 1];
+	const after = values[low];
+	if (before === undefined) return after;
+	if (after === undefined) return before;
+	return value - before <= after - value ? before : after;
+}
+
+/** Resolves one axis, retaining its active anchor until the larger release threshold is crossed. */
+function snapAxis(start, size, targets, threshold, previous) {
+	const anchors = [start, start + size / 2, start + size];
+	if (previous && Math.abs(previous.target - anchors[previous.anchor]) <= threshold * 5 / 3) {
+		return { delta: previous.target - anchors[previous.anchor], match: previous };
+	}
+	let best = { delta: 0, match: null };
+	let distance = threshold;
+	for (let anchor = 0; anchor < anchors.length; anchor++) {
+		const target = nearest(targets, anchors[anchor]);
+		if (target === undefined) continue;
+		const delta = target - anchors[anchor];
+		if (Math.abs(delta) <= distance) {
+			distance = Math.abs(delta);
+			best = { delta, match: { target, anchor } };
+		}
+	}
+	return best;
+}
+
+/** Snaps translation independently on each axis; thresholds remain constant in screen pixels. */
+export function snapPosition(rect, index, scale = 1, previous = {}) {
+	const threshold = 6 / Math.max(scale, 0.001);
+	const x = snapAxis(rect.left, rect.width, index.x, threshold, previous.x);
+	const y = snapAxis(rect.top, rect.height, index.y, threshold, previous.y);
+	return { left: rect.left + x.delta, top: rect.top + y.delta, matches: { x: x.match, y: y.match } };
+}
+
+/** Snaps only the dragged edges, preserving opposite edges and rejecting sub-minimum matches. */
+export function snapResize(rect, index, scale = 1, previous = {}, minimum = 16, handle = 'se') {
+	const threshold = 6 / Math.max(scale, 0.001);
+	const base = resizeBounds(rect, handle, 0, 0, minimum);
+	const horizontal = handle.includes('w') || handle.includes('e');
+	const vertical = handle.includes('n') || handle.includes('s');
+	const x = horizontal ? snapAxis(base.left + (handle.includes('w') ? 0 : base.width), 0, index.x, threshold, previous.x) : { delta: 0, match: null };
+	const y = vertical ? snapAxis(base.top + (handle.includes('n') ? 0 : base.height), 0, index.y, threshold, previous.y) : { delta: 0, match: null };
+	const validX = base.width + (handle.includes('w') ? -x.delta : x.delta) >= minimum;
+	const validY = base.height + (handle.includes('n') ? -y.delta : y.delta) >= minimum;
+	return {
+		...resizeBounds(base, handle, validX ? x.delta : 0, validY ? y.delta : 0, minimum),
+		matches: { x: validX ? x.match : null, y: validY ? y.match : null },
+	};
+}

package/src/pages/designer/stage/snapPipeline.js

@@ -0,0 +1,17 @@
+import { snapPosition } from './snapGeometry.js';
+import { snapSpacing } from './spacingGeometry.js';
+
+/**
+ * Runs independent translation snap stages in priority order. Missing indexes
+ * disable a stage entirely. Alignment resolves first; equal spacing only fills
+ * free axes, so enabling it cannot replace an existing alignment match.
+ */
+export function snapTranslation(rect, indexes, scale = 1, previous = {}) {
+	const alignmentPrevious = { x: previous.x?.kind === 'spacing' ? null : previous.x, y: previous.y?.kind === 'spacing' ? null : previous.y };
+	const aligned = indexes.alignment
+		? snapPosition(rect, indexes.alignment, scale, alignmentPrevious)
+		: { left: rect.left, top: rect.top, matches: { x: null, y: null } };
+	if (!indexes.spacing) return aligned;
+	const spaced = snapSpacing({ ...rect, left: aligned.left, top: aligned.top }, indexes.spacing, scale, previous, aligned.matches);
+	return { left: spaced.left, top: spaced.top, matches: { x: aligned.matches.x || spaced.matches.x, y: aligned.matches.y || spaced.matches.y } };
+}

package/src/pages/designer/stage/spacingGeometry.js

@@ -0,0 +1,129 @@
+/** Returns the nearer forward neighbour, with stable ordering for equal starts. */
+function nearer(a, b) {
+	if (!a) return b;
+	if (!b) return a;
+	return a.start <= b.start ? a : b;
+}
+
+/**
+ * Finds adjacent, non-overlapping pairs sharing a perpendicular interval.
+ * An offline sweep and interval minimum tree avoid enumerating all layer pairs:
+ * O(n log n) construction, with at most one forward neighbour per layer/axis.
+ */
+function adjacentPairs(rects, axis) {
+	const items = rects.map((rect) => axis === 'x'
+		? { start: rect.left, end: rect.left + rect.width, low: rect.top, high: rect.top + rect.height }
+		: { start: rect.top, end: rect.top + rect.height, low: rect.left, high: rect.left + rect.width });
+	const points = [...new Set(items.flatMap((item) => [item.low, item.high]))].sort((a, b) => a - b);
+	const positions = new Map(points.map((point, index) => [point, index]));
+	const count = points.length - 1;
+	if (count < 1) return [];
+	const best = [];
+	const cover = [];
+	/** Adds a candidate across its perpendicular interval without visiting individual slots. */
+	function insert(node, low, high, from, to, item) {
+		if (to < low || from > high) return;
+		best[node] = nearer(best[node], item);
+		if (from <= low && to >= high) { cover[node] = nearer(cover[node], item); return; }
+		const middle = (low + high) >>> 1;
+		insert(node * 2, low, middle, from, to, item);
+		insert(node * 2 + 1, middle + 1, high, from, to, item);
+	}
+	/** Queries the nearest candidate overlapping any part of the requested interval. */
+	function query(node, low, high, from, to) {
+		if (to < low || from > high) return null;
+		if (from <= low && to >= high) return best[node];
+		const middle = (low + high) >>> 1;
+		return nearer(cover[node], nearer(query(node * 2, low, middle, from, to), query(node * 2 + 1, middle + 1, high, from, to)));
+	}
+	const starts = [...items].sort((a, b) => b.start - a.start);
+	const ends = [...items].sort((a, b) => b.end - a.end);
+	const pairs = [];
+	let cursor = 0;
+	for (const item of ends) {
+		while (cursor < starts.length && starts[cursor].start >= item.end) {
+			const next = starts[cursor++];
+			insert(1, 0, count - 1, positions.get(next.low), positions.get(next.high) - 1, next);
+		}
+		const next = query(1, 0, count - 1, positions.get(item.low), positions.get(item.high) - 1);
+		if (next && next.start > item.end) pairs.push([item, next]);
+	}
+	return pairs;
+}
+
+/**
+ * Snapshots repeated-gap extension targets from visible peer layers only.
+ * The stage and dragged layer must not be passed in. Targets remain immutable
+ * for the gesture; before-pair targets use the moving trailing edge, after-pair
+ * targets use its leading edge, so different layer sizes work naturally.
+ */
+export function createSpacingIndex(rects) {
+	const valid = rects.filter((r) => [r.left, r.top, r.width, r.height].every(Number.isFinite) && r.width > 0 && r.height > 0);
+	const index = {};
+	for (const axis of ['x', 'y']) {
+		const before = [];
+		const after = [];
+		for (const [a, b] of adjacentPairs(valid, axis)) {
+			const gap = b.start - a.end;
+			const shared = { kind: 'spacing', gap, low: Math.max(a.low, b.low), high: Math.min(a.high, b.high), reference: [a.end, b.start] };
+			before.push({ ...shared, target: a.start - gap, anchor: 2, neighbour: a.start });
+			after.push({ ...shared, target: b.end + gap, anchor: 0, neighbour: b.end });
+		}
+		index[axis] = [after.sort((a, b) => a.target - b.target), before.sort((a, b) => a.target - b.target)];
+	}
+	return index;
+}
+
+/** Returns the first target not below a search boundary. */
+function lowerBound(targets, value) {
+	let low = 0;
+	let high = targets.length;
+	while (low < high) {
+		const middle = (low + high) >>> 1;
+		if (targets[middle].target < value) low = middle + 1;
+		else high = middle;
+	}
+	return low;
+}
+
+/** Requires the moving layer to share the pair's row or column, not merely a remote gap value. */
+function overlaps(match, low, high) {
+	return Math.min(match.high, high) > Math.max(match.low, low);
+}
+
+/** Resolves one translation axis with six-pixel acquisition and ten-pixel release at any zoom. */
+function resolveAxis(start, size, low, high, targets, threshold, previous) {
+	let match = null;
+	let distance = threshold;
+	if (previous?.kind === 'spacing' && overlaps(previous, low, high)
+		&& Math.abs(previous.target - start - (previous.anchor === 2 ? size : 0)) <= threshold * 5 / 3) match = previous;
+	if (!match) {
+		for (let side = 0; side < 2; side++) {
+			const value = start + (side ? size : 0);
+			const list = targets[side];
+			for (let i = lowerBound(list, value - threshold); i < list.length && list[i].target <= value + threshold; i++) {
+				const candidate = list[i];
+				const delta = Math.abs(candidate.target - value);
+				if (delta <= distance && overlaps(candidate, low, high)) { match = candidate; distance = delta; }
+			}
+		}
+	}
+	if (!match) return { position: start, match: null };
+	return {
+		position: match.target - (match.anchor === 2 ? size : 0),
+		match: { ...match, cross: (Math.max(match.low, low) + Math.min(match.high, high)) / 2 },
+	};
+}
+
+/** Fills only unlocked translation axes; alignment matches always keep precedence. */
+export function snapSpacing(rect, index, scale = 1, previous = {}, locked = {}) {
+	const threshold = 6 / Math.max(scale, 0.001);
+	const x = locked.x ? { position: rect.left, match: null } : resolveAxis(rect.left, rect.width, rect.top, rect.top + rect.height, index.x, threshold, previous.x);
+	const y = locked.y ? { position: rect.top, match: null } : resolveAxis(rect.top, rect.height, rect.left, rect.left + rect.width, index.y, threshold, previous.y);
+	// A correction on the other axis must not take this layer out of the matched row/column.
+	if (x.match && !overlaps(x.match, y.position, y.position + rect.height)) { x.position = rect.left; x.match = null; }
+	if (y.match && !overlaps(y.match, x.position, x.position + rect.width)) { y.position = rect.top; y.match = null; }
+	if (x.match) x.match.cross = (Math.max(x.match.low, y.position) + Math.min(x.match.high, y.position + rect.height)) / 2;
+	if (y.match) y.match.cross = (Math.max(y.match.low, x.position) + Math.min(y.match.high, x.position + rect.width)) / 2;
+	return { left: x.position, top: y.position, matches: { x: x.match, y: y.match } };
+}

package/src/pages/forms/native-select/DomNativeSelect.vue

@@ -38,10 +38,15 @@ const props = defineProps({
 	},
 });
 
-const emit = defineEmits(['update:modelValue']);
+const emit = defineEmits(['update:modelValue', 'focus', 'blur']);
+/** @param {string|object} option Select option. @returns {string} Visible option label. */
 const labelOf = (option) => (option && typeof option === 'object' ? (option.label ?? option.value) : option);
+/** @param {string|object} option Select option. @returns {unknown} Submitted option value. */
 const valueOf = (option) => (option && typeof option === 'object' ? (option.value ?? option.label) : option);
 const field = useField(props, emit, { idPrefix: 'dom-native-select' });
+
+/** @param {unknown} value Option value. @returns {boolean} Explicit selection for SSR and initial hydration. */
+function isSelected(value) { return String(field.value.value ?? '') === String(value ?? ''); }
 </script>
 
 <template>
@@ -54,8 +59,8 @@ const field = useField(props, emit, { idPrefix: 'dom-native-select' });
 				@focus="field.onFocus"
 				@blur="field.onBlur"
 			>
-				<option v-if="placeholder" disabled value="">{{ placeholder }}</option>
-				<option v-for="option in options" :key="valueOf(option)" :value="valueOf(option)">
+				<option v-if="placeholder" disabled value="" :selected="isSelected('')">{{ placeholder }}</option>
+				<option v-for="option in options" :key="valueOf(option)" :value="valueOf(option)" :selected="isSelected(valueOf(option))">
 					{{ labelOf(option) }}
 				</option>
 			</select>

package/src/pages/forms/number-input/DomNumberInput.vue

@@ -3,6 +3,30 @@ import DomField from '../field/DomField.vue';
 import { fieldProps } from '../field/fieldProps.js';
 import { useField } from '../field/useField.js';
 
+defineOptions({
+	__doc: {
+		name: 'Vue number input',
+		tag: '<DomNumberInput>',
+		description: 'An accessible Vue 3 number input with v-model, labels, validation, and native min, max, and step constraints.',
+		icon: 'M8 7h8M8 12h8M8 17h8',
+		events: [
+			{ name: 'update:modelValue', payload: 'number | string', description: 'Fired with a number as the user types, or an empty string when cleared.' },
+			{ name: 'focus', payload: 'FocusEvent', description: 'Fired when the number input receives focus.' },
+			{ name: 'blur', payload: 'FocusEvent', description: 'Fired when the number input loses focus.' },
+		],
+		playground: {
+			initial: {
+				label: 'Quantity',
+				description: 'Choose between 1 and 99 items.',
+				modelValue: 3,
+				min: 1,
+				max: 99,
+				step: 1,
+			},
+		},
+	},
+});
+
 const props = defineProps({
 	...fieldProps,
 	modelValue: {
@@ -10,9 +34,21 @@ const props = defineProps({
 		default: '',
 		_edit: { description: 'Current numeric value.' },
 	},
-	min: Number,
-	max: Number,
-	step: Number,
+	min: {
+		type: Number,
+		default: null,
+		_edit: { description: 'Minimum accepted number and native spinbutton boundary.' },
+	},
+	max: {
+		type: Number,
+		default: null,
+		_edit: { description: 'Maximum accepted number and native spinbutton boundary.' },
+	},
+	step: {
+		type: Number,
+		default: 1,
+		_edit: { description: 'Increment used by the browser spin buttons and arrow keys.' },
+	},
 });
 const emit = defineEmits(['update:modelValue', 'focus', 'blur']);
 const field = useField(props, emit, { idPrefix: 'dom-number-input' });