lilact 0.0.0

package/src/run.jsx

@@ -0,0 +1,275 @@
+/*
+
+	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" ] ) ʔ
+
+import Lilact from './lilact.jsx';
+
+/**
+ * Runs a jsx script. All scripts can access Lilact namespace as a global object. 
+ * 
+ * Notice that `run` uses eval internally. There is no standard way of getting the error location when
+ * running it with eval. Lilact has its own experimental workarounds for this, but generally speaking it
+ * works better when an script is loaded from a file (using <script type='text/jsx' src=''.../> and is not 
+ * inline, because that way the generated sourcemap will be used by the browser and the exceptions will be
+ * located automatically. When an inline script raises exception, the original exception does not report
+ * which eval has caused the error, so Lilact should guess it from some labels, and for the sake of 
+ * efficiency, it is block based and not exact.
+ *
+ * @param jsx - The code to run.
+ * @param path - The optional path to be used in reporting errors.
+ * @param is_inline - To treat the code as inline. The main difference at the moment is that inline code doesn't include sourcemap.
+ * 
+ * @returns An array representation of the children.
+ */
+export function run(jsx, path=`<string input ${++Lilact.eval_num}>`, is_inline=true)
+{
+	if(Lilact.checkTraceErrors) Lilact.checkTraceErrors;
+
+	const mappings = [];
+
+	let processed;
+
+	try {
+		processed = Lilact.transpileJSX( jsx,
+		{
+			path,
+			mappings,
+			factory: "Lilact.createComponent",
+			append_sourcemap: !is_inline,
+			wrap_all: false
+		} );
+	}
+	catch(e) {
+		e.lilact_trace = path;
+		throw e;
+	}
+
+	// the separation of module property is to create the required object even on error
+
+	const module = {};
+
+	Lilact.transpilerConfig.required[path] = { 	
+		mappings,
+		processed,
+		module,
+		is_inline,
+		path,
+		code: jsx
+	};
+
+	
+	Lilact.scanFunctionLabels(processed, path);
+
+	Lilact.transpilerConfig.func_labels[path] = {
+		path,
+		row: 0,
+		col: 0,
+		label: "<EXEC>",
+		required: Lilact.transpilerConfig.required[path]
+	}
+
+	try {
+		globalThis.Lilact = Lilact;
+
+		const res = eval ( processed );
+		if(module.exports) return module.exports;
+		return res;
+	}
+	catch(e) {
+		e.lilact_trace = path;
+		throw e;
+	}
+}
+
+// export async function importAsync(path)
+// {
+// 	const res = await fetch(path);
+// 	const text = await res.text();
+
+// 	return Lilact.run(text, path, false);
+// }
+
+/**
+ * Loads a jsx script from a path. All scripts can access Lilact namespace as a global object. 
+ * 
+ * Lilact require loads synchronously, as it is expected to be loaded on the next instruction.
+ * It is better to load existing scripts using <script type="text/jsx" src+"..."/> if possible.
+ * 
+ * Notice that run uses eval internally. There is no standard way of getting the error location when
+ * running it with eval. Lilact has its own experimental workarounds for this, but generally speaking it
+ * works better when an script is loaded from a file (using <script type='text/jsx' src=''.../> and is not 
+ * inline, because that way the generated sourcemap will be used by the browser and the exceptions will be
+ * located automatically. When an inline script raises exception, the original exception does not report
+ * which eval has caused the error, so Lilact should guess it from some labels, and for the sake of 
+ * efficiency, it is block based and not exact.
+ *
+ * @param path - The path to the required file.
+ * @param force_update - To treat the code as inline. The main difference at the moment is that inline code doesn't include sourcemap.
+ * 
+ * @returns An array representation of the children.
+ */
+export function require(path, force_update)
+{
+	if(Lilact.transpilerConfig.required[path]!==undefined && !force_update) return Lilact.transpilerConfig.required[path].module;
+
+	if(path[0]==='#') {
+
+		const el = document.querySelector(path);
+
+		if(el) {
+			return Lilact.run(el.innerText, path);
+		}
+
+	}
+	else {
+
+		// note: this makes a sync request. this is not advised,
+		// but import should be sync. for an async solution use importAsync.
+
+		const request = new XMLHttpRequest();
+		request.open("GET", path, false);
+		request.send(null);
+
+		if (request.status === 200) {
+			return Lilact.run(request.responseText, path, false);
+		}
+	}
+
+	throw `required resource not found (${path})`;
+}
+
+
+/**
+ * Debug tool to get the Lilact traced location of an error. It can also produce some block based stack trace 
+ * if `Lilact.transpilerConfig.enableLabelStack` is set to `true` before loading the script. This is `false`
+ * by default for efficiency.
+ *
+ * @returns A new object that includes `path`, `row`, `col`, `msg`, `name`, and optional `stack`. 
+ * The exception itself is stored as `err`.
+ */
+export function traceError(err)
+{
+	const loc = Lilact.getErrorLocation(err);
+
+	const obj = {
+		path: err.fileName,
+		label: null,
+		
+		row: loc[0],
+		col: loc[1],
+
+		msg: err.message,
+		name: err.name,
+
+		stack: null,
+		err: err
+	};		
+
+
+	if(err.lilact_trace!==undefined) {
+
+		// to be able to trace, we assume that all of the scripts are running inside lilact.
+		// if not, the error is returned unchanged and stack and label would remain null.
+
+		let mps;
+		let blk;
+		if(typeof(err.lilact_trace)==='string') {
+			blk = Lilact.func_labels[err.lilact_trace];
+			mps = blk.required.mappings;
+		}
+		else if(typeof(err.lilact_trace)==='object') {
+			blk = Lilact.func_labels[err.lilact_trace[0]];
+			mps = blk.mappings;
+		}
+
+		obj.path = blk.path;
+		obj.label = blk.label;
+
+		[obj.row, obj.col] = Lilact.mapLocation(mps, obj.row,obj.col);
+
+		//const rm = Lilact.func_labels[func_num].required;
+
+		// Lilact.onError( err.message,
+		// 				rm.path,
+		// 				Lilact.func_labels[func_num].label,
+		// 				...Lilact.mapLocation(...loc,mps),
+		// 				Lilact.call_stack.map(
+		// 					(x)=>({ path: Lilact.func_labels[x].path,
+		// 							label: Lilact.func_labels[x].label,
+		// 							row: Lilact.func_labels[x].row
+		// 						})
+		// 				),	err );
+
+		
+	}
+
+	return obj;
+	
+}
+
+function scanScriptTagsWithType() {
+  const scripts = Array.from(
+    document.querySelectorAll('script[type="text/jsx"]')
+  );
+
+  return scripts.map((el) => ({
+    src: el.getAttribute("src") ?? null,
+    content: el.textContent ?? ""
+  }));
+}
+
+// usage (in browser):
+// const result = scanScriptTagsWithType();
+// console.log(result);
+
+
+/**
+ * Scans the whole documents and runs all the script elements with type `text/jsx`.
+ * It is automatically attached to document.onload when Lilact is loaded.
+ * 
+ * If element src is set, it will be loaded via `Lilact.require`.
+ * If element has inner content, it will be executed via `Lilact.run`.
+ * 
+ * If both are present, first the src is loaded and then the inner content is executed.
+ *
+ * Note that it won't detect such elements that are added after document.onload.
+ * @returns {void}
+ */
+
+export function runScripts()
+{
+	const scripts = scanScriptTagsWithType();
+
+	for(const s of scripts) {
+		if(s.src) Lilact.require(s.src);
+		if(s.content) Lilact.run(s.content);
+	}
+}

