@comp0/core 0.1.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mewhhaha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @comp0/core
+
+React 19 behavior hooks and DOM utilities for building accessible headless interfaces. It includes interaction hooks, controllable state, collection and focus utilities, prop merging, ref composition, and presence-based data attributes.
+
+```sh
+pnpm add @comp0/core react@^19
+```
+
+```tsx
+import { dataAttr, usePress } from "@comp0/core";
+
+function PressSurface() {
+  const { pressProps, isPressed } = usePress<HTMLButtonElement>();
+  return (
+    <button {...pressProps} data-pressed={dataAttr(isPressed)}>
+      Press
+    </button>
+  );
+}
+```
+
+The package has one root entry point, and its published JavaScript is already transformed by the React Compiler. See the [documentation](https://comp0-docs.horrible.workers.dev) for API details.
+
+MIT licensed.

package/dist/collection.d.ts

@@ -0,0 +1,25 @@
+/** A logical collection entry, independent from the element used to render it. */
+export type CollectionNode<TValue = string, TKey = string> = {
+    /** Stable application identity used for selection, focus, and collection lookup. */
+    key: TKey;
+    /** The DOM id of the rendered element, when the collection participates in ARIA relationships. */
+    id: string;
+    value: TValue;
+    textValue: string;
+    disabled?: boolean;
+    element: HTMLElement | null;
+};
+/** Returns a copy of collection entries in their current DOM order. */
+export declare function sortByDocumentPosition<TValue, TKey>(items: CollectionNode<TValue, TKey>[]): CollectionNode<TValue, TKey>[];
+/**
+ * Registers collection entries and reads them in DOM order.
+ *
+ * `key` identifies the logical item; `id` remains available for DOM and ARIA references.
+ */
+type CollectionRegistry<TValue, TKey> = {
+    register: (node: CollectionNode<TValue, TKey>) => () => void;
+    getItems: () => CollectionNode<TValue, TKey>[];
+    getEnabledItems: () => CollectionNode<TValue, TKey>[];
+};
+export declare function useCollectionRegistry<TValue = string, TKey = string>(): CollectionRegistry<TValue, TKey>;
+export {};

package/dist/collection.js

@@ -0,0 +1,65 @@
+import { c as _c } from "react/compiler-runtime";
+import { useCallback, useRef } from "react";
+/** Returns a copy of collection entries in their current DOM order. */
+export function sortByDocumentPosition(items) {
+	return [...items].sort((a, b) => {
+		if (!a.element || !b.element || a.element === b.element) return 0;
+		const position = a.element.compareDocumentPosition(b.element);
+		return position & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1;
+	});
+}
+export function useCollectionRegistry() {
+	const $ = _c(5);
+	let t0;
+	if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+		t0 = new Map();
+		$[0] = t0;
+	} else {
+		t0 = $[0];
+	}
+	const itemsRef = useRef(t0);
+	let t1;
+	if ($[1] === Symbol.for("react.memo_cache_sentinel")) {
+		t1 = (node) => {
+			itemsRef.current.set(node.key, node);
+			return () => {
+				itemsRef.current.delete(node.key);
+			};
+		};
+		$[1] = t1;
+	} else {
+		t1 = $[1];
+	}
+	const register = t1;
+	let t2;
+	if ($[2] === Symbol.for("react.memo_cache_sentinel")) {
+		t2 = () => sortByDocumentPosition([...itemsRef.current.values()]);
+		$[2] = t2;
+	} else {
+		t2 = $[2];
+	}
+	const getItems = t2;
+	let t3;
+	if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
+		t3 = () => getItems().filter(_temp);
+		$[3] = t3;
+	} else {
+		t3 = $[3];
+	}
+	const getEnabledItems = t3;
+	let t4;
+	if ($[4] === Symbol.for("react.memo_cache_sentinel")) {
+		t4 = {
+			register,
+			getItems,
+			getEnabledItems
+		};
+		$[4] = t4;
+	} else {
+		t4 = $[4];
+	}
+	return t4;
+}
+function _temp(item) {
+	return !item.disabled;
+}

