lilact 0.0.0

package/LICENSE.TXT

@@ -0,0 +1,26 @@
+
+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.

package/README.md

@@ -0,0 +1,116 @@
+<img src="./icon.png" alt="Description" width="200" style="margin-left: -.75rem"/>
+
+# Lilact
+
+### A Little JSX/React Runtime Implementation for Browser
+
+`Lilact` is an extremely lightweight implementation of the React API that is
+designed to work in the browser. It can be used as a single script
+that is around `70kb` minified and around `25kb` gzipped and includes everything.
+`Lilact` is very fast, it uses minimum resources and handles memory very efficiently.
+
+`Lilact` uses its own robust JSX transpiler, and not babel. It is a recursive-descent 
+parser with lookahead, but it doesn't parse the JS syntax completely and relies on the 
+JS runtime to detect some errors. The transpiler weights
+only a few kilobytes and can be even incorporated into other React engines. To
+make it better, it even generates sourcemaps like a charm, without relying on
+any 3rd party library. There is a `transpile.js` helper in the bin directory to
+show how you can use it. 
+
+`Lilact` implements both the **legacy class based** and **modern hook based** APIs. And it 
+has almost everything  necessary. In addition to the API, it also includes the official 
+`Redux` and `PropTypes` libraries to be used (see the `redux.jsx` and `proptypes.jsx` demos). 
+So yes it has redux support and has many of the functions and hooks, i.e. `connect` and 
+`useDispatch`.
+
+It also includes the amazing `@emotion/css` library to ease working with styles.
+It can be accessed through `Lilact.emotion`.
+
+To ease working, it already includes a `HashRouter`, `CSSTransition`, `ErrorBoundary`,
+`Suspense`, `Spinner`, and many other stuff. It also has a specific timeout implementation 
+that can be paused and resumed at will. `Lilact`'s `Suspense` even has a few more features
+than the standard API.
+
+You can see all the methods available in the documentation. And there is a list of
+demos that can all be seen alongside their code at [Lilact Demo Examples](./static/index.html).
+Just note that the modules are separated in the documentation to improve the doc
+structure, and in practice all the methods and members are accessible via the `Lilact` object 
+itself directly.
+
+`Lilact` runs in the browser, so it uses `eval` to run the transpiled scripts, and cannot 
+use import and exports the same as a module. So you should import the functions using the following 
+convention
+
+        const { useState, useRef, render } = Lilact;
+
+And to export you can use `module.exports = ...`. 
+
+
+---
+
+To use in other node projects, install `Lilact` from npm public repository:
+
+        npm install lilact  
+
+It is also available via unpkg CDN and can be included in HTML files using
+
+        <script src="https://unpkg.com/lilact/dist/lilact.development.js"></script>
+
+or
+
+        <script src="https://unpkg.com/lilact/dist/lilact.production.min.js"></script>
+
+
+To use in a webpage, first download the source code and extract it. The minified 
+script itself is available in the `/dist` directory and the documentation 
+can be found in the `/docs` and also in the source files. 
+
+Note that the production version, like the official React API, doesn't do the proptypes 
+checks, but you can access PropTypes using Lilact.PropTypes. 
+
+After being loaded, Lilact automatically scans the document for any scirpt elements
+with `type='text/jsx'` and it will run them. If the `src` attribute is set it will load
+the resource, and if there is inner content it will be executed. Of course this is not the 
+only way.
+
+Lilact wraps the browser events to mimic React events, this mimicry is not perfect, as 
+the footprint was very important, but it works fine. 
+
+As a simple example Lilact can be used like this:
+
+        <!DOCTYPE html>
+        <html>
+        <head>
+                <meta charset="utf-8"/>
+                <title>Lilact Demo</title>
+                <script src='./lilact.development.js' type="module"></script>
+        </head>
+        <body></body>
+        <script type='text/jsx'>
+                                
+                const { render, useState } = Lilact;
+                function App({children}) {
+                        [...]
+                        return <div>Hello World</div>!
+                }
+                
+                render(<App/>, document.body);
+        </script>
+        </html>
+
+
+To know more about using `Lilact`, see the included example and for the details
+see the class documentation. And of course don't forget to check the 
+[Lilact Demo Examples](./static/index.html).
+
+`Lilact` is currently in its beta state. It is under heavy tests and improvements are 
+being made. Please report any possible issues or bugs, they will be fixed
+without any hesitation! 
+
+--------
+
+Copyright (C) 2024-2026 Arash Kazemi <contact.arash.kazemi@gmail.com>. All rights reserved.
+
+Lilact project is subject to the terms of BSD-2-Clause License. See the `LICENSE.TXT` file for more details.
+
+<style>.tsd-page-title{display: none}</style>

package/bin/copy-demo.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+const typedocOut = process.env.TYPEDOC_OUT || 'docs';
+const from = path.resolve(__dirname, '..', 'root');
+const to = path.resolve(__dirname, '..', typedocOut, 'static');
+
+copyDirRecursive(from, to);
+console.log(`Copied ${from} -> ${to}`);

