ajo-cloves 0.1.0

package/src/resize.ts

@@ -0,0 +1,93 @@
+import type { Host } from './core'
+import { dom, live } from './core'
+
+type Callback = (el: Element) => void
+
+const registry = new WeakMap<Element, Set<Callback>>()
+let observer: ResizeObserver | undefined
+let subscriptions = 0
+
+const notify: ResizeObserverCallback = (entries, source) => {
+	if (source !== observer) return
+	for (const entry of entries) {
+		const callbacks = registry.get(entry.target)
+		if (!callbacks) continue
+
+		for (const callback of [...callbacks]) callback(entry.target)
+	}
+}
+
+const subscribe = (el: Element, fn: Callback, signal: AbortSignal) => {
+	if (signal.aborted) return
+
+	observer ??= new ResizeObserver(notify)
+	const currentObserver = observer
+
+	let callbacks = registry.get(el)
+	if (!callbacks) {
+		callbacks = new Set()
+		try {
+			currentObserver.observe(el)
+		} catch (error) {
+			try { currentObserver.unobserve(el) } catch { }
+			if (!subscriptions) {
+				try { currentObserver.disconnect() } catch { }
+				if (observer === currentObserver) observer = undefined
+			}
+			throw error
+		}
+		registry.set(el, callbacks)
+	}
+
+	callbacks.add(fn)
+	subscriptions++
+
+	const unsubscribe = () => {
+		const current = registry.get(el)
+		if (!current?.delete(fn)) return
+
+		subscriptions--
+		if (!current.size) {
+			registry.delete(el)
+			observer?.unobserve(el)
+		}
+
+		if (subscriptions) return
+
+		observer?.disconnect()
+		observer = undefined
+	}
+
+	signal.addEventListener('abort', unsubscribe, { once: true })
+}
+
+/**
+ * Shared ResizeObserver notification for a live target element.
+ *
+ * @example
+ * ```ts
+ * const size = resize(this, { target: () => panel, onResize: el => measure(el) })
+ * while (true) {
+ * 	size.sync()
+ * 	yield <section ref={el => panel = el} />
+ * }
+ * ```
+ */
+export const resize = (host: Host, opts: {
+	/** Live element to observe; call sync() after refs may have changed. */
+	target: () => Element | null | undefined
+	/** Frame-coalesced on size change and on retarget or initial sync. */
+	onResize: (el: Element) => void
+}) => {
+	if (!dom(host) || typeof ResizeObserver == 'undefined') {
+		return {
+			sync() {},
+		}
+	}
+
+	return live(host, {
+		target: opts.target,
+		onChange: opts.onResize,
+		bind: (element, notify, signal) => subscribe(element, notify, signal),
+	})
+}

package/src/restore.ts

@@ -0,0 +1,29 @@
+import type { Host } from './core'
+import { dom } from './core'
+
+/** Captures the focused element and returns focus to it later. */
+export const restore = (host: Host) => {
+	const inert = {
+		capture(_element?: HTMLElement | null) {},
+		restore() {},
+	}
+
+	if (!dom(host)) return inert
+
+	let captured: HTMLElement | null = null
+
+	return {
+		capture(element?: HTMLElement | null) {
+			captured = arguments.length ? element ?? null : document.activeElement as HTMLElement | null
+		},
+		restore() {
+			const element = captured
+			captured = null
+			if (!element) return
+
+			queueMicrotask(() => {
+				if (element.isConnected) element.focus()
+			})
+		},
+	}
+}

package/src/roving.ts

