svelte-ag 0.0.2-dev.72

package/src/lib/bits/internal/events.ts

@@ -0,0 +1,89 @@
+import { on } from "svelte/events";
+import type { Arrayable } from "$lib/internal/types.js";
+
+export type EventCallback<E extends Event = Event> = (event: E) => void;
+
+type GeneralEventListener<E = Event> = (evt: E) => unknown;
+
+export function addEventListener<E extends keyof WindowEventMap>(
+	target: Window,
+	event: Arrayable<E>,
+	handler: (this: Window, ev: WindowEventMap[E]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): VoidFunction;
+
+export function addEventListener<E extends keyof DocumentEventMap>(
+	target: Document,
+	event: Arrayable<E>,
+	handler: (this: Document, ev: DocumentEventMap[E]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): VoidFunction;
+
+export function addEventListener<E extends keyof HTMLElementEventMap>(
+	target: EventTarget,
+	event: Arrayable<E>,
+	handler: GeneralEventListener<HTMLElementEventMap[E]>,
+	options?: boolean | AddEventListenerOptions
+): VoidFunction;
+/**
+ * Adds an event listener to the specified target element(s) for the given event(s), and returns a function to remove it.
+ * @param target The target element(s) to add the event listener to.
+ * @param event The event(s) to listen for.
+ * @param handler The function to be called when the event is triggered.
+ * @param options An optional object that specifies characteristics about the event listener.
+ * @returns A function that removes the event listener from the target element(s).
+ */
+export function addEventListener(
+	target: Window | Document | EventTarget,
+	event: Arrayable<string>,
+	handler: EventListenerOrEventListenerObject,
+	options?: boolean | AddEventListenerOptions
+) {
+	const events = Array.isArray(event) ? event : [event];
+
+	// Add the event listener to each specified event for the target element(s).
+	events.forEach((_event) => target.addEventListener(_event, handler, options));
+
+	// Return a function that removes the event listener from the target element(s).
+	return () => {
+		events.forEach((_event) => target.removeEventListener(_event, handler, options));
+	};
+}
+
+/**
+ * Creates a typed event dispatcher and listener pair for custom events
+ * @template T - The type of data that will be passed in the event detail
+ * @param eventName - The name of the custom event
+ * @param options - CustomEvent options (bubbles, cancelable, etc.)
+ */
+export class CustomEventDispatcher<T = unknown> {
+	constructor(
+		readonly eventName: string,
+		readonly options: Omit<CustomEventInit<T>, "detail"> = { bubbles: true, cancelable: true }
+	) {}
+
+	createEvent(detail?: T): CustomEvent<T> {
+		return new CustomEvent<T>(this.eventName, {
+			...this.options,
+			detail,
+		});
+	}
+
+	dispatch(element: EventTarget, detail?: T): CustomEvent<T> {
+		const event = this.createEvent(detail);
+		element.dispatchEvent(event);
+		return event;
+	}
+
+	listen(
+		element: EventTarget,
+		callback: (event: CustomEvent<T>) => void,
+		options?: AddEventListenerOptions
+	) {
+		const handler = (event: Event) => {
+			callback(event as CustomEvent<T>);
+		};
+
+		return on(element, this.eventName, handler, options);
+	}
+}

package/src/lib/bits/internal/floating-svelte/floating-utils.svelte.ts

@@ -0,0 +1,28 @@
+import type { Getter, MaybeGetter } from "svelte-toolbelt";
+
+export function get<T>(valueOrGetValue: MaybeGetter<T>): T {
+	return typeof valueOrGetValue === "function"
+		? (valueOrGetValue as Getter<T>)()
+		: valueOrGetValue;
+}
+
+export function getDPR(element: Element): number {
+	if (typeof window === "undefined") return 1;
+	const win = element.ownerDocument.defaultView || window;
+	return win.devicePixelRatio || 1;
+}
+
+export function roundByDPR(element: Element, value: number) {
+	const dpr = getDPR(element);
+	return Math.round(value * dpr) / dpr;
+}
+
+export function getFloatingContentCSSVars(name: string) {
+	return {
+		[`--bits-${name}-content-transform-origin`]: `var(--bits-floating-transform-origin)`,
+		[`--bits-${name}-content-available-width`]: `var(--bits-floating-available-width)`,
+		[`--bits-${name}-content-available-height`]: `var(--bits-floating-available-height)`,
+		[`--bits-${name}-anchor-width`]: `var(--bits-floating-anchor-width)`,
+		[`--bits-${name}-anchor-height`]: `var(--bits-floating-anchor-height)`,
+	};
+}

package/src/lib/bits/internal/floating-svelte/types.ts

@@ -0,0 +1,108 @@
+import type {
+	FloatingElement,
+	Middleware,
+	MiddlewareData,
+	Placement,
+	ReferenceElement,
+	Strategy,
+} from "@floating-ui/dom";
+import type { ReadableBox, WritableBox } from "svelte-toolbelt";
+
+type ValueOrGetValue<T> = T | (() => T);
+
+export type Measurable = {
+	getBoundingClientRect: () => DOMRect;
+};
+
+export type UseFloatingOptions = {
+	/**
+	 * Represents the open/close state of the floating element.
+	 * @default true
+	 */
+	open?: ValueOrGetValue<boolean | undefined>;
+	/**
+	 * Where to place the floating element relative to its reference element.
+	 * @default 'bottom'
+	 */
+	placement?: ValueOrGetValue<Placement | undefined>;
+	/**
+	 * The type of CSS position property to use.
+	 * @default 'absolute'
+	 */
+	strategy?: ValueOrGetValue<Strategy | undefined>;
+	/**
+	 * These are plain objects that modify the positioning coordinates in some fashion,
+	 * or provide useful data for the consumer to use.
+	 * @default undefined
+	 */
+	middleware?: ValueOrGetValue<Middleware[] | undefined>;
+	/**
+	 * Whether to use `transform` instead of `top` and `left` styles to
+	 * position the floating element (`floatingStyles`).
+	 * @default true
+	 */
+	transform?: ValueOrGetValue<boolean | undefined>;
+
+	/**
+	 * Reference / Anchor element to position the floating element relative to
+	 */
+	reference: ReadableBox<Measurable | HTMLElement | null>;
+
+	/**
+	 * Callback to handle mounting/unmounting of the elements.
+	 * @default undefined
+	 */
+	whileElementsMounted?: (
+		reference: ReferenceElement,
+		floating: FloatingElement,
+		update: () => void
+	) => () => void;
+};
+
+export type UseFloatingReturn = {
+	/**
+	 * The reference element to position the floating element relative to.
+	 */
+	reference: ReadableBox<Measurable | HTMLElement | null>;
+
+	/**
+	 * The floating element to position.
+	 */
+	floating: WritableBox<HTMLElement | null>;
+
+	/**
+	 * The stateful placement, which can be different from the initial `placement` passed as options.
+	 */
+	placement: Readonly<Placement>;
+
+	/**
+	 * The type of CSS position property to use.
+	 */
+	strategy: Readonly<Strategy>;
+
+	/**
+	 * Additional data from middleware.
+	 */
+	middlewareData: Readonly<MiddlewareData>;
+
+	/**
+	 * The boolean that let you know if the floating element has been positioned.
+	 */
+	isPositioned: Readonly<boolean>;
+
+	/**
+	 * CSS styles to apply to the floating element to position it.
+	 */
+	floatingStyles: Readonly<{
+		position: Strategy;
+		top: string;
+		left: string;
+		transform?: string;
+		willChange?: string;
+	}>;
+
+	/**
+	 * The function to update floating position manually.
+	 */
+	update: () => void;
+};

package/src/lib/bits/internal/floating-svelte/use-floating.svelte.ts

@@ -0,0 +1,133 @@
+import { computePosition } from "@floating-ui/dom";
+import { box } from "svelte-toolbelt";
+import type { UseFloatingOptions, UseFloatingReturn } from "./types.js";
+import { get, getDPR, roundByDPR } from "./floating-utils.svelte.js";
+
+export function useFloating(options: UseFloatingOptions): UseFloatingReturn {
+	/** Options */
+	const whileElementsMountedOption = options.whileElementsMounted;
+	const openOption = $derived(get(options.open) ?? true);
+	const middlewareOption = $derived(get(options.middleware));
+	const transformOption = $derived(get(options.transform) ?? true);
+	const placementOption = $derived(get(options.placement) ?? "bottom");
+	const strategyOption = $derived(get(options.strategy) ?? "absolute");
+	const reference = options.reference;
+
+	/** State */
+	let x = $state(0);
+	let y = $state(0);
+
+	const floating = box<HTMLElement | null>(null);
+
+	let strategy = $state(strategyOption);
+	let placement = $state(placementOption);
+	let middlewareData = $state({});
+	let isPositioned = $state(false);
+	const floatingStyles = $derived.by(() => {
+		const initialStyles = {
+			position: strategy,
+			left: "0",
+			top: "0",
+		};
+
+		if (!floating.current) {
+			return initialStyles;
+		}
+
+		const xVal = roundByDPR(floating.current, x);
+		const yVal = roundByDPR(floating.current, y);
+
+		if (transformOption) {
+			return {
+				...initialStyles,
+				transform: `translate(${xVal}px, ${yVal}px)`,
+				...(getDPR(floating.current) >= 1.5 && {
+					willChange: "transform",
+				}),
+			};
+		}
+
+		return {
+			position: strategy,
+			left: `${xVal}px`,
+			top: `${yVal}px`,
+		};
+	});
+
+	/** Effects */
+	let whileElementsMountedCleanup: (() => void) | undefined;
+
+	function update() {
+		if (reference.current === null || floating.current === null) return;
+		computePosition(reference.current, floating.current, {
+			middleware: middlewareOption,
+			placement: placementOption,
+			strategy: strategyOption,
+		}).then((position) => {
+			x = position.x;
+			y = position.y;
+			strategy = position.strategy;
+			placement = position.placement;
+			middlewareData = position.middlewareData;
+			isPositioned = true;
+		});
+	}
+
+	function cleanup() {
+		if (typeof whileElementsMountedCleanup === "function") {
+			whileElementsMountedCleanup();
+			whileElementsMountedCleanup = undefined;
+		}
+	}
+
+	function attach() {
+		cleanup();
+
+		if (whileElementsMountedOption === undefined) {
+			update();
+			return;
+		}
+
+		if (reference.current === null || floating.current === null) return;
+
+		whileElementsMountedCleanup = whileElementsMountedOption(
+			reference.current,
+			floating.current,
+			update
+		);
+	}
+
+	function reset() {
+		if (!openOption) {
+			isPositioned = false;
+		}
+	}
+
+	$effect(update);
+	$effect(attach);
+	$effect(reset);
+	$effect(() => cleanup);
+
+	return {
+		floating,
+		reference,
+		get strategy() {
+			return strategy;
+		},
+		get placement() {
+			return placement;
+		},
+		get middlewareData() {
+			return middlewareData;
+		},
+		get isPositioned() {
+			return isPositioned;
+		},
+		get floatingStyles() {
+			return floatingStyles;
+		},
+		get update() {
+			return update;
+		},
+	};
+}

package/src/lib/bits/internal/focus.ts

@@ -0,0 +1,111 @@
+import { isBrowser, isElementHidden, isSelectableInput } from "./is.js";
+
+export type FocusableTarget = HTMLElement | { focus: () => void };
+
+/**
+ * Handles `initialFocus` prop behavior for the
+ * Calendar & RangeCalendar components.
+ */
+export function handleCalendarInitialFocus(calendar: HTMLElement) {
+	if (!isBrowser) return;
+	const selectedDay = calendar.querySelector<HTMLElement>("[data-selected]");
+	if (selectedDay) return focusWithoutScroll(selectedDay);
+
+	const today = calendar.querySelector<HTMLElement>("[data-today]");
+	if (today) return focusWithoutScroll(today);
+
+	const firstDay = calendar.querySelector<HTMLElement>("[data-calendar-date]");
+	if (firstDay) return focusWithoutScroll(firstDay);
+}
+
+/**
+ * A utility function that focuses an element without scrolling.
+ */
+export function focusWithoutScroll(element: HTMLElement) {
+	const scrollPosition = {
+		x: window.pageXOffset || document.documentElement.scrollLeft,
+		y: window.pageYOffset || document.documentElement.scrollTop,
+	};
+	element.focus();
+	window.scrollTo(scrollPosition.x, scrollPosition.y);
+}
+
+/**
+ * A utility function that focuses an element.
+ */
+export function focus(element?: FocusableTarget | null, { select = false } = {}) {
+	if (!(element && element.focus)) return;
+	if (document.activeElement === element) return;
+	const previouslyFocusedElement = document.activeElement;
+	// prevent scroll on focus
+	element.focus({ preventScroll: true });
+	// only elect if its not the same element, it supports selection, and we need to select it
+	if (element !== previouslyFocusedElement && isSelectableInput(element) && select) {
+		element.select();
+	}
+}
+
+/**
+ * Attempts to focus the first element in a list of candidates.
+ * Stops when focus is successful.
+ */
+export function focusFirst(candidates: HTMLElement[], { select = false } = {}) {
+	const previouslyFocusedElement = document.activeElement;
+	for (const candidate of candidates) {
+		focus(candidate, { select });
+		if (document.activeElement !== previouslyFocusedElement) {
+			return true;
+		}
+	}
+}
+
+/**
+ * Returns the first visible element in a list.
+ * NOTE: Only checks visibility up to the `container`.
+ */
+export function findVisible(elements: HTMLElement[], container: HTMLElement) {
+	for (const element of elements) {
+		// we stop checking if it's hidden at the `container` level (excluding)
+		if (!isElementHidden(element, container)) return element;
+	}
+}
+
+/**
+ * Returns a list of potential tabbable candidates.
+ *
+ * NOTE: This is only a close approximation. For example it doesn't take into account cases like when
+ * elements are not visible. This cannot be worked out easily by just reading a property, but rather
+ * necessitate runtime knowledge (computed styles, etc). We deal with these cases separately.
+ *
+ * See: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker
+ * Credit: https://github.com/discord/focus-layers/blob/master/src/util/wrapFocus.tsx#L1
+ */
+export function getTabbableCandidates(container: HTMLElement) {
+	const nodes: HTMLElement[] = [];
+	const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		acceptNode: (node: any) => {
+			const isHiddenInput = node.tagName === "INPUT" && node.type === "hidden";
+			if (node.disabled || node.hidden || isHiddenInput) return NodeFilter.FILTER_SKIP;
+			// `.tabIndex` is not the same as the `tabindex` attribute. It works on the
+			// runtime's understanding of tabbability, so this automatically accounts
+			// for any kind of element that could be tabbed to.
+			return node.tabIndex >= 0 ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+		},
+	});
+	while (walker.nextNode()) nodes.push(walker.currentNode as HTMLElement);
+	// we do not take into account the order of nodes with positive `tabIndex` as it
+	// hinders accessibility to have tab order different from visual order.
+	return nodes;
+}
+
+/**
+ * A utility function that returns the first and last elements within a container that are
+ * visible and focusable.
+ */
+export function getTabbableEdges(container: HTMLElement) {
+	const candidates = getTabbableCandidates(container);
+	const first = findVisible(candidates, container);
+	const last = findVisible(candidates.reverse(), container);
+	return [first, last] as const;
+}

