Fixes #77 Fixes #75 (docs for webc:if webc:type=js)

Author: zachleat

.editorconfig

@@ -5,3 +5,7 @@ indent_style = tab
 indent_size = 2
 end_of_line = lf
 charset = utf-8
+
+[/test/**/*]
+trim_trailing_whitespace = false
+insert_final_newline = unset

README.md

@@ -412,6 +412,20 @@ Note that the `<template webc:type>` node is compiled away. If you’d like to k
 
 We do provide two built-in transforms in WebC: JavaScript Render Functions (`webc:type="render"`) and CSS scoping (`webc:scoped`). Those are covered in separate sections. You _can_ override these with the `setTransform` API but it is generally recommended to add your own named transform!
 
+### Conditionals
+
+_(WebC v0.7.1+)_
+
+Use `webc:if` to conditionally render elements. Accepts arbitrary JavaScript (and is async-friendly). Similar to dynamic attributes, this also has access to component attributes and properties.
+
+```html
+<div webc:if="true">This will render</div>
+<div webc:if="false">This will not render</div>
+<div webc:if="myAsyncHelper()">If the helper promise resolves to a truthy value, this will render</div>
+```
+
+For more complex conditionals, `webc:type="js"` _(WebC v0.7.1+)_ is recommended (read more below).
+
 ### Attributes
 
 Consider this example:
@@ -473,7 +487,16 @@ Make any attribute into a prop by prefixing it with `@`. Props are “private”
 
 ### JavaScript Render Functions
 
-You can also transform individual element content using `webc:type`. We provide one built-in type, `render` for JavaScript render functions. These are async friendly (e.g. `async function()`):
+You can also transform individual element content using `webc:type`. There are three built-in types:
+
+* `webc:type="js"` which supercedes `webc:type="render"`
+* `webc:type="css:scoped"` (internal for `webc:scoped`—overridable!)
+
+JavaScript Render Functions are async friendly (e.g. `async function()`):
+
+#### `webc:type="js"` _(WebC v0.7.1+)_
+
+Run any arbitrary server JavaScript in WebC. Outputs the result of the very last statement executed in the script. Async-friendly (return a promise and we’ll resolve it).
 
 `page.webc`:
 
@@ -483,18 +506,32 @@ You can also transform individual element content using `webc:type`. We provide
 
 `components/img.webc`:
 
+```html
+<script webc:type="js" webc:is="template">
+if(!alt) {
+	throw new Error("oh no you didn’t");
+}
+`<img src="${src}" alt="${alt}">`;
+</script>
+```
+
+<details>
+<summary>Expand to see this example with <code>webc:type="render"</code></summary>
+
 ```html
 <script webc:type="render" webc:is="template">
-function() {
-	if(!this.alt) {
-		throw new Error("oh no you didn’t");
+	function() {
+		if(!this.alt) {
+			throw new Error("oh no you didn’t");
 	}
 	// Free idea: use the Eleventy Image plugin to return optimized markup
 	return `<img src="${this.src}" alt="${this.alt}">`;
 }
 </script>
 ```
 
+</details>
+
 Or use a JavaScript render function to generate some CSS:
 
 `page.webc`:
@@ -507,6 +544,14 @@ Or use a JavaScript render function to generate some CSS:
 
 `components/add-banner-to-css.webc`:
 
+```html
+<script webc:type="js" webc:is="style">`/* ${license} */`</script>
+<slot></slot>
+```
+
+<details>
+<summary>Expand to see this example with <code>webc:type="render"</code></summary>
+
 ```html
 <script webc:type="render" webc:is="style">
 function() {
@@ -516,11 +561,32 @@ function() {
 <slot></slot>
 ```
 
-(Yes you can use `<script webc:type="render" webc:scoped>` here too).
+</details>
+
+(Yes you can use `<script webc:type="js" webc:scoped>` too).
+
+A few more examples of conditionals:
+
+```html
+<script webc:type="js">
+alt ? `<img src="${src}" alt="${alt}">` :  `<a href="${src}">Your image didn’t have an alt so you get this link instead.</a>`
+</script>
+```
 
 Note that you have access to the component attributes and properties in the render function (which is covered in another section!).
 
-#### Setting HTML
+```html
+<script webc:type="js">
+if(alt) {
+	`<img src="${src}" alt="${alt}">`
+} else {
+	`<a href="${src}">Your image didn’t have an alt so you get this link instead.</a>`
+}
+</script>
+```
+
+
+### Setting HTML
 
 We provide a special `@html` property to override any tag content with custom JavaScript.
 
@@ -537,7 +603,7 @@ We provide a special `@html` property to override any tag content with custom Ja
 * Using `webc:raw` will prevent reprocessing the result as WebC. (v0.6.0+)
 * Use `@raw` as an alias for `webc:raw @html` . (v0.7.1+)
 
-#### Setting Text
+### Setting Text
 
 We provide a special `@text` property to override any tag content with custom JavaScript. The entire value returned here will be escaped!
 