@@ -0,0 +1,77 @@
+import type { Host } from './core'
+import { dom } from './core'
+
+type RovingStep = number | 'first' | 'last'
+type RovingOrientation = 'horizontal' | 'vertical' | 'both'
+
+const keyStep = (event: KeyboardEvent, orientation: RovingOrientation, dir: 'ltr' | 'rtl'): RovingStep | undefined => {
+	if (event.key === 'Home') return 'first'
+	if (event.key === 'End') return 'last'
+
+	if (orientation === 'vertical' || orientation === 'both') {
+		if (event.key === 'ArrowUp') return -1
+		if (event.key === 'ArrowDown') return 1
+	}
+
+	if (orientation === 'horizontal' || orientation === 'both') {
+		if (event.key === 'ArrowLeft') return dir === 'rtl' ? 1 : -1
+		if (event.key === 'ArrowRight') return dir === 'rtl' ? -1 : 1
+	}
+
+	return undefined
+}
+
+/** List keyboard navigation: resolves arrow/Home/End movement over items; consumers apply focus or virtual effects. */
+export const roving = (host: Host, opts: {
+	/** Live list of navigable elements, in visual order. */
+	items: () => HTMLElement[]
+	/** Axis whose arrow keys move the active item. */
+	orientation?: () => RovingOrientation
+	/** Text direction for horizontal arrows. */
+	dir?: () => 'ltr' | 'rtl'
+	/** Wrap at the ends. */
+	loop?: () => boolean
+	/** Element the next move starts from. */
+	current?: () => HTMLElement | null | undefined
+	/** Applies the movement. */
+	onMove: (target: HTMLElement, event: KeyboardEvent) => void
+}) => {
+	const inert = {
+		handle: (_event: KeyboardEvent) => false,
+		move: (_step: RovingStep, _event: KeyboardEvent) => false,
+	}
+
+	if (!dom(host)) return inert
+
+	const move = (step: RovingStep, event: KeyboardEvent) => {
+		const list = opts.items()
+		if (!list.length) return false
+
+		const active = opts.current?.() ?? document.activeElement
+		const index = Math.max(0, list.indexOf(active as HTMLElement))
+		const target = step === 'first'
+			? list[0]
+			: step === 'last'
+				? list[list.length - 1]
+				: list[index + step] ?? ((opts.loop?.() ?? true) ? list[step > 0 ? 0 : list.length - 1] : undefined)
+
+		if (!target) return false
+
+		opts.onMove(target, event)
+		return true
+	}
+
+	return {
+		// A recognized navigation key is always consumed when there are items,
+		// even when a loopless boundary produces no movement (no scroll fallthrough).
+		handle(event: KeyboardEvent) {
+			const step = keyStep(event, opts.orientation?.() ?? 'vertical', opts.dir?.() ?? 'ltr')
+			if (step == null || !opts.items().length) return false
+
+			event.preventDefault()
+			move(step, event)
+			return true
+		},
+		move,
+	}
+}

package/src/scheme.ts

@@ -0,0 +1,25 @@
+import type { Host } from './core'
+import { media } from './media'
+
+const dark = '(prefers-color-scheme: dark)'
+
+/**
+ * Reactive OS color-scheme preference.
+ *
+ * @example
+ * ```ts
+ * const color = scheme(this)
+ * yield <span>{color.dark ? 'dark' : 'light'}</span>
+ * ```
+ */
+export const scheme = (host: Host) => {
+	const query = media(host, { query: () => dark })
+
+	query.sync()
+
+	return {
+		get dark() {
+			return query.matches
+		},
+	}
+}

package/src/scrolling.ts

@@ -0,0 +1,40 @@
+import type { Host } from './core'
+import { dom, live, on } from './core'
+
+/**
+ * Scroll tracking for a live target element with leak-proof retargeting.
+ *
+ * @example
+ * ```ts
+ * const track = scrolling(this, { target: () => list, onScroll: el => read(el.scrollTop) })
+ * while (true) {
+ * 	track.sync()
+ * 	yield <div ref={el => list = el} />
+ * }
+ * ```
+ */
+export const scrolling = (host: Host, opts: {
+	/** Live element to observe; call sync() after refs may have changed. */
+	target: () => HTMLElement | null | undefined
+	/** Frame-coalesced on scroll and on retarget or initial sync. */
+	onScroll: (el: HTMLElement) => void
+	/** Uncoalesced scrollend passthrough. */
+	onEnd?: (el: HTMLElement) => void
+}) => {
+	if (!dom(host)) {
+		return {
+			sync() {},
+		}
+	}
+
+	return live(host, {
+		target: opts.target,
+		onChange: opts.onScroll,
+		bind: (element, notify, signal) => {
+			on(element, 'scroll', notify, host, { passive: true, signal })
+			if (opts.onEnd) {
+				on(element, 'scrollend', () => opts.onEnd?.(element), host, { passive: true, signal })
+			}
+		},
+	})
+}

