sheer-ui 0.0.0

package/src/lib/internal/arrays.ts

@@ -0,0 +1,253 @@
+/**
+ * Checks if two arrays are equal by comparing their values.
+ */
+export const arraysAreEqual = <T extends Array<unknown>>(arr1: T, arr2: T): boolean =>
+	arr1.length === arr2.length && arr1.every((value, index) => isEqual(value, arr2[index]));
+
+/**
+ * A utility function that compares two values for equality.
+ */
+function isEqual(a: unknown, b: unknown): boolean {
+	if (Number.isNaN(a as number) && Number.isNaN(b as number)) return true;
+
+	if (Array.isArray(a) && Array.isArray(b)) return arraysAreEqual(a as unknown[], b as unknown[]);
+
+	if (typeof a === 'object' && typeof b === 'object') return isDeepEqual(a, b);
+
+	return Object.is(a, b);
+}
+
+/**
+ * A utility function that compares two values for deep equality.
+ */
+function isDeepEqual(a: unknown, b: unknown): boolean {
+	if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+
+	if (aKeys.length !== bKeys.length) return false;
+
+	for (const key of aKeys) {
+		if (!bKeys.includes(key)) return false;
+		if (!isEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Splits an array into chunks of a given size.
+ * @param arr The array to split.
+ * @param size The size of each chunk.
+ * @returns An array of arrays, where each sub-array has `size` elements from the original array.
+ * @example ```ts
+ * const arr = [1, 2, 3, 4, 5, 6, 7, 8];
+ * const chunks = chunk(arr, 3);
+ * // chunks = [[1, 2, 3], [4, 5, 6], [7, 8]]
+ * ```
+ */
+export function chunk<T>(arr: T[], size: number): T[][] {
+	if (size <= 0) return [];
+
+	const result = [];
+	for (let i = 0; i < arr.length; i += size) {
+		result.push(arr.slice(i, i + size));
+	}
+	return result;
+}
+
+/**
+ * Checks if the given index is valid for the given array.
+ *
+ * @param index - The index to check
+ * @param arr - The array to check
+ */
+
+export const isValidIndex = (index: number, arr: unknown[]) => index >= 0 && index < arr.length;
+
+/**
+ * Returns the array element after the given index, or undefined for out-of-bounds or empty arrays.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param loop loop to the beginning of the array if the next index is out of bounds?
+ */
+/**
+ * Returns the array element after the given index, or undefined for out-of-bounds or empty arrays.
+ * For single-element arrays, returns the element if the index is 0.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param loop loop to the beginning of the array if the next index is out of bounds?
+ */
+export function next<T>(array: T[], index: number, loop = true): T | undefined {
+	if (array.length === 0 || index < 0 || index >= array.length) return;
+	if (array.length === 1 && index === 0) return array[0];
+	if (index === array.length - 1) return loop ? array[0] : undefined;
+	return array[index + 1];
+}
+
+/**
+ * Returns the array element prior to the given index, or undefined for out-of-bounds or empty arrays.
+ * For single-element arrays, returns the element if the index is 0.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param loop loop to the end of the array if the previous index is out of bounds?
+ */
+export function prev<T>(array: T[], index: number, loop = true): T | undefined {
+	if (array.length === 0 || index < 0 || index >= array.length) return;
+	if (array.length === 1 && index === 0) return array[0];
+	if (index === 0) return loop ? array[array.length - 1] : undefined;
+	return array[index - 1];
+}
+
+/**
+ * Returns the element some number after the given index. If the target index is out of bounds:
+ *   - If looping is disabled, the first or last element will be returned.
+ *   - If looping is enabled, it will wrap around the array.
+ * Returns undefined for empty arrays or out-of-bounds initial indices.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param increment the number of elements to move forward (can be negative).
+ * @param loop loop around the array if the target index is out of bounds?
+ */
+export function forward<T>(array: T[], index: number, increment: number, loop = true): T | undefined {
+	if (array.length === 0 || index < 0 || index >= array.length) return;
+
+	let targetIndex = index + increment;
+
+	if (loop) {
+		// Ensure positive modulus
+		targetIndex = ((targetIndex % array.length) + array.length) % array.length;
+	} else {
+		// Clamp to array bounds when not looping
+		targetIndex = Math.max(0, Math.min(targetIndex, array.length - 1));
+	}
+
+	return array[targetIndex];
+}
+
+/**
+ * Returns the element some number before the given index. If the target index is out of bounds:
+ *   - If looping is disabled, the first or last element will be returned.
+ *   - If looping is enabled, it will wrap around the array.
+ * Returns undefined for empty arrays or out-of-bounds initial indices.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param decrement the number of elements to move backward (can be negative).
+ * @param loop loop around the array if the target index is out of bounds?
+ */
+export function backward<T>(array: T[], index: number, decrement: number, loop = true): T | undefined {
+	if (array.length === 0 || index < 0 || index >= array.length) return;
+
+	let targetIndex = index - decrement;
+
+	if (loop) {
+		// Ensure positive modulus
+		targetIndex = ((targetIndex % array.length) + array.length) % array.length;
+	} else {
+		// Clamp to array bounds when not looping
+		targetIndex = Math.max(0, Math.min(targetIndex, array.length - 1));
+	}
+
+	return array[targetIndex];
+}
+
+/**
+ * Finds the next matching item from a list of values based on a search string.
+ *
+ * This function handles several special cases in typeahead behavior:
+ *
+ * 1. Space handling: When a search string ends with a space, it handles it specially:
+ *    - If there's only one match for the text before the space, it ignores the space
+ *    - If there are multiple matches and the current match already starts with the search prefix
+ *      followed by a space, it keeps the current match (doesn't change selection on space)
+ *    - Only after typing characters beyond the space will it move to a more specific match
+ *
+ * 2. Repeated character handling: If a search consists of repeated characters (e.g., "aaa"),
+ *    it treats it as a single character for matching purposes
+ *
+ * 3. Cycling behavior: The function wraps around the values array starting from the current match
+ *    to find the next appropriate match, creating a cycling selection behavior
+ *
+ * @param values - Array of string values to search through (e.g., the text content of menu items)
+ * @param search - The current search string typed by the user
+ * @param currentMatch - The currently selected/matched item, if any
+ * @returns The next matching value that should be selected, or undefined if no match is found
+ */
+export function getNextMatch(values: string[], search: string, currentMatch?: string) {
+	const lowerSearch = search.toLowerCase();
+
+	if (lowerSearch.endsWith(' ')) {
+		const searchWithoutSpace = lowerSearch.slice(0, -1);
+		const matchesWithoutSpace = values.filter((value) => value.toLowerCase().startsWith(searchWithoutSpace));
+
+		/**
+		 * If there's only one match for the prefix without space, we don't
+		 * watch to match with space.
+		 */
+		if (matchesWithoutSpace.length <= 1) {
+			return getNextMatch(values, searchWithoutSpace, currentMatch);
+		}
+
+		const currentMatchLowercase = currentMatch?.toLowerCase();
+
+		/**
+		 * If the current match already starts with the search prefix and has a space afterward,
+		 * and the user has only typed up to that space, keep the current match until they
+		 * disambiguate.
+		 */
+		if (
+			currentMatchLowercase &&
+			currentMatchLowercase.startsWith(searchWithoutSpace) &&
+			currentMatchLowercase.charAt(searchWithoutSpace.length) === ' ' &&
+			search.trim() === searchWithoutSpace
+		) {
+			return currentMatch;
+		}
+
+		/**
+		 * With multiple matches, find items that match the full search string with space
+		 */
+		const spacedMatches = values.filter((value) => value.toLowerCase().startsWith(lowerSearch));
+
+		/**
+		 * If we found matches with the space, use the first one that's not the current match
+		 */
+		if (spacedMatches.length > 0) {
+			const currentMatchIndex = currentMatch ? values.indexOf(currentMatch) : -1;
+
+			// the first match that is not the current one, falling back to current if no other is found.
+			const nextMatch = findWrapped(spacedMatches, Math.max(currentMatchIndex, 0), (match) => match !== currentMatch);
+			return nextMatch || currentMatch;
+		}
+	}
+
+	const isRepeated = search.length > 1 && Array.from(search).every((char) => char === search[0]);
+	const normalizedSearch = isRepeated ? search[0]! : search;
+	const normalizedLowerSearch = normalizedSearch.toLowerCase();
+
+	const currentMatchIndex = currentMatch ? values.indexOf(currentMatch) : -1;
+	const excludeCurrentMatch = normalizedSearch.length === 1;
+	const nextMatch = findWrapped(
+		values,
+		Math.max(currentMatchIndex, 0),
+		(value) => (!excludeCurrentMatch || value !== currentMatch) && value.toLowerCase().startsWith(normalizedLowerSearch),
+	);
+
+	return nextMatch !== currentMatch ? nextMatch : undefined;
+}
+
+/**
+ * Circular find: scans `array` from `startIndex` (wrapping past the end) and returns the first element
+ * satisfying `predicate`. What every caller of the old rotate-copy (`wrapArray`) actually consumed —
+ * same visit order, without allocating the rotation.
+ */
+export const findWrapped = <T>(array: T[], startIndex: number, predicate: (item: T) => boolean): T | undefined => {
+	for (let step = 0; step < array.length; step++) {
+		const item = array[(startIndex + step) % array.length]!;
+		if (predicate(item)) return item;
+	}
+	return undefined;
+};

package/src/lib/internal/attribute-types.ts

@@ -0,0 +1,53 @@
+import type {
+	HTMLAnchorAttributes,
+	HTMLAttributes,
+	HTMLButtonAttributes,
+	HTMLImgAttributes,
+	HTMLInputAttributes,
+	HTMLLabelAttributes,
+	HTMLLiAttributes,
+	HTMLSelectAttributes,
+	HTMLTableAttributes,
+	HTMLTdAttributes,
+	HTMLThAttributes,
+	SVGAttributes,
+} from 'svelte/elements';
+
+export type BitsDivAttributes = HTMLAttributes<HTMLDivElement>;
+export type BitsSpanAttributes = HTMLAttributes<HTMLSpanElement>;
+export type BitsHeadingAttributes = HTMLAttributes<HTMLHeadingElement>;
+export type BitsUListAttributes = HTMLAttributes<HTMLUListElement>;
+export type BitsElementAttributes = HTMLAttributes<HTMLElement>;
+export type BitsTableSectionAttributes = HTMLAttributes<HTMLTableSectionElement>;
+export type BitsTableRowAttributes = HTMLAttributes<HTMLTableRowElement>;
+export type BitsSVGElementAttributes = SVGAttributes<SVGElement>;
+export type BitsSelectAttributes = HTMLSelectAttributes;
+
+/**
+ * We override the `id` prop type to not allow it to be `null`. We rely on the
+ * `id` heavily in the internals of Bits UI for node references. We also override
+ * children to allow for custom children snippet props. We extend `style` to allow
+ * for either a `StyleProperties` object or a string of CSS properties.
+ */
+type BitsPrimitive<T> = Omit<T, 'style' | 'id' | 'children'> & { id?: string };
+
+export type BitsPrimitiveButtonAttributes = BitsPrimitive<HTMLButtonAttributes>;
+export type BitsPrimitiveDivAttributes = BitsPrimitive<BitsDivAttributes>;
+export type BitsPrimitiveInputAttributes = BitsPrimitive<HTMLInputAttributes>;
+export type BitsPrimitiveSpanAttributes = BitsPrimitive<BitsSpanAttributes>;
+export type BitsPrimitiveImgAttributes = BitsPrimitive<HTMLImgAttributes>;
+export type BitsPrimitiveHeadingAttributes = BitsPrimitive<BitsHeadingAttributes>;
+export type BitsPrimitiveLabelAttributes = BitsPrimitive<HTMLLabelAttributes>;
+export type BitsPrimitiveSVGAttributes = BitsPrimitive<BitsSVGElementAttributes>;
+export type BitsPrimitiveAnchorAttributes = BitsPrimitive<HTMLAnchorAttributes>;
+export type BitsPrimitiveLiAttributes = BitsPrimitive<HTMLLiAttributes>;
+export type BitsPrimitiveElementAttributes = BitsPrimitive<BitsElementAttributes>;
+export type BitsPrimitiveUListAttributes = BitsPrimitive<BitsUListAttributes>;
+export type BitsPrimitiveTdAttributes = BitsPrimitive<HTMLTdAttributes>;
+export type BitsPrimitiveThAttributes = BitsPrimitive<HTMLThAttributes>;
+export type BitsPrimitiveTableAttributes = BitsPrimitive<HTMLTableAttributes>;
+export type BitsPrimitiveTbodyAttributes = BitsPrimitive<BitsTableSectionAttributes>;
+export type BitsPrimitiveTrAttributes = BitsPrimitive<BitsTableRowAttributes>;
+export type BitsPrimitiveTheadAttributes = BitsPrimitive<BitsTableSectionAttributes>;
+export type BitsPrimitiveHeaderAttributes = BitsPrimitive<BitsElementAttributes>;
+export type BitsPrimitiveSelectAttributes = BitsPrimitive<BitsSelectAttributes>;

package/src/lib/internal/attrs.ts

@@ -0,0 +1,64 @@
+export const boolToStr = (condition: boolean): 'true' | 'false' => condition ? 'true' : 'false';
+
+export const boolToStrTrueOrUndef = (condition: boolean): 'true' | undefined => condition ? 'true' : undefined;
+
+export const boolToEmptyStrOrUndef = (condition: boolean): '' | undefined => condition ? '' : undefined;
+
+export const boolToTrueOrUndef = (condition: boolean): true | undefined => condition ? true : undefined;
+
+export const getDataOpenClosed = (condition: boolean): 'open' | 'closed' => condition ? 'open' : 'closed';
+
+export type TransitionState = 'starting' | 'ending' | 'idle' | undefined;
+
+export const getAriaChecked = (checked: boolean, indeterminate: boolean): 'true' | 'false' | 'mixed' =>
+	indeterminate ? 'mixed' : checked ? 'true' : 'false';
+
+export type BitsAttrsConfig<T extends readonly string[]> = {
+	component: string;
+	parts: T;
+	getVariant?: () => string | null;
+};
+
+export type CreateBitsAttrsReturn<T extends readonly string[]> = {
+	[K in T[number]]: string;
+} & {
+	selector: (part: T[number]) => string;
+	getAttr: (part: T[number], variant?: string) => string;
+};
+
+export class BitsAttrs<T extends readonly string[]> {
+	readonly #variant: string | null;
+	readonly #prefix: string;
+	attrs: Record<T[number], string>;
+
+	constructor(config: BitsAttrsConfig<T>) {
+		this.#variant = config.getVariant ? config.getVariant() : null;
+		this.#prefix = this.#variant ? `data-${this.#variant}-` : `data-${config.component}-`;
+
+		this.getAttr = this.getAttr.bind(this);
+		this.selector = this.selector.bind(this);
+
+		this.attrs = Object.fromEntries(config.parts.map((part) => [part, this.getAttr(part)])) as Record<T[number], string>;
+	}
+
+	getAttr(part: T[number], variantOverride?: string): string {
+		if (variantOverride) return `data-${variantOverride}-${part}`;
+		return `${this.#prefix}${part}`;
+	}
+
+	selector(part: T[number], variantOverride?: string): string {
+		return `[${this.getAttr(part, variantOverride)}]`;
+	}
+}
+
+export function createBitsAttrs<const T extends readonly string[]>(
+	config: Omit<BitsAttrsConfig<T>, 'parts'> & { parts: T },
+): CreateBitsAttrsReturn<T> {
+	const bitsAttrs = new BitsAttrs(config);
+
+	return {
+		...bitsAttrs.attrs,
+		selector: bitsAttrs.selector,
+		getAttr: bitsAttrs.getAttr,
+	} as CreateBitsAttrsReturn<T>;
+}

package/src/lib/internal/body-scroll-lock.svelte.ts

@@ -0,0 +1,330 @@
+import { SvelteMap } from 'svelte/reactivity';
+import { type Attachment, createAttachmentKey } from 'svelte/attachments';
+import { type Getter, type ReadableBox, boxWith } from './tools/index.js';
+import type { Fn } from './types.js';
+import { isIOS } from './tools/utils/dom.js';
+import { BROWSER } from 'esm-env';
+import { SharedState } from './shared-state.svelte.js';
+import { on } from 'svelte/events';
+import { getAbortSignal, onMount, tick, untrack } from 'svelte';
+
+export interface ScrollBodyOption {
+	padding?: boolean | number;
+	margin?: boolean | number;
+}
+/** A map of lock instances to their `locked` state. */
+const lockMap = new SvelteMap<BodyScrollLock, boolean>();
+
+let initialBodyStyle: string | null = $state<string | null>(null);
+let stopTouchMoveListener: Fn | null = null;
+let cleanupTimeoutId: number | null = null;
+let isInCleanupTransition = false;
+
+function cleanupTouchMoveListener() {
+	stopTouchMoveListener?.();
+	stopTouchMoveListener = null;
+}
+
+const anyLocked = boxWith(() => {
+	for (const value of lockMap.values()) {
+		if (value) return true;
+	}
+	return false;
+});
+
+/**
+ * We track the time we scheduled the cleanup to prevent race conditions
+ * when multiple locks are created/destroyed in the same tick, ensuring
+ * only the last one to schedule the cleanup will run.
+ *
+ * reference: https://github.com/huntabyte/bits-ui/issues/1639
+ */
+let cleanupScheduledAt: number | null = null;
+
+const bodyLockStackCount = new SharedState(() => {
+	const doc = BROWSER && typeof document !== 'undefined' ? document : null;
+	const win = doc?.defaultView ?? (BROWSER && typeof window !== 'undefined' ? window : null);
+
+	function getDOM() {
+		if (!doc?.body || !doc.documentElement || !win) return null;
+		return {
+			body: doc.body,
+			documentElement: doc.documentElement,
+			doc,
+			win,
+		};
+	}
+
+	function resetBodyStyle() {
+		const dom = getDOM();
+		if (!dom) {
+			initialBodyStyle = null;
+			return;
+		}
+		dom.body.setAttribute('style', initialBodyStyle ?? '');
+		if (isIOS) {
+			cleanupTouchMoveListener();
+		}
+		// reset initialBodyStyle so next locker captures the correct styles
+		initialBodyStyle = null;
+	}
+
+	function cancelPendingCleanup() {
+		if (cleanupTimeoutId === null) return;
+		win?.clearTimeout(cleanupTimeoutId);
+		cleanupTimeoutId = null;
+	}
+
+	function scheduleCleanupIfNoNewLocks(delay: number | null, callback: () => void) {
+		cancelPendingCleanup();
+		if (!win) {
+			isInCleanupTransition = false;
+			return;
+		}
+		isInCleanupTransition = true;
+
+		cleanupScheduledAt = Date.now();
+		const currentCleanupId = cleanupScheduledAt;
+
+		/**
+		 * We schedule the cleanup to run after a delay to allow new locks to register
+		 * that might have been added in the same tick as the current cleanup.
+		 *
+		 * If a new lock is added in the same tick, the cleanup will be cancelled and
+		 * a new cleanup will be scheduled.
+		 *
+		 * This is to prevent the cleanup from running too early and resetting the body
+		 * style before the new lock has had a chance to apply its styles.
+		 */
+		const cleanupFn = () => {
+			cleanupTimeoutId = null;
+
+			// check if this cleanup is still valid (no newer cleanups scheduled)
+			if (cleanupScheduledAt !== currentCleanupId) return;
+
+			// ensure no new locks were added during the delay
+			if (!isAnyLocked(lockMap)) {
+				isInCleanupTransition = false;
+				callback();
+			} else {
+				isInCleanupTransition = false;
+			}
+		};
+
+		const actualDelay = delay === null ? 24 : delay;
+		cleanupTimeoutId = win.setTimeout(cleanupFn, actualDelay);
+	}
+
+	function ensureInitialStyleCaptured() {
+		const dom = getDOM();
+		if (!dom) return;
+		// only capture initial style once, when no locks exist and no cleanup is in progress
+		if (initialBodyStyle === null && lockMap.size === 0 && !isInCleanupTransition) {
+			initialBodyStyle = dom.body.getAttribute('style');
+		}
+	}
+
+	$effect(() => {
+		anyLocked.current;
+		const signal = getAbortSignal();
+		untrack(() => {
+			if (!anyLocked.current) return;
+			const dom = getDOM();
+			if (!dom) return;
+
+			// ensure we've captured the initial style before applying any lock styles
+			ensureInitialStyleCaptured();
+
+			// if we're applying lock styles, we're no longer in a cleanup transition
+			isInCleanupTransition = false;
+
+			const htmlStyle = dom.win.getComputedStyle(dom.documentElement);
+			const bodyStyle = dom.win.getComputedStyle(dom.body);
+
+			// ui.css sets `scrollbar-gutter: stable` on html, so the measurement branch below is
+			// the fallback for engines without support (Safari <18.2).
+			const hasStableGutter = htmlStyle.scrollbarGutter?.includes('stable') || bodyStyle.scrollbarGutter?.includes('stable');
+
+			// TODO: account for RTL direction, etc.
+			const verticalScrollbarWidth = dom.win.innerWidth - dom.documentElement.clientWidth;
+			const paddingRight = Number.parseInt(bodyStyle.paddingRight ?? '0', 10);
+
+			const config = {
+				padding: paddingRight + verticalScrollbarWidth,
+				margin: Number.parseInt(bodyStyle.marginRight ?? '0', 10),
+			};
+
+			// only add padding compensation if stable gutter isn't handling it
+			if (verticalScrollbarWidth > 0 && !hasStableGutter) {
+				dom.body.style.paddingRight = `${config.padding}px`;
+				dom.body.style.marginRight = `${config.margin}px`;
+			}
+			dom.body.style.overflow = 'hidden';
+
+			if (isIOS && !stopTouchMoveListener) {
+				// IOS devices are special and require a touchmove listener to prevent scrolling.
+				// Guard against duplicate listeners when concurrent locks mutate lockMap.
+				stopTouchMoveListener = on(
+					dom.doc,
+					'touchmove',
+					(e) => {
+						if (e.target !== dom.documentElement) return;
+
+						if (e.touches.length > 1) return;
+						e.preventDefault();
+					},
+					{ passive: false },
+				);
+			}
+
+			/**
+			 * We ensure pointer-events: none is applied _after_ DOM updates, so that any focus/
+			 * interaction changes from opening overlays/menus complete _before_ we block pointer
+			 * events.
+			 *
+			 * this avoids race conditions where pointer-events could be set too early and break
+			 * focus/interaction.
+			 */
+			tick().then(() => {
+				const latestDOM = getDOM();
+				if (signal.aborted || !latestDOM || !isAnyLocked(lockMap)) return;
+				latestDOM.body.style.pointerEvents = 'none';
+				latestDOM.body.style.overflow = 'hidden';
+			});
+		});
+	});
+
+	$effect(() => {
+		return () => {
+			cleanupTouchMoveListener();
+		};
+	});
+
+	return {
+		get lockMap() {
+			return lockMap;
+		},
+		resetBodyStyle,
+		scheduleCleanupIfNoNewLocks,
+		cancelPendingCleanup,
+		ensureInitialStyleCaptured,
+	};
+});
+
+export class BodyScrollLock {
+	readonly #initialState: boolean | undefined;
+	readonly #restoreScrollDelay: Getter<number | null> = () => null;
+	readonly #countState: ReturnType<typeof bodyLockStackCount.get>;
+	readonly locked: ReadableBox<boolean> | undefined;
+	#released = false;
+
+	constructor(initialState?: boolean | undefined, restoreScrollDelay: Getter<number | null> = () => null) {
+		this.#initialState = initialState;
+		this.#restoreScrollDelay = restoreScrollDelay;
+		this.#countState = bodyLockStackCount.get();
+
+		if (!this.#countState) return;
+
+		/**
+		 * Since a new lock is being created, we cancel any pending cleanup to
+		 * prevent the cleanup from running too early and resetting the body style
+		 * before the new lock has had a chance to apply its styles.
+		 *
+		 * reference: https://github.com/huntabyte/bits-ui/issues/1639
+		 */
+		this.#countState.cancelPendingCleanup();
+
+		// capture initial style before this lock is registered
+		this.#countState.ensureInitialStyleCaptured();
+
+		this.#countState.lockMap.set(this, this.#initialState ?? false);
+
+		this.locked = boxWith(
+			() => this.#countState.lockMap.get(this) ?? false,
+			(v) => this.#countState.lockMap.set(this, v),
+		);
+
+		// Component-form owners (a lock constructed during init) release on unmount; effect owners
+		// release through their cleanup, for which this is a no-op.
+		onMount(() => () => this.release());
+	}
+
+	/**
+	 * Unregisters the lock; the owner returns this as its effect cleanup. Registration is
+	 * synchronous in the constructor, so the release must not depend on a child effect having
+	 * run: an owner effect that re-runs before its children execute (an attachment re-run in
+	 * the same flush) would otherwise never unregister the lock, and the body stays locked.
+	 */
+	release() {
+		if (this.#released || !this.#countState) return;
+		this.#released = true;
+		this.#countState.lockMap.delete(this);
+
+		// if not the last lock, we don't need to do anything
+		if (isAnyLocked(this.#countState.lockMap)) return;
+
+		/**
+		 * We schedule the cleanup to run after a delay to handle same-tick
+		 * destroy/create scenarios.
+		 *
+		 * reference: https://github.com/huntabyte/bits-ui/issues/1639
+		 */
+		this.#countState.scheduleCleanupIfNoNewLocks(this.#restoreScrollDelay(), () => {
+			this.#countState.resetBodyStyle();
+		});
+	}
+}
+
+function isAnyLocked(map: Map<BodyScrollLock, boolean>) {
+	for (const [_, value] of map) {
+		if (value) return true;
+	}
+	return false;
+}
+
+/** Surface props shared by every scroll-locking overlay (moved from the retired internal/scroll-lock). */
+export type ScrollLockProps = {
+	/**
+	 * Whether to prevent body scrolling when the content is open.
+	 *
+	 * @default true
+	 */
+	preventScroll?: boolean;
+
+	/**
+	 * The delay in milliseconds before the scrollbar is restored after closing the
+	 * dialog. This is only applicable when using the `child` snippet for custom
+	 * transitions and `preventScroll` is `true`. You should set this to a value
+	 * greater than the transition duration to prevent content from shifting during
+	 * the transition.
+	 *
+	 * @default null
+	 */
+	restoreScrollDelay?: number | null;
+};
+
+/**
+ * Attachment form of the body lock — replaces the renderless `<ScrollLock>` component.
+ * Locks while the host element is connected AND `enabled()` is true; `enabled` is a tracked
+ * read, so surfaces whose element persists across open/close re-run the attachment as their
+ * open state flips, and the lock is released through the attachment's own cleanup (see
+ * `BodyScrollLock.release`).
+ *
+ * Spreadable (`{...lock}` / a `mergeProps` argument); create it ONCE in the script so the
+ * attachment's identity is stable across renders.
+ */
+export function scrollLockAttachment(opts: {
+	enabled?: Getter<boolean>;
+	restoreScrollDelay?: Getter<number | null>;
+} = {}): Record<symbol, Attachment> {
+	const { enabled = () => true, restoreScrollDelay = () => null } = opts;
+	return {
+		[createAttachmentKey()]: () => {
+			if (!enabled()) return;
+			// untracked: registering in the shared lockMap is a deliberate write from a tracked
+			// context (the attach effect).
+			const lock = untrack(() => new BodyScrollLock(true, restoreScrollDelay));
+			return () => lock.release();
+		},
+	};
+}