@zeix/le-truc 0.15.0

package/src/context.ts

@@ -0,0 +1,156 @@
+import {
+	type Cleanup,
+	type Computed,
+	createComputed,
+	isFunction,
+	isString,
+} from '@zeix/cause-effect'
+
+import type { Component, ComponentProps } from './component'
+import { type Fallback, getFallback, type Reader } from './parsers'
+import type { UI } from './ui'
+
+/** @see https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md */
+
+/* === Types === */
+
+/**
+ * A context key.
+ *
+ * A context key can be any type of object, including strings and symbols. The
+ *  Context type brands the key type with the `__context__` property that
+ * carries the type of the value the context references.
+ */
+type Context<K, V> = K & { __context__: V }
+
+/**
+ * An unknown context type
+ */
+type UnknownContext = Context<unknown, unknown>
+
+/**
+ * A helper type which can extract a Context value type from a Context type
+ */
+type ContextType<T extends UnknownContext> =
+	T extends Context<infer _, infer V> ? V : never
+
+/**
+ * A callback which is provided by a context requester and is called with the value satisfying the request.
+ * This callback can be called multiple times by context providers as the requested value is changed.
+ */
+type ContextCallback<V> = (value: V, unsubscribe?: () => void) => void
+
+declare global {
+	interface HTMLElementEventMap {
+		/**
+		 * A 'context-request' event can be emitted by any element which desires
+		 * a context value to be injected by an external provider.
+		 */
+		'context-request': ContextRequestEvent<UnknownContext>
+	}
+}
+
+/* === Constants === */
+
+const CONTEXT_REQUEST = 'context-request'
+
+/* === Exported class === */
+
+/**
+ * Class for context-request events
+ *
+ * An event fired by a context requester to signal it desires a named context.
+ *
+ * A provider should inspect the `context` property of the event to determine if it has a value that can
+ * satisfy the request, calling the `callback` with the requested value if so.
+ *
+ * If the requested context event contains a truthy `subscribe` value, then a provider can call the callback
+ * multiple times if the value is changed, if this is the case the provider should pass an `unsubscribe`
+ * function to the callback which requesters can invoke to indicate they no longer wish to receive these updates.
+ *
+ * @class ContextRequestEvent
+ * @extends {Event}
+ *
+ * @property {T} context - context key
+ * @property {ContextCallback<ContextType<T>>} callback - callback function for value getter and unsubscribe function
+ * @property {boolean} [subscribe=false] - whether to subscribe to context changes
+ */
+class ContextRequestEvent<T extends UnknownContext> extends Event {
+	readonly context: T
+	readonly callback: ContextCallback<ContextType<T>>
+	readonly subscribe: boolean
+
+	constructor(
+		context: T,
+		callback: ContextCallback<ContextType<T>>,
+		subscribe: boolean = false,
+	) {
+		super(CONTEXT_REQUEST, {
+			bubbles: true,
+			composed: true,
+		})
+		this.context = context
+		this.callback = callback
+		this.subscribe = subscribe
+	}
+}
+
+/**
+ * Provide a context for descendant component consumers
+ *
+ * @since 0.13.3
+ * @param {Context<string, P[K]>[]} contexts - Array of contexts to provide
+ * @returns {(host: Component<P>) => Cleanup} Function to add an event listener for ContextRequestEvent returning a cleanup function to remove the event listener
+ */
+const provideContexts =
+	<P extends ComponentProps>(
+		contexts: Array<keyof P>,
+	): ((host: Component<P>) => Cleanup) =>
+	(host: Component<P>) => {
+		const listener = (e: ContextRequestEvent<UnknownContext>) => {
+			const { context, callback } = e
+			if (
+				isString(context) &&
+				contexts.includes(context as unknown as Extract<keyof P, string>) &&
+				isFunction(callback)
+			) {
+				e.stopImmediatePropagation()
+				callback(() => host[context])
+			}
+		}
+		host.addEventListener(CONTEXT_REQUEST, listener)
+		return () => host.removeEventListener(CONTEXT_REQUEST, listener)
+	}
+
+/**
+ * Consume a context value for a component
+ *
+ * @since 0.15.0
+ * @param {Context<string, () => T>} context - Context key to consume
+ * @param {Fallback<T, U>} fallback - Fallback value or reader function for fallback
+ * @returns {Reader<Computed<T>, U>} Computed signal that returns the consumed context the fallback value
+ */
+const requestContext =
+	<T extends {}, P extends ComponentProps, U extends UI>(
+		context: Context<string, () => T>,
+		fallback: Fallback<T, U & { host: Component<P> }>,
+	): Reader<Computed<T>, U & { host: Component<P> }> =>
+	(ui: U & { host: Component<P> }) => {
+		let consumed = () => getFallback(ui, fallback)
+		ui.host.dispatchEvent(
+			new ContextRequestEvent(context, (getter: () => T) => {
+				consumed = getter
+			}),
+		)
+		return createComputed(consumed)
+	}
+
+export {
+	type Context,
+	type UnknownContext,
+	type ContextType,
+	CONTEXT_REQUEST,
+	ContextRequestEvent,
+	provideContexts,
+	requestContext,
+}

