ajo-cloves 0.1.0

package/src/indicator.ts

@@ -0,0 +1,122 @@
+import type { Host } from './core'
+import { dom, frame } from './core'
+import { resize } from './resize'
+
+/**
+ * Tracks a marked child inside a live container and stamps its box on the
+ * container as CSS variables (`--indicator-x/y/w/h`, px in the container's
+ * content coordinates) plus a `data-indicator="true"` marker while a mark
+ * exists. Themes draw a pseudo-element positioned by the variables and
+ * transition it, so the active marker glides between children instead of
+ * jumping.
+ *
+ * On first placement the variables land one frame before the marker
+ * attribute, so a theme pseudo-element fades in at its resting position
+ * instead of sliding in from the container origin.
+ *
+ * @example
+ * ```ts
+ * const mark = indicator(this, {
+ * 	target: () => list,
+ * 	of: container => container.querySelector('[data-state="active"]'),
+ * })
+ * while (true) {
+ * 	mark.sync()
+ * 	yield ...
+ * }
+ * ```
+ */
+export const indicator = (host: Host, opts: {
+	/** Live container that receives the variables; call sync() after refs may have changed. */
+	target: () => HTMLElement | null | undefined
+	/** Resolves the marked child inside the container. */
+	of: (container: HTMLElement) => HTMLElement | null
+	/** Container events that can move the mark without a re-render (e.g. focusin). */
+	on?: string[]
+}) => {
+	if (!dom(host)) {
+		return {
+			sync() {},
+		}
+	}
+
+	let container: HTMLElement | undefined
+	let control: AbortController | undefined
+	let placed = false
+
+	const clear = (el: HTMLElement) => {
+		el.removeAttribute('data-indicator')
+		for (const name of ['x', 'y', 'w', 'h']) el.style.removeProperty(`--indicator-${name}`)
+		placed = false
+	}
+
+	// The marker attribute trails the variables by one frame so the theme's
+	// transitioned pseudo-element first paints already in position.
+	const reveal = frame(() => {
+		if (container && placed) container.setAttribute('data-indicator', 'true')
+	})
+
+	const measure = () => {
+		if (!container) return
+
+		const mark = opts.of(container)
+
+		if (!mark || !container.contains(mark)) {
+			container.removeAttribute('data-indicator')
+			placed = false
+			return
+		}
+
+		// Content coordinates (scroll included) so the mark stays glued to its
+		// child while the container scrolls.
+		const box = container.getBoundingClientRect()
+		const rect = mark.getBoundingClientRect()
+		const style = container.style
+		style.setProperty('--indicator-x', `${rect.left - box.left + container.scrollLeft}px`)
+		style.setProperty('--indicator-y', `${rect.top - box.top + container.scrollTop}px`)
+		style.setProperty('--indicator-w', `${rect.width}px`)
+		style.setProperty('--indicator-h', `${rect.height}px`)
+
+		if (placed) return
+		placed = true
+		reveal()
+	}
+
+	const schedule = frame(measure)
+
+	const size = resize(host, { target: () => container, onResize: () => schedule() })
+
+	const retarget = (next: HTMLElement | undefined) => {
+		if (next === container) return
+
+		control?.abort()
+		control = undefined
+		if (container) clear(container)
+		container = next
+
+		if (!container || !opts.on?.length) return
+
+		control = new AbortController()
+		host.signal.addEventListener('abort', () => control?.abort(), { signal: control.signal })
+		for (const type of opts.on) {
+			container.addEventListener(type, () => schedule(), { passive: true, signal: control.signal })
+		}
+	}
+
+	host.signal.addEventListener('abort', () => {
+		schedule.cancel()
+		reveal.cancel()
+		control?.abort()
+		if (container) clear(container)
+		container = undefined
+	}, { once: true })
+
+	return {
+		sync() {
+			if (host.signal.aborted) return
+			retarget(opts.target() ?? undefined)
+			size.sync()
+			schedule()
+		},
+	}
+}

