sheer-ui 0.0.0

package/src/lib/internal/roving-focus-item.svelte.ts

@@ -0,0 +1,51 @@
+import { type ReadableBox, type RefAttachment, type WritableBox, attachRef } from './tools/index.js';
+import type { RovingFocusGroup } from './roving-focus-group.js';
+
+type MaybeReadableBoolean = boolean | ReadableBox<boolean>;
+
+type RovingFocusItemOptions<T extends HTMLElement = HTMLElement> = {
+	group: RovingFocusGroup;
+	ref: WritableBox<T | null>;
+	enabled?: MaybeReadableBoolean;
+	both?: MaybeReadableBoolean;
+	onRefChange?: (node: T | null) => void;
+};
+
+function readBoolean(value: MaybeReadableBoolean | undefined, fallback: boolean) {
+	if (value === undefined) return fallback;
+	return typeof value === 'boolean' ? value : value.current;
+}
+
+export class RovingFocusItem<T extends HTMLElement = HTMLElement> {
+	readonly #opts: RovingFocusItemOptions<T>;
+	readonly attachment: RefAttachment<T>;
+	#tabIndex = $state(0);
+
+	constructor(opts: RovingFocusItemOptions<T>) {
+		this.#opts = opts;
+		this.attachment = attachRef(opts.ref, opts.onRefChange);
+		this.handleKeydown = this.handleKeydown.bind(this);
+
+		$effect(() => {
+			if (!readBoolean(this.#opts.enabled, true)) {
+				this.#tabIndex = 0;
+				return;
+			}
+
+			this.#tabIndex = this.#opts.group.getTabIndex(this.#opts.ref.current);
+		});
+	}
+
+	handleKeydown(e: KeyboardEvent) {
+		if (!readBoolean(this.#opts.enabled, true)) return;
+		return this.#opts.group.handleKeydown(this.#opts.ref.current, e, readBoolean(this.#opts.both, false));
+	}
+
+	readonly props = $derived.by(
+		() =>
+			({
+				tabindex: this.#tabIndex,
+				...this.attachment,
+			}) as const,
+	);
+}

package/src/lib/internal/safe-polygon.svelte.ts

@@ -0,0 +1,239 @@
+import type { Getter } from './tools/index.js';
+import { on } from 'svelte/events';
+import { isElement } from './tools/utils/dom.js';
+import { createEffectTimeout } from './timeout-fn.svelte.js';
+import {
+	AXIS_VERTICAL,
+	DIR_POS,
+	type Point,
+	type SideBits,
+	TARGET_CONTENT,
+	TARGET_NONE,
+	TARGET_TRIGGER,
+	type TargetBits,
+	flipSide,
+	getCorridorPolygon,
+	getSide,
+	isInsideRect,
+	isPointInPolygon,
+} from './hover-intent-geometry.js';
+
+export interface SafePolygonOptions {
+	enabled: Getter<boolean>;
+	triggerNode: Getter<HTMLElement | null>;
+	contentNode: Getter<HTMLElement | null>;
+	onPointerExit: () => void;
+	buffer?: number;
+	transitIntentTimeout?: number;
+	/** nodes that should not trigger a close when they become the relatedTarget on trigger leave (e.g. sibling triggers in singleton mode) */
+	ignoredTargets?: Getter<HTMLElement[]>;
+}
+
+/**
+ * Creates a safe polygon area that allows users to move their cursor between
+ * the trigger and floating content without closing it.
+ */
+export class SafePolygon {
+	readonly #opts: SafePolygonOptions;
+	readonly #buffer: number;
+	readonly #transitIntentTimeout: number | null;
+
+	// tracks the cursor position when leaving trigger or content
+	#exitPoint: Point | null = null;
+	// tracks what we're moving toward
+	#exitTarget: TargetBits = TARGET_NONE;
+	#transitTargets: HTMLElement[] = [];
+	#trackedTriggerNode: HTMLElement | null = null;
+	#leaveFallbackRafId: number | null = null;
+	// start() is gated on #transitIntentTimeout being set (see #scheduleTransitIntentTimeout).
+	#transitIntentTimer = createEffectTimeout(() => this.#exitIfLeft(), () => this.#transitIntentTimeout!);
+
+	#cancelLeaveFallback() {
+		if (this.#leaveFallbackRafId !== null) {
+			cancelAnimationFrame(this.#leaveFallbackRafId);
+			this.#leaveFallbackRafId = null;
+		}
+	}
+
+	#scheduleLeaveFallback() {
+		this.#cancelLeaveFallback();
+		this.#leaveFallbackRafId = requestAnimationFrame(() => {
+			this.#leaveFallbackRafId = null;
+			this.#exitIfLeft();
+		});
+	}
+
+	#exitIfLeft() {
+		if (!this.#exitPoint || !this.#exitTarget) return;
+		this.#clearTracking();
+		this.#opts.onPointerExit();
+	}
+
+	#scheduleTransitIntentTimeout() {
+		if (this.#transitIntentTimeout === null) return;
+		this.#transitIntentTimer.start();
+	}
+
+	constructor(opts: SafePolygonOptions) {
+		this.#opts = opts;
+		this.#buffer = opts.buffer ?? 1;
+		const transitIntentTimeout = opts.transitIntentTimeout;
+		this.#transitIntentTimeout = typeof transitIntentTimeout === 'number' && transitIntentTimeout > 0 ? transitIntentTimeout : null;
+
+		$effect(() => {
+			const triggerNode = opts.triggerNode();
+			const contentNode = opts.contentNode();
+			const enabled = opts.enabled();
+			if (!triggerNode || !contentNode || !enabled) {
+				this.#trackedTriggerNode = null;
+				this.#clearTracking();
+				return;
+			}
+			if (this.#trackedTriggerNode && this.#trackedTriggerNode !== triggerNode) {
+				this.#clearTracking();
+			}
+			this.#trackedTriggerNode = triggerNode;
+
+			const doc = triggerNode.ownerDocument;
+
+			return [
+				on(doc, 'pointermove', (e) => this.#onPointerMove([e.clientX, e.clientY], triggerNode, contentNode)),
+				on(triggerNode, 'pointerleave', (e) => {
+					// when leaving trigger toward content, record exit point
+					const target = e.relatedTarget;
+					// if going directly to content, no need for polygon tracking
+					if (isElement(target) && contentNode.contains(target)) {
+						return;
+					}
+					// if moving to an ignored target (e.g. a sibling trigger), don't close —
+					// the sibling's enter handler will take over
+					const ignoredTargets = this.#opts.ignoredTargets?.() ?? [];
+					if (isElement(target) && ignoredTargets.some((n) => n === target || n.contains(target))) {
+						return;
+					}
+					this.#transitTargets = isElement(target) && ignoredTargets.length > 0 ? ignoredTargets.filter((n) => target.contains(n)) : [];
+					// for unrelated elements, defer close decisions to pointer geometry checks.
+					// this allows the cursor to pass through intermediate elements on the way
+					// to content without immediately closing.
+					this.#exitPoint = [e.clientX, e.clientY];
+					this.#exitTarget = TARGET_CONTENT;
+					this.#scheduleLeaveFallback();
+				}),
+				on(triggerNode, 'pointerenter', () => {
+					// reached trigger, clear tracking
+					this.#clearTracking();
+				}),
+				on(contentNode, 'pointerenter', () =>
+					// reached content, clear tracking
+					this.#clearTracking(),
+				),
+				on(contentNode, 'pointerleave', (e) => {
+					// when leaving content, check if going directly back to trigger
+					const target = e.relatedTarget;
+					if (isElement(target) && triggerNode.contains(target)) {
+						// going directly to trigger, no polygon tracking needed
+						return;
+					}
+					// set up polygon tracking toward trigger — pointermove decides whether to close
+					this.#exitPoint = [e.clientX, e.clientY];
+					this.#exitTarget = TARGET_TRIGGER;
+					this.#scheduleLeaveFallback();
+				}),
+			].reduce(
+				(acc, cleanup) => () => {
+					acc();
+					cleanup();
+				},
+				() => {},
+			);
+		});
+	}
+
+	#onPointerMove(clientPoint: Point, triggerNode: HTMLElement, contentNode: HTMLElement): void {
+		const exitPoint = this.#exitPoint;
+		const exitTarget = this.#exitTarget;
+		if (!exitPoint || !exitTarget) return;
+
+		this.#cancelLeaveFallback();
+		this.#scheduleTransitIntentTimeout();
+
+		const triggerRect = triggerNode.getBoundingClientRect();
+		const contentRect = contentNode.getBoundingClientRect();
+		const targetRect = exitTarget & TARGET_CONTENT ? contentRect : triggerRect;
+
+		if (isInsideRect(clientPoint, targetRect)) {
+			this.#clearTracking();
+			return;
+		}
+
+		if (exitTarget & TARGET_CONTENT) {
+			for (const transitTarget of this.#transitTargets) {
+				const transitRect = transitTarget.getBoundingClientRect();
+
+				if (isInsideRect(clientPoint, transitRect)) return;
+
+				const transitSide = getSide(triggerRect, transitRect);
+				const transitCorridor = getCorridorPolygon(triggerRect, transitRect, transitSide, this.#buffer);
+
+				if (isPointInPolygon(clientPoint, transitCorridor)) return;
+			}
+		}
+
+		const side = getSide(triggerRect, contentRect);
+		const corridor = getCorridorPolygon(triggerRect, contentRect, side, this.#buffer);
+
+		if (isPointInPolygon(clientPoint, corridor)) return;
+
+		const safePolygon = this.#getSafePolygon(exitPoint, targetRect, side, exitTarget);
+
+		if (isPointInPolygon(clientPoint, safePolygon)) return;
+
+		this.#clearTracking();
+		this.#opts.onPointerExit();
+	}
+
+	#clearTracking() {
+		this.#exitPoint = null;
+		this.#exitTarget = TARGET_NONE;
+		this.#transitTargets = [];
+		this.#cancelLeaveFallback();
+		this.#transitIntentTimer.stop();
+	}
+
+	/**
+	 * Creates a triangular/trapezoidal safe zone from the exit point to the target.
+	 */
+	#getSafePolygon(exitPoint: Point, targetRect: DOMRect, side: SideBits, exitTarget: TargetBits): Point[] {
+		const b = this.#buffer * 4;
+		const [x, y] = exitPoint;
+		const { top, right, bottom, left } = targetRect;
+
+		const effectiveSide = exitTarget & TARGET_TRIGGER ? flipSide(side) : side;
+		const dir = effectiveSide & DIR_POS;
+		const sign = dir === 0 ? 1 : -1;
+
+		if (effectiveSide & AXIS_VERTICAL) {
+			const edgeNear = dir === 0 ? bottom : top;
+			const edgeFar = dir === 0 ? top : bottom;
+			return [
+				[x - b, y + sign * b],
+				[x + b, y + sign * b],
+				[right + b, edgeNear],
+				[right + b, edgeFar],
+				[left - b, edgeFar],
+				[left - b, edgeNear],
+			];
+		}
+
+		const edgeNear = dir === 0 ? right : left;
+		const edgeFar = dir === 0 ? left : right;
+		return [
+			[x + sign * b, y - b],
+			[x + sign * b, y + b],
+			[edgeNear, bottom + b],
+			[edgeFar, bottom + b],
+			[edgeFar, top - b],
+			[edgeNear, top - b],
+		];
+	}
+}

