sheer-ui 0.0.0

package/src/lib/internal/date-time/utils.ts

@@ -0,0 +1,243 @@
+import {
+	CalendarDate,
+	CalendarDateTime,
+	type DateValue,
+	Time,
+	ZonedDateTime,
+	getDayOfWeek,
+	getLocalTimeZone,
+	parseDate,
+	parseDateTime,
+	parseZonedDateTime,
+	toCalendar,
+} from '@internationalized/date';
+import type { DateMatcher, Granularity, TimeGranularity, TimeValue } from './types.js';
+
+type GetDefaultDateProps = {
+	defaultValue?: DateValue | DateValue[] | undefined;
+	minValue?: DateValue;
+	maxValue?: DateValue;
+	granularity?: Granularity;
+};
+
+type GetDefaultTimeProps = {
+	defaultValue?: TimeValue | undefined;
+	granularity?: TimeGranularity;
+};
+
+const defaultDateDefaults = {
+	defaultValue: undefined,
+	granularity: 'day',
+};
+
+/**
+ * A helper function used throughout the various date builders
+ * to generate a default `DateValue` using the `defaultValue`,
+ * `defaultPlaceholder`, `minValue`, `maxValue`, and `granularity` props.
+ *
+ * It's important to match the `DateValue` type being used
+ * elsewhere in the builder, so they behave according to the
+ * behavior the user expects based on the props they've provided.
+ *
+ */
+export function getDefaultDate(opts: GetDefaultDateProps): DateValue {
+	const withDefaults = { ...defaultDateDefaults, ...opts };
+	const { defaultValue, granularity, minValue, maxValue } = withDefaults;
+
+	if (Array.isArray(defaultValue) && defaultValue.length) {
+		return defaultValue[defaultValue.length - 1]!;
+	}
+
+	if (defaultValue && !Array.isArray(defaultValue)) {
+		return defaultValue;
+	}
+
+	let date = new Date();
+	if (minValue && date < minValue.toDate(getLocalTimeZone())) {
+		date = minValue.toDate(getLocalTimeZone());
+	} else if (maxValue && date > maxValue.toDate(getLocalTimeZone())) {
+		date = maxValue.toDate(getLocalTimeZone());
+	}
+	const year = date.getFullYear();
+	const month = date.getMonth() + 1;
+	const day = date.getDate();
+	const calendarDateTimeGranularities = ['hour', 'minute', 'second'];
+
+	if (calendarDateTimeGranularities.includes(granularity ?? 'day')) {
+		return new CalendarDateTime(year, month, day, 0, 0, 0);
+	}
+
+	return new CalendarDate(year, month, day);
+}
+
+export const getDefaultTime = ({ defaultValue }: GetDefaultTimeProps): TimeValue => defaultValue ?? new Time(0, 0, 0);
+
+/**
+ * Given a date string and a reference `DateValue` object, parse the
+ * string to the same type as the reference object.
+ *
+ * Useful for parsing strings from data attributes, which are always
+ * strings, to the same type being used by the date component.
+ */
+export function parseStringToDateValue(dateStr: string, referenceVal: DateValue): DateValue {
+	let dateValue: DateValue;
+	if (referenceVal instanceof ZonedDateTime) {
+		dateValue = parseZonedDateTime(dateStr);
+	} else if (referenceVal instanceof CalendarDateTime) {
+		dateValue = parseDateTime(dateStr);
+	} else {
+		dateValue = parseDate(dateStr);
+	}
+
+	// ensure the parsed date is in the same calendar as the reference date set by the user.
+	return dateValue.calendar !== referenceVal.calendar ? toCalendar(dateValue, referenceVal.calendar) : dateValue;
+}
+
+/**
+ * Given a `DateValue` object, convert it to a native `Date` object.
+ * If a timezone is provided, the date will be converted to that timezone.
+ * If no timezone is provided, the date will be converted to the local timezone.
+ */
+export const toDate = (dateValue: DateValue, tz: string = getLocalTimeZone()) =>
+	dateValue instanceof ZonedDateTime ? dateValue.toDate() : dateValue.toDate(tz);
+
+export function getDateValueType(date: DateValue): string {
+	if (date instanceof CalendarDate) return 'date';
+	if (date instanceof CalendarDateTime) return 'datetime';
+	if (date instanceof ZonedDateTime) return 'zoneddatetime';
+	throw new Error('Unknown date type');
+}
+
+export function parseAnyDateValue(value: string, type: string): DateValue {
+	switch (type) {
+		case 'date':
+			return parseDate(value);
+		case 'datetime':
+			return parseDateTime(value);
+		case 'zoneddatetime':
+			return parseZonedDateTime(value);
+		default:
+			throw new Error(`Unknown date type: ${type}`);
+	}
+}
+export const isZonedDateTime = (dateValue: DateValue | TimeValue): dateValue is ZonedDateTime => dateValue instanceof ZonedDateTime;
+
+export const hasTime = (dateValue: DateValue): dateValue is CalendarDateTime | ZonedDateTime =>
+	dateValue instanceof CalendarDateTime || isZonedDateTime(dateValue);
+
+/**
+ * Given a date, return the number of days in the month.
+ */
+export function getDaysInMonth(date: Date | DateValue) {
+	if (date instanceof Date) {
+		const year = date.getFullYear();
+		const month = date.getMonth() + 1;
+		/**
+		 * By using zero as the day, we get the
+		 * last day of the previous month, which
+		 * is the month we originally passed in.
+		 */
+		return new Date(year, month, 0).getDate();
+	}
+	return date.set({ day: 100 }).day;
+}
+
+/**
+ * Determine if a date is before the reference date.
+ * @param dateToCompare - is this date before the `referenceDate`
+ * @param referenceDate - is the `dateToCompare` before this date
+ *
+ * @see {@link isBeforeOrSame} for inclusive
+ */
+export const isBefore = (dateToCompare: DateValue, referenceDate: DateValue) => dateToCompare.compare(referenceDate) < 0;
+
+/**
+ * Determine if a date is after the reference date.
+ * @param dateToCompare - is this date after the `referenceDate`
+ * @param referenceDate - is the `dateToCompare` after this date
+ *
+ * @see {@link isAfterOrSame} for inclusive
+ */
+export const isAfter = (dateToCompare: DateValue, referenceDate: DateValue) => dateToCompare.compare(referenceDate) > 0;
+
+/**
+ * Determine if a date is before or the same as the reference date.
+ *
+ * @param dateToCompare - the date to compare
+ * @param referenceDate - the reference date to make the comparison against
+ *
+ * @see {@link isBefore} for non-inclusive
+ */
+const isBeforeOrSame = (dateToCompare: DateValue, referenceDate: DateValue) => dateToCompare.compare(referenceDate) <= 0;
+
+/**
+ * Determine if a date is after or the same as the reference date.
+ *
+ * @param dateToCompare - is this date after or the same as the `referenceDate`
+ * @param referenceDate - is the `dateToCompare` after or the same as this date
+ *
+ * @see {@link isAfter} for non-inclusive
+ */
+const isAfterOrSame = (dateToCompare: DateValue, referenceDate: DateValue) => dateToCompare.compare(referenceDate) >= 0;
+
+/**
+ * Determine if a date is inclusively between a start and end reference date.
+ *
+ * @param date - is this date inclusively between the `start` and `end` dates
+ * @param start - the start reference date to make the comparison against
+ * @param end - the end reference date to make the comparison against
+ *
+ * @see {@link isBetween} for non-inclusive
+ */
+export const isBetweenInclusive = (date: DateValue, start: DateValue, end: DateValue) =>
+	isAfterOrSame(date, start) && isBeforeOrSame(date, end);
+
+export function getLastFirstDayOfWeek<T extends DateValue = DateValue>(date: T, firstDayOfWeek: number, locale: string): T {
+	const day = getDayOfWeek(date, locale);
+
+	if (firstDayOfWeek > day) {
+		return date.subtract({ days: day + 7 - firstDayOfWeek }) as T;
+	}
+	if (firstDayOfWeek === day) {
+		return date as T;
+	}
+	return date.subtract({ days: day - firstDayOfWeek }) as T;
+}
+
+export function getNextLastDayOfWeek<T extends DateValue = DateValue>(date: T, firstDayOfWeek: number, locale: string): T {
+	const day = getDayOfWeek(date, locale);
+	const lastDayOfWeek = firstDayOfWeek === 0 ? 6 : firstDayOfWeek - 1;
+
+	if (day === lastDayOfWeek) {
+		return date as T;
+	}
+
+	if (day > lastDayOfWeek) {
+		return date.add({ days: 7 - day + lastDayOfWeek }) as T;
+	}
+
+	return date.add({ days: lastDayOfWeek - day }) as T;
+}
+
+export function areAllDaysBetweenValid(
+	start: DateValue,
+	end: DateValue,
+	isUnavailable: DateMatcher | undefined,
+	isDisabled: DateMatcher | undefined,
+) {
+	if (isUnavailable === undefined && isDisabled === undefined) {
+		return true;
+	}
+	let dCurrent = start.add({ days: 1 });
+	if (isDisabled?.(dCurrent) || isUnavailable?.(dCurrent)) {
+		return false;
+	}
+	const dEnd = end;
+	while (dCurrent.compare(dEnd) < 0) {
+		dCurrent = dCurrent.add({ days: 1 });
+		if (isDisabled?.(dCurrent) || isUnavailable?.(dCurrent)) {
+			return false;
+		}
+	}
+	return true;
+}