package/src/lib/bits/internal/get-directional-keys.test.ts

@@ -0,0 +1,51 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, expect, it } from "vitest";
+import { getDirectionalKeys } from "./get-directional-keys.js";
+import { kbd } from "./kbd.js";
+
+describe("getDirectionalKeys", () => {
+	it("should return correct keys for default direction and orientation", () => {
+		const result = getDirectionalKeys();
+		expect(result).toEqual({
+			nextKey: kbd.ARROW_RIGHT,
+			prevKey: kbd.ARROW_LEFT,
+		});
+	});
+
+	it("should return correct keys for rtl direction and horizontal orientation", () => {
+		const result = getDirectionalKeys("rtl", "horizontal");
+		expect(result).toEqual({
+			nextKey: kbd.ARROW_LEFT,
+			prevKey: kbd.ARROW_RIGHT,
+		});
+	});
+
+	it("should return correct keys for ltr direction and vertical orientation", () => {
+		const result = getDirectionalKeys("ltr", "vertical");
+		expect(result).toEqual({
+			nextKey: kbd.ARROW_DOWN,
+			prevKey: kbd.ARROW_UP,
+		});
+	});
+
+	it("should return correct keys for rtl direction and vertical orientation", () => {
+		const result = getDirectionalKeys("rtl", "vertical");
+		expect(result).toEqual({
+			nextKey: kbd.ARROW_DOWN,
+			prevKey: kbd.ARROW_UP,
+		});
+	});
+
+	it("should handle invalid direction and orientation values", () => {
+		const result1 = getDirectionalKeys("invalid" as any, "horizontal");
+		const result2 = getDirectionalKeys("ltr", "invalid" as any);
+		expect(result1).toEqual({
+			nextKey: kbd.ARROW_RIGHT,
+			prevKey: kbd.ARROW_LEFT,
+		});
+		expect(result2).toEqual({
+			nextKey: kbd.ARROW_RIGHT,
+			prevKey: kbd.ARROW_LEFT,
+		});
+	});
+});

