sheer-ui 0.0.0

package/src/lib/internal/table/table.svelte.ts

@@ -0,0 +1,330 @@
+import { SvelteSet } from 'svelte/reactivity';
+import type { CellContext, ColumnDef, ColumnFilter, ColumnSort, FilterFn, HeaderContext } from './types.js';
+import { facetCounts, makeAccessor, resolveColumnId, sortRows } from './core.js';
+import { inferSortingFn } from './sorting-fns.js';
+import { includesString, shouldAutoRemoveFilter } from './filter-fns.js';
+
+export interface DataTableOptions<TData> {
+	/** Thunk so the table tracks the consumer's own reactive source. */
+	data: () => TData[];
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	columns: ColumnDef<TData, any>[] | (() => ColumnDef<TData, any>[]);
+	/** Omit for an unpaginated table. */
+	pageSize?: number;
+}
+
+export const createDataTable = <TData>(options: DataTableOptions<TData>) => new DataTable(options);
+
+export class DataTable<TData> {
+	readonly #data: () => TData[];
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	readonly #defs: () => ColumnDef<TData, any>[];
+	readonly #paginated: boolean;
+	readonly #selection = new SvelteSet<string>();
+
+	sorting = $state<ColumnSort[]>([]);
+	columnFilters = $state<ColumnFilter[]>([]);
+	columnVisibility = $state<Record<string, boolean>>({});
+	#pageIndex = $state(0);
+	#pageSize = $state(10);
+
+	constructor(options: DataTableOptions<TData>) {
+		this.#data = options.data;
+		const { columns } = options;
+		this.#defs = typeof columns === 'function' ? columns : () => columns;
+		this.#paginated = options.pageSize !== undefined;
+		if (options.pageSize !== undefined) this.#pageSize = options.pageSize;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	readonly #columns: Column<TData, any>[] = $derived.by(() => this.#defs().map((def) => new Column(this, def)));
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	readonly #columnsById = $derived(new Map<string, Column<TData, any>>(this.#columns.map((column) => [column.id, column])));
+	readonly #coreRows: readonly Row<TData>[] = $derived.by(() => this.#data().map((original, index) => new Row(this, this.#selection, original, index)));
+
+	readonly #activeFilters = $derived(
+		this.columnFilters.flatMap((filter) => {
+			const column = this.#columnsById.get(filter.id);
+			return column ? [{ id: filter.id, filterFn: column.filterFn, value: filter.value }] : [];
+		}),
+	);
+	// One row-id set per active filter, reused by both the filtered model and every facet.
+	readonly #masks = $derived(
+		this.#activeFilters.map((filter) => new Set(this.#coreRows.filter((row) => filter.filterFn(row, filter.id, filter.value)).map((row) => row.id))),
+	);
+
+	readonly filteredRows: readonly Row<TData>[] = $derived(
+		this.#masks.length === 0 ? this.#coreRows : this.#coreRows.filter((row) => this.#masks.every((mask) => mask.has(row.id))),
+	);
+
+	readonly #sorted = $derived(
+		sortRows(this.filteredRows, this.sorting, (columnId) =>
+			this.#columnsById.get(columnId)?.canSort ? inferSortingFn(this.filteredRows, columnId) : undefined,
+		),
+	);
+
+	readonly pageCount = $derived.by(() => (this.#paginated ? Math.max(1, Math.ceil(this.#sorted.length / this.#pageSize)) : 1));
+	// Clamped on read, never written back: data shrinking under a stale index lands on the last page.
+	readonly #safeIndex = $derived(Math.min(this.#pageIndex, this.pageCount - 1));
+
+	readonly rows: readonly Row<TData>[] = $derived.by(() =>
+		this.#paginated ? this.#sorted.slice(this.#safeIndex * this.#pageSize, (this.#safeIndex + 1) * this.#pageSize) : this.#sorted,
+	);
+
+	readonly canPreviousPage = $derived(this.#safeIndex > 0);
+	readonly canNextPage = $derived(this.#safeIndex < this.pageCount - 1);
+
+	get pagination(): { pageIndex: number; pageSize: number } {
+		return { pageIndex: this.#safeIndex, pageSize: this.#pageSize };
+	}
+
+	setPageIndex(index: number) {
+		this.#pageIndex = Math.min(Math.max(index, 0), this.pageCount - 1);
+	}
+	nextPage() {
+		this.setPageIndex(this.#safeIndex + 1);
+	}
+	previousPage() {
+		this.setPageIndex(this.#safeIndex - 1);
+	}
+	setPageSize(size: number) {
+		const next = Math.max(1, size);
+		// Keep the current top row visible, matching upstream's paging math.
+		this.#pageIndex = Math.floor((this.#safeIndex * this.#pageSize) / next);
+		this.#pageSize = next;
+	}
+
+	// User-initiated sort and filter changes restart paging; a data refetch underneath does not.
+	setSorting(sorting: ColumnSort[]) {
+		this.sorting = sorting;
+		this.#pageIndex = 0;
+	}
+	setColumnFilters(filters: ColumnFilter[]) {
+		this.columnFilters = filters;
+		this.#pageIndex = 0;
+	}
+	resetColumnFilters() {
+		this.setColumnFilters([]);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	get allColumns(): readonly Column<TData, any>[] {
+		return this.#columns;
+	}
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	column(id: string): Column<TData, any> | undefined {
+		return this.#columnsById.get(id);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	readonly visibleColumns: readonly Column<TData, any>[] = $derived(this.#columns.filter((column) => column.isVisible));
+	readonly headerGroups: readonly HeaderGroup<TData>[] = $derived([
+		{ id: '0', headers: this.visibleColumns.map((column) => new Header(this, column)) },
+	]);
+
+	get selectedRowIds(): ReadonlySet<string> {
+		return this.#selection;
+	}
+	setSelectedRowIds(ids: Iterable<string>) {
+		const next = new Set(ids);
+		for (const id of this.#selection) if (!next.has(id)) this.#selection.delete(id);
+		for (const id of next) this.#selection.add(id);
+	}
+
+	readonly selectedRows: readonly Row<TData>[] = $derived(this.#coreRows.filter((row) => row.isSelected));
+	readonly filteredSelectedRows: readonly Row<TData>[] = $derived(this.filteredRows.filter((row) => row.isSelected));
+
+	readonly isAllPageRowsSelected = $derived(this.rows.length > 0 && this.rows.every((row) => row.isSelected));
+	readonly isSomePageRowsSelected = $derived(this.isAllPageRowsSelected ? false : this.rows.some((row) => row.isSelected));
+	toggleAllPageRowsSelected(value?: boolean) {
+		const resolved = value ?? !this.isAllPageRowsSelected;
+		for (const row of this.rows) row.toggleSelected(resolved);
+	}
+
+	/** Core rows minus every active filter except `columnId`'s own, so a facet counts its remaining options. */
+	facetedRows(columnId: string): readonly Row<TData>[] {
+		const masks = this.#activeFilters.flatMap((filter, index) => (filter.id === columnId ? [] : [this.#masks[index]!]));
+		return masks.length === 0 ? this.#coreRows : this.#coreRows.filter((row) => masks.every((mask) => mask.has(row.id)));
+	}
+}
+
+export class Column<TData, TValue = unknown> {
+	readonly id: string;
+	readonly columnDef: ColumnDef<TData, TValue>;
+	readonly accessorFn?: (original: TData, index: number) => unknown;
+	readonly filterFn: FilterFn<TData>;
+	readonly #table: DataTable<TData>;
+
+	constructor(table: DataTable<TData>, def: ColumnDef<TData, TValue>) {
+		this.#table = table;
+		this.columnDef = def;
+		this.id = resolveColumnId(def);
+		this.accessorFn = makeAccessor(def);
+		this.filterFn = def.filterFn ?? includesString;
+	}
+
+	get canSort(): boolean {
+		return (this.columnDef.enableSorting ?? true) && this.accessorFn !== undefined;
+	}
+	get isSorted(): false | 'asc' | 'desc' {
+		const entry = this.#table.sorting.find((sort) => sort.id === this.id);
+		return entry ? (entry.desc ? 'desc' : 'asc') : false;
+	}
+
+	// String columns start ascending, everything else descending (upstream's getAutoSortDir).
+	#firstSortDir(): 'asc' | 'desc' {
+		return typeof this.#table.filteredRows[0]?.getValue(this.id) === 'string' ? 'asc' : 'desc';
+	}
+	// Three-state cycle with removal: first direction → other direction → unsorted.
+	#nextSortingOrder(): 'asc' | 'desc' | false {
+		const first = this.#firstSortDir();
+		const isSorted = this.isSorted;
+		if (!isSorted) return first;
+		if (isSorted !== first) return false;
+		return isSorted === 'desc' ? 'asc' : 'desc';
+	}
+
+	toggleSorting(desc?: boolean, multi = false) {
+		const nextOrder = this.#nextSortingOrder();
+		const hasManualValue = desc !== undefined;
+		const nextDesc = hasManualValue ? desc : nextOrder === 'desc';
+
+		const old = this.#table.sorting;
+		const existing = old.find((sort) => sort.id === this.id);
+		const existingIndex = old.findIndex((sort) => sort.id === this.id);
+
+		if (old.length > 0 && this.#canMultiSort && multi) {
+			this.#table.setSorting(
+				existing
+					? !hasManualValue && nextOrder === false
+						? old.filter((sort) => sort.id !== this.id)
+						: old.map((sort) => (sort.id === this.id ? { ...sort, desc: nextDesc } : sort))
+					: [...old, { id: this.id, desc: nextDesc }],
+			);
+			return;
+		}
+
+		// Single mode: only the most recently applied sort toggles through the cycle; anything else replaces.
+		if (existing !== undefined && existingIndex === old.length - 1) {
+			this.#table.setSorting(
+				!hasManualValue && nextOrder === false
+					? old.filter((sort) => sort.id !== this.id)
+					: old.map((sort) => (sort.id === this.id ? { ...sort, desc: nextDesc } : sort)),
+			);
+			return;
+		}
+		this.#table.setSorting([{ id: this.id, desc: nextDesc }]);
+	}
+
+	get #canMultiSort(): boolean {
+		return this.accessorFn !== undefined;
+	}
+
+	readonly sortHandler = (event: MouseEvent) => {
+		if (!this.canSort) return;
+		this.toggleSorting(undefined, this.#canMultiSort && event.shiftKey);
+	};
+
+	get canHide(): boolean {
+		return this.columnDef.enableHiding ?? true;
+	}
+	get isVisible(): boolean {
+		return this.#table.columnVisibility[this.id] ?? true;
+	}
+	toggleVisibility(visible?: boolean) {
+		if (!this.canHide) return;
+		this.#table.columnVisibility = { ...this.#table.columnVisibility, [this.id]: visible ?? !this.isVisible };
+	}
+
+	get filterValue(): unknown {
+		return this.#table.columnFilters.find((filter) => filter.id === this.id)?.value;
+	}
+	setFilterValue(value: unknown) {
+		const others = this.#table.columnFilters.filter((filter) => filter.id !== this.id);
+		this.#table.setColumnFilters(shouldAutoRemoveFilter(value) ? others : [...others, { id: this.id, value }]);
+	}
+
+	get facetedUniqueValues(): ReadonlyMap<unknown, number> {
+		return facetCounts(this.#table.facetedRows(this.id), this.id);
+	}
+}
+
+export class Row<TData> {
+	readonly id: string;
+	readonly index: number;
+	readonly original: TData;
+	readonly #table: DataTable<TData>;
+	readonly #selection: SvelteSet<string>;
+	// Plain Maps on purpose: both are written during $derived reads (sorting, templates), and a
+	// reactive container there is a write-inside-read loop (effect_update_depth_exceeded).
+	readonly #values = new Map<string, unknown>();
+	readonly #cells = new Map<string, Cell<TData>>();
+
+	constructor(table: DataTable<TData>, selection: SvelteSet<string>, original: TData, index: number) {
+		this.#table = table;
+		this.#selection = selection;
+		this.original = original;
+		this.index = index;
+		this.id = String(index);
+	}
+
+	getValue<TValue = unknown>(columnId: string): TValue {
+		if (this.#values.has(columnId)) return this.#values.get(columnId) as TValue;
+		const value = this.#table.column(columnId)?.accessorFn?.(this.original, this.index);
+		this.#values.set(columnId, value);
+		return value as TValue;
+	}
+
+	get isSelected(): boolean {
+		return this.#selection.has(this.id);
+	}
+	toggleSelected(value?: boolean) {
+		if (value ?? !this.isSelected) this.#selection.add(this.id);
+		else this.#selection.delete(this.id);
+	}
+
+	get visibleCells(): Cell<TData>[] {
+		return this.#table.visibleColumns.map((column) => {
+			let cell = this.#cells.get(column.id);
+			if (cell === undefined) {
+				cell = new Cell(this.#table, column, this);
+				this.#cells.set(column.id, cell);
+			}
+			return cell;
+		});
+	}
+}
+
+export class Cell<TData, TValue = unknown> {
+	readonly id: string;
+	readonly column: Column<TData, TValue>;
+	readonly row: Row<TData>;
+	readonly context: CellContext<TData, TValue>;
+
+	constructor(table: DataTable<TData>, column: Column<TData, TValue>, row: Row<TData>) {
+		this.id = `${row.id}_${column.id}`;
+		this.column = column;
+		this.row = row;
+		this.context = { table, column, row, cell: this };
+	}
+}
+
+export class Header<TData, TValue = unknown> {
+	readonly id: string;
+	readonly colSpan = 1;
+	readonly isPlaceholder = false;
+	readonly column: Column<TData, TValue>;
+	readonly context: HeaderContext<TData, TValue>;
+
+	constructor(table: DataTable<TData>, column: Column<TData, TValue>) {
+		this.id = column.id;
+		this.column = column;
+		this.context = { table, column, header: this };
+	}
+}
+
+export interface HeaderGroup<TData> {
+	id: string;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	headers: Header<TData, any>[];
+}

package/src/lib/internal/table/types.ts

@@ -0,0 +1,33 @@
+import type { Cell, Column, DataTable, Header, Row } from './table.svelte.js';
+
+export type ColumnDefTemplate<TProps> = string | ((props: TProps) => unknown);
+
+export type FilterFn<TData> = (row: Row<TData>, columnId: string, value: unknown) => boolean;
+
+export interface ColumnDef<TData, TValue = unknown> {
+	id?: string;
+	accessorKey?: string;
+	accessorFn?: (original: TData, index: number) => TValue;
+	header?: ColumnDefTemplate<HeaderContext<TData, TValue>>;
+	cell?: ColumnDefTemplate<CellContext<TData, TValue>>;
+	filterFn?: FilterFn<TData>;
+	enableSorting?: boolean;
+	enableHiding?: boolean;
+	meta?: { class?: string };
+}
+
+export type ColumnSort = { id: string; desc: boolean };
+export type ColumnFilter = { id: string; value: unknown };
+
+export interface HeaderContext<TData, TValue = unknown> {
+	table: DataTable<TData>;
+	column: Column<TData, TValue>;
+	header: Header<TData, TValue>;
+}
+
+export interface CellContext<TData, TValue = unknown> {
+	table: DataTable<TData>;
+	column: Column<TData, TValue>;
+	row: Row<TData>;
+	cell: Cell<TData, TValue>;
+}

package/src/lib/internal/timeout-fn.svelte.ts

@@ -0,0 +1,36 @@
+import type { AnyFn } from './types.js';
+
+/**
+ * A self-cancelling timeout. `start()` (re)schedules `cb` after `getInterval()` ms,
+ * `stop()` clears it; auto-stops when the owning component/effect is destroyed.
+ */
+export function createEffectTimeout<T extends AnyFn>(cb: T, getDelay: () => number) {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+
+	const stop = () => {
+		if (timer === undefined) return;
+
+		clearTimeout(timer);
+		timer = undefined;
+	};
+
+	const start = (...args: Parameters<T>) => {
+		stop();
+
+		timer = setTimeout(() => {
+			timer = undefined;
+			cb(...args);
+		}, getDelay());
+	};
+
+	$effect(() => stop);
+
+	return {
+		start,
+		stop,
+		// Not reactive: a plain `let`, only ever read from event handlers.
+		get pending() {
+			return timer !== undefined;
+		},
+	};
+}

package/src/lib/internal/tools/box.svelte.ts

@@ -0,0 +1,153 @@
+import { untrack } from 'svelte';
+
+const BoxSymbol = Symbol('box');
+const isWritableSymbol = Symbol('is-writable');
+
+export type ReadableBox<T> = {
+	readonly [BoxSymbol]: true;
+	readonly current: T;
+};
+
+export type WritableBox<T> = ReadableBox<T> & {
+	readonly [isWritableSymbol]: true;
+	current: T;
+};
+
+function createWritableBox<T>(): WritableBox<T | undefined>;
+function createWritableBox<T>(initialValue: T): WritableBox<T>;
+function createWritableBox(initialValue?: unknown) {
+	let current = $state(initialValue);
+
+	return {
+		[BoxSymbol]: true,
+		[isWritableSymbol]: true,
+		get current() {
+			return current as unknown;
+		},
+		set current(v: unknown) {
+			current = v;
+		},
+	};
+}
+
+/**
+ * Creates a readonly box.
+ *
+ * @param getter Function to get the value of the box.
+ * @returns A box with a `current` property whose value is the result of the getter.
+ */
+function boxWith<T>(getter: () => T): ReadableBox<T>;
+
+/**
+ * Creates a writable box.
+ *
+ * @param getter Function to get the value of the box.
+ * @param setter Function to set the value of the box.
+ * @returns A box with a `current` property which can be set to a new value.
+ */
+function boxWith<T>(getter: () => T, setter: (v: T) => void): WritableBox<T>;
+
+function boxWith<T>(getter: () => T, setter?: (v: T) => void) {
+	if (setter) {
+		return {
+			[BoxSymbol]: true,
+			[isWritableSymbol]: true,
+			get current() {
+				return getter();
+			},
+			set current(v: T) {
+				setter(v);
+			},
+		};
+	}
+
+	return {
+		[BoxSymbol]: true,
+		get current() {
+			return getter();
+		},
+	};
+}
+
+/**
+ * The one bridge for a stateful `$bindable` prop: write the prop, then notify.
+ *
+ * `set` must write unconditionally — equality/idempotence guards belong to the
+ * caller (the *State class), so a write through this box always means a real
+ * change and `notify` fires exactly once per change. Pass `notify` as a closure
+ * (`(v) => onValueChange?.(v)`) so the latest callback prop is read at call
+ * time; a bare reference freezes the prop's value at bundle creation.
+ *
+ * Convention: writable bridges (value/open/checked/ref/...) use `bindableWith`;
+ * `boxWith` is for read-only views. A two-argument `boxWith` is legacy.
+ */
+export function bindableWith<T>(get: () => T, set: (v: T) => void, notify?: (v: T) => void): WritableBox<T> {
+	return boxWith(get, (v) => {
+		set(v);
+		notify?.(v);
+	});
+}
+
+/**
+ * Repair a bindable value synchronously for setup/SSR, then repair it again
+ * before DOM updates whenever the tracked source changes.
+ */
+export function repairBindable(track: () => unknown, repair: () => void) {
+	repair();
+
+	$effect.pre(() => {
+		track();
+		untrack(repair);
+	});
+}
+
+export const simpleBox = createWritableBox;
+
+export { boxWith };
+
+type BoxAutoResetOptions<T> = {
+	afterMs?: number;
+	onChange?: (value: T) => void;
+	getWindow: () => Window & typeof globalThis;
+};
+
+const defaultBoxAutoResetOptions: Partial<BoxAutoResetOptions<unknown>> = {
+	afterMs: 10000,
+	onChange: () => {},
+};
+
+/**
+ * Creates a box which will be reset to the default value after some time.
+ *
+ * @param defaultValue The value which will be set.
+ * @param afterMs      A zero-or-greater delay in milliseconds.
+ */
+export function boxAutoReset<T>(defaultValue: T, options: BoxAutoResetOptions<T>): WritableBox<T> {
+	const { afterMs, onChange, getWindow } = { ...defaultBoxAutoResetOptions, ...options };
+
+	let timeout: number | null = null;
+	let value = $state(defaultValue);
+
+	function resetAfter() {
+		return getWindow().setTimeout(() => {
+			value = defaultValue;
+			onChange?.(defaultValue);
+		}, afterMs);
+	}
+
+	$effect(() => {
+		return () => {
+			if (timeout) getWindow().clearTimeout(timeout);
+		};
+	});
+
+	return boxWith(
+		() => value,
+		(v) => {
+			value = v;
+			onChange?.(v);
+			if (timeout) getWindow().clearTimeout(timeout);
+			timeout = resetAfter();
+		},
+	);
+}

package/src/lib/internal/tools/index.ts

@@ -0,0 +1,22 @@
+export {
+	bindableWith,
+	boxWith,
+	boxAutoReset,
+	repairBindable,
+	simpleBox,
+	type WritableBox,
+	type ReadableBox,
+} from './box.svelte.js';
+export { get } from './types.js';
+export type {
+	AnyFn,
+	Box,
+	Expand,
+	Getter,
+	MaybeGetter,
+	ReadableBoxedValues,
+	WithChildren,
+	WithRefProps,
+	WritableBoxedValues,
+} from './types.js';
+export * from './utils/index.js';

package/src/lib/internal/tools/types.ts

@@ -0,0 +1,44 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Snippet } from 'svelte';
+import type { ReadableBox, WritableBox } from './box.svelte.js';
+import { BROWSER } from 'esm-env';
+
+export type Getter<T> = () => T;
+export type MaybeGetter<T> = T | Getter<T>;
+
+export const get = <T>(value: MaybeGetter<T>): T => (typeof value === 'function' ? (value as Getter<T>)() : value);
+
+export type Box<T> = ReadableBox<T> | WritableBox<T>;
+
+export type Expand<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
+
+/**
+ * Given a Record type T, returns a type that represents the same type, but with
+ * all values wrapped in a `ReadableBox`.
+ */
+export type ReadableBoxedValues<T> = {
+	[K in keyof T]: ReadableBox<T[K]>;
+};
+
+/**
+ * Given a Record type T, returns a type that represents the same type, but with
+ * all values wrapped in a `WritableBox`.
+ */
+export type WritableBoxedValues<T> = {
+	[K in keyof T]: WritableBox<T[K]>;
+};
+
+export type WithChildren<Props = {}> = Props & {
+	children?: Snippet | undefined;
+};
+
+export type WithRefProps<T = {}> = T & ReadableBoxedValues<{ id: string }> & WritableBoxedValues<{ ref: HTMLElement | null }>;
+
+/** camelCase CSS property names from the DOM lib, plus custom properties. Values are not typed per property: every
+ *  style object here ends up in overrule's `styleToString`, which takes strings anyway. */
+type CSSPropertyName = {
+	[K in keyof CSSStyleDeclaration]: K extends string ? (CSSStyleDeclaration[K] extends string ? K : never) : never;
+}[keyof CSSStyleDeclaration];
+export type StyleProperties = Partial<Record<CSSPropertyName, string | number>> & { [custom: `--${string}`]: string | number };
+
+export type AnyFn = (...args: any[]) => any;

package/src/lib/internal/tools/utils/attach-ref.ts

@@ -0,0 +1,74 @@
+import { untrack } from 'svelte';
+import { createAttachmentKey, type Attachment } from 'svelte/attachments';
+
+export type RefSetter<T> = (value: T) => void;
+export type WritableRef<T> = { current: T };
+export type RefAttachment<T extends EventTarget = Element> = {
+	[key: symbol]: Attachment<T>;
+};
+
+const shouldClearRef = (node: EventTarget) => !('isConnected' in node && node.isConnected === true);
+
+/**
+ * Creates a Svelte Attachment that attaches a DOM element to a ref.
+ * The ref can be either a writable ref object or a callback function.
+ *
+ * @param ref - Either a writable ref object to store the element in, or a callback function that receives the element
+ * @param onChange - Optional callback that fires when the ref changes
+ * @returns An object with a spreadable attachment key that should be spread onto the element
+ *
+ * @example
+ * // Using with a writable ref object
+ * const ref = box<HTMLDivElement | null>(null);
+ * <div {...attachRef(ref)}>Content</div>
+ *
+ * @example
+ * // Using with callback
+ * <div {...attachRef((node) => myNode = node)}>Content</div>
+ *
+ * @example
+ * // Using with onChange
+ * <div {...attachRef(ref, (node) => console.log(node))}>Content</div>
+ */
+export function attachRef<T extends EventTarget = Element>(
+	ref: WritableRef<T | null> | RefSetter<T | null>,
+	onChange?: (value: T | null) => void,
+): RefAttachment<T> {
+	return {
+		[createAttachmentKey()]: (node) => {
+			if (typeof ref === 'function') {
+				ref(node);
+				untrack(() => onChange?.(node));
+
+				return () => {
+					if (!shouldClearRef(node)) return;
+
+					ref(null);
+					onChange?.(null);
+				};
+			}
+
+			ref.current = node;
+			untrack(() => onChange?.(node));
+
+			return () => {
+				if (!shouldClearRef(node)) return;
+
+				ref.current = null;
+				onChange?.(null);
+			};
+		},
+	};
+}
+
+export function mountedAttachment<T extends EventTarget = Element>(setMounted: (mounted: boolean) => void): RefAttachment<T> {
+	return {
+		[createAttachmentKey()]: () => {
+			setMounted(true);
+
+			return () => {
+				setMounted(false);
+			};
+		},
+	};
+}