@zeix/le-truc 0.15.0

package/src/effects.ts

@@ -0,0 +1,412 @@
+import {
+	type Cleanup,
+	createEffect,
+	isFunction,
+	isRecord,
+	isSignal,
+	isString,
+	type MaybeCleanup,
+	type Signal,
+	toError,
+	UNSET,
+	valueString,
+} from '@zeix/cause-effect'
+import type { Component, ComponentProps } from './component'
+import { InvalidEffectsError } from './errors'
+import { type Collection, isCollection } from './signals/collection'
+import type { ElementFromKey, UI } from './ui'
+import { DEV_MODE, elementName, LOG_ERROR, log } from './util'
+
+/* === Types === */
+
+type Effect<P extends ComponentProps, E extends Element> = (
+	host: Component<P>,
+	target: E,
+) => MaybeCleanup
+
+type ElementEffects<P extends ComponentProps, E extends Element> =
+	| Effect<P, E>
+	| Effect<P, E>[]
+
+type Effects<
+	P extends ComponentProps,
+	U extends UI & { host: Component<P> },
+> = {
+	[K in keyof U]?: ElementEffects<P, ElementFromKey<U, K>>
+}
+
+type Reactive<T, P extends ComponentProps, E extends Element> =
+	| keyof P
+	| Signal<T & {}>
+	| ((target: E) => T | null | undefined)
+
+type UpdateOperation = 'a' | 'c' | 'd' | 'h' | 'm' | 'p' | 's' | 't'
+
+type ElementUpdater<E extends Element, T> = {
+	op: UpdateOperation
+	name?: string
+	read: (element: E) => T | null
+	update: (element: E, value: T) => void
+	delete?: (element: E) => void
+	resolve?: (element: E) => void
+	reject?: (error: unknown) => void
+}
+
+/* type ElementInserter<E extends Element> = {
+	position?: InsertPosition
+	create: (parent: E) => Element | null
+	resolve?: (parent: E) => void
+	reject?: (error: unknown) => void
+} */
+
+/* === Constants === */
+
+// Special value explicitly marked as any so it can be used as signal value of any type
+const RESET: any = Symbol('RESET')
+
+/* === Internal Functions === */
+
+const getUpdateDescription = (
+	op: UpdateOperation,
+	name: string = '',
+): string => {
+	const ops: Record<UpdateOperation, string> = {
+		a: 'attribute ',
+		c: 'class ',
+		d: 'dataset ',
+		h: 'inner HTML',
+		m: 'method call ',
+		p: 'property ',
+		s: 'style property ',
+		t: 'text content',
+	}
+	return ops[op] + name
+}
+
+/* === Exported Functions === */
+
+/**
+ * Run element effects
+ *
+ * @since 0.15.0
+ * @param {U} host - Host component
+ * @param {E} target - Target element
+ * @param {ElementEffects<P, E>} effects - Effect functions to run
+ * @returns {MaybeCleanup} - Cleanup function that runs collected cleanup functions
+ * @throws {InvalidEffectsError} - If the effects are invalid
+ */
+const runElementEffects = <P extends ComponentProps, E extends Element>(
+	host: Component<P>,
+	target: E,
+	effects: ElementEffects<P, E>,
+): MaybeCleanup => {
+	const cleanups: Cleanup[] = []
+
+	const run = (fn: Effect<P, E>) => {
+		const cleanup = fn(host, target)
+		if (cleanup) cleanups.push(cleanup)
+	}
+
+	if (Array.isArray(effects)) for (const fn of effects) run(fn)
+	else run(effects)
+
+	return () => {
+		cleanups.forEach(cleanup => cleanup())
+		cleanups.length = 0
+	}
+}
+
+/**
+ * Run collection effects
+ *
+ * @since 0.15.0
+ * @param {Component<P>} host - Host component
+ * @param {Collection<E>} collection - Collection of elements
+ * @param {ElementEffects<P, E>} effects - Element effects
+ * @returns {Cleanup} - Cleanup function that runs collected cleanup functions
+ * @throws {InvalidEffectsError} - If the effects are invalid
+ */
+const runCollectionEffects = <P extends ComponentProps, E extends Element>(
+	host: Component<P>,
+	collection: Collection<E>,
+	effects: ElementEffects<P, E>,
+): Cleanup => {
+	const cleanups: Map<E, Cleanup> = new Map()
+
+	const attach = (targets: readonly E[]) => {
+		for (const target of targets) {
+			const cleanup = runElementEffects(host, target, effects)
+			if (cleanup) cleanups.set(target, cleanup)
+		}
+	}
+	const detach = (targets: readonly E[]) => {
+		for (const target of targets) {
+			cleanups.get(target)?.()
+			cleanups.delete(target)
+		}
+	}
+
+	collection.on('add', attach)
+	collection.on('remove', detach)
+	attach(collection.get())
+	return () => {
+		for (const cleanup of cleanups.values()) cleanup()
+		cleanups.clear()
+	}
+}
+
+/**
+ * Run component effects
+ *
+ * @since 0.15.0
+ * @param {ComponentUI<P, U>} ui - Component UI
+ * @param {Effects<P, U>} effects - Effect functions to run
+ * @returns {Cleanup} - Cleanup function that runs collected cleanup functions
+ * @throws {InvalidEffectsError} - If the effects are invalid
+ */
+const runEffects = <
+	P extends ComponentProps,
+	U extends UI & { host: Component<P> },
+>(
+	ui: U,
+	effects: Effects<P, U>,
+): Cleanup => {
+	if (!isRecord(effects)) throw new InvalidEffectsError(ui.host)
+
+	const cleanups: Cleanup[] = []
+	const keys = Object.keys(effects)
+	for (const key of keys) {
+		const k = key as keyof U
+		if (!effects[k]) continue
+
+		const elementEffects = Array.isArray(effects[k]) ? effects[k] : [effects[k]]
+		if (isCollection<ElementFromKey<U, typeof k>>(ui[k])) {
+			cleanups.push(runCollectionEffects(ui.host, ui[k], elementEffects))
+		} else if (ui[k]) {
+			const cleanup = runElementEffects(
+				ui.host,
+				ui[k] as ElementFromKey<U, typeof k>,
+				elementEffects,
+			)
+			if (cleanup) cleanups.push(cleanup)
+		}
+	}
+	return () => {
+		for (const cleanup of cleanups) cleanup()
+		cleanups.length = 0
+	}
+}
+
+/**
+ * Resolve reactive property name, reader function or signal
+ *
+ * @param {Reactive<T, P, E>} reactive - Reactive property name, reader function or signal
+ * @param {Component<P, U>} host - Component host element
+ * @param {E} target - Element to resolve reactive value for
+ * @param {string} [context] - Context for error logging
+ * @returns {T} - Resolved reactive value
+ */
+const resolveReactive = <
+	T extends {},
+	P extends ComponentProps,
+	E extends Element,
+>(
+	reactive: Reactive<T, P, E>,
+	host: Component<P>,
+	target: E,
+	context?: string,
+): T => {
+	try {
+		return isString(reactive)
+			? (host[reactive] as unknown as T)
+			: isSignal(reactive)
+				? reactive.get()
+				: isFunction(reactive)
+					? (reactive(target) as unknown as T)
+					: RESET
+	} catch (error) {
+		if (context) {
+			log(
+				error,
+				`Failed to resolve value of ${valueString(reactive)}${
+					context ? ` for ${context}` : ''
+				} in ${elementName(target)}${
+					(host as unknown as E) !== target ? ` in ${elementName(host)}` : ''
+				}`,
+				LOG_ERROR,
+			)
+		}
+		return RESET
+	}
+}
+
+/**
+ * Core effect function for updating element properties based on reactive values.
+ * This function handles the lifecycle of reading, updating, and deleting element properties
+ * while providing proper error handling and debugging support.
+ *
+ * @since 0.9.0
+ * @param {Reactive<T, P, E>} reactive - The reactive value that drives the element updates
+ * @param {ElementUpdater<E, T>} updater - Configuration object defining how to read, update, and delete the element property
+ * @returns {Effect<P, E>} Effect function that manages the element property updates
+ */
+const updateElement =
+	<T extends {}, P extends ComponentProps, E extends Element>(
+		reactive: Reactive<T, P, E>,
+		updater: ElementUpdater<E, T>,
+	): Effect<P, E> =>
+	(host, target): Cleanup => {
+		const { op, name = '', read, update } = updater
+		const operationDesc = getUpdateDescription(op, name)
+
+		const ok = (verb: string) => () => {
+			if (DEV_MODE && host.debug) {
+				log(
+					target,
+					`${verb} ${operationDesc} of ${elementName(target)} in ${elementName(host)}`,
+				)
+			}
+			updater.resolve?.(target)
+		}
+
+		const err = (verb: string) => (error: unknown) => {
+			log(
+				error,
+				`Failed to ${verb} ${operationDesc} of ${elementName(target)} in ${elementName(host)}`,
+				LOG_ERROR,
+			)
+			updater.reject?.(error)
+		}
+
+		const fallback = read(target)
+
+		return createEffect(() => {
+			const value = resolveReactive(reactive, host, target, operationDesc)
+			const resolvedValue =
+				value === RESET
+					? fallback
+					: value === UNSET
+						? updater.delete
+							? null
+							: fallback
+						: value
+
+			if (updater.delete && resolvedValue === null) {
+				try {
+					updater.delete!(target)
+					ok('delete')()
+				} catch (error) {
+					err('delete')(error)
+				}
+			} else if (resolvedValue != null) {
+				const current = read(target)
+				if (Object.is(resolvedValue, current)) return
+				try {
+					update(target, resolvedValue)
+					ok('update')()
+				} catch (error) {
+					err('update')(error)
+				}
+			}
+		})
+	}
+
+/**
+ * Effect for dynamically inserting or removing elements based on a reactive numeric value.
+ * Positive values insert elements, negative values remove them.
+ *
+ * @since 0.12.1
+ * @param {Reactive<number, P, E>} reactive - Reactive value determining number of elements to insert (positive) or remove (negative)
+ * @param {ElementInserter<E>} inserter - Configuration object defining how to create and position elements
+ * @returns {Effect<P, E>} Effect function that manages element insertion and removal
+ * /
+const insertOrRemoveElement =
+	<P extends ComponentProps, E extends Element = HTMLElement>(
+		reactive: Reactive<number, P, E>,
+		inserter?: ElementInserter<E>,
+	): Effect<P, E> =>
+	(host, target) => {
+		const ok = (verb: string) => () => {
+			if (DEV_MODE && host.debug) {
+				log(
+					target,
+					`${verb} element in ${elementName(target)} in ${elementName(host)}`,
+				)
+			}
+			if (isFunction(inserter?.resolve)) {
+				inserter.resolve(target)
+			} else {
+				const signal = isSignal<number>(reactive) ? reactive : undefined
+				if (isState(signal)) signal.set(0)
+			}
+		}
+
+		const err = (verb: string) => (error: unknown) => {
+			log(
+				error,
+				`Failed to ${verb} element in ${elementName(target)} in ${elementName(host)}`,
+				LOG_ERROR,
+			)
+			inserter?.reject?.(error)
+		}
+
+		return createEffect(() => {
+			const diff = resolveReactive(
+				reactive,
+				host,
+				target,
+				'insertion or deletion',
+			)
+			const resolvedDiff = diff === RESET ? 0 : diff
+
+			if (resolvedDiff > 0) {
+				// Positive diff => insert element
+				if (!inserter) throw new TypeError(`No inserter provided`)
+				try {
+					for (let i = 0; i < resolvedDiff; i++) {
+						const element = inserter.create(target)
+						if (!element) continue
+						target.insertAdjacentElement(
+							inserter.position ?? 'beforeend',
+							element,
+						)
+					}
+					ok('insert')()
+				} catch (error) {
+					err('insert')(error)
+				}
+			} else if (resolvedDiff < 0) {
+				try {
+					if (
+						inserter &&
+						(inserter.position === 'afterbegin' ||
+							inserter.position === 'beforeend')
+					) {
+						for (let i = 0; i > resolvedDiff; i--) {
+							if (inserter.position === 'afterbegin')
+								target.firstElementChild?.remove()
+							else target.lastElementChild?.remove()
+						}
+					} else {
+						target.remove()
+					}
+					ok('remove')()
+				} catch (error) {
+					err('remove')(error)
+				}
+			}
+		})
+		} */
+
+export {
+	type Effect,
+	type Effects,
+	type ElementEffects,
+	type ElementUpdater,
+	type Reactive,
+	runEffects,
+	runElementEffects,
+	resolveReactive,
+	updateElement,
+	RESET,
+}