package/bin/transpile-dir.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+"use strict";
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from 'url';
+
+import { spawnSync } from "child_process";
+
+function usage() {
+  console.error(
+    "Usage:\n" +
+      "  transpile-dir <inDir> --outDir <outDir> [Options]\n\n" +
+      "Options:\n" +
+      "  --inDir <dir>          Input directory for transpiled files (required)\n\n" +
+      "  --outDir <dir>         Output directory for transpiled files (required)\n\n" +
+      "  --isDebug              Add debug labels \n" +
+      "  --discardComments      Discard comments \n" +
+      "  --injectTraceLabels    Inject trace labels needed by Lilact only \n" +
+      "  --factory <func>       The factory function (default: createComponent)\n" +
+      "  -h, --help             Show help\n"
+  );
+  process.exit(1);
+}
+
+let factory = "createComponent";
+let discardComments = false;
+let injectTraceLabels = false;
+let isDebug = false;
+
+let outDir, inDir;
+const argv = process.argv.slice(2);
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--outDir") {
+    outDir = argv[++i];
+    if (!outDir) usage();
+    outDir = path.resolve(outDir);
+  } 
+  else if (a === "--inDir") {
+    inDir = argv[++i];
+    if (!inDir) usage();
+    inDir = path.resolve(inDir);
+  } 
+  else if (a === "--isDebug") {
+    globalThis.DEBUG = true;
+  } 
+  else if (a === "--discardComments") {
+    discardComments = true;
+  } 
+  else if (a === "--injectTraceLabels") {
+    injectTraceLabels = true;
+  } 
+  else if (a === "--factory") {
+    factory = argv[++i];
+  } 
+  else {
+    usage();
+  } 
+}
+
+function walkJsxFiles(dir) {
+  const out = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const ent of entries) {
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) out.push(...walkJsxFiles(full));
+    else if (ent.isFile() && (ent.name.endsWith(".js") || ent.name.endsWith(".jsx") ) ) out.push(full);
+  }
+  return out;
+}
+
+const files = walkJsxFiles(inDir);
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const transpileBin = path.resolve(__dirname, "transpile.js");
+
+if (!fs.existsSync(transpileBin)) {
+  throw new Error(`Missing ${transpileBin}`);
+}
+
+for (const inputPath of files) {
+
+  const relPath = path.relative(inDir, inputPath);
+
+  let targetOutFile = path.join(outDir, relPath); // file-level destination
+
+  if(targetOutFile.endsWith('.jsx')) {
+    targetOutFile = targetOutFile.slice(0,targetOutFile.length-1);
+  }
+
+  if (fs.existsSync(targetOutFile)) {
+    fs.unlinkSync(targetOutFile);
+  }
+
+  const args = [transpileBin, inputPath, "--out", targetOutFile, "--factory", factory];
+
+  if(isDebug) args.push("--isDebug");
+  if(discardComments) args.push("--discardComments");
+  if(injectTraceLabels) args.push("--injectTraceLabels");
+
+  const res = spawnSync(
+    process.execPath,
+    args,
+    { stdio: "inherit" }
+  );
+
+  if (res.status !== 0) process.exit(res.status ?? 1);
+}

package/bin/transpile.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/*
+
+	Lilact
+	Copyright (C) 2024-2025 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.
+
+*/
+
+import fs from "fs";
+import path from "path";
+
+import {transpileJSX} from "../src/jsx.js";
+
+
+
+function usage() 
+{
+	console.error(
+		"Usage:\n" +
+			"  transpile <entries...> [Options] \n\n" +
+			"Options:\n" +
+			"  --out <filepath>      Output filepath for transpiled files. Multiple inputs will be concatenated. If not given, each file will have a separate output with an additinoal .transpiled.js in its name.\n" +
+			"  --isDebug             Add debug labels \n\n" +
+			"  --discardComments     Discard comments \n\n" +
+			"  --injectTraceLabels   Inject trace labels needed by Lilact only \n\n" +
+			"  --factory <func>      The factory function (default: createComponent)\n\n" +
+			"  -h, --help            Show help\n\n" +
+			"Example:\n" +
+			"  transpile src/test.jsx dist/test.js"
+	);
+	process.exit(1);
+}
+
+
+
+const argv = process.argv.slice(2);
+if (argv.length === 0) usage();
+
+let out = null;
+
+let factory = "createComponent";
+let discardComments = false;
+let injectTraceLabels = false;
+
+const entries = [];
+
+globalThis.DEBUG = false;
+
+for (let i = 0; i < argv.length; i++) {
+	const a = argv[i];
+	if (a === "--out") {
+		out = argv[++i];
+		if (!out) usage();
+		out = path.resolve(out);
+	} 
+	else if (a === "--isDebug") {
+		globalThis.DEBUG = true;
+	} 
+	else if (a === "--discardComments") {
+		discardComments = true;
+	} 
+	else if (a === "--injectTraceLabels") {
+		injectTraceLabels = true;
+	} 
+	else if (a === "--factory") {
+		factory = argv[++i];
+	} 
+	else if (a === "-h" || a === "--help") {
+		usage();
+	} 
+	else {
+		entries.push(a);
+	}
+}
+
+
+if (entries.length === 0) usage();
+
+if (out) {
+	let p = path.dirname(out);
+	if(p!==".") {
+		fs.mkdirSync(p, { recursive: true });
+	}
+}
+
+
+for (const entry of entries) {
+	const inputPath = path.resolve(entry);
+	const code = fs.readFileSync(inputPath, "utf8");
+
+	const result = transpileJSX(code,
+								{ 
+									path: inputPath,
+									appendSourcemap: globalThis.DEBUG,
+									factory, 
+									//mappings: [], 
+									injectTraceLabels: injectTraceLabels,
+									discardComments: discardComments
+								}
+	);
+
+	let outFile;
+	
+	if (out) {
+		outFile = out;
+		fs.appendFileSync(outFile, result, "utf8");
+	}
+	else {
+		outFile = inputPath + ".transpiled.js";
+		fs.writeFileSync(outFile, result, "utf8");
+	}
+
+	console.log(`Preprocessed: ${inputPath} -> ${outFile}`);
+}