package/src/selection.ts

@@ -0,0 +1,55 @@
+import type { Host } from './core'
+import { controlled } from './controlled'
+
+/** Single/multi selection semantics over a controlled list of values. */
+export const selection = (host: Host, opts: {
+	/** Multi-select mode. */
+	multiple?: () => boolean
+	/** Forbid deselecting the last selected value. */
+	required?: () => boolean
+	/** Initial uncontrolled values. */
+	fallback?: string[]
+	/** Called whenever values change. */
+	onChange?: (values: string[], event?: Event) => void
+}) => {
+	const state = controlled(host, {
+		fallback: [...(opts.fallback ?? [])],
+		onChange: opts.onChange,
+	})
+
+	return {
+		get values() {
+			return state.value
+		},
+		has(value: string) {
+			return state.value.includes(value)
+		},
+		toggle(value: string, event?: Event) {
+			const base = state.value
+			const exists = base.includes(value)
+			let next: string[]
+
+			if (opts.multiple?.() ?? false) {
+				if (exists) {
+					if ((opts.required?.() ?? false) && base.length <= 1) return
+					next = base.filter(item => item !== value)
+				} else {
+					next = Array.from(new Set([...base, value]))
+				}
+			} else if (exists) {
+				if (opts.required?.() ?? false) return
+				next = []
+			} else {
+				next = [value]
+			}
+
+			state.set(next, event)
+		},
+		set(values: string[], event?: Event) {
+			state.set([...values], event)
+		},
+		sync(values: string[] | null | undefined) {
+			return state.sync(values == null ? undefined : [...values])
+		},
+	}
+}

package/src/spin.ts

@@ -0,0 +1,48 @@
+import type { Host } from './core'
+
+/** Semantic spinbutton movement resolved from stepping keys. */
+export type SpinMove =
+	| { step: 1 | -1 }
+	| { page: 1 | -1 }
+	| { edge: 'min' | 'max' }
+
+const move = (event: KeyboardEvent): SpinMove | undefined => {
+	if (event.key === 'ArrowUp') return { step: 1 }
+	if (event.key === 'ArrowDown') return { step: -1 }
+	if (event.key === 'PageUp') return { page: 1 }
+	if (event.key === 'PageDown') return { page: -1 }
+	if (event.key === 'Home') return { edge: 'min' }
+	if (event.key === 'End') return { edge: 'max' }
+	return undefined
+}
+
+/**
+ * Spinbutton keyboard stepping: resolves ArrowUp/ArrowDown/PageUp/PageDown/Home/End to semantic movement.
+ *
+ * The host parameter keeps the clove signature uniform; spin holds no
+ * per-host state and needs no cleanup. Aria and value state stay in the
+ * consumer; composes with roving when the consumer dispatches spin first.
+ *
+ * @example
+ * ```ts
+ * const stepper = spin(this, { onMove: move => stepValue(move) })
+ * ```
+ */
+export const spin = (host: Host, opts: {
+	/** Receives the semantic movement resolved from a handled keydown. */
+	onMove: (move: SpinMove, event: KeyboardEvent) => void
+}) => {
+	void host
+
+	return {
+		/** Routes a keydown. Returns true and prevents default for spin keys. */
+		handle(event: KeyboardEvent): boolean {
+			const next = move(event)
+			if (!next) return false
+
+			event.preventDefault()
+			opts.onMove(next, event)
+			return true
+		},
+	}
+}

