boxwood 0.74.1 → 0.75.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 - 2022 buxlabs
+Copyright (c) 2018 - 2024 buxlabs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,9 +5,28 @@
 
 > Server side templating engine written in JavaScript
 
+[boxwood](https://github.com/buxlabs/boxwood) was created to achieve the following design goals:
+
+1. templates can be split into components
+2. css is hashed per component
+3. css is automatically minified
+4. critical css is inlined
+5. templates can import other dependencies
+6. inline images or svgs
+7. i18n support
+8. server side
+9. good for seo
+10. small (1 file, 700 LOC~)
+11. easy to start, familiar syntax
+12. easy to test
+
+The template starts with a standard js file, which builds a tree of nodes, that get rendered to html.
+
 ## Table of Contents
 
 - [Install](#install)
+- [Usage](#usage)
+- [Syntax](#syntax)
 - [Maintainers](#maintainers)
 - [Contributing](#contributing)
 - [License](#license)
@@ -16,6 +35,98 @@
 
 `npm install boxwood`
 
+## Usage
+
+```js
+const { compile } = require("boxwood")
+const { join } = require("path")
+// ...
+const path = join(__dirname, "index.js")
+const { template } = await compile(path)
+// ...
+const html = template({ foo: "bar" })
+console.log(html)
+```
+
+## Syntax
+
+```js
+// example/index.js
+const layout = require("./layout")
+const banner = require("./banner")
+
+module.exports = () => {
+  return layout([
+    banner({
+      title: "Hello, world!",
+      description: "Lorem ipsum dolor sit amet",
+    }),
+  ])
+}
+```
+
+```js
+// example/layout/index.js
+
+const { component, css, html, head, body } = require("boxwood")
+const head = require("./head")
+
+const styles = css.load(__dirname)
+
+module.exports = component(
+  (children) => {
+    return html([head(), body({ className: styles.layout }, children)])
+  },
+  { styles }
+)
+```
+
+```js
+// example/head/index.js
+const { head, title } = require("boxwood")
+
+module.exports = () => {
+  return head([title("example")])
+}
+```
+
+```js
+// example/banner/index.js
+const { component, css, h1, p, section } = require("boxwood")
+
+const styles = css.load(__dirname)
+
+module.exports = component(
+  ({ title, description }) => {
+    return section({ className: styles.banner }, [
+      h1(title),
+      description && p(description),
+    ])
+  },
+  { styles }
+)
+```
+
+```js
+// example/banner/index.test.js
+const test = require("node:test")
+const assert = require("node:assert")
+const { compile } = require("boxwood")
+
+test("banner renders a title", () => {
+  const { template } = await compile(__dirname)
+  const html = template({ title: 'foo' })
+  assert(html.includes('<h1>foo</h1>'))
+})
+
+test('banner renders an optional description', () => {
+  const { template } = await compile(__dirname)
+  const html = template({ title: 'foo', description: 'bar' })
+  assert(html.includes('<h1>foo</h1>'))
+  assert(html.includes('<p>bar</p>'))
+})
+```
+
 ## Maintainers
 
 [@emilos](https://github.com/emilos)

package/benchmark/index.js

@@ -6,7 +6,6 @@ const {
 } = require("fs")
 const { Suite } = require("benchmark")
 const underscore = require("underscore")
-const template = require("lodash.template")
 const handlebars = require("handlebars")
 const mustache = require("mustache")
 const { compile } = require("..")
@@ -34,10 +33,9 @@ async function benchmark(dir) {
     path.join(__dirname, `./fixtures/${dir}/boxwood.js`)
   )
   const fn2 = underscore.template(source2)
-  const fn3 = template(source3)
-  const fn4 = handlebars.compile(source4)
-  const fn5 = (data) => mustache.render(source5, data)
-  const fn6 = require(path.join(__dirname, `./fixtures/${dir}/vanilla.js`))
+  const fn3 = handlebars.compile(source4)
+  const fn4 = (data) => mustache.render(source5, data)
+  const fn5 = require(path.join(__dirname, `./fixtures/${dir}/vanilla.js`))
   mustache.parse(source5)
 
   const data = require(path.join(__dirname, `./fixtures/${dir}/data.json`))
@@ -52,12 +50,11 @@ async function benchmark(dir) {
   assert.deepEqual(result, normalize(fn3(data)))
   assert.deepEqual(result, normalize(fn4(data)))
   assert.deepEqual(result, normalize(fn5(data)))
-  assert.deepEqual(result, normalize(fn6(data)))
 
   await new Promise((resolve) => {
     suite
       .add("vanilla[js]", function () {
-        fn6(data)
+        fn5(data)
       })
       .add("boxwood[js]", function () {
         fn1(data)
@@ -65,14 +62,11 @@ async function benchmark(dir) {
       .add("underscore[ejs]", function () {
         fn2(data)
       })
-      .add("lodash[ejs]", function () {
-        fn3(data)
-      })
       .add("handlebars[hbs]", function () {
-        fn4(data)
+        fn3(data)
       })
       .add("mustache[mst]", function () {
-        fn5(data)
+        fn4(data)
       })
       .on("cycle", function (event) {
         console.log(`${dir}: ${String(event.target)}`)

package/index.js

@@ -314,9 +314,20 @@ function js(inputs) {
 }
 
 js.load = function () {
-  const path = join(...arguments)
+  const parts = []
+  for (const param of arguments) {
+    if (typeof param === "string") {
+      parts.push(param)
+    }
+  }
+  const path = join(...parts)
   const file = path.endsWith(".js") ? path : join(path, "index.js")
   const content = readFileSync(file, "utf8")
+
+  const options = arguments[arguments.length - 1]
+  if (options && options.transform) {
+    return js`${options.transform(content)}`
+  }
   return js`${content}`
 }
 
@@ -539,7 +550,7 @@ i18n.load = function () {
   }
 }
 
-function component(fn, { styles, i18n, code } = {}) {
+function component(fn, { styles, i18n, scripts } = {}) {
   function execute(a, b) {
     if (typeof a === "string" || typeof a === "number" || Array.isArray(a)) {
       return fn({}, a)
@@ -571,11 +582,11 @@ function component(fn, { styles, i18n, code } = {}) {
   }
   return function (a, b) {
     const tree = execute(a, b)
-    if (styles && code) {
+    if (styles && scripts) {
       if (Array.isArray(tree)) {
-        return tree.concat(styles.css, code.js)
+        return tree.concat(styles.css, scripts.js)
       }
-      return [tree, styles.css, code.js]
+      return [tree, styles.css, scripts.js]
     }
     if (styles) {
       if (Array.isArray(tree)) {
@@ -583,11 +594,11 @@ function component(fn, { styles, i18n, code } = {}) {
       }
       return [tree, styles.css]
     }
-    if (code) {
+    if (scripts) {
       if (Array.isArray(tree)) {
-        return tree.concat(code.js)
+        return tree.concat(scripts.js)
       }
-      return [tree, code.js]
+      return [tree, scripts.js]
     }
     return tree
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boxwood",
-  "version": "0.74.1",
+  "version": "0.75.0",
   "description": "Compile HTML templates into JS",
   "main": "index.js",
   "scripts": {
@@ -45,13 +45,11 @@
   },
   "homepage": "https://github.com/buxlabs/boxwood#readme",
   "devDependencies": {
-    "ava": "^6.1.2",
     "benchmark": "2.1.4",
     "c8": "^9.1.0",
     "express": "^4.19.2",
     "handlebars": "^4.7.8",
     "jsdom": "^24.0.0",
-    "lodash.template": "4.5.0",
     "mustache": "^4.2.0",
     "underscore": "^1.13.6"
   },
@@ -65,6 +63,6 @@
   "dependencies": {
     "css-tree": "^2.3.1",
     "string-hash": "^1.1.3",
-    "yaml": "^2.4.1"
+    "yaml": "^2.4.2"
   }
 }