package/src/timers.jsx

@@ -0,0 +1,313 @@
+/*
+
+	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.
+
+*/
+
+// note: lilact timers can be used without lilact. uncomment the directive below to
+// get the transpiled version in dist directory.
+//ʔ outputJS('./dist/timers.js');
+
+
+ʔ defineSymbols("LILACT:TIMERS", ["CORE", "IDX", "DUE", "REPEAT", "CLEARED", "INTERVAL", "CALLBACK", "ARGS"] ) ʔ
+
+/**
+ * Timer helpers for a promise-friendly timer framework.
+ *
+ * These functions keep the same call signatures as the standard JavaScript timer APIs where applicable (`setTimeout`/`setInterval`/`clearTimeout`/`clearInterval`), but add extra capabilities for promise-friendly control and lifecycle management. This module can “grab” timers and later pause/resume/reset/release them, plus provide promise wrappers like `timeoutPromise` and `animationFramePromise`.
+ *
+ * - `setTimeout` / `setInterval`: schedule callbacks (same interface as the built-ins).
+ * - `clearTimeout` / `clearInterval`: cancel scheduled timers (same interface as the built-ins).
+ * - `grabTimers` / `pauseTimers` / `resumeTimers` / `resetTimers` / `releaseTimers`: manage tracked timers (implementation-dependent behavior).
+ * - `timeoutPromise` / `animationFramePromise`: promise-based convenience wrappers.
+ */
+
+
+let timer_pause_time = undefined;
+let current_timer_idx = -1;
+let timer_list = [];
+let timer_timeout = -1;
+let all_timers = {};
+
+
+// original functions
+const _setTimeout = window.setTimeout,
+_setInterval = window.setInterval,
+_clearTimeout = window.clearTimeout,
+_clearInterval = window.clearInterval;
+
+
+function get_bucket(target) 
+{
+	let left = 0;
+	let right = timer_list.length - 1;
+
+	while (left <= right) {
+		const mid = Math.floor((left + right) / 2);
+		const mid_val = timer_list[mid][DUE];
+
+		if (mid_val === target) {
+			return [mid, timer_list[mid]];
+		} 
+		else if (mid_val < target) {
+			left = mid + 1;
+		} 
+		else {
+			right = mid - 1;
+		}
+	}
+
+	const bucket = [];
+	bucket[DUE] = target;
+
+	timer_list.splice(left, 0, bucket); 
+	return [left, bucket];
+}
+
+function add_timer(t, is_repeat=false)
+{
+	const [i,bucket] = get_bucket(t[DUE]);
+
+	if(!is_repeat) {
+		current_timer_idx++;
+		all_timers[current_timer_idx]=t;
+		t[IDX] = current_timer_idx;
+	}
+
+	bucket.push(t);
+
+	if(timer_list[0][0]===t) {
+		_clearTimeout( timer_timeout );
+		timer_timeout = _setTimeout( run_timer, t[INTERVAL] );
+	}
+
+	return current_timer_idx;
+}
+
+function run_timer()
+{
+	const now = Date.now();
+
+	let i = 0;
+	let buck = timer_list[i];
+
+	while( buck && buck[DUE]-now <= 0 ) {
+		for(const t of buck) {
+
+			if(!t[CLEARED]) {
+				t[CALLBACK](...t[ARGS]);			
+				if(t[REPEAT]) {
+					t[DUE] = Date.now()+t[INTERVAL];
+					add_timer(t, true);
+				}
+				else {
+					delete all_timers[t[IDX]];
+				}
+			}
+			else {
+				delete all_timers[t[IDX]];
+			}
+		}
+		i++;
+		buck = timer_list[i];
+	}
+
+	timer_list.splice(0,i);
+
+	if(timer_list.length>0) {
+		_clearTimeout( timer_timeout );
+		timer_timeout = _setTimeout( run_timer, timer_list[0][DUE] - now);
+	}
+
+}
+
+//---
+
+/**
+ * Resets managed timers back to their initial scheduled state.
+ * @returns {void}
+ */
+export function  resetTimers()
+{
+	_clearTimeout(timer_timeout);
+	timer_pause_time = undefined;
+	current_timer_idx = -1;
+	timer_list = [];
+	timer_timeout = -1;
+	all_timers = {};
+}
+
+/**
+ * Pauses all grabbed timers.
+ * @returns {void}
+ */
+export function  pauseTimers()
+{
+	_clearTimeout( timer_timeout );
+	timer_pause_time = Date.now();
+}
+
+/**
+ * Resumes paused timers.
+ * @returns {void}
+ */
+export function resumeTimers()
+{
+	if(!timer_pause_time) return;
+
+	if(timer_list.length>0) {
+		const now = Date.now();
+
+		timer_pause_time -= now;
+
+		for( const t of timer_list ) {
+			t[DUE] -= timer_pause_time;
+		}
+
+		timer_timeout = _setTimeout( run_timer, timer_list[0][DUE] - now);
+	}
+
+	timer_pause_time = undefined;
+}
+
+
+/**
+ * Creates a timeout timer (same interface as JS `setTimeout`).
+ * @param {Function} callback - Function to run after the delay.
+ * @param {number} delay - Delay in milliseconds.
+ * @param {...any} [args] - Optional arguments passed to `callback`.
+ * @returns {any} Timeout id.
+ */
+
+
+export function setTimeout(func, interval, ...args)
+{
+	return add_timer( { [CALLBACK]: func, [INTERVAL]: interval, [DUE]: Date.now()+interval, [REPEAT]: false, [ARGS]: args } );
+}
+
+/**
+ * Creates an interval timer (same interface as JS `setInterval`).
+ * @param {Function} callback - Function to run repeatedly.
+ * @param {number} interval - Delay in milliseconds between executions.
+ * @param {...any} [args] - Optional arguments passed to `callback`.
+ * @returns {any} Interval id.
+ */
+
+export function setInterval(func, interval, ...args)
+{
+	return add_timer( { [CALLBACK]: func, [INTERVAL]: interval, [DUE]: Date.now()+interval, [REPEAT]: true, [ARGS]: args } );
+}
+
+/**
+ * Clears a timeout created via this framework’s `setTimeout`.
+ * @param {any} id - Timeout id returned by `setTimeout`.
+ * @returns {void}
+ */
+export function clearTimeout(t)
+{
+	if(all_timers[t]) all_timers[t][CLEARED] = true;
+}
+
+/**
+ * Clears an interval created via this framework’s `setInterval`.
+ * @param {any} id - Interval id returned by `setInterval`.
+ * @returns {void}
+ */
+export function clearInterval(t)
+{
+	if(all_timers[t]) all_timers[t][CLEARED] = true;
+}
+
+/**
+ * Captures/associates all timers with the framework so they can be managed. Calling this will
+ * shadow the global setTimeout and setInterval functions and channel them through Lilact.
+ * @returns {void}
+ */
+export function grabTimers()
+{
+	globalThis.setTimeout = this.setTimeout;
+	globalThis.setInterval = this.setInterval;
+	globalThis.clearTimeout = this.clearTimeout;
+	globalThis.clearInterval = this.clearInterval;
+}
+
+/**
+ * Releases timers from framework control.
+ * @returns {void}
+ */
+export function releaseTimers()
+{
+	globalThis.setTimeout = _setTimeout;
+	globalThis.setInterval = _setInterval;
+	globalThis.clearTimeout = _clearTimeout;
+	globalThis.clearInterval = _clearInterval;
+}
+
+/**
+ * Returns a Promise that resolves after a timeout (framework-managed) using the same delay semantics as `setTimeout`.
+ * @param {number} duration - Delay in milliseconds.
+ * @returns {Promise} Promise that resolves after the delay.
+ */
+export function timeoutPromise(duration=0, timer_source=this) 
+{	
+	let id, resolve, reject;
+
+	const promise = new Promise((res, rej) => {
+		resolve = res;
+		reject = rej;
+		id = timer_source.setTimeout(() => {
+			resolve();
+		}, duration);
+	});
+
+	// note: proceed interrupts the timer, and continues the flow if used with await.
+	promise.proceed = () => {
+		timer_source.clearTimeout(id);
+		resolve();
+	};
+
+	// note: cancel rejects so it throws exception when using with await, this allows handling it differently.
+	promise.cancel = () => {
+		timer_source.clearTimeout(id);
+		reject();
+	};
+
+	return promise;
+}
+
+/**
+ * Schedules a callback on the next animation frame and returns a Promise that resolves on that frame.
+ * @returns {Promise} Promise that resolves when the animation frame runs.
+ */
+export function animationFramePromise() {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => {
+            resolve();
+        });
+    });
+}	
+