boxwood 2.0.0 → 2.2.0

package/README.md

@@ -114,7 +114,76 @@ console.log(html)
 // <div><h1>Hello, World!</h1><p>Welcome to Boxwood</p></div>
 ```
 
-For Express apps, use [express-boxwood](https://www.npmjs.com/package/express-boxwood).
+### Express Integration
+
+Boxwood includes built-in Express support:
+
+```js
+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()
+})
+
+// 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
+})
+```
+
+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>
+```
 
 ## Features
 

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/index.js

@@ -509,6 +509,27 @@ function decamelize(string) {
 
 function stylesheet(input) {
   const object = { ...input }
+  function render(object, selector = "") {
+    let result = []
+    for (const key in object) {
+      const value = object[key]
+      if (value && typeof value === "object") {
+        if (key.startsWith("@")) {
+          result.push(`${key}{${render(value, selector)}}`)
+        } else {
+          const nextSelector = selector ? `${selector} ${key}` : key
+          result.push(render(value, nextSelector))
+        }
+      } else {
+        if (selector) {
+          result.push(`${selector}{${decamelize(key)}:${value};}`)
+        } else {
+          result.push(`${decamelize(key)}:${value};`)
+        }
+      }
+    }
+    return result.join("")
+  }
   return {
     add(item) {
       for (const key in item) {
@@ -519,14 +540,7 @@ function stylesheet(input) {
       object[key] = value
     },
     toString() {
-      let result = []
-      for (const key in object) {
-        const value = object[key]
-        if (value) {
-          result.push(`${decamelize(key)}:${value}`)
-        }
-      }
-      return result.join(";")
+      return render(object)
     },
   }
 }

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "boxwood",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Compile HTML templates into JS",
   "main": "index.js",
   "types": "index.d.ts",
+  "exports": {
+    ".": "./index.js",
+    "./adapters/express": "./adapters/express/index.js",
+    "./ui": "./ui/index.js"
+  },
   "scripts": {
     "test": "node --test --test-reporter=dot \"test/**/*.test.js\" \"test/**/*.spec.js\"",
     "test:debug": "node --test --test-reporter=spec \"test/**/*.test.js\" \"test/**/*.spec.js\"",

package/ui/Group/index.js

@@ -0,0 +1,39 @@
+const { css, component, Div } = require("../..")
+const {
+  normalizeGap,
+  normalizeFlex,
+  normalizeBreakpoint,
+  normalizeWidth,
+} = require("../normalize")
+
+function Group({ align, breakpoint, justify, gap, width, style }, children) {
+  gap = normalizeGap(gap)
+  align = normalizeFlex(align)
+  justify = normalizeFlex(justify)
+  breakpoint = normalizeBreakpoint(breakpoint)
+  width = normalizeWidth(width)
+
+  const styleObject = {
+    display: "flex",
+    "flex-direction": "row",
+    ...(gap && { gap }),
+    ...(align && { "align-items": align }),
+    ...(justify && { "justify-content": justify }),
+    ...(width && { width }),
+    ...(breakpoint && {
+      [`@media (max-width: ${breakpoint})`]: {
+        "flex-direction": "column",
+      },
+    }),
+  }
+
+  const styles = css`
+    .group {
+      ${css.create(styleObject).toString()}
+    }
+  `
+
+  return [Div({ className: styles.group, style }, children), styles.css]
+}
+
+module.exports = component(Group)

package/ui/Stack/index.js

@@ -0,0 +1,28 @@
+const { css, component, Div } = require("../..")
+const { normalizeGap, normalizeFlex, normalizeWidth } = require("../normalize")
+
+function Stack({ align, justify, gap, width, style }, children) {
+  gap = normalizeGap(gap)
+  align = normalizeFlex(align)
+  justify = normalizeFlex(justify)
+  width = normalizeWidth(width)
+
+  const styleObject = {
+    display: "flex",
+    "flex-direction": "column",
+    ...(gap && { gap }),
+    ...(align && { "align-items": align }),
+    ...(justify && { "justify-content": justify }),
+    ...(width && { width }),
+  }
+
+  const styles = css`
+    .stack {
+      ${css.create(styleObject).toString()}
+    }
+  `
+
+  return [Div({ className: styles.stack, style }, children), styles.css]
+}
+
+module.exports = component(Stack)

package/ui/index.js

@@ -0,0 +1,7 @@
+const Group = require("./Group")
+const Stack = require("./Stack")
+
+module.exports = {
+  Group,
+  Stack,
+}

package/ui/normalize.js

@@ -0,0 +1,66 @@
+function normalizeFlex(align) {
+  switch (align) {
+    case "start":
+      return "flex-start"
+    case "end":
+      return "flex-end"
+    default:
+      return align
+  }
+}
+
+const GAP_MAP = {
+  xs: "0.25rem",
+  sm: "0.5rem",
+  md: "1rem",
+  lg: "2rem",
+  xl: "4rem",
+  none: null,
+}
+
+function normalizeGap(gap) {
+  if (!gap) {
+    return "1rem"
+  }
+  if (typeof gap === "number") {
+    return `${gap}px`
+  }
+
+  if (GAP_MAP.hasOwnProperty(gap)) {
+    return GAP_MAP[gap]
+  }
+
+  return gap
+}
+
+const BREAKPOINT_MAP = {
+  xs: "575px",
+  sm: "767px",
+  md: "991px",
+  lg: "1199px",
+  xl: "1399px",
+}
+
+function normalizeBreakpoint(breakpoint) {
+  if (typeof breakpoint === "number") {
+    return `${breakpoint}px`
+  }
+  if (BREAKPOINT_MAP.hasOwnProperty(breakpoint)) {
+    return BREAKPOINT_MAP[breakpoint]
+  }
+  return breakpoint
+}
+
+function normalizeWidth(width) {
+  if (typeof width === "number") {
+    return `${width}px`
+  }
+  return width
+}
+
+module.exports = {
+  normalizeFlex,
+  normalizeGap,
+  normalizeBreakpoint,
+  normalizeWidth,
+}

package/.claude/settings.local.json

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