boxwood 1.1.0 → 2.0.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node test:*)",
+      "Bash(mkdir:*)",
+      "Bash(npm test:*)"
+    ],
+    "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,117 @@ The template starts with a standard js file, which builds a tree of nodes, that
 
 ## Usage
 
-```js
-const { compile } = require("boxwood")
-const { join } = require("path")
-// ...
-const path = join(__dirname, "index.js")
-const { template } = compile(path)
-// ...
-const html = template({ foo: "bar" })
-console.log(html)
-```
-
-You can use [express-boxwood](https://www.npmjs.com/package/express-boxwood) for [express](https://www.npmjs.com/package/express).
-
-## Syntax
+Create a template file:
 
 ```js
-// example/index.js
-const layout = require("./layout")
-const banner = require("./banner")
+// templates/greeting.js
+const { Div, H1, P } = require("boxwood")
 
-module.exports = () => {
-  return layout({ language: "en" }, [
-    banner({
-      title: "Hello, world!",
-      description: "Lorem ipsum dolor sit amet",
-    }),
+module.exports = ({ name, message }) => {
+  return Div([
+    H1(`Hello, ${name}!`),
+    P(message)
   ])
 }
 ```
 
-```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 }
-)
-```
+Compile and render it:
 
 ```js
-// example/layout/head/index.js
-const { head, title } = require("boxwood")
+// app.js
+const { compile } = require("boxwood")
 
-module.exports = () => {
-  return head([title("example")])
-}
+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>
 ```
 
+For Express apps, use [express-boxwood](https://www.npmjs.com/package/express-boxwood).
+
+## Features
+
+### 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/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