boxwood 0.74.1 → 0.76.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", async () => {
+  const { template } = await compile(__dirname)
+  const html = template({ title: "foo" })
+  assert(html.includes("<h1>foo</h1>"))
+})
+
+test("banner renders an optional description", async () => {
+  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/fixtures/friends/boxwood.js

@@ -1,5 +1,4 @@
 const {
-  fragment,
   doctype,
   html,
   head,
@@ -14,7 +13,7 @@ const {
 } = require("../../..")
 
 module.exports = function ({ friends }) {
-  return fragment([
+  return [
     doctype(),
     html({ lang: "en" }, [
       head([meta({ charset: "UTF-8" }), title("Friends")]),
@@ -52,5 +51,5 @@ module.exports = function ({ friends }) {
         ),
       ]),
     ]),
-  ])
+  ]
 }

package/benchmark/fixtures/if/boxwood.js

@@ -1,4 +1,4 @@
-const { fragment, div, span } = require("../../..")
+const { div, span } = require("../../..")
 
 function description(account) {
   if (account.status === "closed") {
@@ -17,5 +17,5 @@ function description(account) {
 }
 
 module.exports = function ({ accounts }) {
-  return fragment(accounts.map((account) => div(description(account))))
+  return accounts.map((account) => div(description(account)))
 }

package/benchmark/fixtures/search/boxwood.js

@@ -1,18 +1,16 @@
-const { fragment, div, ul, li, p } = require("../../..")
+const { div, ul, li, p } = require("../../..")
 
 module.exports = function ({ count, results }) {
   return div({ class: "search" }, [
     div({ class: "loader" }, "Loading..."),
     div({ class: "results" }, [
       p(`${count} results`),
-      ...results.map((result) =>
-        fragment([
-          div({ class: "title" }, result.title),
-          div({ class: "description" }, result.description),
-          result.featured && div({ class: "highlight" }, "Featured!"),
-          result.sizes.length && ul(result.sizes.map((size) => li(size))),
-        ])
-      ),
+      ...results.map((result) => [
+        div({ class: "title" }, result.title),
+        div({ class: "description" }, result.description),
+        result.featured && div({ class: "highlight" }, "Featured!"),
+        result.sizes.length && ul(result.sizes.map((size) => li(size))),
+      ]),
     ]),
   ])
 }

package/benchmark/fixtures/todos/boxwood.js

@@ -1,9 +1,9 @@
-const { h1, h2, ul, li, fragment } = require("../../..")
+const { h1, h2, ul, li } = require("../../..")
 
 module.exports = function ({ title, subtitle, todos }) {
-  return fragment([
+  return [
     h1(title),
     h2(subtitle),
     ul(todos.map((todo) => li(todo.description))),
-  ])
+  ]
 }

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

@@ -2,7 +2,6 @@ const { join } = require("path")
 const { readFileSync } = require("fs")
 const csstree = require("css-tree")
 const toHash = require("string-hash")
-const YAML = require("yaml")
 
 async function compile(path) {
   const fn = require(path)
@@ -175,7 +174,7 @@ const isUnescapedTag = (name) => {
 }
 
 const render = (input, escape = true) => {
-  if (input.ignore) {
+  if (!input || input.ignore) {
     return ""
   }
   if (Array.isArray(input)) {
@@ -188,10 +187,10 @@ const render = (input, escape = true) => {
     return input.toString()
   }
   if (typeof input === "string") {
-    return escape ? escapeHTML(input) : input
-  }
-  if (input.name === "fragment") {
-    return render(input.children)
+    if (escape) {
+      return escapeHTML(input)
+    }
+    return input
   }
   if (input.name === "raw") {
     return render(input.children, false)
@@ -202,32 +201,14 @@ const render = (input, escape = true) => {
     }
     return `<${input.name}>`
   }
-  if (input.attributes && input.children) {
-    return (
-      `<${input.name} ` +
-      attributes(input.attributes) +
-      ">" +
-      render(input.children, isUnescapedTag(input.name)) +
-      `</${input.name}>`
-    )
-  }
-  if (input.attributes) {
-    return (
-      `<${input.name} ` + attributes(input.attributes) + `></${input.name}>`
-    )
-  }
-  if (input.children) {
-    return (
-      `<${input.name}>` +
-      render(input.children, isUnescapedTag(input.name)) +
-      `</${input.name}>`
-    )
-  }
-  return `<${input.name}></${input.name}>`
-}
 
-const fragment = (children) => {
-  return { name: "fragment", children }
+  return (
+    `<${input.name}` +
+    (input.attributes ? " " + attributes(input.attributes) : "") +
+    ">" +
+    render(input.children, isUnescapedTag(input.name)) +
+    `</${input.name}>`
+  )
 }
 
 const raw = (children) => {
@@ -314,9 +295,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}`
 }
 
@@ -493,15 +485,6 @@ function classes() {
   return array.join(" ")
 }
 
-const yaml = {
-  load() {
-    const path = join(...arguments)
-    const file = path.endsWith(".yaml") ? path : join(path, "index.yaml")
-    const content = readFileSync(file, "utf8")
-    return YAML.parse(content)
-  },
-}
-
 const json = {
   load() {
     const path = join(...arguments)
@@ -519,50 +502,47 @@ function i18n(translations) {
 
 i18n.load = function () {
   const path = join(...arguments)
-  const data = path.endsWith(".yaml") ? yaml.load(path) : json.load(path)
+  const data = json.load(path)
   return function translate(language, key) {
-    if (!key) {
-      throw new Error(`TranslationError[${key}][${language}]: key is undefined`)
-    }
     if (!language) {
-      throw new Error(
-        `TranslationError[${key}][${language}]: language is undefined`
-      )
+      throw new Error(`TranslationError: language is undefined`)
     }
-    const translation = data[key][language]
-    if (!translation) {
+    if (!key) {
+      throw new Error(`TranslationError: key is undefined`)
+    }
+    if (!data[key] || !data[key][language]) {
       throw new Error(
-        `TranslationError[${key}][${language}]: translation is undefined`
+        `TranslationError: translation [${key}][${language}] is undefined`
       )
     }
-    return translation
+    return data[key][language]
   }
 }
 
-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)
     }
     if (i18n) {
+      if (!a || !a.language) {
+        throw new Error(
+          `TranslationError: language is undefined for component:\n${fn.toString()}`
+        )
+      }
       const { language } = a
       function translate(key) {
         if (!key) {
           throw new Error(
-            `TranslationError[${key}][${language}]: key is undefined for component:\n${fn.toString()}`
+            `TranslationError: key is undefined for component:\n${fn.toString()}`
           )
         }
-        if (!language) {
+        if (!i18n[key] || !i18n[key][language]) {
           throw new Error(
-            `TranslationError[${key}][${language}]: language is undefined for component:\n${fn.toString()}`
+            `TranslationError: translation [${key}][${language}] is undefined for component:\n${fn.toString()}`
           )
         }
         const translation = i18n[key][language]
-        if (!translation) {
-          throw new Error(
-            `TranslationError[${key}][${language}]: translation is undefined for component:\n${fn.toString()}`
-          )
-        }
         return translation
       }
       return fn({ ...a, translate }, b || [])
@@ -571,25 +551,19 @@ function component(fn, { styles, i18n, code } = {}) {
   }
   return function (a, b) {
     const tree = execute(a, b)
-    if (styles && code) {
-      if (Array.isArray(tree)) {
-        return tree.concat(styles.css, code.js)
-      }
-      return [tree, styles.css, code.js]
-    }
+    let nodes = Array.isArray(tree) ? tree : [tree]
+
     if (styles) {
-      if (Array.isArray(tree)) {
-        return tree.concat(styles.css)
-      }
-      return [tree, styles.css]
+      const data = Array.isArray(styles) ? styles : [styles]
+      nodes = nodes.concat(data.map((style) => style.css))
     }
-    if (code) {
-      if (Array.isArray(tree)) {
-        return tree.concat(code.js)
-      }
-      return [tree, code.js]
+
+    if (scripts) {
+      const data = Array.isArray(scripts) ? scripts : [scripts]
+      nodes = nodes.concat(data.map((script) => script.js))
     }
-    return tree
+
+    return nodes
   }
 }
 
@@ -599,11 +573,9 @@ module.exports = {
   classes,
   doctype,
   escape: escapeHTML,
-  fragment,
   raw,
   css,
   js,
-  yaml,
   json,
   tag,
   i18n,

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "boxwood",
-  "version": "0.74.1",
+  "version": "0.76.0",
   "description": "Compile HTML templates into JS",
   "main": "index.js",
   "scripts": {
-    "test": "node --test",
+    "test": "node --test --test-reporter=dot",
+    "test:debug": "node --test --test-reporter=spec",
     "coverage": "c8 npm test",
     "benchmark": "node --test benchmark/index.js",
     "watch": "npm test -- --watch",
@@ -45,13 +46,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"
   },
@@ -64,7 +63,6 @@
   },
   "dependencies": {
     "css-tree": "^2.3.1",
-    "string-hash": "^1.1.3",
-    "yaml": "^2.4.1"
+    "string-hash": "^1.1.3"
   }
 }