ajo-cloves 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ajo-cloves",
+  "version": "0.1.0",
+  "description": "Reusable stateful component behaviors for Ajo",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "ajo": "^0.1.35"
+  },
+  "devDependencies": {
+    "ajo": "0.1.35"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "keywords": [
+    "ajo",
+    "ui",
+    "state",
+    "components",
+    "accessibility"
+  ],
+  "author": "Cristian Falcone",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cristianfalcone/ajo-kit.git",
+    "directory": "packages/ajo-cloves"
+  },
+  "bugs": {
+    "url": "https://github.com/cristianfalcone/ajo-kit/issues"
+  },
+  "homepage": "https://github.com/cristianfalcone/ajo-kit/tree/main/packages/ajo-cloves#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm -w exec tsx scripts/package-build.ts ajo-cloves",
+    "test": "pnpm -w exec vitest run packages/ajo-cloves/tests"
+  }
+}

package/src/announce.ts

@@ -0,0 +1,61 @@
+import type { Host } from './core'
+import { dom } from './core'
+
+type Channel = 'polite' | 'assertive'
+
+const hidden = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0'
+
+let polite: HTMLDivElement | undefined
+let assertive: HTMLDivElement | undefined
+
+const create = (channel: Channel) => {
+
+	const region = document.createElement('div')
+
+	region.setAttribute('role', channel === 'polite' ? 'status' : 'alert')
+	region.setAttribute('aria-live', channel)
+	region.setAttribute('aria-atomic', 'true')
+	region.setAttribute('style', hidden)
+	document.body.append(region)
+
+	return region
+}
+
+const region = (channel: Channel) => {
+
+	const slot = channel === 'polite' ? polite : assertive
+	const next = slot ?? create(channel)
+
+	if (channel === 'polite') polite = next
+	else assertive = next
+
+	if (!next.isConnected) document.body.append(next)
+	return next
+}
+
+const send = (channel: Channel, message: string) => {
+
+	const target = region(channel)
+
+	target.textContent = ''
+	queueMicrotask(() => target.textContent = message)
+}
+
+/** Screen-reader announcements through lazily created document-lifetime aria-live regions. */
+export const announce = (host: Host) => {
+	if (!dom(host)) {
+		return {
+			polite(_message: string) { },
+			assertive(_message: string) { },
+		}
+	}
+
+	return {
+		polite(message: string) {
+			send('polite', message)
+		},
+		assertive(message: string) {
+			send('assertive', message)
+		},
+	}
+}

package/src/controlled.ts

@@ -0,0 +1,44 @@
+import type { Host } from './core'
+
+/** Controlled/uncontrolled value unification for open/value-style component args. */
+export const controlled = <T>(host: Host, opts: {
+	/** Initial uncontrolled value. */
+	fallback: T
+	/** Called whenever set() or accept() changes the value. */
+	onChange?: (value: T, event?: Event) => void
+}) => {
+	let local = opts.fallback
+	let value = local
+	let bound = false
+
+	return {
+		get value() {
+			return value
+		},
+		get controlled() {
+			return bound
+		},
+		/** undefined = uncontrolled; any other value (null included) binds. */
+		sync(arg: T | null | undefined) {
+			bound = arg !== undefined
+			value = bound ? arg as T : local
+			return value
+		},
+		set(next: T, event?: Event) {
+			opts.onChange?.(next, event)
+			if (!bound) local = next
+			host.next(() => value = next)
+		},
+		accept(next: T, event?: Event) {
+			if (!bound) local = next
+			host.next(() => value = next)
+			opts.onChange?.(next, event)
+		},
+		/** Seeds the uncontrolled value without notifying onChange (lazy defaults). */
+		init(next: T) {
+			if (bound) return
+			local = next
+			host.next(() => value = next)
+		},
+	}
+}

package/src/core.ts

