sheer-ui 0.0.0

package/src/lib/internal/focus-scope/focus-scope.svelte.ts

@@ -0,0 +1,310 @@
+import { type Getter, type RefAttachment } from '../tools/index.js';
+import { getFocusableCandidates, getTabbableCandidates, isFocusable } from '../tabbable.js';
+import { on } from 'svelte/events';
+import { createAttachmentKey, type Attachment } from 'svelte/attachments';
+import { untrack } from 'svelte';
+
+export interface FocusScopeOpts {
+	onOpenAutoFocus: Getter<(event: Event) => void>;
+	onCloseAutoFocus: Getter<(event: Event) => void>;
+	trap: Getter<boolean>;
+	loop: Getter<boolean>;
+}
+
+export interface FocusScopeAttachmentOpts extends FocusScopeOpts {
+	enabled: Getter<boolean>;
+}
+
+/**
+ * Per-document scope stack + focus memory. The active scope is the top of the stack;
+ * an occluded scope needs no paused flag — its handlers gate on isActiveScope at
+ * event time, so activeness is derived from stack position, never synced.
+ */
+class FocusScopeManager {
+	static #instances = new WeakMap<Document, FocusScopeManager>();
+	#scopeStack: FocusScope[] = [];
+	#focusHistory = new WeakMap<FocusScope, HTMLElement>();
+	#preFocusHistory = new WeakMap<FocusScope, HTMLElement>();
+	#document: Document;
+
+	constructor(doc: Document) {
+		this.#document = doc;
+	}
+
+	static getInstance(doc: Document) {
+		let instance = this.#instances.get(doc);
+		if (!instance) {
+			instance = new FocusScopeManager(doc);
+			this.#instances.set(doc, instance);
+		}
+		return instance;
+	}
+
+	register(scope: FocusScope) {
+		// capture the currently focused element before this scope becomes active
+		const activeElement = this.#document.activeElement as HTMLElement;
+		if (activeElement && activeElement !== this.#document.body) {
+			this.#preFocusHistory.set(scope, activeElement);
+		}
+
+		this.#scopeStack = this.#scopeStack.filter((s) => s !== scope);
+		this.#scopeStack.unshift(scope);
+	}
+
+	unregister(scope: FocusScope) {
+		this.#scopeStack = this.#scopeStack.filter((s) => s !== scope);
+	}
+
+	isActiveScope(scope: FocusScope): boolean {
+		return this.#scopeStack[0] === scope;
+	}
+
+	setFocusMemory(scope: FocusScope, element: HTMLElement) {
+		this.#focusHistory.set(scope, element);
+	}
+
+	getFocusMemory(scope: FocusScope): HTMLElement | undefined {
+		return this.#focusHistory.get(scope);
+	}
+
+	getPreFocusMemory(scope: FocusScope): HTMLElement | undefined {
+		return this.#preFocusHistory.get(scope);
+	}
+
+	clearPreFocusMemory(scope: FocusScope) {
+		this.#preFocusHistory.delete(scope);
+	}
+}
+
+class FocusScope {
+	#container: HTMLElement | null = null;
+	#manager: FocusScopeManager | null = null;
+	#trapCleanupFns: Array<() => void> = [];
+	#opts: FocusScopeOpts;
+
+	constructor(opts: FocusScopeOpts) {
+		this.#opts = opts;
+	}
+
+	#cleanup() {
+		for (const fn of this.#trapCleanupFns) {
+			fn();
+		}
+		this.#trapCleanupFns = [];
+	}
+
+	mount(container: HTMLElement) {
+		if (this.#container) {
+			this.unmount();
+		}
+
+		this.#container = container;
+		this.#manager = FocusScopeManager.getInstance(container.ownerDocument);
+		this.#manager.register(this);
+		this.#handleOpenAutoFocus();
+	}
+
+	unmount() {
+		if (!this.#container) return;
+
+		this.#cleanup();
+
+		// handle close auto-focus
+		this.#handleCloseAutoFocus();
+
+		this.#manager?.unregister(this);
+		this.#manager?.clearPreFocusMemory(this);
+		this.#container = null;
+		this.#manager = null;
+	}
+
+	#handleOpenAutoFocus() {
+		if (!this.#container) return;
+
+		const event = new CustomEvent('focusScope.onOpenAutoFocus', {
+			bubbles: false,
+			cancelable: true,
+		});
+		this.#opts.onOpenAutoFocus()(event);
+
+		if (!event.defaultPrevented) {
+			requestAnimationFrame(() => {
+				if (!this.#container) return;
+				const firstTabbable = this.#getFirstTabbable();
+				if (firstTabbable) {
+					firstTabbable.focus();
+					this.#manager?.setFocusMemory(this, firstTabbable);
+				} else {
+					this.#container.focus();
+				}
+			});
+		}
+	}
+
+	#handleCloseAutoFocus() {
+		const event = new CustomEvent('focusScope.onCloseAutoFocus', {
+			bubbles: false,
+			cancelable: true,
+		});
+
+		this.#opts.onCloseAutoFocus()?.(event);
+
+		if (!event.defaultPrevented) {
+			// return focus to the element that was focused before this scope opened
+			const preFocusedElement = this.#manager?.getPreFocusMemory(this);
+			const doc = this.#container?.ownerDocument;
+			if (preFocusedElement && doc?.contains(preFocusedElement)) {
+				// ensure the element is still focusable and in the document
+				try {
+					preFocusedElement.focus();
+				} catch {
+					// fallback if focus fails
+					doc.body.focus();
+				}
+			}
+		}
+	}
+
+	enableTrap() {
+		if (!this.#container || this.#trapCleanupFns.length > 0) return;
+
+		const container = this.#container;
+		const doc = container.ownerDocument;
+
+		const handleFocus = (e: FocusEvent) => {
+			if (!this.#manager?.isActiveScope(this)) return;
+
+			const target = e.target as HTMLElement;
+			if (!target) return;
+
+			const isInside = container.contains(target);
+
+			if (isInside) {
+				// store last focused element
+				this.#manager?.setFocusMemory(this, target);
+			} else {
+				// focus escaped - bring it back
+				const lastFocused = this.#manager?.getFocusMemory(this);
+				if (lastFocused && container.contains(lastFocused) && isFocusable(lastFocused)) {
+					e.preventDefault();
+					lastFocused.focus();
+				} else {
+					// fallback to first tabbable or first focusable or container
+					const firstTabbable = this.#getFirstTabbable();
+					const firstFocusable = this.#getAllFocusables()[0];
+					(firstTabbable || firstFocusable || container).focus();
+				}
+			}
+		};
+
+		const handleKeydown = (e: KeyboardEvent) => {
+			if (!this.#opts.loop() || e.key !== 'Tab') return;
+			if (!this.#manager?.isActiveScope(this)) return;
+
+			const tabbables = this.#getTabbables();
+			if (tabbables.length === 0) return;
+
+			const first = tabbables[0];
+			const last = tabbables[tabbables.length - 1];
+
+			if (!e.shiftKey && doc.activeElement === last) {
+				e.preventDefault();
+				first!.focus();
+			} else if (e.shiftKey && doc.activeElement === first) {
+				e.preventDefault();
+				last!.focus();
+			}
+		};
+
+		this.#trapCleanupFns.push(on(doc, 'focusin', handleFocus, { capture: true }), on(container, 'keydown', handleKeydown));
+
+		const Observer = doc.defaultView?.MutationObserver ?? MutationObserver;
+		const observer = new Observer(() => {
+			const lastFocused = this.#manager?.getFocusMemory(this);
+			if (lastFocused && !container.contains(lastFocused)) {
+				// last focused element was removed
+				const firstTabbable = this.#getFirstTabbable();
+				const firstFocusable = this.#getAllFocusables()[0];
+				const elementToFocus = firstTabbable || firstFocusable;
+
+				if (elementToFocus) {
+					elementToFocus.focus();
+					this.#manager?.setFocusMemory(this, elementToFocus);
+				} else {
+					// no focusable elements left, focus container
+					container.focus();
+				}
+			}
+		});
+
+		observer.observe(container, {
+			childList: true,
+			subtree: true,
+		});
+
+		this.#trapCleanupFns.push(() => observer.disconnect());
+	}
+
+	disableTrap() {
+		this.#cleanup();
+	}
+
+	#getTabbables(): HTMLElement[] {
+		if (!this.#container) return [];
+
+		return getTabbableCandidates(this.#container);
+	}
+
+	#getFirstTabbable(): HTMLElement | null {
+		const tabbables = this.#getTabbables();
+		return tabbables[0] || null;
+	}
+
+	#getAllFocusables(): HTMLElement[] {
+		if (!this.#container) return [];
+
+		return getFocusableCandidates(this.#container);
+	}
+
+}
+
+export function createFocusScopeAttachment(opts: FocusScopeAttachmentOpts): RefAttachment<HTMLElement> {
+	return {
+		[createAttachmentKey()]: ((node) => {
+			if (!opts.enabled()) return;
+
+			const scope = new FocusScope(opts);
+			untrack(() => scope.mount(node));
+
+			$effect(() => {
+				if (!opts.trap()) {
+					untrack(() => scope.disableTrap());
+					return;
+				}
+
+				untrack(() => scope.enableTrap());
+
+				return () => {
+					untrack(() => scope.disableTrap());
+				};
+			});
+
+			return () => {
+				untrack(() => scope.unmount());
+			};
+		}) satisfies Attachment<HTMLElement>,
+	};
+}
+
+export function createFocusScopeProps(opts: FocusScopeAttachmentOpts) {
+	const focusScopeAttachment = createFocusScopeAttachment(opts);
+
+	return {
+		get props() {
+			return {
+				tabindex: -1,
+				...focusScopeAttachment,
+			};
+		},
+	};
+}

package/src/lib/internal/focus-scope/index.ts

@@ -0,0 +1,4 @@
+export { createFocusScopeAttachment, createFocusScopeProps } from './focus-scope.svelte.js';
+
+export type { FocusScopeAttachmentOpts, FocusScopeOpts } from './focus-scope.svelte.js';
+export type { FocusScopeProps } from './types.js';

package/src/lib/internal/focus-scope/types.ts

@@ -0,0 +1,45 @@
+import type { Snippet } from 'svelte';
+import type { EventCallback } from '../tools/utils/events.js';
+import type { ReadableBox } from '../tools/index.js';
+
+export type FocusScopeProps = {
+	/**
+	 * Event handler called when auto-focusing on open.
+	 * Can be prevented.
+	 */
+	onOpenAutoFocus?: EventCallback;
+
+	/**
+	 * Event handler called when auto-focusing on close.
+	 * Can be prevented.
+	 */
+	onCloseAutoFocus?: EventCallback;
+
+	/**
+	 * Whether focus is trapped within the focus scope.
+	 *
+	 * @defaultValue false
+	 */
+	trapFocus?: boolean;
+};
+
+export type FocusScopeImplProps = {
+	/**
+	 * The snippet to render the focus scope container with its props.
+	 */
+	focusScope?: Snippet<[{ props: Record<string, unknown> }]>;
+
+	/**
+	 * When `true` will loop through the tabbable elements in the focus scope.
+	 */
+	loop?: boolean;
+
+	/**
+	 * Whether the content within the focus trap is being force mounted or not.
+	 */
+	forceMount?: boolean;
+
+	enabled: boolean;
+
+	ref: ReadableBox<HTMLElement | null>;
+} & FocusScopeProps;

package/src/lib/internal/focus.ts

@@ -0,0 +1,14 @@
+export function focusFirst(candidates: HTMLElement[], getActiveElement: () => Element | null) {
+	const previouslyFocusedElement = getActiveElement();
+
+	for (const candidate of candidates) {
+		// focus already sits where we want it, so don't walk past it into the next candidate
+		if (candidate === previouslyFocusedElement) return true;
+
+		candidate.focus({ preventScroll: true });
+
+		if (getActiveElement() !== previouslyFocusedElement) return true;
+	}
+
+	return false;
+}

package/src/lib/internal/global-singleton.ts

@@ -0,0 +1,10 @@
+/**
+ * Realm-global singleton keyed on `globalThis`, so layer stacks and the id counter
+ * survive multiple module-graph copies of this library in one page (e.g. two bundles).
+ * Replaces the ambient `app.d.ts` globals: ambient declarations don't travel when the
+ * library is consumed as workspace source, a typed accessor does.
+ */
+export function globalSingleton<T>(key: string, init: () => T): T {
+	const globals = globalThis as unknown as Record<string, T>;
+	return (globals[key] ??= init());
+}

package/src/lib/internal/group-value.svelte.ts

@@ -0,0 +1,36 @@
+import { untrack } from 'svelte';
+import type { ReadableBox, WritableBox } from './tools/index.js';
+
+interface GroupValue {
+	opts: { value: WritableBox<string[]> };
+}
+
+interface GroupItem {
+	value: ReadableBox<string | undefined>;
+	checked: WritableBox<boolean>;
+}
+
+/**
+ * Writes the item's checked state into the group's value array and returns a reader for
+ * the reverse direction: whether the group holds the item's value, or undefined when the
+ * item is outside a group or has no value. The component repairs its own `checked` bindable
+ * from that reader, so a parent-driven change never fires the item's onCheckedChange.
+ */
+export function joinGroup(group: GroupValue | null, item: GroupItem): () => boolean | undefined {
+	if (!group) return () => undefined;
+
+	$effect(() => {
+		const checked = item.checked.current;
+		untrack(() => {
+			const value = item.value.current;
+			const values = group.opts.value.current;
+			if (!value || checked === values.includes(value)) return;
+			group.opts.value.current = checked ? [...values, value] : values.filter((v) => v !== value);
+		});
+	});
+
+	return () => {
+		const value = item.value.current;
+		return value ? group.opts.value.current.includes(value) : undefined;
+	};
+}

package/src/lib/internal/hover-intent-geometry.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared pointer-geometry primitives for "don't close while the cursor is moving toward the
+ * content" hover tracking. Both `SafePolygon` (tooltip/popover/link-preview) and `MenuSubmenuIntent`
+ * (nested menu chains, in menu.svelte.ts) need this exact math. It's kept in the bitmask+tuple
+ * representation SafePolygon originated (cheap integer comparisons instead of string comparisons on
+ * every pointermove) rather than a more "readable" string+object form — this runs on pointer-move
+ * frequency, and the bits are the performant version worth converging on.
+ *
+ * Deliberately excludes the "safe zone" shape builders (getSafePolygon / getIntentPolygon): those are
+ * genuinely different algorithms (a forgiving hexagon vs a precise triangle) driven by different
+ * domain requirements — a single floating trigger/content pair vs densely-packed sibling menu items —
+ * not incidental duplication, so each keeps its own.
+ */
+
+export type Point = [number, number];
+
+export const AXIS_VERTICAL = 0b10;
+export const DIR_POS = 0b01;
+
+export const LEFT = 0b00;
+export const RIGHT = 0b01;
+export const TOP = 0b10;
+export const BOTTOM = 0b11;
+
+export type SideBits = typeof LEFT | typeof RIGHT | typeof TOP | typeof BOTTOM;
+
+export function isPointInPolygon(point: Point, polygon: Point[]): boolean {
+	const [x, y] = point;
+	let isInside = false;
+	const length = polygon.length;
+	for (let i = 0, j = length - 1; i < length; j = i++) {
+		const [xi, yi] = polygon[i] ?? [0, 0];
+		const [xj, yj] = polygon[j] ?? [0, 0];
+		const intersect = yi >= y !== yj >= y && x <= ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+		if (intersect) {
+			isInside = !isInside;
+		}
+	}
+	return isInside;
+}
+
+export const isInsideRect = (point: Point, rect: DOMRect): boolean =>
+	point[0] >= rect.left && point[0] <= rect.right && point[1] >= rect.top && point[1] <= rect.bottom;
+
+export function getSide(triggerRect: DOMRect, contentRect: DOMRect): SideBits {
+	// determine which side the content is on relative to trigger
+	const dx = contentRect.left + contentRect.width / 2 - (triggerRect.left + triggerRect.width / 2);
+	const dy = contentRect.top + contentRect.height / 2 - (triggerRect.top + triggerRect.height / 2);
+
+	return Math.abs(dx) > Math.abs(dy)
+		? ((dx > 0 ? DIR_POS : 0) as SideBits)
+		: ((AXIS_VERTICAL | (dy > 0 ? DIR_POS : 0)) as SideBits);
+}
+
+export const flipSide = (side: SideBits): SideBits => (side ^ DIR_POS) as SideBits;
+
+export const TARGET_NONE = 0;
+export const TARGET_TRIGGER = 0b01;
+export const TARGET_CONTENT = 0b10;
+
+export type TargetBits = typeof TARGET_NONE | typeof TARGET_TRIGGER | typeof TARGET_CONTENT;
+
+/**
+ * A rectangular corridor between trigger and content — this prevents closing when the cursor is in
+ * the gap between them.
+ */
+export function getCorridorPolygon(triggerRect: DOMRect, contentRect: DOMRect, side: SideBits, buffer: number): Point[] {
+	const b = buffer;
+
+	const minX = Math.min(triggerRect.left, contentRect.left) - b;
+	const maxX = Math.max(triggerRect.right, contentRect.right) + b;
+	const minY = Math.min(triggerRect.top, contentRect.top) - b;
+	const maxY = Math.max(triggerRect.bottom, contentRect.bottom) + b;
+
+	const dir = side & DIR_POS;
+
+	if (side & AXIS_VERTICAL) {
+		const triggerY = dir === 0 ? triggerRect.top : triggerRect.bottom;
+		const contentY = dir === 0 ? contentRect.bottom : contentRect.top;
+		return [
+			[minX, triggerY],
+			[minX, contentY],
+			[maxX, contentY],
+			[maxX, triggerY],
+		];
+	}
+
+	const triggerX = dir === 0 ? triggerRect.left : triggerRect.right;
+	const contentX = dir === 0 ? contentRect.right : contentRect.left;
+	return [
+		[triggerX, minY],
+		[contentX, minY],
+		[contentX, maxY],
+		[triggerX, maxY],
+	];
+}

package/src/lib/internal/index.ts

@@ -0,0 +1,44 @@
+// oxlint-disable no-explicit-any
+
+export type Selected<Value> = {
+	value: Value;
+	label?: string;
+};
+
+export type FocusTarget = string | HTMLElement | SVGElement | null;
+export type FocusProp = FocusTarget | ((defaultEl?: HTMLElement | null) => FocusTarget);
+
+export type Orientation = 'horizontal' | 'vertical';
+export type Direction = 'ltr' | 'rtl';
+
+/**
+ * Controls positioning of the slider thumb.
+ *
+ * - `exact`: The thumb is centered exactly at the value of the slider.
+ * - `contain`: The thumb is centered exactly at the value of the slider, but will be contained within the slider track at the ends.
+ */
+export type SliderThumbPositioning = 'exact' | 'contain';
+
+export type { StyleProperties } from './tools/types.js';
+export type { WithoutChild, WithoutChildren, WithoutChildrenOrChild, WithElementRef } from './utils.js';
+export type { WithChild, Without, WithChildren, FloatingContentSnippetProps, StaticContentSnippetProps } from './types.js';
+export type {
+	SegmentPart,
+	EditableSegmentPart,
+	EditableTimeSegmentPart,
+	Month,
+	DateMatcher,
+	DateOnInvalid,
+	DateRangeValidator,
+	DateValidator,
+	DateRange,
+	TimeValue,
+	TimeSegmentPart,
+	TimeEndpoints,
+	TimeValidator,
+	TimeRangeValidator,
+	TimeOnInvalid,
+} from './date-time/types.js';
+
+export { mergeProps } from './merge-props.js';
+export * from './attribute-types.js';

package/src/lib/internal/kbd.ts

@@ -0,0 +1,60 @@
+import type { Direction, Orientation } from './index.js';
+
+export const kbd = {
+	ALT: 'Alt',
+	ARROW_DOWN: 'ArrowDown',
+	ARROW_LEFT: 'ArrowLeft',
+	ARROW_RIGHT: 'ArrowRight',
+	ARROW_UP: 'ArrowUp',
+	BACKSPACE: 'Backspace',
+	CAPS_LOCK: 'CapsLock',
+	CONTROL: 'Control',
+	DELETE: 'Delete',
+	END: 'End',
+	ENTER: 'Enter',
+	ESCAPE: 'Escape',
+	F1: 'F1',
+	F2: 'F2',
+	F3: 'F3',
+	F4: 'F4',
+	F5: 'F5',
+	F6: 'F6',
+	F7: 'F7',
+	F8: 'F8',
+	F9: 'F9',
+	F10: 'F10',
+	F11: 'F11',
+	F12: 'F12',
+	HOME: 'Home',
+	META: 'Meta',
+	PAGE_DOWN: 'PageDown',
+	PAGE_UP: 'PageUp',
+	SHIFT: 'Shift',
+	SPACE: ' ',
+	TAB: 'Tab',
+	CTRL: 'Control',
+	ASTERISK: '*',
+	a: 'a',
+	A: 'A',
+	p: 'p',
+	P: 'P',
+	n: 'n',
+	j: 'j',
+	k: 'k',
+	h: 'h',
+	l: 'l',
+} as const;
+
+export const getDirectionalKeys = (dir: Direction = 'ltr', orientation: Orientation = 'horizontal') => ({
+	nextKey: orientation === 'vertical' ? kbd.ARROW_DOWN : dir === 'rtl' ? kbd.ARROW_LEFT : kbd.ARROW_RIGHT,
+	prevKey: orientation === 'vertical' ? kbd.ARROW_UP : dir === 'rtl' ? kbd.ARROW_RIGHT : kbd.ARROW_LEFT,
+});
+
+/**
+ * Keyboard key-sets shared across menu, select, and roving-focus navigation.
+ * Membership is tested with `.includes()`, so element order is irrelevant.
+ */
+export const FIRST_KEYS: string[] = [kbd.ARROW_DOWN, kbd.PAGE_UP, kbd.HOME];
+export const LAST_KEYS: string[] = [kbd.ARROW_UP, kbd.PAGE_DOWN, kbd.END];
+export const FIRST_LAST_KEYS: string[] = [...FIRST_KEYS, ...LAST_KEYS];
+export const SELECTION_KEYS: string[] = [kbd.ENTER, kbd.SPACE];

package/src/lib/internal/layer-stack.ts

@@ -0,0 +1,37 @@
+/**
+ * A registry of active "layers" (dismissible overlays, escape-key listeners, text-selection
+ * locks, ...) that answers "am I responsible for handling this event right now" — the topmost
+ * registered layer whose value is in the closing set, falling back to the first-registered layer
+ * if none defer. `isClosingBehavior` defaults to always-true, matching stacks that don't have a
+ * behavior-type distinction at all (just "the most recently registered layer is responsible").
+ *
+ * Each layer type gets its own stack via its own `createLayerStack()` call — they don't compete
+ * with each other for "who's on top".
+ */
+export interface LayerStack<TInstance, TValue> {
+	register(instance: TInstance, value: TValue): void;
+	unregister(instance: TInstance): void;
+	isResponsible(instance: TInstance): boolean;
+}
+
+export function createLayerStack<TInstance, TValue>(
+	isClosingBehavior: (value: TValue) => boolean = () => true,
+): LayerStack<TInstance, TValue> {
+	const layers = new Map<TInstance, TValue>();
+
+	return {
+		register(instance, value) {
+			layers.set(instance, value);
+		},
+		unregister(instance) {
+			layers.delete(instance);
+		},
+		isResponsible(instance) {
+			const entries = [...layers];
+			const topMost = entries.findLast(([, value]) => isClosingBehavior(value));
+			if (topMost) return topMost[0] === instance;
+			const firstEntry = entries[0];
+			return firstEntry !== undefined && firstEntry[0] === instance;
+		},
+	};
+}

package/src/lib/internal/math.ts

@@ -0,0 +1,11 @@
+export const linearScale = ([d0, d1]: [number, number], [r0, r1]: [number, number], clamp = true) => {
+	const slope = d1 === d0 ? 0 : (r1 - r0) / (d1 - d0);
+	const min = Math.min(r0, r1);
+	const max = Math.max(r0, r1);
+
+	return (x: number) => {
+		const value = r0 + slope * (x - d0);
+
+		return clamp ? Math.min(max, Math.max(min, value)) : value;
+	};
+};

package/src/lib/internal/merge-props.ts

@@ -0,0 +1,7 @@
+import { createMergeProps } from 'overrule/props';
+
+export const mergeProps = createMergeProps({
+	styleAs: 'string',
+	dropFalseAttrs: ['hidden', 'disabled'],
+	isEventHandler: (key: string) => key.length > 2 && key.startsWith('on') && key === key.toLowerCase(),
+});