package/src/lib/internal/shared-state.svelte.ts

@@ -0,0 +1,39 @@
+import type { AnyFn } from './types.js';
+
+export class SharedState<T extends AnyFn> {
+	#factory: T;
+	#subscribers = 0;
+	#state: ReturnType<T> | undefined = $state();
+	#disposeRoot: (() => void) | undefined;
+
+	constructor(factory: T) {
+		this.#factory = factory;
+	}
+
+	#release = () => {
+		// Deferred a microtask so a same-tick destroy→create (last overlay closing while the
+		// next one opens) lands on the still-alive root instead of disposing and rebuilding it —
+		// the same race svelte core defers for in createSubscriber.
+		queueMicrotask(() => {
+			this.#subscribers -= 1;
+
+			if (this.#subscribers > 0) return;
+
+			this.#disposeRoot?.();
+			this.#disposeRoot = undefined;
+			this.#state = undefined;
+		});
+	};
+
+	get(...args: Parameters<T>): ReturnType<T> {
+		this.#subscribers += 1;
+
+		this.#disposeRoot ??= $effect.root(() => {
+			this.#state = this.#factory(...args);
+		});
+
+		$effect(() => this.#release);
+
+		return this.#state!;
+	}
+}

package/src/lib/internal/state-machine.ts