package/src/lib/internal/dismissible-layer/index.ts

@@ -0,0 +1,3 @@
+export { interactOutsideAttachment } from './use-dismissable-layer.svelte.js';
+
+export type { DismissibleLayerProps } from './types.js';

package/src/lib/internal/dismissible-layer/scheduler.ts

@@ -0,0 +1,48 @@
+/**
+ * The timer seam for the dismissible (interact-outside) layer.
+ *
+ * The layer decides "am I the responsible top layer for this outside pointer event" across a
+ * few timers: a 1ms registration gate, a 10ms interact-outside debounce, and a 20ms reset. That
+ * timing is the fragile part, so — mirroring the `SettleRunner` seam in
+ * `animations-settled.svelte.ts` — the timers are funnelled through this small contract. The default
+ * adapter {@link realTimers} is the real global timers, byte-for-byte the behaviour before the
+ * seam existed; tests inject a manual/fake clock to drive the windows deterministically.
+ */
+
+export type TimerHandle = ReturnType<typeof setTimeout>;
+
+// oxlint-disable-next-line no-explicit-any -- variadic debounce, matches the original signature
+export interface Debounced<T extends (...args: any[]) => any> {
+	(...args: Parameters<T>): void;
+	destroy(): void;
+}
+
+/** The whole timer surface the dismissible layer needs; `debounce` is built on top of it. */
+export interface Timers {
+	setTimeout(fn: () => void, ms: number): TimerHandle;
+	clearTimeout(handle: TimerHandle | undefined): void;
+}
+
+/**
+ * The layer's debounce — the *same* logic it has always used, with the timer pair parameterised,
+ * so the real and fake clocks run identical code and a fake clock just supplies fake time.
+ */
+// oxlint-disable-next-line no-explicit-any -- variadic debounce, matches the original signature
+export function debounce<T extends (...args: any[]) => any>(timers: Timers, fn: T, wait: number): Debounced<T> {
+	let timeout: TimerHandle | undefined;
+
+	const debounced = ((...args: Parameters<T>) => {
+		timers.clearTimeout(timeout);
+		timeout = timers.setTimeout(() => fn(...args), wait);
+	}) as Debounced<T>;
+
+	debounced.destroy = () => timers.clearTimeout(timeout);
+
+	return debounced;
+}
+
+/** Default adapter. Wrapped, not referenced: a detached `window.setTimeout` throws Illegal invocation. */
+export const realTimers: Timers = {
+	setTimeout: (fn, ms) => setTimeout(fn, ms),
+	clearTimeout: (handle) => clearTimeout(handle),
+};