package/src/lib/bits/internal/get-directional-keys.ts

@@ -0,0 +1,43 @@
+import { kbd } from "./kbd.js";
+import type { Direction, Orientation } from "$lib/shared/index.js";
+
+export const FIRST_KEYS = [kbd.ARROW_DOWN, kbd.PAGE_UP, kbd.HOME];
+export const LAST_KEYS = [kbd.ARROW_UP, kbd.PAGE_DOWN, kbd.END];
+export const FIRST_LAST_KEYS = [...FIRST_KEYS, ...LAST_KEYS];
+export const SELECTION_KEYS = [kbd.SPACE, kbd.ENTER];
+
+/**
+ * A utility function that returns the next key based on the direction and orientation.
+ */
+export function getNextKey(dir: Direction = "ltr", orientation: Orientation = "horizontal") {
+	return {
+		horizontal: dir === "rtl" ? kbd.ARROW_LEFT : kbd.ARROW_RIGHT,
+		vertical: kbd.ARROW_DOWN,
+	}[orientation];
+}
+
+/**
+ * A utility function that returns the previous key based on the direction and orientation.
+ */
+export function getPrevKey(dir: Direction = "ltr", orientation: Orientation = "horizontal") {
+	return {
+		horizontal: dir === "rtl" ? kbd.ARROW_RIGHT : kbd.ARROW_LEFT,
+		vertical: kbd.ARROW_UP,
+	}[orientation];
+}
+
+/**
+ * A utility function that returns the next and previous keys based on the direction
+ * and orientation.
+ */
+export function getDirectionalKeys(
+	dir: Direction = "ltr",
+	orientation: Orientation = "horizontal"
+) {
+	if (!["ltr", "rtl"].includes(dir)) dir = "ltr";
+	if (!["horizontal", "vertical"].includes(orientation)) orientation = "horizontal";
+	return {
+		nextKey: getNextKey(dir, orientation),
+		prevKey: getPrevKey(dir, orientation),
+	};
+}

