lilact 0.0.0

package/src/events.jsx

@@ -0,0 +1,175 @@
+/*
+
+	Lilact
+	Copyright (C) 2024-2026 Arash Kazemi <contact.arash.kazemi@gmail.com>
+	All rights reserved.
+
+	BSD-2-Clause
+
+	Redistribution and use in source and binary forms, with or without
+	modification, are permitted provided that the following conditions are met:
+
+	* Redistributions of source code must retain the above copyright
+		notice, this list of conditions and the following disclaimer.
+	* Redistributions in binary form must reproduce the above copyright
+		notice, this list of conditions and the following disclaimer in the
+		documentation and/or other materials provided with the distribution.
+
+	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+	ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+	DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+	(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+	LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+	ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+	(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+	THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*/
+
+
+// Minimal shims (small and explicit)
+if (typeof Element !== 'undefined' && !Element.prototype.matches) {
+	Element.prototype.matches = Element.prototype.msMatchesSelector ||
+															Element.prototype.webkitMatchesSelector ||
+															function(s) {
+																var matches = (this.document || this.ownerDocument).querySelectorAll(s);
+																var i = matches.length;
+																while (--i >= 0 && matches.item(i) !== this) {}
+																return i > -1;
+															};
+}
+
+if (typeof Event !== 'undefined' && !Event.prototype.composedPath) {
+	Event.prototype.composedPath = function() {
+		var path = [];
+		var el = this.target;
+		while (el) {
+			path.push(el);
+			el = el.parentElement;
+		}
+		path.push(window);
+		return path;
+	};
+}
+
+// Event pool for reuse
+const _pool = [];
+const MAX_POOL_SIZE = 10;
+
+function createSyntheticEvent(nativeEvent, currentTarget) {
+	// Reuse object from pool if available
+	const e = _pool.length ? _pool.pop() : {};
+
+	e.nativeEvent = nativeEvent;
+	e.type = nativeEvent.type;
+	e.target = nativeEvent.target || nativeEvent.srcElement || null;
+	e.currentTarget = currentTarget || nativeEvent.currentTarget || null;
+	e.timeStamp = nativeEvent.timeStamp || Date.now();
+	e.defaultPrevented = !!(nativeEvent.defaultPrevented);
+	e.isPropagationStopped = false;
+	e.isPersistent = false;
+
+	e.isDefaultPrevented = () => e.defaultPrevented;
+	e.preventDefault = () => {
+		if (nativeEvent.preventDefault) nativeEvent.preventDefault();
+		e.defaultPrevented = true;
+	};
+	e.stopPropagation = () => {
+		if (nativeEvent.stopPropagation) nativeEvent.stopPropagation();
+		e.isPropagationStopped = true;
+	};
+	e.persist = () => { e.isPersistent = true; };
+
+	// Convenience: normalized values for common props (touch, key, target value)
+	e.nativeEvent = nativeEvent;
+	e.key = nativeEvent.key || null;
+	e.code = nativeEvent.code || null;
+	e.which = nativeEvent.which || nativeEvent.keyCode || null;
+
+	// For input-like events normalize value and checked
+	try {
+		const tgt = e.target;
+		e.value = tgt && ('value' in tgt) ? tgt.value : undefined;
+		e.checked = tgt && ('checked' in tgt) ? tgt.checked : undefined;
+	} catch (err) {
+		e.value = undefined;
+		e.checked = undefined;
+	}
+
+	// composedPath helper
+	e.path = typeof nativeEvent.composedPath === 'function' ? nativeEvent.composedPath() : [e.target];
+
+	return e;
+}
+
+function releaseSyntheticEvent(e) {
+	if (e && !e.isPersistent) {
+		// Clean up references to avoid leaks
+		e.nativeEvent = null;
+		e.type = null;
+		e.target = null;
+		e.currentTarget = null;
+		e.timeStamp = 0;
+		e.defaultPrevented = false;
+		e.isPropagationStopped = false;
+		e.isPersistent = false;
+		e.isDefaultPrevented = null;
+		e.preventDefault = null;
+		e.stopPropagation = null;
+		e.persist = null;
+		e.key = null;
+		e.code = null;
+		e.which = null;
+		e.value = undefined;
+		e.checked = undefined;
+		e.path = null;
+
+		if (_pool.length < MAX_POOL_SIZE) _pool.push(e);
+	}
+}
+
+// Main wrapper factory
+// fn: function(syntheticEvent) { ... }
+// opts: { capture: bool, passive: bool, once: bool, stopPropagationOnTrueReturn: bool }
+function wrapListener(fn, opts = {}) {
+	const { stopPropagationOnTrueReturn = false } = opts;
+
+	return function handler(nativeEvent) {
+
+		const currentTarget = this || nativeEvent.currentTarget || null;
+		const sEvent = createSyntheticEvent(nativeEvent, currentTarget);
+
+		try {
+			const result = fn(sEvent);
+
+			// If user returns true and opted in, stop propagation
+			if (stopPropagationOnTrueReturn && result === true) {
+				sEvent.stopPropagation();
+			}
+		} finally {
+			// Release back to pool unless persisted
+			releaseSyntheticEvent(sEvent);
+		}
+	};
+}
+
+// Convenience: add/remove wrapper-managed listener
+function addWrappedEventListener(target, type, fn, options = {}) {
+	const handler = wrapListener(fn, options);
+
+	target.addEventListener(type, handler, options);
+	// Return a remover
+	return () => target.removeEventListener(type, handler, options);
+}
+
+// Export (CommonJS / ES module-friendly)
+const EventWrapper = {
+	wrapListener,
+	addWrappedEventListener,
+	createSyntheticEvent, // exported for advanced use
+	releaseSyntheticEvent
+};
+
+export default EventWrapper;