package/src/label.ts

@@ -0,0 +1,171 @@
+import type { Host } from './core'
+import { dom, id } from './core'
+
+/** Stable ids generated for one labelled field. */
+export type LabelIds = {
+	/** Id for the primary control. */
+	readonly control: string
+	/** Id for the optional description element. */
+	readonly description: string
+	/** Id for the optional error element. */
+	readonly error: string
+	/** Id for the label element. */
+	readonly label: string
+}
+
+/** Plain attributes for native labelable controls. */
+export type LabelControlAttrs = {
+	/** Space-separated ids of description/error elements when present. */
+	'aria-describedby'?: string
+	/** Error id when the field is invalid. */
+	'aria-errormessage'?: string
+	/** Invalid state marker when the field is invalid. */
+	'aria-invalid'?: 'true'
+	/** Control id referenced by the label. */
+	id: string
+}
+
+/** Plain attributes for button-like field controls. */
+export type LabelButtonAttrs = LabelControlAttrs & {
+	/** Label id used instead of native label-for activation. */
+	'aria-labelledby': string
+}
+
+/** Plain attributes for grouped field surfaces without a control id. */
+export type LabelGroupAttrs = {
+	/** Space-separated ids of description/error elements when present. */
+	'aria-describedby'?: string
+	/** Label id for the group. */
+	'aria-labelledby': string
+}
+
+/** Reactive inputs used to configure one field-labelling view. */
+export type LabelOptions = {
+	/** Prefix used for the stable ids. Default: `field`. */
+	prefix?: () => string | undefined
+}
+
+/** Live field-labelling view returned by the label clove. */
+export type LabelView = {
+	/** Stable ids for the field parts. */
+	readonly ids: LabelIds
+	/** Attributes for button-like controls. */
+	readonly buttonAttrs: LabelButtonAttrs
+	/** Attributes for native labelable controls. */
+	readonly controlAttrs: LabelControlAttrs
+	/** Attributes for the description element. */
+	readonly descriptionAttrs: { id: string }
+	/** Records whether a description element rendered in this pass. */
+	describe(present: boolean): void
+	/** Attributes for the error element. */
+	readonly errorAttrs: { id: string }
+	/** Attributes for grouped field surfaces. */
+	readonly groupAttrs: LabelGroupAttrs
+	/** Attributes for the label element. */
+	readonly labelAttrs: { for: string; id: string }
+	/** Begins a render pass that may re-register description presence. */
+	reset(): void
+	/** Updates invalid/error wiring from current args. */
+	sync(invalid: boolean): void
+}
+
+/** Field labelling: stable ids and label/control/description/error wiring for one form field. */
+export const label = (host: Host, options: LabelOptions = {}): LabelView => {
+	const base = id(options.prefix?.() ?? 'field')
+	const ids = {
+		control: base,
+		description: `${base}-description`,
+		error: `${base}-error`,
+		label: `${base}-label`,
+	} as const
+	let described = false
+	let invalid = false
+	let pending = false
+	let present = false
+	let pass = 0
+
+	const schedule = () => {
+		if (!dom(host) || pending) return
+
+		pending = true
+		queueMicrotask(() => {
+			pending = false
+			host.next()
+		})
+	}
+
+	const describedby = () => {
+		const values: string[] = []
+		if (described) values.push(ids.description)
+		if (invalid) values.push(ids.error)
+		return values.join(' ') || undefined
+	}
+
+	const controlAttrs = (): LabelControlAttrs => ({
+		id: ids.control,
+		'aria-describedby': describedby(),
+		'aria-invalid': invalid ? 'true' : undefined,
+		'aria-errormessage': invalid ? ids.error : undefined,
+	})
+
+	return {
+		ids,
+		sync(next) {
+			invalid = next
+		},
+		describe(next) {
+			if (next) {
+				present = true
+				if (described) return
+				described = true
+				schedule()
+				return
+			}
+
+			present = false
+			if (!described) return
+			described = false
+			schedule()
+		},
+		get labelAttrs() {
+			return {
+				id: ids.label,
+				for: ids.control,
+			}
+		},
+		get controlAttrs() {
+			return controlAttrs()
+		},
+		get buttonAttrs() {
+			return {
+				...controlAttrs(),
+				'aria-labelledby': ids.label,
+			}
+		},
+		get groupAttrs() {
+			return {
+				'aria-labelledby': ids.label,
+				'aria-describedby': describedby(),
+			}
+		},
+		get descriptionAttrs() {
+			return { id: ids.description }
+		},
+		get errorAttrs() {
+			return { id: ids.error }
+		},
+		reset() {
+			present = false
+
+			if (!described || !dom(host)) return
+			const current = ++pass
+
+			queueMicrotask(() => {
+				if (current !== pass || present || !described) return
+				host.next(() => {
+					described = false
+				})
+			})
+		},
+	}
+}