package/src/effects/attribute.ts

@@ -0,0 +1,82 @@
+import type { ComponentProps } from '../component'
+import { type Effect, type Reactive, updateElement } from '../effects'
+
+/* === Internal Functions === */
+
+const isSafeURL = (value: string): boolean => {
+	if (/^(mailto|tel):/i.test(value)) return true
+	if (value.includes('://')) {
+		try {
+			const url = new URL(value, window.location.origin)
+			return ['http:', 'https:', 'ftp:'].includes(url.protocol)
+		} catch {
+			return false
+		}
+	}
+	return true
+}
+
+const safeSetAttribute = (
+	element: Element,
+	attr: string,
+	value: string,
+): void => {
+	if (/^on/i.test(attr)) throw new Error(`Unsafe attribute: ${attr}`)
+	value = String(value).trim()
+	if (!isSafeURL(value)) throw new Error(`Unsafe URL for ${attr}: ${value}`)
+	element.setAttribute(attr, value)
+}
+
+/* === Exported Functions === */
+
+/**
+ * Effect for setting an attribute on an element.
+ * Sets the specified attribute with security validation for unsafe values.
+ *
+ * @since 0.8.0
+ * @param {string} name - Name of the attribute to set
+ * @param {Reactive<string, P, E>} reactive - Reactive value bound to the attribute value (defaults to attribute name)
+ * @returns {Effect<P, E>} Effect function that sets the attribute on the element
+ */
+const setAttribute = <P extends ComponentProps, E extends Element>(
+	name: string,
+	reactive: Reactive<string, P, E> = name as Reactive<string, P, E>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'a',
+		name,
+		read: el => el.getAttribute(name),
+		update: (el, value) => {
+			safeSetAttribute(el, name, value)
+		},
+		delete: el => {
+			el.removeAttribute(name)
+		},
+	})
+
+/**
+ * Effect for toggling a boolean attribute on an element.
+ * When the reactive value is true, the attribute is present; when false, it's absent.
+ *
+ * @since 0.8.0
+ * @param {string} name - Name of the attribute to toggle
+ * @param {Reactive<boolean, P, E>} reactive - Reactive value bound to the attribute presence (defaults to attribute name)
+ * @returns {Effect<P, E>} Effect function that toggles the attribute on the element
+ */
+const toggleAttribute = <
+	P extends ComponentProps,
+	E extends Element = HTMLElement,
+>(
+	name: string,
+	reactive: Reactive<boolean, P, E> = name as Reactive<boolean, P, E>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'a',
+		name,
+		read: el => el.hasAttribute(name),
+		update: (el, value) => {
+			el.toggleAttribute(name, value)
+		},
+	})
+
+export { setAttribute, toggleAttribute }