@@ -0,0 +1,254 @@
+import type { Host as AjoHost } from 'ajo'
+
+/** Ajo host protocol that cloves bind lifecycle and invalidation to. */
+export type Host<TElement extends object = HTMLElement, TArgs = Record<string, unknown>> = AjoHost<TElement, TArgs>
+
+/** True when a value is structurally a DOM element in a document-bearing runtime. */
+export const dom = (value: unknown): value is Element =>
+	typeof document != 'undefined' &&
+	(value as { nodeType?: unknown } | null)?.nodeType === 1
+
+/** True when both Window and Document globals are available. */
+export const browser = () =>
+	typeof window != 'undefined' && typeof document != 'undefined'
+
+const statefulArg = (key: string) =>
+	key === 'key' || key === 'memo' || key === 'ref' || key === 'skip' || key.startsWith('set:')
+
+/** Maps rest attrs onto an Ajo stateful host, prefixing DOM attributes with `attr:`. */
+export const statefulRootAttrs = (attrs: Record<string, unknown>) => {
+	const result: Record<string, unknown> = {}
+	for (const [key, value] of Object.entries(attrs)) result[statefulArg(key) ? key : `attr:${key}`] = value
+	return result
+}
+
+/** Calls an externally supplied DOM event handler when it is a function. */
+export const callHandler = <EventType extends Event>(handler: unknown, event: EventType) => {
+	if (typeof handler === 'function') (handler as (event: EventType) => void)(event)
+}
+
+/** Calls an externally supplied Ajo ref callback when it is a function. */
+export const callRef = <ElementType>(ref: unknown, element: ElementType | null) => {
+	if (typeof ref === 'function') (ref as (element: ElementType | null) => void)(element)
+}
+
+const hostSignal = (host: Host, signal?: AbortSignal) =>
+	signal && signal !== host.signal ? AbortSignal.any([signal, host.signal]) : host.signal
+
+/** Adds a listener to a DOM host for at most the caller and host lifetimes. */
+export const listen = <EventType extends keyof GlobalEventHandlersEventMap>(
+	host: Host,
+	type: EventType,
+	handler: (event: GlobalEventHandlersEventMap[EventType]) => void,
+	opts?: AddEventListenerOptions,
+) => {
+	if (!dom(host)) return
+	host.addEventListener(type, handler, { ...opts, signal: hostSignal(host, opts?.signal) })
+}
+
+/** Adds a listener bound to the host lifecycle. */
+export function on<K extends keyof GlobalEventHandlersEventMap>(
+	target: EventTarget,
+	type: K,
+	fn: (event: GlobalEventHandlersEventMap[K]) => void,
+	host: Host,
+	opts?: AddEventListenerOptions,
+): void
+export function on(
+	target: EventTarget,
+	type: string,
+	fn: EventListener,
+	host: Host,
+	opts?: AddEventListenerOptions,
+): void
+export function on(
+	target: EventTarget,
+	type: string,
+	fn: EventListener,
+	host: Host,
+	opts?: AddEventListenerOptions,
+) {
+	target.addEventListener(type, fn, { ...opts, signal: hostSignal(host, opts?.signal) })
+}
+
+type SharedStop = () => void
+
+const sources = new Map<string, {
+	stop: SharedStop
+	subscribers: Set<() => void>
+}>()
+
+/** Subscribes to a lazily-started shared source; the real source stops with the last unsubscribe. */
+export const shared = (
+	key: string,
+	start: (notify: () => void) => SharedStop,
+	fn: () => void,
+	signal: AbortSignal,
+): void => {
+
+	if (signal.aborted) return
+
+	let source = sources.get(key)
+	const created = !source
+
+	if (!source) {
+		source = {
+			stop: () => { },
+			subscribers: new Set(),
+		}
+		sources.set(key, source)
+	}
+
+	source.subscribers.add(fn)
+
+	const unsubscribe = () => {
+
+		const current = sources.get(key)
+
+		if (!current) return
+
+		current.subscribers.delete(fn)
+
+		if (current.subscribers.size) return
+
+		current.stop()
+		sources.delete(key)
+	}
+
+	signal.addEventListener('abort', unsubscribe, { once: true })
+
+	if (!created) return
+
+	try {
+		source.stop = start(() => {
+
+			const current = sources.get(key)
+
+			if (!current) return
+
+			for (const subscriber of [...current.subscribers]) subscriber()
+		})
+	} catch (error) {
+		unsubscribe()
+		throw error
+	}
+}
+
+/** Wraps fn so multiple calls within one frame collapse into one run on the next frame. */
+export const frame = (fn: () => void): (() => void) & { cancel(): void } => {
+
+	let handle: number | undefined
+
+	const run = () => {
+		handle = undefined
+		fn()
+	}
+
+	const schedule = (() => {
+
+		if (typeof requestAnimationFrame == 'undefined') {
+			fn()
+			return
+		}
+
+		if (handle != null) return
+
+		handle = requestAnimationFrame(run)
+
+	}) as (() => void) & { cancel(): void }
+
+	schedule.cancel = () => {
+
+		if (handle == null) return
+		if (typeof cancelAnimationFrame != 'undefined') cancelAnimationFrame(handle)
+
+		handle = undefined
+	}
+
+	return schedule
+}
+
+/** Owns frame-coalesced binding to one live element target at a time. */
+export const live = <T extends Element>(host: Host, opts: {
+	target: () => T | null | undefined
+	onChange: (element: T) => void
+	bind: (element: T, notify: () => void, signal: AbortSignal) => void
+}) => {
+	const signal = host.signal
+	let target: T | undefined
+	let scope: AbortController | undefined
+
+	const schedule = frame(() => {
+		const current = target
+		if (current) opts.onChange(current)
+	})
+
+	const stop = () => {
+		scope?.abort()
+		scope = undefined
+		target = undefined
+		schedule.cancel()
+	}
+
+	signal.addEventListener('abort', stop, { once: true })
+
+	return {
+		sync() {
+			if (signal.aborted) return
+
+			const next = opts.target() ?? undefined
+			if (next === target) return
+
+			scope?.abort()
+			scope = undefined
+			schedule.cancel()
+			target = next
+
+			if (!next) return
+
+			const controller = new AbortController()
+			const notify = () => {
+				if (!controller.signal.aborted && target === next) schedule()
+			}
+			scope = controller
+			try {
+				opts.bind(next, notify, controller.signal)
+			} catch (error) {
+				if (scope === controller) {
+					controller.abort()
+					scope = undefined
+					target = undefined
+					schedule.cancel()
+				}
+				throw error
+			}
+			notify()
+		},
+	}
+}
+
+const counters: Record<string, number> = Object.create(null)
+
+/** Monotonic per-prefix unique id. */
+export const id = (prefix: string) => `${prefix}-${counters[prefix] = (counters[prefix] ?? 0) + 1}`
+
+/** Stores a value while keeping at most `limit` insertion-ordered cache keys. */
+export const remember = <Key, Value>(
+	cache: Map<Key, Value>,
+	key: Key,
+	value: Value,
+	limit = 32,
+): Value => {
+	if (!Number.isInteger(limit) || limit < 1) throw new RangeError('remember limit must be a positive integer')
+	cache.set(key, value)
+	while (cache.size > limit) {
+		const oldest = cache.keys().next()
+		if (oldest.done) break
+		cache.delete(oldest.value)
+	}
+	return value
+}
+
+/** Clamps a number into the inclusive [min, max] range. */
+export const clamp = (value: number, min: number, max: number) =>
+	Math.min(Math.max(value, min), max)