package/src/storage.ts

@@ -0,0 +1,146 @@
+import type { Host } from './core'
+import { dom, shared } from './core'
+
+type Area = 'local' | 'session'
+
+type StorageOptions = {
+	/** Live storage key. */
+	key: () => string
+	/** Value returned when storage is unavailable or the key is missing. */
+	fallback: string
+	/** Storage area. Default: 'local'. */
+	area?: Area
+}
+
+let last: StorageEvent | undefined
+
+const source = (notify: () => void) => {
+	const handler = (event: StorageEvent) => {
+		last = event
+		notify()
+	}
+
+	window.addEventListener('storage', handler)
+	return () => {
+		window.removeEventListener('storage', handler)
+		last = undefined
+	}
+}
+
+const area = (name: Area) => {
+	try {
+		return name === 'local' ? window.localStorage : window.sessionStorage
+	} catch {
+		return undefined
+	}
+}
+
+const get = (name: Area, key: string, fallback: string) => {
+	const store = area(name)
+	if (!store) return fallback
+
+	try {
+		return store.getItem(key) ?? fallback
+	} catch {
+		return fallback
+	}
+}
+
+const put = (name: Area, key: string, value: string) => {
+	const store = area(name)
+	if (!store) return
+
+	try {
+		store.setItem(key, value)
+	} catch { }
+}
+
+const drop = (name: Area, key: string) => {
+	const store = area(name)
+	if (!store) return
+
+	try {
+		store.removeItem(key)
+	} catch { }
+}
+
+/**
+ * Reactive localStorage or sessionStorage string value with cross-tab sync.
+ *
+ * @example
+ * ```ts
+ * const theme = storage(this, { key: () => 'theme', fallback: 'light' })
+ * yield <button set:onclick={() => theme.set('dark')}>{theme.value}</button>
+ * ```
+ */
+export const storage = (host: Host, opts: StorageOptions) => {
+	const name = opts.area ?? 'local'
+
+	if (!dom(host)) {
+		return {
+			get value() {
+				return opts.fallback
+			},
+			set(_next: string) {},
+			remove() {},
+		}
+	}
+
+	let key = opts.key()
+	let current = get(name, key, opts.fallback)
+
+	const sync = () => {
+		if (host.signal.aborted) return
+		const next = opts.key()
+		if (next === key) return
+
+		host.next(() => {
+			key = next
+			current = get(name, key, opts.fallback)
+		})
+	}
+
+	const set = (next: string) => {
+		host.next(() => {
+			current = next
+		})
+	}
+
+	shared('storage', source, () => {
+		sync()
+
+		const event = last
+		const store = area(name)
+
+		if (event?.storageArea && store && event.storageArea !== store) return
+		if (event?.key != null && event.key !== key) return
+
+		const next = event?.key == null ? opts.fallback
+			: event.key === key ? event.newValue ?? opts.fallback
+				: get(name, key, opts.fallback)
+
+		if (next === current) return
+		host.next(() => {
+			current = next
+		})
+	}, host.signal)
+
+	return {
+		get value() {
+			sync()
+			return current
+		},
+		set(next: string) {
+			if (host.signal.aborted) return
+			sync()
+			put(name, key, next)
+			set(next)
+		},
+		remove() {
+			if (host.signal.aborted) return
+			sync()
+			drop(name, key)
+			set(opts.fallback)
+		},
+	}
+}

package/src/timer.ts