package/dist/date.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure ISO calendar-date helpers. Every public value is a "YYYY-MM-DD"
+ * string; Date objects only appear internally, pinned to UTC noon so
+ * daylight-saving transitions can never skip or repeat a calendar day.
+ */
+/** One cell of a month matrix: an ISO date plus whether it belongs to a neighboring month. */
+export type MonthMatrixCell = {
+    iso: string;
+    outsideMonth: boolean;
+};
+/** The number of days in a one-based month of a given year. */
+export declare function daysInMonth(year: number, month: number): number;
+/** Parses "YYYY-MM-DD" into a UTC-noon Date, or null for malformed or impossible dates. */
+export declare function parseISODate(value: string): Date | null;
+/** Formats a Date's UTC calendar day as "YYYY-MM-DD". */
+export declare function formatISODate(date: Date): string;
+/** Whether a string is a real "YYYY-MM-DD" calendar date. */
+export declare function isValidISODate(value: string): boolean;
+/** Today's date in the runtime's local timezone as "YYYY-MM-DD". */
+export declare function todayISODate(): string;
+/** Adds days to an ISO date; UTC-noon arithmetic keeps DST from shifting the day. */
+export declare function addDays(iso: string, amount: number): string;
+/** Adds months to an ISO date, clamping the day to the target month's end (Jan 31 + 1 month is Feb 29 in a leap year). */
+export declare function addMonths(iso: string, amount: number): string;
+/** Whether ISO date a falls strictly before b. */
+export declare function isBefore(a: string, b: string): boolean;
+/** Whether ISO date a falls strictly after b. */
+export declare function isAfter(a: string, b: string): boolean;
+/** Clamps an ISO date into an inclusive [min, max] range; either bound may be omitted. */
+export declare function clampISODate(iso: string, min: string | undefined, max: string | undefined): string;
+/**
+ * Weeks covering an ISO month ("YYYY-MM"), each exactly seven cells wide.
+ * weekStart follows the Intl.Locale weekInfo convention: 1 = Monday through
+ * 7 = Sunday. Leading and trailing cells from neighboring months are marked
+ * outsideMonth.
+ */
+export declare function monthMatrix(isoMonth: string, weekStart: number): MonthMatrixCell[][];

package/dist/date.js