package/src/lib/internal/dismissible-layer/types.ts

@@ -0,0 +1,57 @@
+import type { Snippet } from 'svelte';
+import type { WritableBox } from '../tools/index.js';
+
+export type InteractOutsideEvent = PointerEvent;
+export type InteractOutsideEventHandler = (e: PointerEvent) => void;
+
+export type InteractOutsideBehaviorType = 'close' | 'defer-otherwise-close' | 'defer-otherwise-ignore' | 'ignore';
+
+export type DismissibleLayerProps = {
+	/**
+	 * Callback fired when an outside interaction event completes,
+	 * which is either a `pointerup`, `mouseup`, or `touchend`
+	 * event, depending on the user's input device.
+	 */
+	onInteractOutside?: InteractOutsideEventHandler;
+
+	/**
+	 * Interact outside behavior type.
+	 * `close`: Closes the element immediately.
+	 * `defer-otherwise-close`: Delegates the action to the parent element. If no parent is found, it closes the element.
+	 * `defer-otherwise-ignore`: Delegates the action to the parent element. If no parent is found, nothing is done.
+	 * `ignore`: Prevents the element from closing and also blocks the parent element from closing in response to an outside interaction.
+	 *
+	 * @defaultValue `close`
+	 */
+	interactOutsideBehavior?: InteractOutsideBehaviorType;
+
+	/**
+	 * Callback fired when focus leaves the dismissible layer.
+	 */
+	onFocusOutside?: (event: FocusEvent) => void;
+};
+
+export type DismissibleLayerImplProps = {
+	/**
+	 * Whether the layer is enabled.
+	 */
+	enabled: boolean;
+
+	/**
+	 * ID of the layer.
+	 */
+	id: string;
+
+	/**
+	 * Provide a custom event validator function to determine if the event should be
+	 * considered a dismissal event. This was added to handle the case where a user
+	 * has one context menu open and right clicks on another context menu. We normally ignore
+	 * right clicks for "close" events, but in this case we want to close the context menu when
+	 * another is open.
+	 */
+	isValidEvent?: (e: PointerEvent, node: HTMLElement) => boolean;
+
+	children?: Snippet<[{ props: Record<string, unknown> }]>;
+
+	ref: WritableBox<HTMLElement | null>;
+} & DismissibleLayerProps;