package/src/dismiss.ts

@@ -0,0 +1,53 @@
+import type { Host } from './core'
+import { dom, on } from './core'
+
+/** Closes a surface on Escape within the given elements and/or pointerdown outside them. */
+export const dismiss = (host: Host, opts: {
+	/** Gate that enables dismissal channels only while true. */
+	active: () => boolean
+	/** Additional elements treated as inside the surface, such as portaled content. */
+	inside?: () => (Element | null | undefined)[]
+	/** Escape scope. Defaults to host; document also catches focus that moved away. */
+	escape?: false | 'host' | 'document'
+	/** Also dismiss on pointerdown outside the host and the inside() elements. Default: false. */
+	outside?: boolean
+	/** preventDefault the Escape keydown (never applied to outside pointerdown). Default: false. */
+	prevent?: boolean
+	/** Receives the Escape keydown or outside pointerdown that requested dismissal. */
+	onDismiss: (event: Event) => void
+}): void => {
+	if (!dom(host)) return
+	const document = host.ownerDocument
+	const view = document.defaultView
+	const node = (value: unknown): value is Node => Boolean(view && value instanceof view.Node)
+
+	const escape = opts.escape ?? 'host'
+	if (escape) {
+		on(escape === 'document' ? document : host, 'keydown', event => {
+			if (event.key !== 'Escape' || !opts.active()) return
+
+			if (escape === 'host' && opts.inside) {
+				const target = event.target
+				const elements = opts.inside().filter((element): element is Element => !!element)
+
+				if (elements.length && !(node(target) && elements.some(element => element.contains(target)))) return
+			}
+
+			if (opts.prevent) event.preventDefault()
+			opts.onDismiss(event)
+		}, host)
+	}
+
+	if (opts.outside) {
+		on(document, 'pointerdown', event => {
+			if (!opts.active()) return
+
+			const target = event.target
+			if (!node(target)) return
+			if ((host as Element).contains(target)) return
+			if (opts.inside?.().some(element => element?.contains(target))) return
+
+			opts.onDismiss(event)
+		}, host, { capture: true })
+	}
+}