package/src/media.ts

@@ -0,0 +1,95 @@
+import type { Host } from './core'
+import { dom, shared } from './core'
+
+/** Reactive inputs used to configure a shared media-query view. */
+export type MediaOptions = {
+	/** Server and unsupported-browser match value. Default: false. */
+	fallback?: () => boolean
+	/** Current media-query string, read by `sync()`. */
+	query: () => string
+}
+
+const lists = new Map<string, MediaQueryList>()
+
+const fallback = (opts: MediaOptions) => opts.fallback?.() ?? false
+
+const start = (query: string) => (notify: () => void) => {
+	const list = window.matchMedia(query)
+
+	lists.set(query, list)
+	list.addEventListener('change', notify)
+
+	return () => {
+		list.removeEventListener('change', notify)
+		if (lists.get(query) === list) lists.delete(query)
+	}
+}
+
+const read = (query: string | undefined, opts: MediaOptions) =>
+	query ? lists.get(query)?.matches ?? fallback(opts) : fallback(opts)
+
+/**
+ * Reactive media-query match, shared per query string.
+ *
+ * @example
+ * ```ts
+ * const narrow = media(this, { query: () => '(max-width: 768px)' })
+ * for (const args of this) {
+ * 	narrow.sync()
+ * 	yield <span>{narrow.matches ? 'narrow' : 'wide'}</span>
+ * }
+ * ```
+ */
+export const media = (host: Host, options: MediaOptions) => {
+	const { query } = options
+	let active: string | undefined
+	let current = fallback(options)
+	let scope: AbortController | undefined
+
+	const stop = () => {
+		scope?.abort()
+		scope = undefined
+		active = undefined
+	}
+
+	const update = () => {
+		const next = read(active, options)
+		if (next === current) return
+
+		host.next(() => {
+			current = next
+		})
+	}
+
+	if (!dom(host) || typeof window.matchMedia != 'function') {
+		return {
+			get matches() {
+				return fallback(options)
+			},
+			sync() {},
+		}
+	}
+
+	host.signal.addEventListener('abort', stop, { once: true })
+
+	return {
+		get matches() {
+			return read(active, options)
+		},
+		sync() {
+			if (host.signal.aborted) return
+
+			const next = query()
+			if (next === active) {
+				current = read(active, options)
+				return
+			}
+
+			scope?.abort()
+			scope = new AbortController()
+			active = next
+			shared(`media:${next}`, start(next), update, scope.signal)
+			current = read(active, options)
+		},
+	}
+}

package/src/move.ts