package/src/errors.ts

@@ -0,0 +1,160 @@
+import { valueString } from '@zeix/cause-effect'
+import { elementName } from './util'
+
+/* === Error Classes === */
+
+/**
+ * Error thrown when a circular dependency is detected in a selection signal
+ *
+ * @since 0.14.0
+ */
+class CircularMutationError extends Error {
+	/**
+	 * @param {HTMLElement} host - Host component
+	 * @param {string} selector - Selector used to find the elements
+	 */
+	constructor(host: HTMLElement, selector: string) {
+		super(
+			`Circular dependency detected in selection signal for component ${elementName(host)} with selector "${selector}"`,
+		)
+		this.name = 'CircularMutationError'
+	}
+}
+
+/**
+ * Error thrown when component name violates rules for custom element names
+ *
+ * @since 0.14.0
+ */
+class InvalidComponentNameError extends TypeError {
+	/**
+	 * @param {string} component - Component name
+	 */
+	constructor(component: string) {
+		super(
+			`Invalid component name "${component}". Custom element names must contain a hyphen, start with a lowercase letter, and contain only lowercase letters, numbers, and hyphens.`,
+		)
+		this.name = 'InvalidComponentNameError'
+	}
+}
+
+/**
+ * Error thrown when trying to assign a property name that conflicts with reserved words or inherited HTMLElement properties
+ *
+ * @since 0.14.0
+ */
+class InvalidPropertyNameError extends TypeError {
+	/**
+	 * @param {string} component - Component name
+	 * @param {string} prop - Property name
+	 * @param {string} reason - Explanation why the property is invalid
+	 */
+	constructor(component: string, prop: string, reason: string) {
+		super(
+			`Invalid property name "${prop}" for component <${component}>. ${reason}`,
+		)
+		this.name = 'InvalidPropertyNameError'
+	}
+}
+
+/**
+ * Error thrown when setup function does not return effects
+ *
+ * @since 0.14.0
+ */
+class InvalidEffectsError extends TypeError {
+	/**
+	 * @param {HTMLElement} host - Host component
+	 * @param {Error} cause - Error that caused the invalid effects
+	 */
+	constructor(host: HTMLElement, cause?: Error) {
+		super(
+			`Invalid effects in component ${elementName(host)}. Effects must be a record of effects for UI elements or the component, or a Promise that resolves to effects.`,
+		)
+		this.name = 'InvalidEffectsError'
+		if (cause) this.cause = cause
+	}
+}
+
+/**
+ * Error thrown when a required desacendent element does not exist in a component's DOM subtree
+ *
+ * @since 0.14.0
+ */
+class MissingElementError extends Error {
+	/**
+	 * @param {HTMLElement} host - Host component
+	 * @param {string} selector - Selector used to find the elements
+	 * @param {string} required - Explanation why the element is required
+	 */
+	constructor(host: HTMLElement, selector: string, required: string) {
+		super(
+			`Missing required element <${selector}> in component ${elementName(host)}. ${required}`,
+		)
+		this.name = 'MissingElementError'
+	}
+}
+
+/**
+ * Error when a component's dependencies are not met within a specified timeout
+ *
+ * @since 0.14.0
+ */
+class DependencyTimeoutError extends Error {
+	/**
+	 * @param {HTMLElement} host - Host component
+	 * @param {string[]} missing - List of missing dependencies
+	 */
+	constructor(host: HTMLElement, missing: string[]) {
+		super(
+			`Timeout waiting for: [${missing.join(', ')}] in component ${elementName(host)}.`,
+		)
+		this.name = 'DependencyTimeoutError'
+	}
+}
+
+/**
+ * Error thrown when reactives passed to a component are invalid
+ *
+ * @since 0.15.0
+ */
+class InvalidReactivesError extends TypeError {
+	/**
+	 * @param {HTMLElement} host - Host component
+	 * @param {HTMLElement} target - Target component
+	 * @param {unknown} reactives - Reactives passed to the component
+	 */
+	constructor(host: HTMLElement, target: HTMLElement, reactives: unknown) {
+		super(
+			`Expected reactives passed from ${elementName(host)} to ${elementName(target)} to be a record of signals, reactive property names or functions. Got ${valueString(reactives)}.`,
+		)
+		this.name = 'InvalidReactivesError'
+	}
+}
+
+/**
+ * Error thrown when target element is not a custom element as expected
+ *
+ * @since 0.15.0
+ */
+class InvalidCustomElementError extends TypeError {
+	/**
+	 * @param {HTMLElement} target - Target component
+	 * @param {string} where - Location where the error occurred
+	 */
+	constructor(target: HTMLElement, where: string) {
+		super(`Target ${elementName(target)} is not a custom element in ${where}.`)
+		this.name = 'InvalidCustomElementError'
+	}
+}
+
+export {
+	CircularMutationError,
+	DependencyTimeoutError,
+	InvalidComponentNameError,
+	InvalidCustomElementError,
+	InvalidPropertyNameError,
+	InvalidEffectsError,
+	InvalidReactivesError,
+	MissingElementError,
+}

