boxwood 1.1.1 → 2.1.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node test:*)",
+      "Bash(mkdir:*)",
+      "Bash(npm test:*)",
+      "Bash(mv:*)"
+    ],
+    "deny": []
+  }
+}

package/README.md

@@ -3,24 +3,71 @@
 [![npm](https://img.shields.io/npm/v/boxwood.svg)](https://www.npmjs.com/package/boxwood)
 [![build](https://github.com/buxlabs/boxwood/workflows/build/badge.svg)](https://github.com/buxlabs/boxwood/actions)
 
-> Server side templating engine written in JavaScript
+> It's just JavaScript™ - A template engine that gets out of your way
 
-[boxwood](https://github.com/buxlabs/boxwood) was created to achieve the following design goals:
+## Why Boxwood?
 
-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, 890 LOC~)
-11. easy to start, familiar syntax
-12. easy to test
+Unlike traditional template engines, Boxwood templates are **just JavaScript functions**. No new syntax to learn, no parsing overhead, and full access to the JavaScript ecosystem.
 
-The template starts with a standard js file, which builds a tree of nodes, that get rendered to html.
+```javascript
+// This is your template - just a function that returns HTML nodes
+const HomePage = ({ posts }) => {
+  return Div([
+    H1("Blog"),
+    posts.map(post => Article([
+      H2(post.title),
+      P(post.summary)
+    ]))
+  ])
+}
+```
+
+## Key Advantages
+
+### Zero Learning Curve
+If you know JavaScript, you already know Boxwood. Use `map`, `filter`, `if/else`, and all standard JS features naturally.
+
+### IDE Support
+Get autocomplete, refactoring, and go-to-definition out of the box. Your templates are just code, so your editor understands them.
+
+### True Composition
+Components are functions. Compose them like functions. No slots, no special APIs - just parameters and return values.
+
+### Performance
+No template parsing at runtime. Templates are already JavaScript functions, eliminating parsing overhead.
+
+### Security Helpers
+- Automatic HTML escaping by default
+- Basic sanitization for loaded SVG/HTML files
+- Path traversal protection for file operations
+- Remember: security is ultimately your responsibility
+
+### Integrated CSS Management
+- Automatic CSS scoping with hash-based class names
+- CSS-in-JS with zero runtime
+- Critical CSS inlining
+- Automatic minification
+
+### Built-in i18n Support
+First-class internationalization support with a simple, component-friendly API for multi-language applications.
+
+### Asset Handling
+- Inline images as base64
+- SVG loading with automatic sanitization
+- JSON data loading
+- Raw HTML imports with XSS protection
+
+### SEO Friendly
+- Pure server-side rendering - search engines see fully rendered HTML
+- Lightning fast pages with inlined critical CSS
+- Minimal payload size improves Core Web Vitals scores
+- No client-side hydration delays
+
+### Minimal Footprint
+Single file implementation (~950 lines). No complex build process or heavy dependencies.
+
+### Testable by Design
+Templates are pure functions - easy to unit test with any testing framework.
 
 ## Table of Contents
 
@@ -37,122 +84,186 @@ The template starts with a standard js file, which builds a tree of nodes, that
 
 ## Usage
 
+Create a template file:
+
 ```js
+// templates/greeting.js
+const { Div, H1, P } = require("boxwood")
+
+module.exports = ({ name, message }) => {
+  return Div([
+    H1(`Hello, ${name}!`),
+    P(message)
+  ])
+}
+```
+
+Compile and render it:
+
+```js
+// app.js
 const { compile } = require("boxwood")
-const { join } = require("path")
-// ...
-const path = join(__dirname, "index.js")
-const { template } = compile(path)
-// ...
-const html = template({ foo: "bar" })
+
+const { template } = compile("./templates/greeting.js")
+const html = template({ 
+  name: "World",
+  message: "Welcome to Boxwood"
+})
+
 console.log(html)
+// <div><h1>Hello, World!</h1><p>Welcome to Boxwood</p></div>
 ```
 
-You can use [express-boxwood](https://www.npmjs.com/package/express-boxwood) for [express](https://www.npmjs.com/package/express).
+### Express Integration
 
-## Syntax
+Boxwood includes built-in Express support:
 
 ```js
-// example/index.js
-const layout = require("./layout")
-const banner = require("./banner")
+import express from 'express'
+import engine from 'boxwood/adapters/express'
+import crypto from 'crypto'
+
+const app = express()
+
+// Register Boxwood as template engine
+app.engine('js', engine())
+app.set('views', './views')
+app.set('view engine', 'js')
+
+// CSP (Content Security Policy) nonce for inline scripts
+// A nonce is a unique random value generated for each request that allows
+// specific inline scripts to execute while blocking potential XSS attacks
+app.use((req, res, next) => {
+  // Generate a cryptographically secure random nonce
+  res.locals.nonce = crypto.randomBytes(16).toString('base64')
+  
+  // Set CSP header - only scripts with this exact nonce can execute
+  res.setHeader(
+    'Content-Security-Policy',
+    `script-src 'nonce-${res.locals.nonce}' 'strict-dynamic';`
+  )
+  next()
+})
 
-module.exports = () => {
-  return layout({ language: "en" }, [
-    banner({
-      title: "Hello, world!",
-      description: "Lorem ipsum dolor sit amet",
-    }),
-  ])
-}
+// Render templates - nonce is automatically injected into all inline scripts
+app.get('/', (req, res) => {
+  res.render('home', { title: 'Welcome' })
+  // Boxwood automatically adds nonce="${res.locals.nonce}" to script tags
+})
 ```
 
-```js
-// example/layout/index.js
-const { component, css, doctype, html, body } = require("boxwood")
-const head = require("./head")
-
-const styles = css.load(__dirname)
-
-module.exports = component(
-  ({ language }, children) => {
-    return [
-      doctype(),
-      html({ lang: language }, [
-        head(),
-        body({ className: styles.layout }, children),
-      ]),
-    ]
-  },
-  { styles }
-)
+The Express adapter automatically:
+- Handles template caching in production
+- Hot reloads templates in development
+- Injects CSP nonces from `res.locals.nonce` into all inline scripts and styles
+
+#### Understanding CSP Nonces
+
+A Content Security Policy (CSP) nonce is a security feature that helps prevent Cross-Site Scripting (XSS) attacks:
+
+1. **Without CSP**: Any injected `<script>` tag can execute, making XSS attacks possible
+2. **With CSP nonce**: Only scripts with the correct nonce attribute can run
+3. **How it works**:
+   - Server generates a unique random nonce for each request
+   - Server adds this nonce to the CSP header: `script-src 'nonce-abc123'`
+   - Server adds the same nonce to legitimate scripts: `<script nonce="abc123">`
+   - Browser only executes scripts that have the matching nonce
+   - Attackers can't guess the nonce, so injected scripts are blocked
+
+Example output:
+```html
+<!-- HTTP Header -->
+Content-Security-Policy: script-src 'nonce-rAnd0m123' 'strict-dynamic';
+
+<!-- Generated HTML -->
+<script nonce="rAnd0m123">
+  console.log("This legitimate script will execute")
+</script>
+
+<script>
+  console.log("This injected script will be blocked!")
+</script>
 ```
 
-```js
-// example/layout/head/index.js
-const { head, title } = require("boxwood")
+## Features
 
-module.exports = () => {
-  return head([title("example")])
-}
-```
+### Components with CSS
 
 ```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 }
-)
+// button.js
+const { component, css, Button: ButtonTag } = require("boxwood")
+
+const styles = css`
+  .button {
+    padding: 8px 16px;
+    background: blue;
+    color: white;
+  }
+  .secondary {
+    background: gray;
+  }
+`
+
+const Button = ({ variant, children }) => {
+  return ButtonTag({ 
+    // className accepts arrays - falsy values are automatically filtered
+    className: [styles.button, variant === 'secondary' && styles.secondary]
+  }, children)
+}
+
+module.exports = component(Button, { styles })
 ```
 
-```js
-// example/banner/index.test.js
-const test = require("node:test")
-const assert = require("node:assert")
-const { compile } = require("boxwood")
+### Internationalization
 
-test("banner renders a title", async () => {
-  const { template } = compile(__dirname)
-  const html = template({ title: "foo" })
-  assert(html.includes("<h1>foo</h1>"))
-})
+```js
+// welcome.js
+const { component, i18n, H1, P } = require("boxwood")
+
+const Welcome = ({ translate, username }) => {
+  return [
+    H1(translate("greeting").replace("{name}", username)),
+    P(translate("intro"))
+  ]
+}
 
-test("banner renders an optional description", async () => {
-  const { template } = compile(__dirname)
-  const html = template({ title: "foo", description: "bar" })
-  assert(html.includes("<h1>foo</h1>"))
-  assert(html.includes("<p>bar</p>"))
+module.exports = component(Welcome, { 
+  i18n: i18n.load(__dirname) 
 })
 ```
 
-You can check the `test` dir for more examples.
+### Asset Loading
 
-## Security
+```js
+const { Img, Svg } = require("boxwood")
 
-By default, boxwood sanitizes all HTML, SVG and i18n content loaded via its API to protect against basic XSS attacks.
+// Load and inline images
+const Logo = Img.load("./assets/logo.png")
 
-Disabling sanitization ({ sanitize: false }) is only safe for trusted, developer-controlled files. Never use it with user-generated or untrusted content.
+// Load and sanitize SVGs
+const Icon = Svg.load("./assets/icon.svg")
 
-All file access is restricted to the project directory and symlinks are not allowed by default to prevent path traversal attacks.
+module.exports = () => {
+  return [Logo(), Icon]
+}
+```
+
+Additional examples are available in the `test` directory.
+
+## Security
 
-That said, the library is pretty small so please review it and suggest improvements if you have any.
+Boxwood provides basic security features:
 
-## Maintainers
+- HTML content is escaped by default
+- Loaded SVG and HTML files are sanitized
+- File access is restricted to the project directory
+- Symlinks are blocked to prevent directory traversal
 
-[@emilos](https://github.com/emilos)
+The `sanitize: false` option should only be used with trusted content. Security remains the developer's responsibility.
 
 ## Contributing
 
-All contributions are highly appreciated. Please feel free to open new issues and send PRs.
+Issues and pull requests are welcome. The codebase is intentionally small and focused.
 
 ## License
 

package/adapters/express/index.js

@@ -0,0 +1,49 @@
+const NODE_ENV = process.env.NODE_ENV || "development"
+const { compile } = require("../..")
+
+function purge(path) {
+  const name = require.resolve(path)
+  const dependency = require.cache[name]
+  if (dependency && dependency.children) {
+    dependency.children.forEach((child) => {
+      delete require.cache[child.id]
+      purge(child.id)
+    })
+    delete require.cache[name]
+  }
+}
+
+function engine(options = {}) {
+  const env = options.env || NODE_ENV
+  const cache = new Map()
+  async function compileFile(path) {
+    if (env === "development") {
+      purge(path)
+      const { template } = await compile(path)
+      return template
+    }
+    if (cache.has(path)) return cache.get(path)
+    const { template } = await compile(path)
+    cache.set(path, template)
+    return template
+  }
+
+  async function render(path, options, callback) {
+    try {
+      const template = await compileFile(path)
+      // Automatically inject nonce from res.locals if available
+      const templateOptions = options && options._locals && options._locals.nonce
+        ? { ...options, nonce: options._locals.nonce }
+        : options
+      const html = template(templateOptions)
+      if (callback) return callback(null, html)
+      return html
+    } catch (error) {
+      if (callback) return callback(error)
+      return error.message
+    }
+  }
+  return render
+}
+
+module.exports = engine

package/examples/typescript-example.ts

@@ -0,0 +1,49 @@
+// Example of using boxwood with TypeScript
+import { Div, H1, Button, Form, Input, component, classes } from 'boxwood';
+
+// Define typed component props
+interface UserCardProps {
+  name: string;
+  email: string;
+  isActive: boolean;
+}
+
+// Create a typed component
+const UserCard = component<UserCardProps>(
+  ({ name, email, isActive }, children) => {
+    return Div({ 
+      className: classes('user-card', { active: isActive }) 
+    }, [
+      H1({}, name),
+      Div({ className: 'email' }, email),
+      children
+    ]);
+  }
+);
+
+// Use the component with type checking
+const app = Div({ id: 'app' }, [
+  UserCard({ 
+    name: 'John Doe',
+    email: 'john@example.com',
+    isActive: true
+  }, 
+    Button({ onclick: () => alert('Hello!') }, 'Click me')
+  ),
+  
+  Form({ method: 'post' }, [
+    Input({ 
+      type: 'email',
+      name: 'email',
+      required: true,
+      placeholder: 'Enter email'
+    }),
+    Button({ type: 'submit' }, 'Submit')
+  ])
+]);
+
+// TypeScript will provide:
+// - Autocomplete for all element attributes
+// - Type checking for attribute values
+// - Error highlighting for invalid props
+// - IntelliSense documentation