@@ -0,0 +1,70 @@
+import type { Host } from './core'
+
+/** Managed one-shot timer with pause/resume, auto-cleared with the host lifecycle. */
+export const timer = (host: Host) => {
+	const signal = host.signal
+	let handle: ReturnType<typeof setTimeout> | undefined
+	let task: (() => void) | undefined
+	let due = 0
+	let left = 0
+	let paused = false
+
+	const stop = () => {
+		if (handle != null) clearTimeout(handle)
+		handle = undefined
+		task = undefined
+		due = 0
+		left = 0
+		paused = false
+	}
+
+	const done = () => {
+		const fn = task
+		handle = undefined
+		task = undefined
+		due = 0
+		left = 0
+		paused = false
+		fn?.()
+	}
+
+	const schedule = (ms: number) => {
+		left = Math.max(0, ms)
+		due = Date.now() + left
+		handle = setTimeout(done, left)
+	}
+
+	const view = {
+		start(ms: number, fn: () => void) {
+			stop()
+			if (signal.aborted) return
+			task = fn
+			paused = false
+			schedule(ms)
+		},
+		stop,
+		pause() {
+			if (handle == null) return
+			left = Math.max(0, due - Date.now())
+			clearTimeout(handle)
+			handle = undefined
+			paused = true
+		},
+		resume() {
+			if (!paused || !task) return
+			paused = false
+			schedule(left)
+		},
+		get running() {
+			return handle != null
+		},
+		get remaining() {
+			if (handle) return Math.max(0, due - Date.now())
+			return paused ? left : 0
+		},
+	}
+
+	signal.addEventListener('abort', stop, { once: true })
+
+	return view
+}

package/src/typeahead.ts

@@ -0,0 +1,50 @@
+import type { Host } from './core'
+import { dom } from './core'
+import { timer } from './timer'
+
+const label = (item: HTMLElement) => item.dataset.label ?? item.textContent?.trim() ?? ''
+
+const printable = (event: KeyboardEvent) =>
+	event.key.length === 1 && event.key !== ' ' && !event.ctrlKey && !event.metaKey && !event.altKey
+
+/** Typeahead: buffers printable keys and matches by label prefix without preventing default. */
+export const typeahead = (host: Host, opts: {
+	/** Live list of searchable elements. */
+	items: () => HTMLElement[]
+	/** Label text for an item. */
+	text?: (item: HTMLElement) => string
+	/** Buffer reset delay in ms. */
+	delay?: () => number
+	/** Applies a matching item. */
+	onMatch: (item: HTMLElement, event: KeyboardEvent) => void
+}) => {
+	const inert = {
+		handle: (_event: KeyboardEvent) => false,
+		reset() {},
+	}
+
+	if (!dom(host)) return inert
+
+	const resetter = timer(host)
+	let query = ''
+
+	const reset = () => {
+		query = ''
+		resetter.stop()
+	}
+
+	return {
+		handle(event: KeyboardEvent) {
+			if (!printable(event)) return false
+
+			query = `${query}${event.key}`.toLowerCase()
+			resetter.start(opts.delay?.() ?? 600, () => query = '')
+
+			const text = opts.text ?? label
+			const match = opts.items().find(item => text(item).toLowerCase().startsWith(query))
+			if (match) opts.onMatch(match, event)
+			return true
+		},
+		reset,
+	}
+}

package/src/visibility.ts

@@ -0,0 +1,45 @@
+import type { Host } from './core'
+import { dom, shared } from './core'
+
+const start = (notify: () => void) => {
+	document.addEventListener('visibilitychange', notify)
+	return () => document.removeEventListener('visibilitychange', notify)
+}
+
+const read = () => document.visibilityState !== 'hidden'
+
+/**
+ * Reactive document visibility.
+ *
+ * @example
+ * ```ts
+ * const page = visibility(this)
+ * yield <span>{page.visible ? 'visible' : 'hidden'}</span>
+ * ```
+ */
+export const visibility = (host: Host) => {
+	if (!dom(host)) {
+		return {
+			get visible() {
+				return true
+			},
+		}
+	}
+
+	let current = read()
+
+	shared('visibility', start, () => {
+		const next = read()
+		if (next === current) return
+
+		host.next(() => {
+			current = next
+		})
+	}, host.signal)
+
+	return {
+		get visible() {
+			return current
+		},
+	}
+}