lui-templates 0.0.6

package/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+	"json.schemas": [
+		{
+			"fileMatch": [
+				"/test/templates/*.json"
+			],
+			"url": "/schema/intermediary.json"
+		}
+	]
+}

package/README.md

@@ -0,0 +1,103 @@
+# lui-templates
+
+[lui](https://github.com/L3P3/lui) is quite simple to use -- as long as you are a JavaScript developer.
+
+This tool lets you write lui components without writing JavaScript but via template files. 🎉
+
+## Supported formats
+
+Here are some templating languages I think about supporting:
+
+- [ ] [pug](https://pugjs.org/api/getting-started.html)
+- [ ] [Haml](https://haml.info/)
+- [x] [Liquid](https://shopify.github.io/liquid/) (proof of concept)
+- [ ] [Handlebars](https://handlebarsjs.com/)
+- [ ] [Knockout](https://knockoutjs.com/documentation/introduction.html)
+- [x] Raw JSON (as intermediary format, see test/templates/greeting.json)
+
+## Usage
+
+```sh
+npx lui-templates src/templates/greeting.liquid > src/components/greeting.js
+```
+
+```sh
+npx lui-templates --help
+```
+
+## Example
+
+###  `src/templates/greeting.liquid`
+
+```liquid
+<h1>Hello {{ name }}!</h1>
+```
+
+### `src/main.js`
+
+```js
+import { init, node } from 'lui';
+
+import Greeting from './components/greeting.js';
+
+init(() => {
+	return [
+		node(Greeting, { name: 'World' }),
+	];
+});
+```
+
+### `build.js`
+
+```js
+import lui_templates from 'lui-templates';
+
+const code = await lui_templates('src/templates/Greeting.liquid');
+await fs.writeFile('src/generated/Greeting.js', code, 'utf8');
+
+await bundleApp('src/main.js'); // or whatever
+```
+
+### `src/generated/greeting.js` (generated)
+
+The generated component is looking like this:
+
+```js
+// generated by lui-templates
+
+import { hook_dom } from "lui";
+
+export default function Greeting({ name }) {
+	hook_dom("h1", {
+		innerText: `Hello ${name}!`,
+	});
+
+	return null;
+}
+```
+
+You may have it in your `.gitignore` to prevent duplication.
+
+... And did I mention that this file is generated? 🎉
+
+## Interface of `lui_templates(path[, {options}])`
+
+### `path`
+
+The template file to read. Can be in one of the [supported formats](#supported-formats), determined by its ending. If it is a directory, all contained templates will be read.
+
+### option `lui_name`
+
+The name of the lui module to import from. Defaults to `lui`.
+
+### option `components_name`
+
+The name of the module to import unknown components from. Defaults to `./externs.js`.
+
+### return value
+
+The returned ES module imports the needed methods and exports the component(s).
+
+For a single template file, the default export is the component.
+
+For a directory, each component is exported by its name.

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "lui-templates",
+	"version": "0.0.6",
+	"description": "transform html templates into lui components",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/l3p3/lui-templates"
+	},
+	"bugs": {
+		"url": "https://github.com/l3p3/lui-templates/issues"
+	},
+	"main": "./src/main.js",
+	"module": "./src/main.js",
+	"exports": {
+		".": "./src/main.js"
+	},
+	"type": "module",
+	"scripts": {
+		"test": "cd test && node basic.js"
+	},
+	"bin": "./src/cli.js",
+	"keywords": [
+		"lui",
+		"templates",
+		"liquid",
+		"framework",
+		"html",
+		"tiny"
+	],
+	"author": "L3P3 <dev@l3p3.de> (https://l3p3.de)",
+	"license": "Zlib"
+}

package/schema/intermediary.json

@@ -0,0 +1,147 @@
+{
+	"$schema": "https://json-schema.org/draft-07/schema",
+	"$id": "https://l3p3.de/shr/schema/lui-templates.intermediary.json",
+	"$title": "Intermediary format for templates",
+	"$description": "All templates should be parsed into this format before being turned into a component. You can also pass a template.json directly, following this schema.",
+
+	"type": "object",
+	"properties": {
+		"inputs": {
+			"$description": "list of component prop definitions",
+			"type": "array",
+			"items": {"$ref": "#/$defs/input"}
+		},
+		"transformations": {
+			"$description": "list of transformations",
+			"type": "array",
+			"items": {"$ref": "#/$defs/transformation"}
+		},
+		"effects": {
+			"$description": "list of effects",
+			"type": "array",
+			"items": {"$ref": "#/$defs/effect"}
+		},
+		"nodes": {
+			"$description": "list of contained nodes",
+			"type": "array",
+			"items": {"$ref": "#/$defs/node"}
+		}
+	},
+	"required": ["inputs", "transformations", "effects", "nodes"],
+
+	"$defs": {
+		"value": {
+			"$description": "expression representing a runtime value",
+			"oneOf": [
+				{
+					"$description": "static value",
+					"type": "object",
+					"properties": {
+						"type": {"const": 0},
+						"data": {"type": ["string", "number", "boolean", "null"]}
+					},
+					"required": ["type", "data"]
+				},
+				{
+					"$description": "field reference",
+					"type": "object",
+					"properties": {
+						"type": {"const": 1},
+						"data": {"type": "string"}
+					},
+					"required": ["type", "data"]
+				},
+				{
+					"$description": "string concatenation",
+					"type": "object",
+					"properties": {
+						"type": {"const": 2},
+						"data": {
+							"type": "array",
+							"items": {"$ref": "#/$defs/value"}
+						}
+					},
+					"required": ["type", "data"]
+				}
+			]
+		},
+		"props": {
+			"$description": "map of arbitrary property keys and their assigned values",
+			"type": "object",
+			"additionalProperties": {"$ref": "#/$defs/value"}
+		},
+		"input": {
+			"$description": "component prop definition",
+			"type": "object",
+			"properties": {
+				"name": {"type": "string"},
+				"fallback": {"type": ["string", "number", "boolean", "null"]}
+			},
+			"required": ["name"]
+		},
+		"transformation": {
+			"$description": "transformation from a list of fields into a single field",
+			"type": "object",
+			"properties": {}
+		},
+		"effect": {
+			"$description": "effect to be run depending on field values",
+			"type": "object",
+			"properties": {}
+		},
+		"node": {
+			"$description": "node in the template tree",
+			"oneOf": [
+				{
+					"$description": "single component",
+					"type": "object",
+					"properties": {
+						"type": {"const": 0},
+						"component": {"type": "string"},
+						"props": {"$ref": "#/$defs/props"},
+						"children": {
+							"type": "array",
+							"items": {"$ref": "#/$defs/node"}
+						}
+					},
+					"required": ["type", "component", "props", "children"]
+				},
+				{
+					"$description": "html element",
+					"type": "object",
+					"properties": {
+						"type": {"const": 1},
+						"tag": {"type": "string"},
+						"props": {"$ref": "#/$defs/props"},
+						"children": {
+							"type": "array",
+							"items": {"$ref": "#/$defs/node"}
+						}
+					},
+					"required": ["type", "tag", "props", "children"]
+				},
+				{
+					"$description": "if statement",
+					"type": "object",
+					"properties": {
+						"type": {"const": 2},
+						"condition": {"$ref": "#/$defs/value"},
+						"child": {"$ref": "#/$defs/node"}
+					},
+					"required": ["type", "condition", "child"]
+				},
+				{
+					"$description": "map component",
+					"type": "object",
+					"properties": {
+						"type": {"const": 3},
+						"from": {"type": "string"},
+						"component": {"type": "string"},
+						"props": {"$ref": "#/$defs/props"}
+					},
+					"required": ["type", "from", "component", "props"]
+				}
+			]
+		}
+	}
+}

package/src/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import {
+	readFileSync,
+} from 'fs';
+
+import lui_templates from './main.js';
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
+	console.error(`Usage: lui-templates input [options]
+Input: The template file or directory containing the templates
+Options:
+  -e, --externs <path>    File unknown components are imported from
+  -h, --help              Show this help message
+  --version               Show version information
+
+Example:
+  lui-templates ./templates/button.liquid > ./components/button.js
+`);
+	process.exit(0);
+}
+if (args[0] === '--version') {
+	const { version } = JSON.parse(
+		readFileSync(
+			new URL('../package.json', import.meta.url)
+		)
+	);
+	console.error(`lui-templates version ${version}`);
+	process.exit(0);
+}
+
+if (args[0].startsWith('-')) {
+	console.error('Must first specify the input, see --help');
+	process.exit(1);
+}
+
+const path = args.shift();
+let arg_externs = './externs.js';
+
+while (args.length > 0) {
+	const arg = args.shift();
+	switch (arg) {
+		case '-e':
+		case '--externs':
+			arg_externs = args.shift();
+			break;
+		default:
+			console.error(`Unknown argument: ${arg}, see --help`);
+			process.exit(1);
+	}
+}
+
+const result = await lui_templates(path, {
+	components_name: arg_externs,
+});
+
+console.log(result);

package/src/constants.js

@@ -0,0 +1,8 @@
+export const NODE_TYPE_COMPONENT = 0;
+export const NODE_TYPE_ELEMENT = 1;
+export const NODE_TYPE_IF = 2;
+export const NODE_TYPE_MAP = 3;
+
+export const VALUE_TYPE_STATIC = 0;
+export const VALUE_TYPE_FIELD = 1;
+export const VALUE_TYPE_STRING_CONCAT = 2;

package/src/generator.js

@@ -0,0 +1,276 @@
+import {
+	NODE_TYPE_COMPONENT,
+	NODE_TYPE_ELEMENT,
+	NODE_TYPE_IF,
+	NODE_TYPE_MAP,
+	VALUE_TYPE_FIELD,
+	VALUE_TYPE_STATIC,
+	VALUE_TYPE_STRING_CONCAT,
+} from './constants.js';
+
+export function generate(name, parsed, lui_imports, component_imports) {
+	const {effects, inputs, transformations} = parsed;
+	let {nodes} = parsed;
+
+	const body = [];
+
+	// TODO: transformations
+	// stuff like `const variable2 = variable1 + 1`
+
+	if (nodes.length === 1 && nodes[0].type === NODE_TYPE_ELEMENT) {
+		const [node] = nodes;
+		lui_imports.add('hook_dom');
+		body.push(`hook_dom("${
+			descriptor_generate(node)
+		}"${
+			attrs_generate(Object.entries(node.props), 1)
+		});`);
+		nodes = node.children;
+	}
+
+	// TODO: effects
+	// stuff like when variable1 is updated, function doSomething is invoked
+
+	if (nodes.length === 0) {
+		body.push('return null;');
+	} else {
+		body.push(`return [${
+			childs_generate(nodes, 1, lui_imports, component_imports)
+		}];`);
+	}
+
+	return `function ${name}(${
+		inputs_generate(inputs)
+	}) {\n\t${
+		body.join('\n\n\t')
+	}\n}`;
+}
+
+/**
+	formats name for a component
+	@param {string} name some-name
+	@returns {string} SomeName
+*/
+export function name_format(name) {
+	name =
+		name.charAt(0).toUpperCase() +
+		name.slice(1)
+		.replaceAll(/[\s_]+/g, '-')
+		.replace(
+			/-([a-z])/g,
+			(_, char) => char.toUpperCase()
+		);
+	assert_identifier(name);
+	return name;
+}
+
+function inputs_generate(inputs) {
+	if (inputs.length === 0) return '';
+
+	const declarations = inputs.map(input => {
+		assert_identifier(input.name);
+		if (input.fallback !== undefined) {
+			return `${input.name} = ${JSON.stringify(input.fallback)}`;
+		}
+		return input.name;
+	});
+
+	return `{${list_generate(declarations, 0)}}`;
+}
+
+function descriptor_generate(node) {
+	if (node.tag.includes('[')) throw new SyntaxError(`Tag must not contain "[": ${node.tag}`);
+	const attributes = Object.entries(node.props)
+		.filter(entry => entry[1].type === VALUE_TYPE_STATIC)
+		.map(descriptor_attribute_generate)
+		.filter(Boolean);
+	if (attributes.length === 0) return node.tag;
+	const invalid = attributes.find(attribute => attribute.includes(']['));
+	if (invalid) throw new SyntaxError(`Static attributes must not contain "][": ${invalid}`);
+	return `${node.tag}[${attributes.sort().join('][')}]`;
+}
+
+function descriptor_attribute_generate([key, value]) {
+	assert_identifier(key);
+	if (value.data === false) return '';
+	if (value.data === true) return key;
+	return `${key}=${string_escape(value.data)}`;
+}
+
+function attrs_generate(entries, identation) {
+	return props_generate(
+		entries.filter(entry => entry[1].type !== VALUE_TYPE_STATIC),
+		identation
+	);
+}
+
+function props_generate(entries, identation) {
+	if (entries.length === 0) return '';
+	for (const entry of entries) assert_identifier(entry[0]);
+	const assignments = entries.map(entry => {
+		const key = entry[0];
+		const value = value_generate(entry[1], identation);
+		return (
+			key === value
+			?	key
+			:	`${entry[0]}: ${value}`
+		);
+	});
+	return `, {${list_generate(assignments, identation)}}`;
+}
+
+function value_generate(value, identation) {
+	switch (value.type) {
+	case VALUE_TYPE_STATIC: return JSON.stringify(value.data);
+	case VALUE_TYPE_FIELD:
+		// Allow js expressions for unless or ternary conditions
+		// TODO do this with transformations instead
+		// assert_identifier(value.data);
+		return value.data;
+	case VALUE_TYPE_STRING_CONCAT: return string_concat_generate(value.data, identation);
+	}
+	throw new TypeError(`Unknown value type: ${value.type}`);
+}
+
+function childs_generate(nodes, identation, lui_imports, component_imports) {
+	return list_generate(
+		nodes.map(node => node_generate(node, identation, lui_imports, component_imports)),
+		identation,
+		true
+	);
+}
+
+function node_generate(node, identation, lui_imports, component_imports) {
+	switch (node.type) {
+	case NODE_TYPE_COMPONENT:
+		assert_identifier(node.component);
+		lui_imports.add('node');
+		component_imports.add(node.component);
+		const props = props_generate(Object.entries(node.props), identation + 1);
+		return `node(${
+			node.component
+		}${
+			props === '' && node.children.length > 0
+			?	', null'
+			:	props
+		}${
+			node.children.length === 0
+			?	''
+			:	`, [${
+					childs_generate(node.children, identation + 1, lui_imports, component_imports)
+				}]`
+		})`;
+	case NODE_TYPE_ELEMENT:
+		lui_imports.add('node_dom');
+		const attrs = attrs_generate(Object.entries(node.props), identation + 1);
+		return `node_dom("${
+			descriptor_generate(node)
+		}"${
+			attrs === '' && node.children.length > 0
+			?	', null'
+			:	attrs
+		}${
+			node.children.length === 0
+			?	''
+			:	`, [${
+					childs_generate(node.children, identation + 1, lui_imports, component_imports)
+				}]`
+		})`;
+	case NODE_TYPE_IF:
+		return `${
+			value_generate(node.condition, identation)
+		} &&\n${
+			'\t'.repeat(identation + 1) +
+			node_generate(node.child, identation, lui_imports, component_imports)
+		}`;
+	case NODE_TYPE_MAP:
+		assert_identifier(node.component);
+		assert_identifier(node.from);
+		lui_imports.add('node_map');
+		component_imports.add(node.component);
+		return `node_map(${
+			node.component
+		}, ${
+			node.from
+		}${
+			props_generate(Object.entries(node.props), identation + 1)
+		})`;
+	}
+	throw new TypeError(`Unknown node type: ${node.type}`);
+}
+
+function string_concat_generate(data, identation) {
+	identation++;
+	if (data.length === 2) {
+		return data.map(item =>
+			item.type === VALUE_TYPE_STATIC
+			?	JSON.stringify(item.data)
+			:	value_generate(item, identation)
+		).join(' + ');
+	}
+	return `\`${
+		data.map(item => {
+			switch (item.type) {
+			case VALUE_TYPE_STATIC: return template_escape(item.data);
+			case VALUE_TYPE_FIELD:
+				// assert_identifier(item.data);
+				return `\${${item.data}}`;
+			}
+			return `\${\n${
+				'\t'.repeat(identation + 1) +
+				value_generate(item, identation)
+			}\n${'\t'.repeat(identation)}}`;
+		}).join('')
+	}\``;
+}
+
+function template_escape(string) {
+	return (
+		String(string)
+		.replaceAll('\\', '\\\\')
+		.replaceAll('`', '\\`')
+		.replaceAll('$', '\\$')
+	);
+}
+
+function string_escape(string) {
+	return (
+		String(string)
+		.replaceAll('\\', '\\\\')
+		.replaceAll('"', '\\"')
+		.replaceAll('\n', '\\n')
+	);
+}
+
+/**
+	Throws an error if the string is not a valid JavaScript identifier
+	@param {string} string
+	@throws {SyntaxError} if the string is not a valid JavaScript
+*/
+function assert_identifier(string) {
+	if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(string)) {
+		throw new SyntaxError(`Invalid identifier: ${string}`);
+	}
+}
+
+/**
+	if a list entry contains one of these characters, it must be put on its own line
+*/
+const regexp_noinline = /[\n:{[(]/;
+
+/**
+	formats an object/array content, braces/brackets not included
+	@param {string[]} entries
+	@param {number} identation
+	@param {boolean} ordered
+	@return {string}
+*/
+export function list_generate(entries, identation, ordered = false) {
+	switch (entries.length) {
+	case 0: return '';
+	case 1:	if (!regexp_noinline.test(entries[0])) return ` ${entries[0]} `;
+	}
+	if (!ordered) entries.sort();
+	identation = '\t'.repeat(identation);
+	return `\n\t${identation + entries.join(',\n\t' + identation)},\n` + identation;
+}