@zeix/cause-effect 0.18.0 → 0.18.2

package/examples/events-sensor.ts

@@ -0,0 +1,187 @@
+import { createSensor, isSensor, type Sensor } from '..'
+
+/* === Types === */
+
+type ReservedWords =
+	| 'constructor'
+	| 'prototype'
+	| '__proto__'
+	| 'toString'
+	| 'valueOf'
+	| 'hasOwnProperty'
+	| 'isPrototypeOf'
+	| 'propertyIsEnumerable'
+	| 'toLocaleString'
+
+type ComponentProp = Exclude<string, keyof HTMLElement | ReservedWords>
+type ComponentProps = Record<ComponentProp, NonNullable<unknown>>
+
+type Component<P extends ComponentProps> = HTMLElement & P
+
+type UI = Record<string, Element | Sensor<Element[]>>
+
+type EventType<K extends string> = K extends keyof HTMLElementEventMap
+	? HTMLElementEventMap[K]
+	: Event
+
+type EventHandler<
+	T extends {},
+	Evt extends Event,
+	U extends UI,
+	E extends Element,
+> = (context: {
+	event: Evt
+	ui: U
+	target: E
+	prev: T
+}) => T | void | Promise<void>
+
+type EventHandlers<T extends {}, U extends UI, E extends Element> = {
+	[K in keyof HTMLElementEventMap]?: EventHandler<T, EventType<K>, U, E>
+}
+
+type ElementFromKey<U extends UI, K extends keyof U> = NonNullable<
+	U[K] extends Sensor<infer E extends Element>
+		? E
+		: U[K] extends Element
+			? U[K]
+			: never
+>
+
+type Parser<T extends {}, U extends UI> = (
+	ui: U,
+	value: string | null | undefined,
+	old?: string | null,
+) => T
+
+type Reader<T extends {}, U extends UI> = (ui: U) => T
+type Fallback<T extends {}, U extends UI> = T | Reader<T, U>
+
+type ParserOrFallback<T extends {}, U extends UI> =
+	| Parser<T, U>
+	| Fallback<T, U>
+
+/* === Internal === */
+
+const pendingElements = new Set<Element>()
+const tasks = new WeakMap<Element, () => void>()
+let requestId: number | undefined
+
+const runTasks = () => {
+	requestId = undefined
+	const elements = Array.from(pendingElements)
+	pendingElements.clear()
+	for (const element of elements) tasks.get(element)?.()
+}
+
+const requestTick = () => {
+	if (requestId) cancelAnimationFrame(requestId)
+	requestId = requestAnimationFrame(runTasks)
+}
+
+const schedule = (element: Element, task: () => void) => {
+	tasks.set(element, task)
+	pendingElements.add(element)
+	requestTick()
+}
+
+// High-frequency events that are passive by default and should be scheduled
+const PASSIVE_EVENTS = new Set([
+	'scroll',
+	'resize',
+	'mousewheel',
+	'touchstart',
+	'touchmove',
+	'wheel',
+])
+
+const isReader = <T extends {}, U extends UI>(
+	value: unknown,
+): value is Reader<T, U> => typeof value === 'function'
+
+const getFallback = <T extends {}, U extends UI>(
+	ui: U,
+	fallback: ParserOrFallback<T, U>,
+): T => (isReader<T, U>(fallback) ? fallback(ui) : (fallback as T))
+
+/* === Exported Functions === */
+
+/**
+ * Produce an event-driven sensor from transformed event data
+ *
+ * @since 0.16.0
+ * @param {S} key - name of UI key
+ * @param {ParserOrFallback<T>} init - Initial value, reader or parser
+ * @param {EventHandlers<T, ElementFromSelector<S>, C>} events - Transformation functions for events
+ * @returns {Extractor<Sensor<T>, C>} Extractor function for value from event
+ */
+const createEventsSensor =
+	<T extends {}, P extends ComponentProps, U extends UI, K extends keyof U>(
+		init: ParserOrFallback<T, U>,
+		key: K,
+		events: EventHandlers<T, U, ElementFromKey<U, K>>,
+	): ((ui: U & { host: Component<P> }) => Sensor<T>) =>
+	(ui: U & { host: Component<P> }) => {
+		const { host } = ui
+		let value: T = getFallback(ui, init)
+		const targets = isSensor<ElementFromKey<U, K>[]>(ui[key])
+			? ui[key].get()
+			: [ui[key] as ElementFromKey<U & { host: Component<P> }, K>]
+		const eventMap = new Map<string, EventListener>()
+
+		const getTarget = (
+			eventTarget: Node,
+		): ElementFromKey<U, K> | undefined => {
+			for (const t of targets)
+				if (t.contains(eventTarget)) return t as ElementFromKey<U, K>
+		}
+
+		return createSensor<T>(
+			set => {
+				for (const [type, handler] of Object.entries(events)) {
+					const options = { passive: PASSIVE_EVENTS.has(type) }
+					const listener = (e: Event) => {
+						const eventTarget = e.target as Node
+						if (!eventTarget) return
+						const target = getTarget(eventTarget)
+						if (!target) return
+						e.stopPropagation()
+
+						const task = () => {
+							try {
+								const next = handler({
+									event: e as any,
+									ui,
+									target,
+									prev: value,
+								})
+								if (next == null || next instanceof Promise)
+									return
+								if (!Object.is(next, value)) {
+									value = next
+									set(next)
+								}
+							} catch (error) {
+								e.stopImmediatePropagation()
+								throw error
+							}
+						}
+						if (options.passive) schedule(host, task)
+						else task()
+					}
+					eventMap.set(type, listener)
+					host.addEventListener(type, listener, options)
+				}
+				return () => {
+					if (eventMap.size) {
+						for (const [type, listener] of eventMap)
+							host.removeEventListener(type, listener)
+						eventMap.clear()
+					}
+				}
+			},
+			{ value },
+		)
+	}
+
+export { createEventsSensor, type EventHandler, type EventHandlers }