package/src/effects/class.ts

@@ -0,0 +1,28 @@
+import type { ComponentProps } from '../component'
+import { type Effect, type Reactive, updateElement } from '../effects'
+
+/* === Exported Function === */
+
+/**
+ * Effect for toggling a CSS class token on an element.
+ * When the reactive value is true, the class is added; when false, it's removed.
+ *
+ * @since 0.8.0
+ * @param {string} token - CSS class token to toggle
+ * @param {Reactive<boolean, P, E>} reactive - Reactive value bound to the class presence (defaults to class name)
+ * @returns {Effect<P, U, E>} Effect function that toggles the class on the element
+ */
+const toggleClass = <P extends ComponentProps, E extends Element>(
+	token: string,
+	reactive: Reactive<boolean, P, E> = token as Reactive<boolean, P, E>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'c',
+		name: token,
+		read: el => el.classList.contains(token),
+		update: (el, value) => {
+			el.classList.toggle(token, value)
+		},
+	})
+
+export { toggleClass }

package/src/effects/event.ts

@@ -0,0 +1,67 @@
+import { batch, type Cleanup, isRecord } from '@zeix/cause-effect'
+import type { ComponentProps } from '../component'
+import { type Effect } from '../effects'
+import { PASSIVE_EVENTS, schedule } from '../scheduler'
+import { elementName, LOG_ERROR, log } from '../util'
+
+/* === Types === */
+
+type EventType<K extends string> = K extends keyof HTMLElementEventMap
+	? HTMLElementEventMap[K]
+	: Event
+
+type EventHandler<P extends ComponentProps, Evt extends Event> = (
+	event: Evt,
+) => { [K in keyof P]?: P[K] } | void | Promise<void>
+
+/* === Exported Function === */
+
+/**
+ * Effect for attaching an event listener to an element.
+ * Provides proper cleanup when the effect is disposed.
+ *
+ * @since 0.14.0
+ * @param {K} type - Event type
+ * @param {EventHandler<P, E, EventType<K>>} handler - Event handler function
+ * @param {AddEventListenerOptions | boolean} options - Event listener options
+ * @returns {Effect<ComponentProps, E>} Effect function that manages the event listener
+ */
+const on =
+	<
+		K extends keyof HTMLElementEventMap | string,
+		P extends ComponentProps,
+		E extends Element = HTMLElement,
+	>(
+		type: K,
+		handler: EventHandler<P, EventType<K>>,
+		options: AddEventListenerOptions = {},
+	): Effect<P, E> =>
+	(host, target): Cleanup => {
+		if (!('passive' in options))
+			options = { ...options, passive: PASSIVE_EVENTS.has(type) }
+		const listener = (e: Event) => {
+			const task = () => {
+				const result = handler(e as EventType<K>)
+				if (!isRecord(result)) return
+				batch(() => {
+					for (const [key, value] of Object.entries(result)) {
+						try {
+							host[key as keyof P] = value
+						} catch (error) {
+							log(
+								error,
+								`Reactive property "${key}" on ${elementName(host)} from event ${type} on ${elementName(target)} could not be set, because it is read-only.`,
+								LOG_ERROR,
+							)
+						}
+					}
+				})
+			}
+			if (options.passive) schedule(target, task)
+			else task()
+		}
+		target.addEventListener(type, listener, options)
+		return () => target.removeEventListener(type, listener)
+	}
+
+export { type EventHandler, type EventType, on }

package/src/effects/html.ts