@@ -0,0 +1,185 @@
+import type { Host } from './core'
+import { dom, on } from './core'
+
+type CaptureElement = HTMLElement | SVGElement
+
+type MoveData = {
+	/** Client coordinates of the current event. */
+	x: number
+	y: number
+	/** Deltas from the session start. */
+	dx: number
+	dy: number
+	/** True when the session ended via pointercancel, Escape, or capture loss. */
+	canceled: boolean
+}
+
+type MoveSession = {
+	controller: AbortController
+	data: MoveData
+	element: CaptureElement
+	pointer: number
+	startX: number
+	startY: number
+}
+
+type MoveView = {
+	/** Begins a drag session from the consumer's own pointerdown. Ignores non-primary buttons. */
+	start(event: PointerEvent): boolean
+	/** True while a session is running. */
+	readonly active: boolean
+}
+
+const isCaptureElement = (value: EventTarget | null): value is CaptureElement =>
+	value instanceof HTMLElement || value instanceof SVGElement
+
+const capture = (event: PointerEvent) =>
+	isCaptureElement(event.currentTarget) ? event.currentTarget
+		: isCaptureElement(event.target) ? event.target
+			: undefined
+
+const update = (session: MoveSession, event: PointerEvent, canceled: boolean) => {
+	const { data } = session
+
+	data.x = event.clientX
+	data.y = event.clientY
+	data.dx = event.clientX - session.startX
+	data.dy = event.clientY - session.startY
+	data.canceled = canceled
+
+	return data
+}
+
+const release = (session: MoveSession) => {
+	try {
+		session.element.releasePointerCapture(session.pointer)
+	} catch { }
+}
+
+/**
+ * Pointer-drag session lifecycle: capture, move deltas, and guaranteed cleanup.
+ *
+ * `data` is one object mutated across callbacks within a session; read it
+ * during the callback and do not retain it across events. Consumers own
+ * gesture CSS such as `touch-action`, and Escape is reported without
+ * preventDefault so consumers can decide that policy.
+ *
+ * @example
+ * ```ts
+ * function* Handle(this: Host) {
+ * 	const drag = move(this, { onMove(data) { resize(data.dx, data.dy) } })
+ * 	yield <div set:onpointerdown={event => drag.start(event)} />
+ * }
+ * ```
+ */
+export const move = (host: Host, opts: {
+	/** Called once after a drag session starts. */
+	onStart?: (data: MoveData, event: PointerEvent) => void
+	/** Called for pointer moves during the active session. */
+	onMove: (data: MoveData, event: PointerEvent) => void
+	/** Called once when the session ends normally or is canceled. */
+	onEnd?: (data: MoveData, event: PointerEvent | KeyboardEvent) => void
+}): MoveView => {
+	if (!dom(host)) {
+		return {
+			start(_event: PointerEvent) {
+				return false
+			},
+			get active() {
+				return false
+			},
+		}
+	}
+
+	const lifetime = host.signal
+	let session: MoveSession | undefined
+
+	const finish = (
+		current: MoveSession,
+		event: PointerEvent | KeyboardEvent,
+		canceled: boolean,
+		releaseCapture = true,
+	) => {
+		if (session !== current || current.controller.signal.aborted) return
+
+		const data = event instanceof PointerEvent
+			? update(current, event, canceled)
+			: current.data
+
+		if (!(event instanceof PointerEvent)) data.canceled = canceled
+
+		session = undefined
+		current.controller.abort()
+		if (releaseCapture) release(current)
+		opts.onEnd?.(data, event)
+	}
+
+	return {
+		start(event: PointerEvent) {
+			if (event.button !== 0 || !event.isPrimary || session || lifetime.aborted) return false
+
+			const element = capture(event)
+			if (!element) return false
+
+			try {
+				element.setPointerCapture(event.pointerId)
+			} catch { }
+
+			const current: MoveSession = {
+				controller: new AbortController(),
+				data: {
+					x: event.clientX,
+					y: event.clientY,
+					dx: 0,
+					dy: 0,
+					canceled: false,
+				},
+				element,
+				pointer: event.pointerId,
+				startX: event.clientX,
+				startY: event.clientY,
+			}
+			const { signal } = current.controller
+
+			session = current
+
+			lifetime.addEventListener('abort', () => {
+				if (session !== current || signal.aborted) return
+
+				session = undefined
+				current.controller.abort()
+				release(current)
+			}, { once: true, signal })
+
+			on(element, 'pointermove', next => {
+				if (next.pointerId !== current.pointer) return
+				opts.onMove(update(current, next, false), next)
+			}, host, { signal })
+
+			on(element, 'pointerup', next => {
+				if (next.pointerId !== current.pointer) return
+				finish(current, next, false)
+			}, host, { signal })
+
+			on(element, 'pointercancel', next => {
+				if (next.pointerId !== current.pointer) return
+				finish(current, next, true)
+			}, host, { signal })
+
+			on(element, 'lostpointercapture', next => {
+				if (next.pointerId !== current.pointer) return
+				finish(current, next, true, false)
+			}, host, { signal })
+
+			on(element.ownerDocument, 'keydown', next => {
+				if (next.key === 'Escape') finish(current, next, true)
+			}, host, { signal })
+
+			opts.onStart?.(current.data, event)
+			return true
+		},
+		get active() {
+			return !!session
+		},
+	}
+}