package/src/hooks.jsx

@@ -0,0 +1,461 @@
+/*
+
+	Lilact
+	Copyright (C) 2024-2026 Arash Kazemi <contact.arash.kazemi@gmail.com>
+	All rights reserved.
+
+	BSD-2-Clause
+
+	Redistribution and use in source and binary forms, with or without
+	modification, are permitted provided that the following conditions are met:
+
+	* Redistributions of source code must retain the above copyright
+		notice, this list of conditions and the following disclaimer.
+	* Redistributions in binary form must reproduce the above copyright
+		notice, this list of conditions and the following disclaimer in the
+		documentation and/or other materials provided with the distribution.
+
+	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+	ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+	DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+	(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+	LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+	ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+	(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+	THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*/
+
+ʔ defineSymbols ( "LILACT", [ "CORE", "COMPONENT" ] ) ʔ
+
+
+/**
+ * Hook wrapper/primitive used to implement custom hooks.
+ * Can be used by the user, but not encouraged. Only use after you
+ * study how Lilact itself uses it.
+ *
+ * @returns {hook} Hook result.
+ */
+export function useHook()
+{
+	const core = Lilact.current_component[0];
+	
+	if(core.hooks[core.hook_index]===undefined) {
+		core.hooks.push({});
+	}
+
+	return core.hooks[core.hook_index++];
+}
+
+/**
+ * Adds state to a component using a React-like [value, setter] pattern.
+ *
+ * @param {any} initialValue - Initial state value.
+ * @returns {any} Hook result (implementation-dependent; typically `[state, setState]`).
+ */
+export function useState(val)
+{
+	const hk = Lilact.useHook();
+
+	if( Lilact.isEmpty(hk) ) {
+		if(typeof(val)==='function') hk.value = val();
+		else hk.value = val;
+		
+		hk.set_func = function(core, hk, val) {
+			if(typeof(val)==='function') hk.value = val(hk.value);
+			else hk.value = val;
+
+			core.component.forceUpdate();
+		}.bind(undefined, Lilact.current_component[0], hk);
+
+	}
+
+	return [hk.value, hk.set_func];
+}
+
+/**
+ * Returns a memoized callback function whose identity stays stable until dependencies change.
+ *
+ * @param {Function} callback - Function to memoize.
+ * @param {Array<any>} deps - Dependency list.
+ * @returns {Function} Memoized callback.
+ */
+export function useCallback(callback, deps=[{}])
+{
+	const hk = Lilact.useHook();
+
+	if( Lilact.isEmpty(hk) ) {
+		hk.callback = callback;
+		hk.deps = deps;
+	}
+	else {
+		for(let d in deps) {
+			if( !Lilact.defaultIsEqual(deps[d],hk.deps[d]) ) {
+				hk.callback = callback;
+
+				hk.deps = deps;
+				break;
+			}
+		}
+	}
+
+	return hk.callback;
+}
+
+/**
+ * Creates a context object for sharing a value through the component tree.
+ *
+ * @param {any} [defaultValue] - Initial context value when no Provider is present.
+ * @returns {any} A context object (implementation-dependent).
+ */
+export function createContext(val)
+{
+	const prov = function({value, children}) {
+		return children;
+	};
+
+	return {
+		default: val,
+		Provider: prov
+	}
+}
+
+/**
+ * Reads the current value from a context.
+ *
+ * @param {any} context - Context object created by `createContext`.
+ * @returns {any} Current context value.
+ */
+export function useContext(ctx)
+{
+	let core = Lilact.current_component[0].parent;
+
+	while(core.entity!==ctx.Provider && core.parent) {
+		core = core.parent;
+	}
+
+	if(core.parent) {
+		let v = core.props?.value;
+		return v??=ctx.default;
+	}
+
+	return ctx.default;
+}
+
+/**
+ * Returns a stable, unique ID that is consistent across renders.
+ *
+ * @param {string} [prefix] - Optional id prefix.
+ * @returns {string} Stable unique id.
+ */
+export function useId(prefix="N")
+{
+	const hk = Lilact.useHook();
+
+	if( Lilact.isEmpty(hk) ) {
+		hk.id = prefix+Lilact.id_num++;
+	}
+
+	return hk.id;
+}
+
+/**
+ * Starts a transition and returns helpers for pending updates vs immediate ones.
+ *
+ * @returns {any} Transition API (implementation-dependent; typically `[isPending, startTransition]`).
+ */
+export function useTransition()
+{
+	const hk = Lilact.useHook();
+
+	if( Lilact.isEmpty(hk) ) {
+		hk.count=0;
+
+		hk.func =
+
+		(async function(core, hk, fn) {
+
+			hk.count++;
+
+			if(hk.count===1) {
+				core.component.forceUpdate();
+			}
+
+			await fn();
+
+			hk.count--;
+
+			if(hk.count===0) {
+				core.component.forceUpdate();
+			}
+		}
+
+		).bind(undefined, Lilact.current_component[0], hk);
+	}
+
+	return [ hk.count!=0, hk.func ];
+}
+
+/**
+ * Persists state in localStorage and keeps it in sync with the app.
+ *
+ * @param {string} key - localStorage key.
+ * @param {any} initialValue - Initial value used if nothing exists in localStorage.
+ * @returns {any} Stored state/result.
+ */
+export function useLocalStorage(key, default_val)
+{
+
+	const hk = Lilact.useHook();
+	let val;
+
+	try {
+		val = JSON.parse(localStorage[key]);
+	}
+	catch(e) {
+	}
+
+	if(val===undefined) {
+		if(typeof(default_val)==='function') default_val = default_val();
+		val = default_val;
+		localStorage[key] = JSON.stringify(val);
+	}
+
+	if( Lilact.isEmpty(hk) ) {
+		hk.value = val;
+		hk.set_func = function(core, hk, val) {
+
+			if(typeof(val)==='function') val = val(hk.value);
+
+			if(val===hk.value) return;
+
+			localStorage[key] = JSON.stringify(val);
+
+			hk.value = val;
+			core.component.forceUpdate();
+
+		}.bind(undefined, Lilact.current_component[0], hk);
+	}
+
+	return [hk.value, hk.set_func];
+}
+
+/**
+ * Creates a mutable ref object with a stable identity across renders.
+ * The `.current` property holds the latest value.
+ *
+ * @param {any} initialValue - Initial ref value.
+ * @returns {Object} Ref object with `.current`.
+ */
+export function useRef(val = null)
+{
+	const hk = Lilact.useHook();
+
+	if( Lilact.isEmpty(hk) ) {
+		hk.current = val;
+	}
+
+	return hk;
+}
+
+/**
+ * Runs an effect synchronously after all DOM mutations but before the browser paints.
+ *
+ * @param {Function} effect - Effect callback.
+ * @param {Array<any>} [deps] - Dependency list.
+ * @returns {void}
+ */
+export function useLayoutEffect(setup, deps=[{}])
+{
+	if(typeof(deps)!=='object' || deps.constructor.name!=='Array') {
+		throw "effect dependencies must be an array or omitted.";
+	}
+
+	const hk = Lilact.useHook();
+
+	if( !Lilact.isEmpty(hk) ) {
+		if(deps.every((v,i)=> v === hk.deps[i])) return;
+		if(hk.cleanup) {
+			hk.cleanup();
+		}
+	}
+
+	hk.deps = deps;
+	Lilact.layout_effects.add( ()=>{ hk.cleanup = setup(); });
+	Lilact.current_component[0].component.forceUpdate();
+
+}
+
+/**
+ * Runs a side effect after render commits.
+ *
+ * @param {Function} effect - Effect callback.
+ * @param {Array<any>} [deps] - Dependency list.
+ * @returns {void}
+ */
+export function useEffect(setup, deps=[{}])
+{
+	if(typeof(deps)!=='object' || deps.constructor.name!=='Array') {
+		throw "effect dependencies must be an array or omitted.";
+	}
+
+	const hk = Lilact.useHook();
+
+	if( !Lilact.isEmpty(hk) ) {
+		if(deps.every((v,i)=> v === hk.deps[i])) return;
+		if(hk.cleanup) {
+			hk.cleanup();
+		}
+	}
+
+	hk.deps = deps;
+	Lilact.setTimeout( ()=>{ hk.cleanup = setup(); }, 0 );
+
+}
+
+/**
+ * Memoizes a computed value until dependencies change.
+ *
+ * @param {Function} factory - Function that creates the value.
+ * @param {Array<any>} deps - Dependency list.
+ * @returns {any} Memoized value.
+ */
+export function useMemo(fn,deps=[])
+{
+	const hk = Lilact.useHook();
+
+	if( Lilact.isEmpty(hk) ) {
+		hk.deps = deps;
+		hk.value = fn();
+	}
+	else {
+		for(let d in deps) {
+			if( !Lilact.defaultIsEqual(deps[d],hk.deps[d]) ) {
+				hk.deps = deps;
+				hk.value = fn(hk.value);
+				break;
+			}
+		}
+	}
+
+	return hk.value;
+}
+
+/**
+ * React-compatible hook for managing an async/queued action and deriving state from it.
+ *
+ * @param {Function} action - The async/queued action function.
+ * @param {any} initialState - Initial state for the hook.
+ * @returns {any} Hook result (implementation-dependent).
+ */
+export function useActionState(fn, initial_state)
+{
+	const hk = Lilact.useHook();
+	const [is_pending, tran_start_func] = Lilact.useTransition();
+
+	if( Lilact.isEmpty(hk) ) {
+
+		hk.state = initial_state;
+
+		hk.form_action = (sub)=>{
+			event.preventDefault();
+
+			tran_start_func(
+					async ()=> {
+						const form_data = new FormData(sub.target, sub.submitter);
+						hk.state = await fn(hk.state, form_data);
+					},
+					[]
+				);
+
+			return false;
+		}
+	}
+
+	return [hk.state, hk.form_action, is_pending];
+}
+
+/**
+ * Manages state via a reducer function and exposes dispatch to trigger state transitions.
+ *
+ * @param {Function} reducer - Reducer function.
+ * @param {any} initialArg - Initial state value (or initializer arg).
+ * @param {Function} [init] - Optional initializer function for lazy initial state.
+ * @returns {any} Hook result (implementation-dependent; typically `[state, dispatch]`).
+ */
+export function useReducer(reducer, initialArg, init)
+{
+	const hk = Lilact.useHook();
+
+	if( Lilact.isEmpty(hk) ) {
+		hk.reducer = reducer;
+		hk.state = init?init(initialArg):initialArg;
+		hk.dispatch = function(core, hk, action) {
+			const newst = hk.reducer(hk.state, action);
+			if(!Lilact.defaultIsEqual(newst,hk.state)) {
+				hk.state = newst;
+				core.component.forceUpdate();
+			}
+
+		}.bind(undefined, Lilact.current_component[0], hk);
+	}
+
+	return [hk.state, hk.dispatch];
+}
+
+
+
+// todo: very simple implementation. not lilactish! must be modified
+
+/**
+ * Returns a deferred value that updates later than the provided input.
+ *
+ * @param {any} value - Value to defer.
+ * @returns {any} Deferred value.
+ */
+export function useDeferredValue(value, initialValue)
+{
+
+	const { useEffect, useRef, useState } = Lilact;
+
+	const [deferred, setDeferred] = useState(
+		typeof initialValue !== "undefined" ? initialValue : value
+	);
+	const lastValueRef = useRef(value);
+	const pendingRef = useRef(null);
+
+	useEffect(() => {
+		if (lastValueRef.current === value) return;
+		lastValueRef.current = value;
+
+		// Cancel any previously scheduled update
+		if (pendingRef.current != null) {
+			pendingRef.current.cancelled = true;
+			pendingRef.current = null;
+		}
+
+		// Schedule update asynchronously using a microtask (Promise.resolve)
+		const job = { cancelled: false };
+		pendingRef.current = job;
+
+		Promise.resolve().then(() => {
+			if (job.cancelled) return;
+			// Batch state update into next event loop tick so current render finishes first.
+			setDeferred(value);
+			pendingRef.current = null;
+		});
+
+		return () => {
+			if (pendingRef.current) {
+				pendingRef.current.cancelled = true;
+				pendingRef.current = null;
+			}
+		};
+	}, [value]);
+
+	return deferred;
+}
+
+