package/src/lib/internal/dismissible-layer/use-dismissable-layer.svelte.ts

@@ -0,0 +1,291 @@
+import {
+	simpleBox,
+	boxWith,
+	attachRef,
+	type Getter,
+	type ReadableBox,
+	type RefAttachment,
+	type WritableBox,
+	mergeHandlers,
+	type ReadableBoxedValues,
+} from '../tools/index.js';
+import { on } from 'svelte/events';
+import { getAbortSignal, onMount, tick } from 'svelte';
+import type { DismissibleLayerImplProps, InteractOutsideBehaviorType, InteractOutsideEventHandler } from './types.js';
+import { type EventCallback } from '../tools/utils/events.js';
+import { createLayerStack } from '../layer-stack.js';
+import { globalSingleton } from '../global-singleton.js';
+import { isElementOrSVGElement } from '../tools/utils/dom.js';
+import { CONTEXT_MENU_CONTENT_ATTR, CONTEXT_MENU_TRIGGER_ATTR } from '../../components/menu/menu.svelte.js';
+import { debounce, realTimers, type Timers, type Debounced } from './scheduler.js';
+
+const isPointerOutsideRect = ({ clientX: x, clientY: y }: PointerEvent, node: HTMLElement) =>
+	(({ left, right, top, bottom }) => x < left || x > right || y < top || y > bottom)(node.getBoundingClientRect());
+
+const dismissableLayers = globalSingleton('bitsDismissableLayers', () =>
+	createLayerStack<DismissibleLayerState, ReadableBox<InteractOutsideBehaviorType>>(
+		(box) => box.current === 'close' || box.current === 'ignore',
+	),
+);
+
+interface DismissibleLayerStateOpts
+	extends ReadableBoxedValues<Required<Pick<DismissibleLayerImplProps, 'enabled' | 'id' | 'interactOutsideBehavior'>>> {
+	ref: WritableBox<HTMLElement | null>;
+	// `onInteractOutside` stays a required key (a layer that notifies nobody is pointless) but may
+	// resolve to undefined; the other two are extras the layer no-ops without.
+	onInteractOutside: ReadableBox<EventCallback<PointerEvent> | undefined>;
+	onFocusOutside?: ReadableBox<((event: FocusEvent) => void) | undefined>;
+	isValidEvent?: ReadableBox<((e: PointerEvent, node: HTMLElement) => boolean) | undefined>;
+	/** Timer seam; defaults to {@link realTimers} (the real global timers). Tests inject a fake clock. */
+	timers?: Timers;
+}
+
+export class DismissibleLayerState {
+	static create(opts: DismissibleLayerStateOpts) {
+		return new DismissibleLayerState(opts);
+	}
+	readonly opts: DismissibleLayerStateOpts;
+	#interactOutsideProp: DismissibleLayerStateOpts['onInteractOutside'];
+	#behaviorType: ReadableBox<InteractOutsideBehaviorType>;
+	#interceptedEvents: Record<string, boolean> = {
+		pointerdown: false,
+	};
+	#isResponsibleLayer = false;
+	#isFocusInsideDOMTree = false;
+	#onFocusOutside: DismissibleLayerStateOpts['onFocusOutside'];
+	#unsubClickListener = () => {};
+	#timers: Timers;
+	#handleInteractOutside: Debounced<(e: PointerEvent) => void>;
+	#resetState: Debounced<() => void>;
+
+	constructor(opts: DismissibleLayerStateOpts) {
+		this.opts = opts;
+		this.#timers = opts.timers ?? realTimers;
+
+		this.#behaviorType = opts.interactOutsideBehavior;
+		this.#interactOutsideProp = opts.onInteractOutside;
+		this.#onFocusOutside = opts.onFocusOutside;
+
+		this.#handleInteractOutside = debounce(this.#timers, (e: PointerEvent) => {
+			if (!this.opts.ref.current) {
+				this.#unsubClickListener();
+				return;
+			}
+			const isEventValid = this.opts.isValidEvent?.current?.(e, this.opts.ref.current) || isValidEvent(e, this.opts.ref.current);
+
+			if (!this.#isResponsibleLayer || this.#isAnyEventIntercepted() || !isEventValid) {
+				this.#unsubClickListener();
+				return;
+			}
+
+			let event = e;
+			if (event.defaultPrevented) {
+				event = createWrappedEvent(event);
+			}
+
+			if (this.#behaviorType.current !== 'close' && this.#behaviorType.current !== 'defer-otherwise-close') {
+				this.#unsubClickListener();
+				return;
+			}
+
+			if (e.pointerType === 'touch') {
+				this.#unsubClickListener();
+
+				const doc = this.opts.ref.current?.ownerDocument ?? document;
+
+				this.#unsubClickListener = on(doc, 'click', this.#handleDismiss, {
+					once: true,
+				});
+			} else {
+				this.#interactOutsideProp.current?.(event);
+			}
+		}, 10);
+
+		this.#resetState = debounce(this.#timers, () => {
+			for (const eventType in this.#interceptedEvents) {
+				this.#interceptedEvents[eventType] = false;
+			}
+			this.#isResponsibleLayer = false;
+		}, 20);
+
+		const cleanup = () => {
+			this.#resetState();
+			dismissableLayers.unregister(this);
+			this.#handleInteractOutside.destroy();
+		};
+
+		$effect(() => {
+			this.opts.enabled.current;
+			this.opts.ref.current;
+			if (!this.opts.enabled.current || !this.opts.ref.current) return;
+			// Minted here, passed into the timeout: a stale timeout firing after this run
+			// was superseded adds listeners against an aborted signal, i.e. not at all.
+			const signal = getAbortSignal();
+			this.#timers.setTimeout(() => {
+				if (!this.opts.ref.current || signal.aborted) return;
+				dismissableLayers.register(this, this.#behaviorType);
+				this.#addEventListeners(signal);
+			}, 1);
+			return cleanup;
+		});
+
+		onMount(() => () => {
+			this.#resetState.destroy();
+			dismissableLayers.unregister(this);
+			this.#handleInteractOutside.destroy();
+			this.#unsubClickListener();
+		});
+	}
+
+	#handleFocus = (event: FocusEvent) => {
+		if (event.defaultPrevented) return;
+		if (!this.opts.ref.current) return;
+		tick().then(() => {
+			if (!this.opts.ref.current || this.#isTargetWithinLayer(event.target as HTMLElement)) return;
+
+			if (event.target && !this.#isFocusInsideDOMTree) {
+				this.#onFocusOutside?.current?.(event);
+			}
+		});
+	};
+
+	#addEventListeners(signal: AbortSignal) {
+		const doc = this.opts.ref.current?.ownerDocument ?? document;
+
+		on(doc, 'pointerdown', mergeHandlers(this.#markInterceptedEvent, this.#markResponsibleLayer), { capture: true, signal });
+		on(doc, 'pointerdown', mergeHandlers(this.#markNonInterceptedEvent, this.#handleInteractOutside), { signal });
+		on(doc, 'focusin', this.#handleFocus, { signal });
+	}
+
+	#handleDismiss = (e: MouseEvent) => {
+		let event = e;
+		if (event.defaultPrevented) {
+			event = createWrappedEvent(e);
+		}
+		this.#interactOutsideProp.current?.(e as PointerEvent);
+	};
+
+	#markInterceptedEvent = (e: PointerEvent) => {
+		this.#interceptedEvents[e.type] = true;
+	};
+
+	#markNonInterceptedEvent = (e: PointerEvent) => {
+		this.#interceptedEvents[e.type] = false;
+	};
+
+	#markResponsibleLayer = () => {
+		if (!this.opts.ref.current) return;
+		this.#isResponsibleLayer = dismissableLayers.isResponsible(this);
+	};
+	#isTargetWithinLayer = (target: HTMLElement) => {
+		return this.opts.ref.current?.contains(target) ?? false;
+	};
+
+	#isAnyEventIntercepted() {
+		const i = Object.values(this.#interceptedEvents).some(Boolean);
+		return i;
+	}
+
+	#onfocuscapture = () => {
+		this.#isFocusInsideDOMTree = true;
+	};
+
+	#onblurcapture = () => {
+		this.#isFocusInsideDOMTree = false;
+	};
+
+	props = {
+		onfocuscapture: this.#onfocuscapture,
+		onblurcapture: this.#onblurcapture,
+	};
+}
+
+/**
+ * The dismissible (interact-outside) behavior, without the renderless `<DismissibleLayer>` wrapper.
+ * Returns the focus-capture props (`onfocuscapture`/`onblurcapture`) and a node-lifecycle attachment
+ * separately, because the wrapper's two consumers differ: most overlays merge BOTH onto the content
+ * element, but dialog/sheet/alert-dialog historically merged only the activation (their default-slot
+ * usage dropped the capture props) — so callers keep that choice by merging `props` or not.
+ *
+ * Must be called during component init (the state uses `onMount`). The global `bitsDismissableLayers`
+ * stack (a shared `LayerStack`, see `internal/layer-stack.ts`) and the listeners are unchanged; the
+ * attachment just owns the node (registers on mount, deregisters on removal).
+ */
+export function interactOutsideAttachment(opts: {
+	id: Getter<string>;
+	interactOutsideBehavior: Getter<InteractOutsideBehaviorType>;
+	onInteractOutside: Getter<InteractOutsideEventHandler | undefined>;
+	onFocusOutside?: Getter<((event: FocusEvent) => void) | undefined>;
+	enabled: Getter<boolean>;
+	isValidEvent?: Getter<((e: PointerEvent, node: HTMLElement) => boolean) | undefined>;
+}): { props: { onfocuscapture: () => void; onblurcapture: () => void }; attachment: RefAttachment<HTMLElement> } {
+	const ref = simpleBox<HTMLElement | null>(null);
+	const state = DismissibleLayerState.create({
+		id: boxWith(opts.id),
+		interactOutsideBehavior: boxWith(opts.interactOutsideBehavior),
+		onInteractOutside: boxWith(opts.onInteractOutside),
+		enabled: boxWith(opts.enabled),
+		onFocusOutside: boxWith(() => opts.onFocusOutside?.()),
+		isValidEvent: boxWith(() => opts.isValidEvent?.()),
+		ref,
+	});
+	return { props: state.props, attachment: attachRef(ref) };
+}
+
+function isValidEvent(e: PointerEvent, node: HTMLElement): boolean {
+	const target = e.target;
+	if (!isElementOrSVGElement(target)) return false;
+
+	const targetIsContextMenuTrigger = Boolean(target.closest(`[${CONTEXT_MENU_TRIGGER_ATTR}]`));
+
+	// A context menu re-triggering over its own content: only the primary button counts.
+	if (targetIsContextMenuTrigger && node.closest(`[${CONTEXT_MENU_CONTENT_ATTR}]`)) return e.button === 0;
+	// Secondary buttons never dismiss, unless they landed on a context-menu trigger.
+	if (e.button > 0 && !targetIsContextMenuTrigger) return false;
+
+	return target.ownerDocument.documentElement.contains(target) && !node.contains(target) && isPointerOutsideRect(e, node);
+}
+
+export type FocusOutsideEvent = CustomEvent<{ originalEvent: FocusEvent }>;
+
+function createWrappedEvent(e: PointerEvent | MouseEvent): PointerEvent {
+	const capturedCurrentTarget = e.currentTarget;
+	const capturedTarget = e.target;
+
+	// A `click` is already a PointerEvent in modern browsers; a synthetic MouseEvent replays as pointerdown.
+	const newEvent = new PointerEvent(e instanceof PointerEvent ? e.type : 'pointerdown', e);
+
+	// track the prevented state separately
+	let isPrevented = false;
+
+	// Create a proxy to intercept property access and method calls
+	const wrappedEvent = new Proxy(newEvent, {
+		get: (target, prop) => {
+			if (prop === 'currentTarget') {
+				return capturedCurrentTarget;
+			}
+			if (prop === 'target') {
+				return capturedTarget;
+			}
+			if (prop === 'preventDefault') {
+				return () => {
+					isPrevented = true;
+					if (typeof target.preventDefault === 'function') {
+						target.preventDefault();
+					}
+				};
+			}
+			if (prop === 'defaultPrevented') {
+				return isPrevented;
+			}
+			if (prop in target) {
+				// oxlint-disable-next-line no-explicit-any
+				return (target as any)[prop];
+			}
+			// oxlint-disable-next-line no-explicit-any
+			return (e as any)[prop];
+		},
+	});
+
+	return wrappedEvent as PointerEvent;
+}