package/src/lib/bits/internal/is.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { isNumberString } from "./is.js";
+
+describe("isNumberString", () => {
+	it("should return true for valid number strings", () => {
+		expect(isNumberString("123")).toBe(true);
+		expect(isNumberString("0")).toBe(true);
+		expect(isNumberString("-42")).toBe(true);
+		expect(isNumberString("3.14")).toBe(true);
+	});
+
+	it("should return false for strings that are not valid numbers", () => {
+		expect(isNumberString("abc")).toBe(false);
+		expect(isNumberString("1a2b3c")).toBe(false);
+		expect(isNumberString("number")).toBe(false);
+		expect(isNumberString("--123")).toBe(false);
+	});
+
+	it("should return false for empty string", () => {
+		expect(isNumberString("")).toBe(false);
+	});
+
+	it("should return true for strings with leading or trailing whitespace", () => {
+		expect(isNumberString("  123")).toBe(true);
+		expect(isNumberString("456  ")).toBe(true);
+		expect(isNumberString(" 789 ")).toBe(true);
+	});
+
+	it("should return false for strings with non-numeric characters and whitespace", () => {
+		expect(isNumberString("  abc123")).toBe(false);
+		expect(isNumberString("123def  ")).toBe(false);
+		expect(isNumberString(" 456 xyz ")).toBe(false);
+	});
+
+	it("should return true for strings with exponential notation", () => {
+		expect(isNumberString("1e3")).toBe(true);
+		expect(isNumberString("2.5e-4")).toBe(true);
+		expect(isNumberString("-3.2E+5")).toBe(true);
+	});
+});