package/src/jsx.addons.js

@@ -0,0 +1,70 @@
+/*
+
+	Lilact
+	Copyright (C) 2024-2026 Arash Kazemi <contact.arash.kazemi@gmail.com>
+	All rights reserved.
+
+	BSD-2-Clause
+
+	Redistribution and use in source and binary forms, with or without
+	modification, are permitted provided that the following conditions are met:
+
+	* Redistributions of source code must retain the above copyright
+	  notice, this list of conditions and the following disclaimer.
+	* Redistributions in binary form must reproduce the above copyright
+	  notice, this list of conditions and the following disclaimer in the
+	  documentation and/or other materials provided with the distribution.
+
+	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+	ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+	DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+	(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+	LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+	ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+	(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+	THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*/
+
+const TRANSPILER_OUTPUT = Symbol.for("LILACT:TRANSPILER_OUTPUT");
+
+
+export function defineSymbols(ns, defs) {
+
+	if(defs===undefined) {
+		defs=ns;
+		ns='';
+	}
+	else ns+=':';
+
+	const out = [];
+	const lbls = [];
+	if(defs instanceof Array) {
+		if(ns!=='') {
+			if(typeof(ns)!=='string') ns='';
+			for(let d of defs) {
+				lbls.push(d);
+				out.push(`Symbol.for('${ns}${d}')`);
+			}
+		}
+		else {
+			for(const d of defs) {
+				lbls.push(d);
+				out.push(`Symbol()`);
+			}
+		}
+		return `const [${lbls.join(',')}]=[${out.join(',')}];`;
+	}
+}
+
+export const quote = (x)=>`"${String(x).replace(/(["\n])/g, '\\$1')}"`;
+
+
+// note: this directive is used for files that can be used separatly (i.e. timers.jsx)
+// 		 or in case  you want to check the preprocessors output. 
+
+export function outputJS(filepath) {
+	globalThis[TRANSPILER_OUTPUT] = filepath;
+}