@@ -0,0 +1,60 @@
+import type { ComponentProps } from '../component'
+import { type Effect, type Reactive, updateElement } from '../effects'
+import { schedule } from '../scheduler'
+
+/* === Types === */
+
+type DangerouslySetInnerHTMLOptions = {
+	shadowRootMode?: ShadowRootMode
+	allowScripts?: boolean
+}
+
+/* === Exported Function === */
+
+/**
+ * Effect for setting the inner HTML of an element with optional Shadow DOM support.
+ * Provides security options for script execution and shadow root creation.
+ *
+ * @since 0.11.0
+ * @param {Reactive<string, P, E>} reactive - Reactive value bound to the inner HTML content
+ * @param {DangerouslySetInnerHTMLOptions} options - Configuration options: shadowRootMode, allowScripts
+ * @returns {Effect<P, E>} Effect function that sets the inner HTML of the element
+ */
+const dangerouslySetInnerHTML = <P extends ComponentProps, E extends Element>(
+	reactive: Reactive<string, P, E>,
+	options: DangerouslySetInnerHTMLOptions = {},
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'h',
+		read: el =>
+			(el.shadowRoot || !options.shadowRootMode ? el : null)?.innerHTML ?? '',
+		update: (el, html) => {
+			const { shadowRootMode, allowScripts } = options
+			if (!html) {
+				if (el.shadowRoot) el.shadowRoot.innerHTML = '<slot></slot>'
+				return ''
+			}
+			if (shadowRootMode && !el.shadowRoot)
+				el.attachShadow({ mode: shadowRootMode })
+			const target = el.shadowRoot || el
+			schedule(el, () => {
+				target.innerHTML = html
+				if (allowScripts) {
+					target.querySelectorAll('script').forEach(script => {
+						const newScript = document.createElement('script')
+						newScript.appendChild(
+							document.createTextNode(script.textContent ?? ''),
+						)
+						// Safely copy only the type attribute to preserve module/MIME type info
+						const typeAttr = script.getAttribute('type')
+						if (typeAttr) newScript.setAttribute('type', typeAttr)
+						target.appendChild(newScript)
+						script.remove()
+					})
+				}
+			})
+			return allowScripts ? ' with scripts' : ''
+		},
+	})
+
+export { type DangerouslySetInnerHTMLOptions, dangerouslySetInnerHTML }

package/src/effects/method.ts

@@ -0,0 +1,57 @@
+import type { ComponentProps } from '../component'
+import { type Effect, type Reactive, updateElement } from '../effects'
+import { hasMethod } from '../util'
+
+/* === Exported Functions === */
+
+/**
+ * Effect for calling a method on an element.
+ *
+ * @since 0.13.3
+ * @param {K} methodName - Name of the method to call
+ * @param {Reactive<boolean, P, E>} reactive - Reactive value bound to the method call
+ * @param {unknown[]} args - Arguments to pass to the method
+ * @returns Effect function that calls the method on the element
+ */
+const callMethod = <
+	P extends ComponentProps,
+	E extends HTMLElement,
+	K extends keyof E & string,
+>(
+	methodName: K,
+	reactive: Reactive<boolean, P, E>,
+	args?: unknown[],
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'm',
+		name: String(methodName),
+		read: () => null,
+		update: (el, value) => {
+			if (value && hasMethod(el, methodName)) {
+				if (args) el[methodName](...args)
+				else el[methodName]()
+			}
+		},
+	})
+
+/**
+ * Effect for controlling element focus by calling the 'focus()' method.
+ * If the reactive value is true, element will be focussed; when false, nothing happens.
+ *
+ * @since 0.13.3
+ * @param {Reactive<boolean, P, E>} reactive - Reactive value bound to the focus state
+ * @returns {Effect<P, E>} Effect function that sets element focus
+ */
+const focus = <P extends ComponentProps, E extends HTMLElement>(
+	reactive: Reactive<boolean, P, E>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'm',
+		name: 'focus',
+		read: el => el === document.activeElement,
+		update: (el, value) => {
+			if (value && hasMethod(el, 'focus')) el.focus()
+		},
+	})
+
+export { callMethod, focus }