@@ -0,0 +1,32 @@
+import { simpleBox, type WritableBox } from './tools/index.js';
+
+interface Machine<S> {
+	[k: string]: { [k: string]: S };
+}
+type MachineState<T> = keyof T;
+type MachineEvent<T> = keyof UnionToIntersection<T[keyof T]>;
+
+// 🤯 https://fettblog.eu/typescript-union-to-intersection/
+// oxlint-disable-next-line no-explicit-any
+type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;
+
+export class StateMachine<M> {
+	readonly state: WritableBox<MachineState<M>>;
+	readonly #machine: M & Machine<MachineState<M>>;
+
+	constructor(initialState: MachineState<M>, machine: M & Machine<MachineState<M>>) {
+		this.state = simpleBox(initialState);
+		this.#machine = machine;
+		this.dispatch = this.dispatch.bind(this);
+	}
+
+	#reducer(event: MachineEvent<M>) {
+		// @ts-expect-error  state.current is keyof M
+		const nextState = this.#machine[this.state.current][event];
+		return nextState ?? this.state.current;
+	}
+
+	dispatch(event: MachineEvent<M>) {
+		this.state.current = this.#reducer(event);
+	}
+}

package/src/lib/internal/svelte-resize-observer.svelte.ts

@@ -0,0 +1,37 @@
+import { createAttachmentKey, type Attachment } from 'svelte/attachments';
+
+type MaybeElement = Element | null | undefined | false;
+
+/** rAF-debounced ResizeObserver over `nodes`, returning its teardown. */
+function observeNodes(nodes: Element[], onResize: ResizeObserverCallback, options?: ResizeObserverOptions) {
+	let rAF = 0;
+
+	const resizeObserver = new ResizeObserver((entries, observer) => {
+		window.cancelAnimationFrame(rAF);
+		rAF = window.requestAnimationFrame(() => onResize(entries, observer));
+	});
+
+	for (const node of nodes) {
+		resizeObserver.observe(node, options);
+	}
+
+	return () => {
+		window.cancelAnimationFrame(rAF);
+		resizeObserver.disconnect();
+	};
+}
+
+export function resizeAttachment<T extends Element = HTMLElement>(onResize: ResizeObserverCallback, options?: ResizeObserverOptions) {
+	return {
+		[createAttachmentKey()]: ((node: T) => observeNodes([node], onResize, options)) satisfies Attachment<T>,
+	};
+}
+
+export function observeResizeMany(getNodes: () => Iterable<MaybeElement>, onResize: () => void, options?: ResizeObserverOptions) {
+	$effect(() => {
+		const nodes = [...getNodes()].filter(Boolean) as Element[];
+		if (nodes.length === 0) return;
+
+		return observeNodes(nodes, onResize, options);
+	});
+}