package/src/parsers/boolean.ts

@@ -0,0 +1,14 @@
+import type { Parser } from '../parsers'
+import type { UI } from '../ui'
+
+/**
+ * Parse a boolean attribute as an actual boolean value
+ *
+ * @since 0.13.1
+ * @returns {Parser<boolean, UI>}
+ */
+const asBoolean =
+	(): Parser<boolean, UI> => (_: UI, value: string | null | undefined) =>
+		value != null && value !== 'false'
+
+export { asBoolean }

package/src/parsers/json.ts

@@ -0,0 +1,33 @@
+import { type Fallback, getFallback, type Parser } from '../parsers'
+import type { UI } from '../ui'
+
+/**
+ * Parse a string as a JSON serialized object with a fallback
+ *
+ * @since 0.11.0
+ * @param {Fallback<T, U>} fallback - Fallback value or reader function
+ * @returns {Parser<T, U>} Parser function
+ * @throws {TypeError} If the value and fallback are both null or undefined
+ * @throws {SyntaxError} If value is not a valid JSON string
+ */
+const asJSON =
+	<T extends {}, U extends UI>(fallback: Fallback<T, U>): Parser<T, U> =>
+	(ui: U, value: string | null | undefined) => {
+		if ((value ?? fallback) == null)
+			throw new TypeError(
+				'asJSON: Value and fallback are both null or undefined',
+			)
+		if (value == null) return getFallback(ui, fallback)
+		if (value === '') throw new TypeError('Empty string is not valid JSON')
+		let result: T | undefined
+		try {
+			result = JSON.parse(value)
+		} catch (error) {
+			throw new SyntaxError(`Failed to parse JSON: ${String(error)}`, {
+				cause: error,
+			})
+		}
+		return result ?? getFallback(ui, fallback)
+	}
+
+export { asJSON }