package/src/lib/internal/escape-layer/index.ts

@@ -0,0 +1,3 @@
+export { escapeKeydownAttachment } from './use-escape-layer.svelte.js';
+
+export type { EscapeLayerProps } from './types.js';

package/src/lib/internal/escape-layer/types.ts

@@ -0,0 +1,34 @@
+import type { Snippet } from 'svelte';
+import type { Box } from '../tools/index.js';
+
+export type EscapeBehaviorType = 'close' | 'defer-otherwise-close' | 'defer-otherwise-ignore' | 'ignore';
+
+export type EscapeLayerProps = {
+	/**
+	 * Callback fired when escape is pressed.
+	 */
+	onEscapeKeydown?: (e: KeyboardEvent) => void;
+
+	/**
+	 * Escape behavior type.
+	 * `close`: Closes the element immediately.
+	 * `defer-otherwise-close`: Delegates the action to its parent component that has an
+	 * escape keydown handler. If no parent is found, it closes the element.
+	 * `defer-otherwise-ignore`: Delegates the action to the parent element. If no parent is found, nothing is done.
+	 * `ignore`: Prevents the element from closing and also blocks the parent element from closing in response to an escape key press.
+	 *
+	 * @defaultValue `close`
+	 */
+	escapeKeydownBehavior?: EscapeBehaviorType;
+};
+
+// internal props not exposed to the user but used in the implementation
+export type EscapeLayerImplProps = {
+	/**
+	 * Whether the layer is enabled. Currently, we determine this with the
+	 * `presence` returned from the `presence` layer.
+	 */
+	enabled: boolean;
+	children?: Snippet;
+	ref: Box<HTMLElement | null>;
+} & EscapeLayerProps;