@@ -553,7 +619,7 @@ We provide a special `@text` property to override any tag content with custom Ja
 <p @text="dataProperty" webc:nokeep></p>
 ```
 
-#### Helper Functions
+### Helper Functions
 
 If you want to add custom JavaScript functions for use in render functions, `@html`, or dynamic attributes you can use the `setHelper` method.
 
@@ -579,7 +645,7 @@ function() {
 
 ### Raw Content (no WebC processing)
 
-Opt out of WebC template processing using `webc:raw`. This works well with `<template>` content.
+Opt out of WebC template processing using `webc:raw`. This works well with `<template>` content. See also the special `@raw` content property _(WebC v0.7.1+)_
 
 ```html
 <template webc:raw>

src/ast.js

@@ -127,7 +127,7 @@ class AstSerializer {
 		this.setTransform(AstSerializer.transformTypes.JS, function(content) {
 			// returns promise
 			return ModuleScript.evaluateScript(`${AstSerializer.attrs.RENDER}="${AstSerializer.transformTypes.JS}"`, content, this, {
-				allowRequire: true
+				injectGlobals: true
 			});
 		});
 
@@ -181,7 +181,6 @@ class AstSerializer {
 	static transformTypes = {
 		JS: "js",
 		RENDER: "render",
-		MODULE: "module", // alias for render
 		SCOPED: "css:scoped",
 	};
 
@@ -1250,9 +1249,9 @@ class AstSerializer {
 
 		let ifExprContent = this.getAttributeValue(node, AstSerializer.attrs.IF);
 		if(ifExprContent) {
-			let ifExprValue = await this.evaluateAttribute(AstSerializer.attrs.HTML, ifExprContent, options);
-			if(ifExprValue === false) {
-				return false;
+			let ifExprValue = await this.evaluateAttribute(AstSerializer.attrs.IF, ifExprContent, options);
+			if(!ifExprValue) {
+				return { html: "" };
 			}
 		}
 

src/moduleScript.cjs

@@ -23,12 +23,19 @@ class ModuleScript {
 
 	static async evaluateScript(name, content, data, options = {}) {
 		options = Object.assign({
-			allowRequire: false
+			injectGlobals: false
 		}, options);
 
 		try {
 			let context = ModuleScript.getProxiedContext(data);
-			if(options.allowRequire) {
+
+			if(options.injectGlobals) {
+				// Add globals https://nodejs.org/api/globals.html#global
+				context = {
+					...global,
+					...context,
+				};
+
 				context.require = function(target) {
 					const path = require("path");
 
@@ -40,6 +47,8 @@ class ModuleScript {
 
 					return require(target)
 				};
+
+				// TODO wrap in function if the `js` content includes a `return` statement
 			}
 
 			let returnValue = vm.runInNewContext(content, context, {

test/flowcontrolTest.js

@@ -1,6 +1,29 @@
 import test from "ava";
 import { WebC } from "../webc.js";
 
+test("Using webc:if=undefined", async t => {
+	let component = new WebC();
+
+	component.setContent(`<!doctype html>
+<html>
+	<body><div webc:if="myText">Hi</div></body>
+</html>`);
+
+	let { html, css, js, components } = await component.compile({
+		data: {}
+	});
+
+	t.deepEqual(js, []);
+	t.deepEqual(css, []);
+	t.deepEqual(components, []);
+
+	t.is(html, `<!doctype html>
+<html>
+<head></head><body>
+</body>
+</html>`);
+});
+
 test("Using webc:if=false", async t => {
 	let component = new WebC();
 
@@ -50,3 +73,65 @@ test("Using webc:if=true", async t => {
 </body>
 </html>`);
 });
+
+test("Using webc:if with a promise (resolves true)", async t => {
+	let component = new WebC();
+	component.setHelper("timeoutTrue", async () => {
+		return new Promise(resolve => {
+			setTimeout(() => {
+				resolve(true);
+			}, 50);
+		});
+	})
+	component.setContent(`<!doctype html>
+<html>
+	<body><div webc:if="timeoutTrue()">Hi</div></body>
+</html>`);
+
+	let { html, css, js, components } = await component.compile({
+		data: {
+			myText: true
+		}
+	});
+
+	t.deepEqual(js, []);
+	t.deepEqual(css, []);
+	t.deepEqual(components, []);
+
+	t.is(html, `<!doctype html>
+<html>
+<head></head><body><div>Hi</div>
+</body>
+</html>`);
+});
+
+test("Using webc:if with a promise (resolves false)", async t => {
+	let component = new WebC();
+	component.setHelper("timeoutTrue", async () => {
+		return new Promise(resolve => {
+			setTimeout(() => {
+				resolve(false);
+			}, 50);
+		});
+	})
+	component.setContent(`<!doctype html>
+<html>
+	<body><div webc:if="timeoutTrue()">Hi</div></body>
+</html>`);
+
+	let { html, css, js, components } = await component.compile({
+		data: {
+			myText: true
+		}
+	});
+
+	t.deepEqual(js, []);
+	t.deepEqual(css, []);
+	t.deepEqual(components, []);
+
+	t.is(html, `<!doctype html>
+<html>
+<head></head><body>
+</body>
+</html>`);
+});