package/src/effects/pass.ts

@@ -0,0 +1,103 @@
+import {
+	createComputed,
+	isComputedCallback,
+	isFunction,
+	isRecord,
+	isSignal,
+	isString,
+	type MaybeCleanup,
+	UNSET,
+} from '@zeix/cause-effect'
+import type { Component, ComponentProps } from '../component'
+import type { Effect, Reactive } from '../effects'
+import { InvalidCustomElementError, InvalidReactivesError } from '../errors'
+import { elementName, isCustomElement } from '../util'
+
+/* === Types === */
+
+type PassedProp<T, P extends ComponentProps, E extends HTMLElement> =
+	| Reactive<T, P, E>
+	| [Reactive<T, P, E>, (value: T) => void]
+
+type PassedProps<P extends ComponentProps, Q extends ComponentProps> = {
+	[K in keyof Q & string]?: PassedProp<Q[K], P, Component<Q>>
+}
+
+/* === Exported Function === */
+
+/**
+ * Effect for passing reactive values to a descendant Le Truc component.
+ *
+ * @since 0.15.0
+ * @param {MutableReactives<Component<Q>, P>} props - Reactive values to pass
+ * @returns {Effect<P, Component<Q>>} Effect function that passes reactive values to the descendant component
+ * @throws {InvalidCustomElementError} When the target element is not a valid custom element
+ * @throws {InvalidReactivesError} When the provided reactives is not a record of signals, reactive property names or functions
+ * @throws {Error} When passing signals failed for some other reason
+ */
+const pass =
+	<P extends ComponentProps, Q extends ComponentProps>(
+		props: PassedProps<P, Q> | ((target: Component<Q>) => PassedProps<P, Q>),
+	): Effect<P, Component<Q>> =>
+	(host, target): MaybeCleanup => {
+		if (!isCustomElement(target))
+			throw new InvalidCustomElementError(
+				target,
+				`pass from ${elementName(host)}`,
+			)
+		const reactives = isFunction(props) ? props(target) : props
+		if (!isRecord(reactives))
+			throw new InvalidReactivesError(host, target, reactives)
+
+		const resetProperties: PropertyDescriptorMap = {}
+
+		// Return getter from signal, reactive property name or function
+		const getGetter = (value: unknown) => {
+			if (isSignal(value)) return value.get
+			const fn =
+				isString(value) && value in host
+					? () => host[value as keyof typeof host]
+					: isComputedCallback(value)
+						? value
+						: undefined
+			return fn ? createComputed(fn).get : undefined
+		}
+
+		// Iterate through reactives
+		for (const [prop, reactive] of Object.entries(reactives)) {
+			if (reactive == null) continue
+
+			// Ensure target has configurable property
+			const descriptor = Object.getOwnPropertyDescriptor(target, prop)
+			if (!(prop in target) || !descriptor?.configurable) continue
+
+			// Determine getter	and setter
+			const applied =
+				isFunction(reactive) && reactive.length === 1
+					? reactive(target)
+					: reactive
+			const isArray = Array.isArray(applied) && applied.length === 2
+			const getter = getGetter(isArray ? applied[0] : applied)
+			const setter = isArray && isFunction(applied[1]) ? applied[1] : undefined
+			if (!getter) continue
+
+			// Store original descriptor for reset and assign new descriptor
+			resetProperties[prop] = descriptor
+			Object.defineProperty(target, prop, {
+				configurable: true,
+				enumerable: true,
+				get: getter,
+				set: setter,
+			})
+
+			// Unset previous value so subscribers are notified
+			descriptor.set?.call(target, UNSET)
+		}
+
+		// Reset to original descriptors on cleanup
+		return () => {
+			Object.defineProperties(target, resetProperties)
+		}
+	}
+
+export { type PassedProp, type PassedProps, pass }

package/src/effects/property.ts