package/src/grid.ts

@@ -0,0 +1,52 @@
+import type { Host } from './core'
+
+/** Semantic 2D keyboard movement resolved from grid navigation keys. */
+export type GridMove =
+	| { cols: number }
+	| { rows: number }
+	| { edge: 'start' | 'end'; extent: 'row' | 'all' }
+	| { page: number; large: boolean }
+
+const move = (event: KeyboardEvent, rtl: boolean): GridMove | undefined => {
+	if (event.key === 'ArrowLeft') return { cols: rtl ? 1 : -1 }
+	if (event.key === 'ArrowRight') return { cols: rtl ? -1 : 1 }
+	if (event.key === 'ArrowUp') return { rows: -1 }
+	if (event.key === 'ArrowDown') return { rows: 1 }
+	if (event.key === 'Home') return { edge: 'start', extent: event.ctrlKey ? 'all' : 'row' }
+	if (event.key === 'End') return { edge: 'end', extent: event.ctrlKey ? 'all' : 'row' }
+	if (event.key === 'PageUp') return { page: -1, large: event.shiftKey }
+	if (event.key === 'PageDown') return { page: 1, large: event.shiftKey }
+	return undefined
+}
+
+/**
+ * 2D grid keyboard navigation: resolves arrows/Home/End/PageUp/PageDown to semantic movement.
+ *
+ * The host parameter keeps the clove signature uniform; grid holds no
+ * per-host state and needs no cleanup.
+ *
+ * @example
+ * ```ts
+ * const nav = grid(this, { onMove: move => focusCell(move) })
+ * ```
+ */
+export const grid = (host: Host, opts: {
+	/** Right-to-left column direction. Default: false. */
+	rtl?: () => boolean
+	/** Receives the semantic movement resolved from a handled keydown. */
+	onMove: (move: GridMove, event: KeyboardEvent) => void
+}) => {
+	void host
+
+	return {
+		/** Routes a keydown. Returns true and prevents default for grid navigation keys. */
+		handle(event: KeyboardEvent): boolean {
+			const next = move(event, opts.rtl?.() ?? false)
+			if (!next) return false
+
+			event.preventDefault()
+			opts.onMove(next, event)
+			return true
+		},
+	}
+}

package/src/hotkey.ts