@@ -0,0 +1,97 @@
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_MONTH_PATTERN = /^(\d{4})-(\d{2})$/;
+/** The number of days in a one-based month of a given year. */
+export function daysInMonth(year, month) {
+	return new Date(Date.UTC(year, month, 0, 12)).getUTCDate();
+}
+/** Parses "YYYY-MM-DD" into a UTC-noon Date, or null for malformed or impossible dates. */
+export function parseISODate(value) {
+	const match = ISO_DATE_PATTERN.exec(value);
+	if (!match) return null;
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	const day = Number(match[3]);
+	if (month < 1 || month > 12) return null;
+	if (day < 1 || day > daysInMonth(year, month)) return null;
+	return new Date(Date.UTC(year, month - 1, day, 12));
+}
+/** Formats a Date's UTC calendar day as "YYYY-MM-DD". */
+export function formatISODate(date) {
+	const year = String(date.getUTCFullYear()).padStart(4, "0");
+	const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+	const day = String(date.getUTCDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+/** Whether a string is a real "YYYY-MM-DD" calendar date. */
+export function isValidISODate(value) {
+	return parseISODate(value) !== null;
+}
+/** Today's date in the runtime's local timezone as "YYYY-MM-DD". */
+export function todayISODate() {
+	const now = new Date();
+	return formatISODate(new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate(), 12)));
+}
+/** Adds days to an ISO date; UTC-noon arithmetic keeps DST from shifting the day. */
+export function addDays(iso, amount) {
+	const date = parseISODate(iso);
+	if (!date) return iso;
+	date.setUTCDate(date.getUTCDate() + amount);
+	return formatISODate(date);
+}
+/** Adds months to an ISO date, clamping the day to the target month's end (Jan 31 + 1 month is Feb 29 in a leap year). */
+export function addMonths(iso, amount) {
+	const date = parseISODate(iso);
+	if (!date) return iso;
+	const monthIndex = date.getUTCMonth() + amount;
+	const year = date.getUTCFullYear() + Math.floor(monthIndex / 12);
+	const month = (monthIndex % 12 + 12) % 12 + 1;
+	const day = Math.min(date.getUTCDate(), daysInMonth(year, month));
+	return formatISODate(new Date(Date.UTC(year, month - 1, day, 12)));
+}
+/** Whether ISO date a falls strictly before b. */
+export function isBefore(a, b) {
+	return a < b;
+}
+/** Whether ISO date a falls strictly after b. */
+export function isAfter(a, b) {
+	return a > b;
+}
+/** Clamps an ISO date into an inclusive [min, max] range; either bound may be omitted. */
+export function clampISODate(iso, min, max) {
+	if (min && isBefore(iso, min)) return min;
+	if (max && isAfter(iso, max)) return max;
+	return iso;
+}
+/**
+* Weeks covering an ISO month ("YYYY-MM"), each exactly seven cells wide.
+* weekStart follows the Intl.Locale weekInfo convention: 1 = Monday through
+* 7 = Sunday. Leading and trailing cells from neighboring months are marked
+* outsideMonth.
+*/
+export function monthMatrix(isoMonth, weekStart) {
+	const match = ISO_MONTH_PATTERN.exec(isoMonth);
+	if (!match) return [];
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	if (month < 1 || month > 12) return [];
+	const first = new Date(Date.UTC(year, month - 1, 1, 12));
+	// getUTCDay counts 0 = Sunday through 6; weekInfo counts 1 = Monday through 7 = Sunday.
+	const firstWeekday = first.getUTCDay() === 0 ? 7 : first.getUTCDay();
+	const lead = (firstWeekday - weekStart + 7) % 7;
+	const total = daysInMonth(year, month);
+	const weekCount = Math.ceil((lead + total) / 7);
+	const weeks = [];
+	for (let weekIndex = 0; weekIndex < weekCount; weekIndex += 1) {
+		const week = [];
+		for (let dayIndex = 0; dayIndex < 7; dayIndex += 1) {
+			const offset = weekIndex * 7 + dayIndex - lead;
+			const date = new Date(Date.UTC(year, month - 1, 1 + offset, 12));
+			week.push({
+				iso: formatISODate(date),
+				outsideMonth: date.getUTCMonth() !== month - 1
+			});
+		}
+		weeks.push(week);
+	}
+	return weeks;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./collection.js";
+export * from "./date.js";
+export * from "./interactions.js";
+export * from "./roving-focus.js";
+export * from "./state.js";
+export * from "./typeahead.js";
+export * from "./utils.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./collection.js";
+export * from "./date.js";
+export * from "./interactions.js";
+export * from "./roving-focus.js";
+export * from "./state.js";
+export * from "./typeahead.js";
+export * from "./utils.js";

package/dist/interactions.d.ts

@@ -0,0 +1,30 @@
+import { type HTMLAttributes } from "react";
+/**
+ * Tracks focus and keyboard-visible focus for an element.
+ *
+ * Modality listeners are installed only after the element receives focus, on that
+ * element's `ownerDocument`, and are removed when no focus ring remains focused.
+ */
+export declare function useFocusRing<TElement extends HTMLElement = HTMLElement>(options?: {
+    disabled?: boolean;
+}): {
+    focusProps: HTMLAttributes<TElement>;
+    isFocused: boolean;
+    isFocusVisible: boolean;
+};
+/** Tracks pointer hover while ignoring touch pointers and disabled elements. */
+export declare function useHover<TElement extends HTMLElement = HTMLElement>(options?: {
+    disabled?: boolean;
+}): {
+    hoverProps: HTMLAttributes<TElement>;
+    isHovered: boolean;
+};
+/** Tracks pointer and keyboard press state for an element. */
+export declare function usePress<TElement extends HTMLElement = HTMLElement>(options?: {
+    disabled?: boolean;
+}): {
+    pressProps: HTMLAttributes<TElement>;
+    isPressed: boolean;
+};
+/** Merges interaction props, chaining event handlers in declaration order. */
+export declare function mergeInteractionProps<T extends HTMLAttributes<HTMLElement>>(...propsList: T[]): T;

package/dist/interactions.js

@@ -0,0 +1,251 @@
+import { c as _c } from "react/compiler-runtime";
+import { useEffect, useRef, useState } from "react";
+import { chainHandlers } from "./utils.js";
+const focusVisibleDocumentStates = new WeakMap();
+function getFocusVisibleDocumentState(ownerDocument) {
+	let state = focusVisibleDocumentStates.get(ownerDocument);
+	if (!state) {
+		const subscribers = new Set();
+		const notify = () => {
+			for (const callback of subscribers) callback();
+		};
+		const nextState = {
+			hadKeyboardEvent: false,
+			subscribers,
+			onKeyDown(event) {
+				if (event.metaKey || event.altKey || event.ctrlKey) return;
+				nextState.hadKeyboardEvent = true;
+				notify();
+			},
+			onPointerDown() {
+				nextState.hadKeyboardEvent = false;
+				notify();
+			}
+		};
+		state = nextState;
+		focusVisibleDocumentStates.set(ownerDocument, state);
+	}
+	return state;
+}
+function subscribeToFocusVisible(ownerDocument, subscriber) {
+	const state = getFocusVisibleDocumentState(ownerDocument);
+	if (state.subscribers.size === 0) {
+		ownerDocument.addEventListener("keydown", state.onKeyDown, true);
+		ownerDocument.addEventListener("pointerdown", state.onPointerDown, true);
+	}
+	state.subscribers.add(subscriber);
+	return () => {
+		state.subscribers.delete(subscriber);
+		if (state.subscribers.size !== 0) return;
+		ownerDocument.removeEventListener("keydown", state.onKeyDown, true);
+		ownerDocument.removeEventListener("pointerdown", state.onPointerDown, true);
+		focusVisibleDocumentStates.delete(ownerDocument);
+	};
+}
+/**
+* Tracks focus and keyboard-visible focus for an element.
+*
+* Modality listeners are installed only after the element receives focus, on that
+* element's `ownerDocument`, and are removed when no focus ring remains focused.
+*/
+export function useFocusRing(t0) {
+	const $ = _c(12);
+	let t1;
+	if ($[0] !== t0) {
+		t1 = t0 === undefined ? {} : t0;
+		$[0] = t0;
+		$[1] = t1;
+	} else {
+		t1 = $[1];
+	}
+	const options = t1;
+	const [isFocused, setFocused] = useState(false);
+	const [isFocusVisible, setFocusVisible] = useState(false);
+	const [ownerDocument, setOwnerDocument] = useState();
+	const isFocusedRef = useRef(false);
+	let t2;
+	let t3;
+	if ($[2] !== isFocused || $[3] !== ownerDocument) {
+		t2 = () => {
+			if (!ownerDocument || !isFocused) {
+				return;
+			}
+			return subscribeToFocusVisible(ownerDocument, () => {
+				if (isFocusedRef.current) {
+					setFocusVisible(getFocusVisibleDocumentState(ownerDocument).hadKeyboardEvent);
+				}
+			});
+		};
+		t3 = [isFocused, ownerDocument];
+		$[2] = isFocused;
+		$[3] = ownerDocument;
+		$[4] = t2;
+		$[5] = t3;
+	} else {
+		t2 = $[4];
+		t3 = $[5];
+	}
+	useEffect(t2, t3);
+	let t4;
+	if ($[6] !== options) {
+		t4 = {
+			onFocus(event) {
+				if (options.disabled) {
+					return;
+				}
+				const document = event.currentTarget.ownerDocument;
+				isFocusedRef.current = true;
+				setOwnerDocument(document);
+				setFocused(true);
+				setFocusVisible(getFocusVisibleDocumentState(document).hadKeyboardEvent || event.currentTarget.matches(":focus-visible"));
+			},
+			onBlur() {
+				isFocusedRef.current = false;
+				setFocused(false);
+				setFocusVisible(false);
+			}
+		};
+		$[6] = options;
+		$[7] = t4;
+	} else {
+		t4 = $[7];
+	}
+	const focusProps = t4;
+	let t5;
+	if ($[8] !== focusProps || $[9] !== isFocusVisible || $[10] !== isFocused) {
+		t5 = {
+			focusProps,
+			isFocused,
+			isFocusVisible
+		};
+		$[8] = focusProps;
+		$[9] = isFocusVisible;
+		$[10] = isFocused;
+		$[11] = t5;
+	} else {
+		t5 = $[11];
+	}
+	return t5;
+}
+/** Tracks pointer hover while ignoring touch pointers and disabled elements. */
+export function useHover(t0) {
+	const $ = _c(7);
+	let t1;
+	if ($[0] !== t0) {
+		t1 = t0 === undefined ? {} : t0;
+		$[0] = t0;
+		$[1] = t1;
+	} else {
+		t1 = $[1];
+	}
+	const options = t1;
+	const [isHovered, setHovered] = useState(false);
+	let t2;
+	if ($[2] !== options) {
+		t2 = {
+			onPointerEnter(event) {
+				if (options.disabled || event.pointerType === "touch") {
+					return;
+				}
+				setHovered(true);
+			},
+			onPointerLeave() {
+				setHovered(false);
+			}
+		};
+		$[2] = options;
+		$[3] = t2;
+	} else {
+		t2 = $[3];
+	}
+	const hoverProps = t2;
+	let t3;
+	if ($[4] !== hoverProps || $[5] !== isHovered) {
+		t3 = {
+			hoverProps,
+			isHovered
+		};
+		$[4] = hoverProps;
+		$[5] = isHovered;
+		$[6] = t3;
+	} else {
+		t3 = $[6];
+	}
+	return t3;
+}
+/** Tracks pointer and keyboard press state for an element. */
+export function usePress(t0) {
+	const $ = _c(7);
+	let t1;
+	if ($[0] !== t0) {
+		t1 = t0 === undefined ? {} : t0;
+		$[0] = t0;
+		$[1] = t1;
+	} else {
+		t1 = $[1];
+	}
+	const options = t1;
+	const [isPressed, setPressed] = useState(false);
+	let t2;
+	if ($[2] !== options) {
+		t2 = {
+			onPointerDown(event) {
+				if (options.disabled || event.button !== 0) {
+					return;
+				}
+				setPressed(true);
+			},
+			onPointerUp() {
+				setPressed(false);
+			},
+			onPointerCancel() {
+				setPressed(false);
+			},
+			onPointerLeave() {
+				setPressed(false);
+			},
+			onKeyDown(event_0) {
+				if (options.disabled) {
+					return;
+				}
+				if (event_0.key === " " || event_0.key === "Enter") {
+					setPressed(true);
+				}
+			},
+			onKeyUp() {
+				setPressed(false);
+			}
+		};
+		$[2] = options;
+		$[3] = t2;
+	} else {
+		t2 = $[3];
+	}
+	const pressProps = t2;
+	let t3;
+	if ($[4] !== isPressed || $[5] !== pressProps) {
+		t3 = {
+			pressProps,
+			isPressed
+		};
+		$[4] = isPressed;
+		$[5] = pressProps;
+		$[6] = t3;
+	} else {
+		t3 = $[6];
+	}
+	return t3;
+}
+/** Merges interaction props, chaining event handlers in declaration order. */
+export function mergeInteractionProps(...propsList) {
+	return propsList.reduce((acc, props) => {
+		for (const [key, value] of Object.entries(props)) {
+			if (/^on[A-Z]/.test(key) && typeof value === "function" && typeof acc[key] === "function") {
+				acc[key] = chainHandlers(acc[key], value);
+			} else {
+				acc[key] = value;
+			}
+		}
+		return acc;
+	}, {});
+}

package/dist/roving-focus.d.ts

@@ -0,0 +1,13 @@
+/** The arrow-key directions supported by a roving-focus collection. */
+export type RovingFocusOrientation = "horizontal" | "vertical" | "both";
+/** The identity and enabled state needed for roving focus navigation. */
+export interface RovingFocusItem {
+    key: string;
+    disabled?: boolean | undefined;
+}
+/** Resolves the next enabled item for an APG-style roving-focus key press. */
+export declare function getRovingFocusTarget(items: RovingFocusItem[], currentKey: string | undefined, key: string, options?: {
+    orientation?: RovingFocusOrientation;
+    dir?: "ltr" | "rtl";
+    loop?: boolean;
+}): string | undefined;

package/dist/roving-focus.js

@@ -0,0 +1,28 @@
+function isForwardKey(key, orientation, dir) {
+	if (orientation !== "vertical" && key === "ArrowRight") return dir === "ltr";
+	if (orientation !== "vertical" && key === "ArrowLeft") return dir === "rtl";
+	if (orientation !== "horizontal" && key === "ArrowDown") return true;
+	return false;
+}
+function isBackwardKey(key, orientation, dir) {
+	if (orientation !== "vertical" && key === "ArrowLeft") return dir === "ltr";
+	if (orientation !== "vertical" && key === "ArrowRight") return dir === "rtl";
+	if (orientation !== "horizontal" && key === "ArrowUp") return true;
+	return false;
+}
+/** Resolves the next enabled item for an APG-style roving-focus key press. */
+export function getRovingFocusTarget(items, currentKey, key, options = {}) {
+	const orientation = options.orientation ?? "both";
+	const dir = options.dir ?? "ltr";
+	const enabledItems = items.filter((item) => !item.disabled);
+	if (!enabledItems.length) return undefined;
+	if (key === "Home") return enabledItems[0]?.key;
+	if (key === "End") return enabledItems.at(-1)?.key;
+	const direction = isForwardKey(key, orientation, dir) ? 1 : isBackwardKey(key, orientation, dir) ? -1 : 0;
+	if (direction === 0) return undefined;
+	const currentIndex = Math.max(0, enabledItems.findIndex((item) => item.key === currentKey));
+	const nextIndex = currentIndex + direction;
+	if (nextIndex >= 0 && nextIndex < enabledItems.length) return enabledItems[nextIndex]?.key;
+	if (!options.loop) return enabledItems[currentIndex]?.key;
+	return direction > 0 ? enabledItems[0]?.key : enabledItems.at(-1)?.key;
+}

package/dist/state.d.ts

@@ -0,0 +1,10 @@
+/** Options for a controlled or uncontrolled state value. */
+export interface ControllableStateOptions<T> {
+    value?: T | undefined;
+    defaultValue: T;
+    onChange?: ((value: T) => void) | undefined;
+}
+/**
+ * Manages a value that may be controlled by the caller or initialized internally.
+ */
+export declare function useControllableState<T>(options: ControllableStateOptions<T>): readonly [T, (next: T | ((current: T) => T)) => void];

package/dist/state.js

@@ -0,0 +1,60 @@
+import { c as _c } from "react/compiler-runtime";
+import { useCallback, useRef, useState } from "react";
+import { useEventCallback, useIsoLayoutEffect } from "./utils.js";
+export function useControllableState(t0) {
+	const $ = _c(9);
+	const { value, defaultValue, onChange } = t0;
+	const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+	const isControlled = value !== undefined;
+	const currentValue = isControlled ? value : uncontrolledValue;
+	const onChangeStable = useEventCallback(onChange);
+	const currentValueRef = useRef(currentValue);
+	const isControlledRef = useRef(isControlled);
+	let t1;
+	let t2;
+	if ($[0] !== currentValue || $[1] !== isControlled) {
+		t1 = () => {
+			currentValueRef.current = currentValue;
+			isControlledRef.current = isControlled;
+		};
+		t2 = [currentValue, isControlled];
+		$[0] = currentValue;
+		$[1] = isControlled;
+		$[2] = t1;
+		$[3] = t2;
+	} else {
+		t1 = $[2];
+		t2 = $[3];
+	}
+	useIsoLayoutEffect(t1, t2);
+	let t3;
+	if ($[4] !== onChangeStable) {
+		t3 = (next) => {
+			const previousValue = currentValueRef.current;
+			const resolvedValue = typeof next === "function" ? next(previousValue) : next;
+			if (Object.is(resolvedValue, previousValue)) {
+				return;
+			}
+			currentValueRef.current = resolvedValue;
+			if (!isControlledRef.current) {
+				setUncontrolledValue(resolvedValue);
+			}
+			onChangeStable(resolvedValue);
+		};
+		$[4] = onChangeStable;
+		$[5] = t3;
+	} else {
+		t3 = $[5];
+	}
+	const setValue = t3;
+	let t4;
+	if ($[6] !== currentValue || $[7] !== setValue) {
+		t4 = [currentValue, setValue];
+		$[6] = currentValue;
+		$[7] = setValue;
+		$[8] = t4;
+	} else {
+		t4 = $[8];
+	}
+	return t4;
+}

package/dist/typeahead.d.ts

@@ -0,0 +1,21 @@
+/** The search fields needed to match a collection item by typed text. */
+export interface TypeaheadItem {
+    key: string;
+    textValue: string;
+    disabled?: boolean | undefined;
+}
+/** Finds the next enabled item whose text begins with the search string. */
+export declare function findTypeaheadMatch(items: TypeaheadItem[], search: string, currentKey?: string): string | undefined;
+/**
+ * Returns an accumulator for typeahead searches: each printable key extends
+ * the search string until the timeout elapses, so typing "co" matches
+ * "Copy" instead of jumping between "c" and "o" items.
+ */
+export declare function useTypeaheadSearch(timeout?: number): (key: string) => string;
+/** Returns a keyboard handler that buffers printable characters for typeahead navigation. */
+export declare function useTypeahead(options: {
+    items: TypeaheadItem[];
+    currentKey?: string | undefined;
+    timeout?: number;
+    onMatch: (key: string) => void;
+}): (event: Pick<KeyboardEvent, "key" | "preventDefault">) => void;

package/dist/typeahead.js

@@ -0,0 +1,67 @@
+import { c as _c } from "react/compiler-runtime";
+import { useRef } from "react";
+/** Finds the next enabled item whose text begins with the search string. */
+export function findTypeaheadMatch(items, search, currentKey) {
+	const enabled = items.filter((item) => !item.disabled);
+	if (!search || !enabled.length) return undefined;
+	const startIndex = Math.max(0, enabled.findIndex((item) => item.key === currentKey) + 1);
+	const ordered = [...enabled.slice(startIndex), ...enabled.slice(0, startIndex)];
+	const normalizedSearch = search.toLocaleLowerCase();
+	return ordered.find((item) => item.textValue.toLocaleLowerCase().startsWith(normalizedSearch))?.key;
+}
+/**
+* Returns an accumulator for typeahead searches: each printable key extends
+* the search string until the timeout elapses, so typing "co" matches
+* "Copy" instead of jumping between "c" and "o" items.
+*/
+export function useTypeaheadSearch(t0) {
+	const $ = _c(2);
+	const timeout = t0 === undefined ? 700 : t0;
+	const bufferRef = useRef("");
+	const timeoutRef = useRef(undefined);
+	let t1;
+	if ($[0] !== timeout) {
+		t1 = (key) => {
+			window.clearTimeout(timeoutRef.current);
+			timeoutRef.current = window.setTimeout(() => {
+				bufferRef.current = "";
+			}, timeout);
+			bufferRef.current = bufferRef.current + key;
+			return bufferRef.current;
+		};
+		$[0] = timeout;
+		$[1] = t1;
+	} else {
+		t1 = $[1];
+	}
+	return t1;
+}
+/** Returns a keyboard handler that buffers printable characters for typeahead navigation. */
+export function useTypeahead(options) {
+	const $ = _c(2);
+	const bufferRef = useRef("");
+	const timeoutRef = useRef(undefined);
+	let t0;
+	if ($[0] !== options) {
+		t0 = (event) => {
+			if (event.key.length !== 1 || event.key.trim() === "") {
+				return;
+			}
+			window.clearTimeout(timeoutRef.current);
+			bufferRef.current = bufferRef.current + event.key;
+			timeoutRef.current = window.setTimeout(() => {
+				bufferRef.current = "";
+			}, options.timeout ?? 700);
+			const match = findTypeaheadMatch(options.items, bufferRef.current, options.currentKey);
+			if (match) {
+				event.preventDefault();
+				options.onMatch(match);
+			}
+		};
+		$[0] = options;
+		$[1] = t0;
+	} else {
+		t0 = $[1];
+	}
+	return t0;
+}

package/dist/utils.d.ts

@@ -0,0 +1,35 @@
+import { type Ref, type RefCallback, useLayoutEffect } from "react";
+/** A minimal event handler shape used by prop-composition utilities. */
+export type AnyEventHandler = (event: {
+    defaultPrevented?: boolean;
+}) => void;
+/** A callback ref, object ref, or omitted ref. */
+export type PossibleRef<T> = Ref<T> | undefined;
+type RefCleanup = () => void;
+/** Whether DOM globals are available in the current runtime. */
+export declare const isBrowser: boolean;
+/** Uses a layout effect in the browser and an effect during server rendering. */
+export declare const useIsoLayoutEffect: typeof useLayoutEffect;
+/** Assigns a value to either form of React ref and returns its React 19 cleanup. */
+export declare function assignRef<T>(ref: PossibleRef<T>, value: T | null): RefCleanup | undefined;
+/** Combines refs into one callback ref that preserves every ref cleanup. */
+export declare function composeRefs<T>(...refs: PossibleRef<T>[]): RefCallback<T>;
+/** Returns a stable callback ref that always writes to the latest supplied refs. */
+export declare function useComposedRefs<T>(...refs: PossibleRef<T>[]): RefCallback<T>;
+/** Returns a stable callback that invokes the latest supplied implementation. */
+export declare function useEventCallback<T extends (...args: never[]) => unknown>(callback: T | undefined): (...args: Parameters<T>) => ReturnType<T> | undefined;
+/** Chains handlers, allowing the first to prevent the second by default. */
+export declare function chainHandlers<T extends AnyEventHandler>(theirs: T | undefined, ours: T | undefined, options?: {
+    checkDefaultPrevented?: boolean;
+}): (event: Parameters<T>[0]) => void;
+/** Merges DOM props, concatenating classes, merging styles, and chaining handlers. */
+export declare function mergeProps<T extends Record<string, unknown>>(...propsList: (T | undefined)[]): T;
+/** Returns an empty string for a present boolean data attribute. */
+export declare function dataAttr(value: boolean | undefined): "" | undefined;
+/** Converts named boolean states into presence-based `data-*` attributes. */
+export declare function dataAttributes(states: Record<string, boolean | undefined>): {
+    [k: string]: string;
+};
+/** Invokes every supplied callback in declaration order. */
+export declare function callAll<T extends (...args: never[]) => unknown>(...callbacks: (T | undefined)[]): (...args: Parameters<T>) => void;
+export {};

package/dist/utils.js

@@ -0,0 +1,193 @@
+import { c as _c } from "react/compiler-runtime";
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
+/** Whether DOM globals are available in the current runtime. */
+export const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+/** Uses a layout effect in the browser and an effect during server rendering. */
+export const useIsoLayoutEffect = isBrowser ? useLayoutEffect : useEffect;
+/** Assigns a value to either form of React ref and returns its React 19 cleanup. */
+export function assignRef(ref, value) {
+	if (typeof ref === "function") {
+		const cleanup = ref(value);
+		if (typeof cleanup === "function") return cleanup;
+		if (value !== null) return () => ref(null);
+		return undefined;
+	}
+	if (ref) {
+		ref.current = value;
+		if (value !== null) {
+			return () => {
+				if (ref.current === value) ref.current = null;
+			};
+		}
+	}
+	return undefined;
+}
+/** Combines refs into one callback ref that preserves every ref cleanup. */
+export function composeRefs(...refs) {
+	return (value) => {
+		const cleanups = refs.flatMap((ref) => assignRef(ref, value) ?? []);
+		if (value === null || cleanups.length === 0) return undefined;
+		return () => {
+			for (const cleanup of cleanups) cleanup();
+		};
+	};
+}
+export function useComposedRefs(...t0) {
+	const $ = _c(4);
+	const refs = t0;
+	const refsRef = useRef(refs);
+	const valueRef = useRef(null);
+	let t1;
+	if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+		t1 = [];
+		$[0] = t1;
+	} else {
+		t1 = $[0];
+	}
+	const assignmentsRef = useRef(t1);
+	let t2;
+	if ($[1] !== refs) {
+		t2 = () => {
+			const value = valueRef.current;
+			refsRef.current = refs;
+			if (value === null) {
+				return;
+			}
+			const previousAssignments = [...assignmentsRef.current];
+			const nextAssignments = refs.map((ref) => {
+				const previousIndex = previousAssignments.findIndex((assignment) => assignment.ref === ref);
+				if (previousIndex === -1) {
+					return {
+						ref,
+						cleanup: undefined,
+						pending: true
+					};
+				}
+				const [previous] = previousAssignments.splice(previousIndex, 1);
+				return {
+					...previous,
+					pending: false
+				};
+			});
+			for (const assignment_0 of previousAssignments) {
+				assignment_0.cleanup?.();
+			}
+			assignmentsRef.current = nextAssignments.map((t3) => {
+				const { ref: ref_0, cleanup, pending } = t3;
+				return {
+					ref: ref_0,
+					cleanup: pending ? assignRef(ref_0, value) : cleanup
+				};
+			});
+		};
+		$[1] = refs;
+		$[2] = t2;
+	} else {
+		t2 = $[2];
+	}
+	useIsoLayoutEffect(t2);
+	let t3;
+	if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
+		t3 = (value_0) => {
+			for (const assignment_1 of assignmentsRef.current) {
+				assignment_1.cleanup?.();
+			}
+			assignmentsRef.current = [];
+			valueRef.current = value_0;
+			if (value_0 === null) {
+				return;
+			}
+			assignmentsRef.current = refsRef.current.map((ref_1) => ({
+				ref: ref_1,
+				cleanup: assignRef(ref_1, value_0)
+			}));
+			return () => {
+				for (const assignment_2 of assignmentsRef.current) {
+					assignment_2.cleanup?.();
+				}
+				assignmentsRef.current = [];
+				valueRef.current = null;
+			};
+		};
+		$[3] = t3;
+	} else {
+		t3 = $[3];
+	}
+	return t3;
+}
+export function useEventCallback(callback) {
+	const $ = _c(3);
+	const callbackRef = useRef(callback);
+	let t0;
+	if ($[0] !== callback) {
+		t0 = () => {
+			callbackRef.current = callback;
+		};
+		$[0] = callback;
+		$[1] = t0;
+	} else {
+		t0 = $[1];
+	}
+	useIsoLayoutEffect(t0);
+	let t1;
+	if ($[2] === Symbol.for("react.memo_cache_sentinel")) {
+		t1 = (...t2) => {
+			const args = t2;
+			return callbackRef.current?.(...args);
+		};
+		$[2] = t1;
+	} else {
+		t1 = $[2];
+	}
+	return t1;
+}
+function isEventHandler(key, value) {
+	return /^on[A-Z]/.test(key) && typeof value === "function";
+}
+/** Chains handlers, allowing the first to prevent the second by default. */
+export function chainHandlers(theirs, ours, options = {}) {
+	return (event) => {
+		theirs?.(event);
+		if (options.checkDefaultPrevented !== false && event.defaultPrevented) return;
+		ours?.(event);
+	};
+}
+/** Merges DOM props, concatenating classes, merging styles, and chaining handlers. */
+export function mergeProps(...propsList) {
+	const merged = {};
+	for (const props of propsList) {
+		if (!props) continue;
+		for (const [key, value] of Object.entries(props)) {
+			if (value === undefined) continue;
+			if (key === "className" && merged.className && value) {
+				merged.className = `${merged.className} ${value}`;
+			} else if (key === "style" && typeof value === "object" && value && typeof merged.style === "object") {
+				merged.style = {
+					...merged.style,
+					...value
+				};
+			} else if (isEventHandler(key, value) && isEventHandler(key, merged[key])) {
+				merged[key] = chainHandlers(merged[key], value);
+			} else {
+				merged[key] = value;
+			}
+		}
+	}
+	return merged;
+}
+/** Returns an empty string for a present boolean data attribute. */
+export function dataAttr(value) {
+	return value ? "" : undefined;
+}
+/** Converts named boolean states into presence-based `data-*` attributes. */
+export function dataAttributes(states) {
+	return Object.fromEntries(Object.entries(states).filter(([, value]) => value).map(([key]) => [`data-${key}`, ""]));
+}
+/** Invokes every supplied callback in declaration order. */
+export function callAll(...callbacks) {
+	return (...args) => {
+		for (const callback of callbacks) {
+			callback?.(...args);
+		}
+	};
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@comp0/core",
+  "version": "0.1.0-next.0",
+  "description": "React behavior hooks and DOM utilities for accessible headless interfaces.",
+  "keywords": [
+    "accessibility",
+    "headless",
+    "hooks",
+    "interactions",
+    "react"
+  ],
+  "homepage": "https://comp0-docs.horrible.workers.dev",
+  "bugs": {
+    "url": "https://github.com/mewhhaha/comp0/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mewhhaha/comp0.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "react": "19.2.7",
+    "react-dom": "19.2.7"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && node ../../scripts/build-package.mjs && tsgo -p tsconfig.build.json",
+    "typecheck": "tsgo -p tsconfig.json"
+  }
+}