package/src/overflow.ts

@@ -0,0 +1,87 @@
+import type { Host } from './core'
+import { dom, frame } from './core'
+import { resize } from './resize'
+import { scrolling } from './scrolling'
+
+const edge = (position: number, size: number, span: number): string | null => {
+	if (span - size <= 1) return null
+
+	// RTL scrollers report negative positions; the stamped values stay
+	// inline-logical ("start" = scrolled away from the inline start).
+	const offset = Math.abs(position)
+	const start = offset > 1
+	const end = offset < span - size - 1
+
+	return start && end ? 'both' : start ? 'start' : 'end'
+}
+
+const stamp = (el: HTMLElement, name: string, value: string | null) => {
+	if (!value) el.removeAttribute(name)
+	else if (el.getAttribute(name) !== value) el.setAttribute(name, value)
+}
+
+/**
+ * Stamps `data-overflow-x` / `data-overflow-y` ("start" | "end" | "both") on
+ * a live scrollable element while content overflows it, tracking scroll,
+ * element resize, and re-renders. Themes pair the attrs with edge fades (the
+ * `[data-overflow-*]` mask preflight); the attrs are absent while everything
+ * fits.
+ *
+ * @example
+ * ```ts
+ * const edges = overflow(this, { target: () => list })
+ * while (true) {
+ * 	edges.sync()
+ * 	yield <div ref={el => list = el} />
+ * }
+ * ```
+ */
+export const overflow = (host: Host, opts: {
+	/** Live element to observe; call sync() after refs may have changed. */
+	target: () => HTMLElement | null | undefined
+}) => {
+	if (!dom(host)) {
+		return {
+			sync() {},
+		}
+	}
+
+	const measure = (el: HTMLElement) => {
+		stamp(el, 'data-overflow-x', edge(el.scrollLeft, el.clientWidth, el.scrollWidth))
+		stamp(el, 'data-overflow-y', edge(el.scrollTop, el.clientHeight, el.scrollHeight))
+	}
+	const clear = (el: HTMLElement) => {
+		stamp(el, 'data-overflow-x', null)
+		stamp(el, 'data-overflow-y', null)
+	}
+	let target: HTMLElement | undefined
+
+	const scroll = scrolling(host, { target: () => target, onScroll: measure })
+	const size = resize(host, { target: () => target, onResize: el => measure(el as HTMLElement) })
+
+	// Content can grow without an element resize or scroll (children added or
+	// relabeled); re-measure on every sync so re-renders refresh the stamps.
+	const schedule = frame(() => {
+		if (target) measure(target)
+	})
+
+	host.signal.addEventListener('abort', () => {
+		schedule.cancel()
+		if (target) clear(target)
+		target = undefined
+	}, { once: true })
+
+	return {
+		sync() {
+			if (host.signal.aborted) return
+			const next = opts.target() ?? undefined
+			if (next !== target) {
+				if (target) clear(target)
+				target = next
+			}
+			scroll.sync()
+			size.sync()
+			schedule()
+		},
+	}
+}