package/src/parsers/number.ts

@@ -0,0 +1,55 @@
+import { type Fallback, getFallback, type Parser } from '../parsers'
+import type { UI } from '../ui'
+
+/* === Internal Functions === */
+
+const parseNumber = (
+	parseFn: (v: string) => number,
+	value: string | null | undefined,
+) => {
+	if (value == null) return
+	const parsed = parseFn(value)
+	return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/* === Exported Functions === */
+
+/**
+ * Parse a string as a number forced to integer with a fallback
+ *
+ * Supports hexadecimal and scientific notation
+ *
+ * @since 0.11.0
+ * @param {Fallback<number, U>} [fallback=0] - Fallback value or reader function
+ * @returns {Parser<number, U>} Parser function
+ */
+const asInteger =
+	<U extends UI>(fallback: Fallback<number, U> = 0): Parser<number, U> =>
+	(ui: U, value: string | null | undefined) => {
+		if (value == null) return getFallback(ui, fallback)
+
+		// Handle hexadecimal notation
+		const trimmed = value.trim()
+		if (trimmed.toLowerCase().startsWith('0x'))
+			return (
+				parseNumber(v => parseInt(v, 16), trimmed) ?? getFallback(ui, fallback)
+			)
+
+		// Handle other formats (including scientific notation)
+		const parsed = parseNumber(parseFloat, value)
+		return parsed != null ? Math.trunc(parsed) : getFallback(ui, fallback)
+	}
+
+/**
+ * Parse a string as a number with a fallback
+ *
+ * @since 0.11.0
+ * @param {Fallback<number, U>} [fallback=0] - Fallback value or reader function
+ * @returns {Parser<number, U>} Parser function
+ */
+const asNumber =
+	<U extends UI>(fallback: Fallback<number, U> = 0): Parser<number, U> =>
+	(ui: U, value: string | null | undefined) =>
+		parseNumber(parseFloat, value) ?? getFallback(ui, fallback)
+
+export { asInteger, asNumber }

package/src/parsers/string.ts

@@ -0,0 +1,32 @@
+import { type Fallback, getFallback, type Parser } from '../parsers'
+import type { UI } from '../ui'
+
+/**
+ * Pass through string with a fallback
+ *
+ * @since 0.11.0
+ * @param {Fallback<string, U>} [fallback=''] - Fallback value or reader function
+ * @returns {Parser<string, U>} Parser function
+ */
+const asString =
+	<U extends UI>(fallback: Fallback<string, U> = ''): Parser<string, U> =>
+	(ui: U, value: string | null | undefined) =>
+		value ?? getFallback(ui, fallback)
+
+/**
+ * Parse a string as a multi-state value (for example: ['true', 'false', 'mixed'], defaulting to the first valid option
+ *
+ * @since 0.9.0
+ * @param {[string, ...string[]]} valid - Array of valid values
+ * @returns {Parser<string, UI>} Parser function
+ */
+const asEnum =
+	(valid: [string, ...string[]]): Parser<string, UI> =>
+	(_: UI, value: string | null | undefined) => {
+		if (value == null) return valid[0]
+		const lowerValue = value.toLowerCase()
+		const matchingValid = valid.find(v => v.toLowerCase() === lowerValue)
+		return matchingValid ? value : valid[0]
+	}
+
+export { asString, asEnum }