boxwood 0.74.0 → 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/fixtures/basic/boxwood.js

@@ -0,0 +1,3 @@
+module.exports = function () {
+  return 'foo'
+}

package/benchmark/fixtures/basic/data.json

@@ -0,0 +1 @@
+{}

package/benchmark/fixtures/basic/handlebars.hbs

@@ -0,0 +1 @@
+foo

package/benchmark/fixtures/basic/lodash.ejs

@@ -0,0 +1 @@
+foo

package/benchmark/fixtures/basic/mustache.mst

@@ -0,0 +1 @@
+foo

package/benchmark/fixtures/basic/underscore.ejs

@@ -0,0 +1 @@
+foo

package/benchmark/fixtures/basic/vanilla.js

@@ -0,0 +1,3 @@
+module.exports = function () {
+  return 'foo'
+}

package/benchmark/fixtures/div/boxwood.js

@@ -0,0 +1,5 @@
+const { div } = require("../../..")
+
+module.exports = function () {
+  return div("foo")
+}

package/benchmark/fixtures/div/data.json

@@ -0,0 +1 @@
+{}

package/benchmark/fixtures/div/handlebars.hbs

@@ -0,0 +1 @@
+<div>foo</div>

package/benchmark/fixtures/div/lodash.ejs

@@ -0,0 +1 @@
+<div>foo</div>

package/benchmark/fixtures/div/mustache.mst

@@ -0,0 +1 @@
+<div>foo</div>

package/benchmark/fixtures/div/underscore.ejs

@@ -0,0 +1 @@
+<div>foo</div>

package/benchmark/fixtures/div/vanilla.js

@@ -0,0 +1,4 @@
+
+module.exports = function () {
+  return '<div>foo</div>'
+}

package/benchmark/fixtures/escape/boxwood.js

@@ -0,0 +1,3 @@
+module.exports = function ({ foo }) {
+  return foo
+}

package/benchmark/fixtures/escape/data.json

@@ -0,0 +1,3 @@
+{
+  "foo": "<img>"
+}

package/benchmark/fixtures/escape/handlebars.hbs

@@ -0,0 +1 @@
+{{foo}}

package/benchmark/fixtures/escape/lodash.ejs

@@ -0,0 +1 @@
+<%- foo %>

package/benchmark/fixtures/escape/mustache.mst

@@ -0,0 +1 @@
+{{foo}}

package/benchmark/fixtures/escape/underscore.ejs

@@ -0,0 +1 @@
+<%- foo %>

package/benchmark/fixtures/escape/vanilla.js

@@ -0,0 +1,5 @@
+const { escape } = require("../../..")
+
+module.exports = function ({ foo }) {
+  return escape(foo)
+}

package/benchmark/fixtures/friends/boxwood.js

@@ -0,0 +1,56 @@
+const {
+  fragment,
+  doctype,
+  html,
+  head,
+  body,
+  meta,
+  img,
+  title,
+  div,
+  ul,
+  li,
+  a,
+} = require("../../..")
+
+module.exports = function ({ friends }) {
+  return fragment([
+    doctype(),
+    html({ lang: "en" }, [
+      head([meta({ charset: "UTF-8" }), title("Friends")]),
+      body([
+        div(
+          { class: "friends" },
+          friends.map((friend) => {
+            return div({ class: "friend" }, [
+              ul([
+                li(`Name: ${friend.name}`),
+                li(`Balance: ${friend.balance}`),
+                li(`Age: ${friend.age}`),
+                li(`Address: ${friend.address}`),
+                li(["Image: ", img({ src: friend.picture })]),
+                li(`Company: ${friend.company}`),
+                li([
+                  "Email: ",
+                  a({ href: `mailto:${friend.email}` }, friend.email),
+                ]),
+                li(`About: ${friend.about}`),
+                friend.tags.length &&
+                  li(["Tags: ", ul(friend.tags.map((tag) => li(tag)))]),
+                friend.friends.length &&
+                  li([
+                    "Friends: ",
+                    ul(
+                      friend.friends.map((friend) =>
+                        li(`${friend.name} (${friend.id})`)
+                      )
+                    ),
+                  ]),
+              ]),
+            ])
+          })
+        ),
+      ]),
+    ]),
+  ])
+}