package/src/lib/bits/internal/is.ts

@@ -0,0 +1,78 @@
+import type { FocusableTarget } from "./focus.js";
+
+export const isBrowser = typeof document !== "undefined";
+
+export const isIOS = getIsIOS();
+
+function getIsIOS() {
+	return (
+		isBrowser &&
+		window?.navigator?.userAgent &&
+		(/iP(ad|hone|od)/.test(window.navigator.userAgent) ||
+			// The new iPad Pro Gen3 does not identify itself as iPad, but as Macintosh.
+			(window?.navigator?.maxTouchPoints > 2 &&
+				/iPad|Macintosh/.test(window?.navigator.userAgent)))
+	);
+}
+
+export function isFunction(value: unknown): value is (...args: unknown[]) => unknown {
+	return typeof value === "function";
+}
+
+export function isHTMLElement(element: unknown): element is HTMLElement {
+	return element instanceof HTMLElement;
+}
+
+export function isElement(element: unknown): element is Element {
+	return element instanceof Element;
+}
+
+export function isElementOrSVGElement(element: unknown): element is Element | SVGElement {
+	return element instanceof Element || element instanceof SVGElement;
+}
+
+export function isNumberString(value: string) {
+	return !Number.isNaN(Number(value)) && !Number.isNaN(Number.parseFloat(value));
+}
+
+export function isNull(value: unknown): value is null {
+	return value === null;
+}
+
+export function isTouch(e: PointerEvent) {
+	return e.pointerType === "touch";
+}
+
+export function isFocusVisible(element: Element) {
+	return element.matches(":focus-visible");
+}
+
+export function isNotNull<T>(value: T | null): value is T {
+	return value !== null;
+}
+
+/**
+ * Determines if the provided object is a valid `HTMLInputElement` with
+ * a `select` method available.
+ */
+export function isSelectableInput(
+	element: unknown
+): element is FocusableTarget & { select: () => void } {
+	return element instanceof HTMLInputElement && "select" in element;
+}
+
+/**
+ * Given a node, determine if it is hidden by walking up the
+ * DOM tree until we hit the `stopAt` node (exclusive), if provided)
+ * otherwise we stop at the document root.
+ */
+export function isElementHidden(node: HTMLElement, stopAt?: HTMLElement) {
+	if (getComputedStyle(node).visibility === "hidden") return true;
+	while (node) {
+		// we stop at `upTo` (excluding it)
+		if (stopAt !== undefined && node === stopAt) return false;
+		if (getComputedStyle(node).display === "none") return true;
+		node = node.parentElement as HTMLElement;
+	}
+	return false;
+}