@@ -0,0 +1,57 @@
+import { UNSET } from '@zeix/cause-effect'
+import type { ComponentProps } from '../component'
+import { type Effect, type Reactive, updateElement } from '../effects'
+
+/* === Exported Functions === */
+
+/**
+ * Effect for setting a property on an element.
+ * Sets the specified property directly on the element object.
+ *
+ * @since 0.8.0
+ * @param {K} key - Name of the property to set
+ * @param {Reactive<E[K], P, E>} reactive - Reactive value bound to the property value (defaults to property name)
+ * @returns {Effect<P, E>} Effect function that sets the property on the element
+ */
+const setProperty = <
+	P extends ComponentProps,
+	E extends Element,
+	K extends keyof E & string,
+>(
+	key: K,
+	reactive: Reactive<E[K] & {}, P, E> = key as unknown as Reactive<
+		E[K] & {},
+		P,
+		E
+	>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'p',
+		name: key,
+		read: el => (key in el ? el[key] : UNSET),
+		update: (el, value) => {
+			el[key] = value
+		},
+	})
+
+/**
+ * Effect for controlling element visibility by setting the 'hidden' property.
+ * When the reactive value is true, the element is shown; when false, it's hidden.
+ *
+ * @since 0.13.1
+ * @param {Reactive<boolean, P, E>} reactive - Reactive value bound to the visibility state
+ * @returns {Effect<P, E>} Effect function that controls element visibility
+ */
+const show = <P extends ComponentProps, E extends HTMLElement = HTMLElement>(
+	reactive: Reactive<boolean, P, E>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 'p',
+		name: 'hidden',
+		read: el => !el.hidden,
+		update: (el, value) => {
+			el.hidden = !value
+		},
+	})
+
+export { setProperty, show }

package/src/effects/style.ts

@@ -0,0 +1,34 @@
+import type { ComponentProps } from '../component'
+import { type Effect, type Reactive, updateElement } from '../effects'
+
+/* === Exported Function === */
+
+/**
+ * Effect for setting a CSS style property on an element.
+ * Sets the specified style property with support for deletion via UNSET.
+ *
+ * @since 0.8.0
+ * @param {string} prop - Name of the CSS style property to set
+ * @param {Reactive<string, P, E>} reactive - Reactive value bound to the style property value (defaults to property name)
+ * @returns {Effect<P, E>} Effect function that sets the style property on the element
+ */
+const setStyle = <
+	P extends ComponentProps,
+	E extends HTMLElement | SVGElement | MathMLElement,
+>(
+	prop: string,
+	reactive: Reactive<string, P, E> = prop as Reactive<string, P, E>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 's',
+		name: prop,
+		read: el => el.style.getPropertyValue(prop),
+		update: (el, value) => {
+			el.style.setProperty(prop, value)
+		},
+		delete: el => {
+			el.style.removeProperty(prop)
+		},
+	})
+
+export { setStyle }

package/src/effects/text.ts

@@ -0,0 +1,28 @@
+import type { ComponentProps } from '../component'
+import { type Effect, type Reactive, updateElement } from '../effects'
+
+/* === Exported Function === */
+
+/**
+ * Effect for setting the text content of an element.
+ * Replaces all child nodes (except comments) with a single text node.
+ *
+ * @since 0.8.0
+ * @param {Reactive<string, P, E>} reactive - Reactive value bound to the text content
+ * @returns {Effect<P, E>} Effect function that sets the text content of the element
+ */
+const setText = <P extends ComponentProps, E extends Element>(
+	reactive: Reactive<string, P, E>,
+): Effect<P, E> =>
+	updateElement(reactive, {
+		op: 't',
+		read: el => el.textContent,
+		update: (el, value) => {
+			Array.from(el.childNodes)
+				.filter(node => node.nodeType !== Node.COMMENT_NODE)
+				.forEach(node => node.remove())
+			el.append(document.createTextNode(value))
+		},
+	})
+
+export { setText }