package/benchmark/fixtures/friends/data.json

@@ -0,0 +1,30 @@
+{
+  "friends": [
+    {
+      "name": "Jan Kowalski",
+      "id": 1,
+      "balance": "100 PLN",
+      "age": 50,
+      "address": "Warszawa",
+      "picture": "jankowalski.png",
+      "email": "jan@kowalski.pl",
+      "about": "I like fishing",
+      "company": "PKO",
+      "tags": ["fisherman"],
+      "friends": [
+        {
+          "name": "Piotr Nowak",
+          "id": 2,
+          "balance": "80 PLN",
+          "age": 40,
+          "address": "Kraków",
+          "picture": "piotrnowak.png",
+          "email": "piotr@nowak.pl",
+          "about": "I like cooking",
+          "company": "ING",
+          "tags": ["chef"]
+        }
+      ]
+    }
+  ]
+}

package/benchmark/fixtures/friends/handlebars.hbs

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Friends</title>
+</head>
+<body>
+  <div class="friends">
+    {{#each friends}}
+      <div class="friend">
+        <ul>
+          <li>Name: {{this.name}}</li>
+          <li>Balance: {{this.balance}}</li>
+          <li>Age: {{this.age}}</li>
+          <li>Address: {{this.address}}</li>
+          <li>Image: <img src="{{this.picture}}"></li>
+          <li>Company: {{this.company}}</li>
+          <li>Email: <a href="mailto:{{this.email}}">{{this.email}}</a></li>
+          <li>About: {{this.about}}</li>
+          {{#if tags.length}}
+            <li>
+              Tags:
+              <ul>
+                {{#each tags}}
+                  <li>{{this}}</li>
+                {{/each}}
+              </ul>
+            </li>
+          {{/if}}
+          {{#if friends.length}}
+            <li>
+              Friends:
+              <ul>
+                {{#each friends}}
+                  <li>{{this.name}} ({{this.id}})</li>
+                {{/each}}
+              </ul>
+            </li>
+          {{/if}}
+        </ul>
+      </div>
+    {{/each}}
+  </div>
+</body>
+</html>

package/benchmark/fixtures/friends/lodash.ejs

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Friends</title>
+</head>
+<body>
+  <div class="friends">
+    <% for (var i = 0, ilen = friends.length; i < ilen; i += 1) { %>
+      <% var friend = friends[i]; %>
+      <div class="friend">
+        <ul>
+          <li>Name: <%- friend.name %></li>
+          <li>Balance: <%- friend.balance %></li>
+          <li>Age: <%- friend.age %></li>
+          <li>Address: <%- friend.address %></li>
+          <li>Image: <img src="<%- friend.picture %>"></li>
+          <li>Company: <%- friend.company %></li>
+          <li>Email: <a href="mailto:<%- friend.email %>"><%- friend.email %></a></li>
+          <li>About: <%- friend.about %></li>
+          <% if (friend.tags.length) { %>
+            <li>
+              Tags:
+              <ul>
+                <% for (var j = 0, jlen = friend.tags.length; j < jlen; j += 1) { %>
+                  <% var tag = friend.tags[i]; %>
+                  <li><%- tag %></li>
+                <% } %>
+              </ul>
+            </li>
+          <% } %>
+          <% if (friend.friends.length) { %>
+            <li>
+              Friends:
+              <ul>
+                <% for (var k = 0, klen = friend.friends.length; k < klen; k += 1) { %>
+                  <% var fr = friend.friends[i] %>
+                  <li><%- fr.name %> (<%- fr.id %>)</li>
+                <% } %>
+              </ul>
+            </li>
+          <% } %>
+        </ul>
+      </div>
+    <% } %>
+  </div>
+</body>
+</html>

package/benchmark/fixtures/friends/mustache.mst

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Friends</title>
+</head>
+<body>
+  <div class="friends">
+    {{#friends}}
+      <div class="friend">
+        <ul>
+          <li>Name: {{name}}</li>
+          <li>Balance: {{balance}}</li>
+          <li>Age: {{age}}</li>
+          <li>Address: {{address}}</li>
+          <li>Image: <img src="{{picture}}"></li>
+          <li>Company: {{company}}</li>
+          <li>Email: <a href="mailto:{{email}}">{{email}}</a></li>
+          <li>About: {{about}}</li>
+          {{#tags.length}}
+            <li>
+              Tags:
+              <ul>
+                {{#tags}}
+                  <li>{{.}}</li>
+                {{/tags}}
+              </ul>
+            </li>
+          {{/tags.length}}
+          {{#friends.length}}
+            <li>
+              Friends:
+              <ul>
+                {{#friends}}
+                  <li>{{name}} ({{id}})</li>
+                {{/friends}}
+              </ul>
+            </li>
+          {{/friends.length}}
+        </ul>
+      </div>
+    {{/friends}}
+  </div>
+</body>
+</html>

package/benchmark/fixtures/friends/underscore.ejs

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Friends</title>
+</head>
+<body>
+  <div class="friends">
+    <% for (var i = 0, ilen = friends.length; i < ilen; i += 1) { %>
+      <% var friend = friends[i]; %>
+      <div class="friend">
+        <ul>
+          <li>Name: <%- friend.name %></li>
+          <li>Balance: <%- friend.balance %></li>
+          <li>Age: <%- friend.age %></li>
+          <li>Address: <%- friend.address %></li>
+          <li>Image: <img src="<%- friend.picture %>"></li>
+          <li>Company: <%- friend.company %></li>
+          <li>Email: <a href="mailto:<%- friend.email %>"><%- friend.email %></a></li>
+          <li>About: <%- friend.about %></li>
+          <% if (friend.tags.length) { %>
+            <li>
+              Tags:
+              <ul>
+                <% for (var j = 0, jlen = friend.tags.length; j < jlen; j += 1) { %>
+                  <% var tag = friend.tags[i]; %>
+                  <li><%- tag %></li>
+                <% } %>
+              </ul>
+            </li>
+          <% } %>
+          <% if (friend.friends.length) { %>
+            <li>
+              Friends:
+              <ul>
+                <% for (var k = 0, klen = friend.friends.length; k < klen; k += 1) { %>
+                  <% var fr = friend.friends[i] %>
+                  <li><%- fr.name %> (<%- fr.id %>)</li>
+                <% } %>
+              </ul>
+            </li>
+          <% } %>
+        </ul>
+      </div>
+    <% } %>
+  </div>
+</body>
+</html>

package/benchmark/fixtures/friends/vanilla.js

@@ -0,0 +1,36 @@
+module.exports = function ({ friends }) {
+  let template = '<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>Friends</title></head><body><div class="friends">'
+  for (let i = 0, ilen = friends.length; i < ilen; i++) {
+    const friend = friends[i]
+    template += '<div class="friend">'
+    template += '<ul>'
+    template += '<li>Name: ' + friend.name + '</li>'
+    template += '<li>Balance: ' + friend.balance + '</li>'
+    template += '<li>Age: ' + friend.age + '</li>'
+    template += '<li>Address: ' + friend.address + '</li>'
+    template += '<li>Image: <img src="' + friend.picture + '"></li>'
+    template += '<li>Company: ' + friend.company + '</li>'
+    template += '<li>Email: <a href="mailto:' + friend.email + '">' + friend.email + '</a></li>'
+    template += '<li>About: ' + friend.about + '</li>'
+    if (friend.tags.length) {
+      template += '<li>Tags: <ul>'
+      for (let j = 0, jlen = friend.tags.length; j < jlen; j++) {
+        const tag = friend.tags[j]
+        template += '<li>' + tag + '</li>'
+      }
+      template += '</ul></li>'
+    }
+    if (friend.friends.length) {
+      template += '<li>Friends: <ul>'
+      for (let j = 0, jlen = friend.friends.length; j < jlen; j++) {
+        const person = friend.friends[j]
+        template += '<li>' + person.name + ' (' + person.id + ')</li>'
+      }
+      template += '</ul></li>'
+    }
+    template += '</ul>'
+    template += '</div>'
+  }
+  template += '</div></body></html>'
+  return template
+}

package/benchmark/fixtures/if/boxwood.js

@@ -0,0 +1,21 @@
+const { fragment, div, span } = require("../../..")
+
+function description(account) {
+  if (account.status === "closed") {
+    return "Your account has been closed!"
+  }
+  if (account.status === "suspended") {
+    return "Your account has been temporarily suspended"
+  }
+  return (
+    "Bank balance: " +
+    span(
+      { class: account.balance >= 0 ? "positive" : "negative" },
+      account.balance
+    )
+  )
+}
+
+module.exports = function ({ accounts }) {
+  return fragment(accounts.map((account) => div(description(account))))
+}

package/benchmark/fixtures/if/data.json

@@ -0,0 +1,12 @@
+{
+  "accounts": [
+    {
+      "closed": true,
+      "suspended": false,
+      "active": false,
+      "status": "closed",
+      "balance": 100,
+      "balanceClass": "positive"
+    }
+  ]
+}

package/benchmark/fixtures/if/handlebars.hbs

@@ -0,0 +1,13 @@
+{{#each accounts}}
+  <div>
+    {{#if this.closed}}
+      Your account has been closed!
+    {{/if}}
+    {{#if this.suspended}}
+      Your account has been temporarily suspended
+    {{/if}}
+    {{#if this.active}}
+      Bank balance: <span class="{{ account.balanceClass }}">{{this.balance}}</span>
+    {{/if}}
+  </div>
+{{/each}}

package/benchmark/fixtures/if/lodash.ejs

@@ -0,0 +1,12 @@
+<% for (var i = 0, ilen = accounts.length; i < ilen; i += 1) { %>
+  <% var account = accounts[i]; %>
+  <div>
+    <% if (account.status === "closed") { %>
+      Your account has been closed!
+    <% } else if (account.status === "suspended") { %>
+      Your account has been temporarily suspended
+    <% } else { %>
+      Bank balance: <span class="<%- account.balance >= 0 ? 'positive' : 'negative' %>"><%- account.balance %></span>
+    <% } %>
+  </div>
+<% } %>

package/benchmark/fixtures/if/mustache.mst

@@ -0,0 +1,13 @@
+{{#accounts}}
+  <div>
+    {{#closed}}
+      Your account has been closed!
+    {{/closed}}
+    {{#suspended}}
+      Your account has been temporarily suspended
+    {{/suspended}}
+    {{#active}}
+      Bank balance: <span class="{{balanceClass}}">{{balance}}</span>
+    {{/active}}
+  </div>
+{{/accounts}}

package/benchmark/fixtures/if/underscore.ejs

@@ -0,0 +1,12 @@
+<% for (var i = 0, ilen = accounts.length; i < ilen; i += 1) { %>
+  <% var account = accounts[i]; %>
+  <div>
+    <% if (account.status === "closed") { %>
+      Your account has been closed!
+    <% } else if (account.status === "suspended") { %>
+      Your account has been temporarily suspended
+    <% } else { %>
+      Bank balance: <span class="<%- account.balance >= 0 ? 'positive' : 'negative' %>"><%- account.balance %></span>
+    <% } %>
+  </div>
+<% } %>

package/benchmark/fixtures/if/vanilla.js

@@ -0,0 +1,14 @@
+function description (account) {
+  if (account.status === 'closed') { return 'Your account has been closed!' }
+  if (account.status === 'suspended') { return 'Your account has been temporarily suspended' }
+  return 'Bank balance: ' + '<span class="' + account.balance >= 0 ? 'positive' : 'negative' + '">' + account.balance + '</span>'
+}
+
+module.exports = function ({ accounts }) {
+  let template = ''
+  for (let i = 0, ilen = accounts.length; i < ilen; i++) {
+    const account = accounts[i]
+    template += '<div>' + description(account) + '</div>'
+  }
+  return template
+}

package/benchmark/fixtures/projects/boxwood.js

@@ -0,0 +1,20 @@
+const { doctype, tag, html, head, body, p, a } = require("../../..")
+
+module.exports = ({ title, projects, text }) => {
+  return [
+    doctype(),
+    html([
+      head([tag("title", title)]),
+      body([
+        p(text),
+        ...projects.map((project) => {
+          return [
+            a({ href: project.url }, project.name),
+            p(project.description),
+          ]
+        }),
+        projects.length === 0 && "No projects",
+      ]),
+    ]),
+  ]
+}