package/examples/selector-sensor.ts

@@ -0,0 +1,173 @@
+import { createMemo, type Memo } from '..'
+
+/* === Types === */
+
+// Split a comma-separated selector into individual selectors
+type SplitByComma<S extends string> = S extends `${infer First},${infer Rest}`
+	? [TrimWhitespace<First>, ...SplitByComma<Rest>]
+	: [TrimWhitespace<S>]
+
+// Trim leading/trailing whitespace from a string
+type TrimWhitespace<S extends string> = S extends ` ${infer Rest}`
+	? TrimWhitespace<Rest>
+	: S extends `${infer Rest} `
+		? TrimWhitespace<Rest>
+		: S
+
+// Extract the rightmost selector part from combinator selectors (space, >, +, ~)
+type ExtractRightmostSelector<S extends string> =
+	S extends `${string} ${infer Rest}`
+		? ExtractRightmostSelector<Rest>
+		: S extends `${string}>${infer Rest}`
+			? ExtractRightmostSelector<Rest>
+			: S extends `${string}+${infer Rest}`
+				? ExtractRightmostSelector<Rest>
+				: S extends `${string}~${infer Rest}`
+					? ExtractRightmostSelector<Rest>
+					: S
+
+// Extract tag name from a simple selector (without combinators)
+type ExtractTagFromSimpleSelector<S extends string> =
+	S extends `${infer T}.${string}`
+		? T
+		: S extends `${infer T}#${string}`
+			? T
+			: S extends `${infer T}:${string}`
+				? T
+				: S extends `${infer T}[${string}`
+					? T
+					: S
+
+// Main extraction logic for a single selector
+type ExtractTag<S extends string> = ExtractTagFromSimpleSelector<
+	ExtractRightmostSelector<S>
+>
+
+// Normalize to lowercase and ensure it's a known HTML tag
+type KnownTag<S extends string> =
+	Lowercase<ExtractTag<S>> extends
+		| keyof HTMLElementTagNameMap
+		| keyof SVGElementTagNameMap
+		| keyof MathMLElementTagNameMap
+		? Lowercase<ExtractTag<S>>
+		: never
+
+// Get element type from a single selector
+type ElementFromSingleSelector<S extends string> =
+	KnownTag<S> extends never
+		? HTMLElement
+		: KnownTag<S> extends keyof HTMLElementTagNameMap
+			? HTMLElementTagNameMap[KnownTag<S>]
+			: KnownTag<S> extends keyof SVGElementTagNameMap
+				? SVGElementTagNameMap[KnownTag<S>]
+				: KnownTag<S> extends keyof MathMLElementTagNameMap
+					? MathMLElementTagNameMap[KnownTag<S>]
+					: HTMLElement
+
+// Map a tuple of selectors to a union of their element types
+type ElementsFromSelectorArray<Selectors extends readonly string[]> = {
+	[K in keyof Selectors]: Selectors[K] extends string
+		? ElementFromSingleSelector<Selectors[K]>
+		: never
+}[number]
+
+// Main type: handle both single selectors and comma-separated selectors
+type ElementFromSelector<S extends string> = S extends `${string},${string}`
+	? ElementsFromSelectorArray<SplitByComma<S>>
+	: ElementFromSingleSelector<S>
+
+type ElementChanges<E extends Element> = {
+	current: Set<E>
+	added: E[]
+	removed: E[]
+}
+
+/* === Internal Functions === */
+
+/**
+ * Extract attribute names from a CSS selector
+ * Handles various attribute selector formats: .class, #id, [attr], [attr=value], [attr^=value], etc.
+ *
+ * @param {string} selector - CSS selector to parse
+ * @returns {string[]} - Array of attribute names found in the selector
+ */
+const extractAttributes = (selector: string): string[] => {
+	const attributes = new Set<string>()
+	if (selector.includes('.')) attributes.add('class')
+	if (selector.includes('#')) attributes.add('id')
+	if (selector.includes('[')) {
+		const parts = selector.split('[')
+		for (let i = 1; i < parts.length; i++) {
+			const part = parts[i]
+			if (!part.includes(']')) continue
+			const attrName = part
+				.split('=')[0]
+				.trim()
+				.replace(/[^a-zA-Z0-9_-]/g, '')
+			if (attrName) attributes.add(attrName)
+		}
+	}
+	return [...attributes]
+}
+
+/* === Exported Functions === */
+
+/**
+ * Observe changes to elements matching a CSS selector.
+ * Returns a Memo that tracks which elements were added and removed.
+ * The MutationObserver is lazily activated when an effect first reads
+ * the memo, and disconnected when no effects are watching.
+ *
+ * @since 0.16.0
+ * @param parent - The parent node to search within
+ * @param selector - The CSS selector to match elements
+ * @returns A Memo of element changes (current set, added, removed)
+ */
+function observeSelectorChanges<S extends string>(
+	parent: ParentNode,
+	selector: S,
+): Memo<ElementChanges<ElementFromSelector<S>>>
+function observeSelectorChanges<E extends Element>(
+	parent: ParentNode,
+	selector: string,
+): Memo<ElementChanges<E>>
+function observeSelectorChanges<S extends string>(
+	parent: ParentNode,
+	selector: S,
+): Memo<ElementChanges<ElementFromSelector<S>>> {
+	type E = ElementFromSelector<S>
+
+	return createMemo(
+		(prev: ElementChanges<E>) => {
+			const next = new Set(
+				Array.from(parent.querySelectorAll<E>(selector)),
+			)
+			const added: E[] = []
+			const removed: E[] = []
+
+			for (const el of next) if (!prev.current.has(el)) added.push(el)
+			for (const el of prev.current) if (!next.has(el)) removed.push(el)
+
+			return { current: next, added, removed }
+		},
+		{
+			value: { current: new Set<E>(), added: [], removed: [] },
+			watched: invalidate => {
+				const observerConfig: MutationObserverInit = {
+					childList: true,
+					subtree: true,
+				}
+				const observedAttributes = extractAttributes(selector)
+				if (observedAttributes.length) {
+					observerConfig.attributes = true
+					observerConfig.attributeFilter = observedAttributes
+				}
+				const observer = new MutationObserver(() => invalidate())
+				observer.observe(parent, observerConfig)
+				return () => observer.disconnect()
+			},
+		},
+	)
+}
+
+export { observeSelectorChanges, type ElementChanges }