@@ -0,0 +1,56 @@
+import type { Host } from './core'
+import { dom, on } from './core'
+
+const modifier = (token: string) =>
+	token === 'mod' || token === 'ctrl' || token === 'meta' || token === 'alt' || token === 'shift'
+
+const matches = (chord: string, event: KeyboardEvent) => {
+	const tokens = chord
+		.split('+')
+		.map(token => token.trim().toLowerCase())
+		.filter(Boolean)
+	const key = tokens.find(token => !modifier(token))
+
+	if (!key) return false
+
+	const wantsMod = tokens.includes('mod')
+	const wantsCtrl = tokens.includes('ctrl')
+	const wantsMeta = tokens.includes('meta')
+	const wantsAlt = tokens.includes('alt')
+	const wantsShift = tokens.includes('shift')
+	const ctrl = event.ctrlKey
+	const meta = event.metaKey
+
+	if (wantsMod) {
+		if (ctrl === meta) return false
+	} else {
+		if (ctrl !== wantsCtrl || meta !== wantsMeta) return false
+	}
+
+	if (event.altKey !== wantsAlt) return false
+	if (event.shiftKey !== wantsShift) return false
+
+	return event.key.toLowerCase() === key
+}
+
+/** Global keyboard shortcut for a single chord like 'mod+b' or 'F8'. */
+export const hotkey = (host: Host, opts: {
+	/** Chord: '+'-separated modifiers (mod|ctrl|meta|alt|shift) plus one key token, e.g. 'mod+b', 'F8'. */
+	keys: () => string
+	/** Called when the active chord matches a keydown. */
+	onPress: (event: KeyboardEvent) => void
+	/** Gate. Default: () => true. */
+	active?: () => boolean
+	/** preventDefault on match. Default: true. */
+	prevent?: boolean
+}): void => {
+	if (!dom(host)) return
+
+	on(window, 'keydown', event => {
+		if (!matches(opts.keys(), event)) return
+		if (!(opts.active?.() ?? true)) return
+
+		if (opts.prevent ?? true) event.preventDefault()
+		opts.onPress(event)
+	}, host)
+}

package/src/hover.ts

@@ -0,0 +1,58 @@
+import type { Host } from './core'
+import { timer } from './timer'
+
+/** Hover intent: zones hold the surface open; delays gate open/close transitions. */
+export const hover = (host: Host, opts: {
+	/** Delay before the first held zone opens the surface, in ms. Default: 0. */
+	openDelay?: () => number
+	/** Delay before the last released zone closes the surface, in ms. Default: 0. */
+	closeDelay?: () => number
+	/** Called when the held-zone state opens or closes the surface. */
+	onChange: (open: boolean, event: Event) => void
+}) => {
+	const zones = new Set<string>()
+	const opening = timer(host)
+	const closing = timer(host)
+	let opened = false
+
+	const flip = (next: boolean, event: Event) => {
+		if (opened === next) return
+		opened = next
+		opts.onChange(next, event)
+	}
+
+	return {
+		get open() {
+			return opened
+		},
+		hold(zone: string, event: Event) {
+			zones.add(zone)
+			closing.stop()
+			if (opened || opening.running) return
+
+			const delay = opts.openDelay?.() ?? 0
+			if (delay <= 0) flip(true, event)
+			else opening.start(delay, () => flip(true, event))
+		},
+		release(zone: string, event: Event) {
+			zones.delete(zone)
+			if (zones.size) return
+
+			opening.stop()
+			if (!opened) return
+
+			const delay = opts.closeDelay?.() ?? 0
+			if (delay <= 0) flip(false, event)
+			else closing.start(delay, () => flip(false, event))
+		},
+		sync(open: boolean) {
+			opened = open
+		},
+		/** Stops pending transitions and forgets every held zone without notifying. */
+		cancel() {
+			opening.stop()
+			closing.stop()
+			zones.clear()
+		},
+	}
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export { announce } from './announce'
+export {
+	browser,
+	callHandler,
+	callRef,
+	clamp,
+	dom,
+	frame,
+	type Host,
+	id,
+	listen,
+	remember,
+	shared,
+	statefulRootAttrs,
+} from './core'
+export { controlled } from './controlled'
+export { dismiss } from './dismiss'
+export { grid, type GridMove } from './grid'
+export { hotkey } from './hotkey'
+export { hover } from './hover'
+export { indicator } from './indicator'
+export { label, type LabelView } from './label'
+export { media } from './media'
+export { move } from './move'
+export { overflow } from './overflow'
+export { resize } from './resize'
+export { restore } from './restore'
+export { roving } from './roving'
+export { scheme } from './scheme'
+export { scrolling } from './scrolling'
+export { selection } from './selection'
+export { spin, type SpinMove } from './spin'
+export { storage } from './storage'
+export { timer } from './timer'
+export { typeahead } from './typeahead'
+export { visibility } from './visibility'