boxwood 1.1.1 → 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

package/index.d.ts

@@ -0,0 +1,545 @@
+// TypeScript definitions for boxwood
+declare module 'boxwood' {
+  // Core types
+  type Child = string | number | Node | Node[] | null | undefined;
+  type Children = Child | Child[];
+
+  interface Node {
+    name: string;
+    attributes?: Record<string, any>;
+    children?: Children;
+    ignore?: boolean;
+  }
+
+  interface ComponentProps {
+    [key: string]: any;
+  }
+
+  interface TranslateFunction {
+    (key: string): string;
+  }
+
+  interface ComponentWithI18n<T = ComponentProps> {
+    (props: T & { translate: TranslateFunction }, children?: Children): Node | Node[];
+  }
+
+  interface Component<T = ComponentProps> {
+    (props?: T, children?: Children): Node | Node[];
+  }
+
+  // HTML Attributes
+  interface GlobalAttributes {
+    accesskey?: string;
+    autocapitalize?: string;
+    class?: string;
+    className?: string;
+    contenteditable?: boolean | 'true' | 'false';
+    contextmenu?: string;
+    dir?: 'ltr' | 'rtl' | 'auto';
+    draggable?: boolean | 'true' | 'false';
+    hidden?: boolean;
+    id?: string;
+    lang?: string;
+    slot?: string;
+    spellcheck?: boolean | 'true' | 'false';
+    style?: string | Record<string, string | number>;
+    tabindex?: number | string;
+    title?: string;
+    translate?: 'yes' | 'no';
+    role?: string;
+    // Data attributes
+    [key: `data-${string}`]: any;
+    // Event handlers
+    onclick?: string | Function;
+    ondblclick?: string | Function;
+    onmousedown?: string | Function;
+    onmouseup?: string | Function;
+    onmouseover?: string | Function;
+    onmousemove?: string | Function;
+    onmouseout?: string | Function;
+    onmouseenter?: string | Function;
+    onmouseleave?: string | Function;
+    onkeydown?: string | Function;
+    onkeyup?: string | Function;
+    onkeypress?: string | Function;
+    onfocus?: string | Function;
+    onblur?: string | Function;
+    onchange?: string | Function;
+    oninput?: string | Function;
+    onsubmit?: string | Function;
+    onreset?: string | Function;
+    onload?: string | Function;
+    onerror?: string | Function;
+    onresize?: string | Function;
+    onscroll?: string | Function;
+  }
+
+  // Element-specific attributes
+  interface AnchorAttributes extends GlobalAttributes {
+    href?: string;
+    target?: '_blank' | '_self' | '_parent' | '_top';
+    rel?: string;
+    download?: string | boolean;
+    hreflang?: string;
+    ping?: string;
+    referrerpolicy?: string;
+    type?: string;
+  }
+
+  interface ImageAttributes extends GlobalAttributes {
+    src?: string;
+    alt?: string;
+    width?: number | string;
+    height?: number | string;
+    loading?: 'lazy' | 'eager';
+    decoding?: 'sync' | 'async' | 'auto';
+    srcset?: string;
+    sizes?: string;
+    crossorigin?: 'anonymous' | 'use-credentials';
+    referrerpolicy?: string;
+  }
+
+  interface InputAttributes extends GlobalAttributes {
+    type?: 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search' | 
+           'date' | 'time' | 'datetime-local' | 'month' | 'week' | 'color' |
+           'checkbox' | 'radio' | 'file' | 'submit' | 'reset' | 'button' |
+           'hidden' | 'image' | 'range';
+    name?: string;
+    value?: string | number;
+    placeholder?: string;
+    required?: boolean;
+    disabled?: boolean;
+    readonly?: boolean;
+    checked?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    pattern?: string;
+    multiple?: boolean;
+    accept?: string;
+    autocomplete?: string;
+    autofocus?: boolean;
+    form?: string;
+    list?: string;
+    maxlength?: number;
+    minlength?: number;
+    size?: number;
+  }
+
+  interface FormAttributes extends GlobalAttributes {
+    action?: string;
+    method?: 'get' | 'post' | 'dialog';
+    enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+    name?: string;
+    target?: string;
+    novalidate?: boolean;
+    autocomplete?: 'on' | 'off';
+  }
+
+  interface ButtonAttributes extends GlobalAttributes {
+    type?: 'submit' | 'reset' | 'button';
+    name?: string;
+    value?: string;
+    disabled?: boolean;
+    form?: string;
+    formaction?: string;
+    formenctype?: string;
+    formmethod?: string;
+    formnovalidate?: boolean;
+    formtarget?: string;
+    autofocus?: boolean;
+  }
+
+  interface TextAreaAttributes extends GlobalAttributes {
+    name?: string;
+    rows?: number;
+    cols?: number;
+    disabled?: boolean;
+    readonly?: boolean;
+    required?: boolean;
+    placeholder?: string;
+    autofocus?: boolean;
+    form?: string;
+    maxlength?: number;
+    minlength?: number;
+    wrap?: 'hard' | 'soft';
+  }
+
+  interface SelectAttributes extends GlobalAttributes {
+    name?: string;
+    disabled?: boolean;
+    required?: boolean;
+    multiple?: boolean;
+    size?: number;
+    form?: string;
+    autofocus?: boolean;
+  }
+
+  interface OptionAttributes extends GlobalAttributes {
+    value?: string;
+    label?: string;
+    selected?: boolean;
+    disabled?: boolean;
+  }
+
+  interface LabelAttributes extends GlobalAttributes {
+    for?: string;
+    htmlFor?: string;
+  }
+
+  interface ScriptAttributes extends GlobalAttributes {
+    src?: string;
+    type?: string;
+    async?: boolean;
+    defer?: boolean;
+    crossorigin?: 'anonymous' | 'use-credentials';
+    integrity?: string;
+    nomodule?: boolean;
+    referrerpolicy?: string;
+    target?: 'head' | 'body';
+  }
+
+  interface LinkAttributes extends GlobalAttributes {
+    href?: string;
+    rel?: string;
+    type?: string;
+    media?: string;
+    as?: string;
+    crossorigin?: 'anonymous' | 'use-credentials';
+    integrity?: string;
+    referrerpolicy?: string;
+    sizes?: string;
+    imagesrcset?: string;
+    imagesizes?: string;
+  }
+
+  interface MetaAttributes extends GlobalAttributes {
+    charset?: string;
+    content?: string;
+    httpEquiv?: string;
+    name?: string;
+    property?: string;
+  }
+
+  interface MediaAttributes extends GlobalAttributes {
+    src?: string;
+    controls?: boolean;
+    autoplay?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    preload?: 'none' | 'metadata' | 'auto';
+    crossorigin?: 'anonymous' | 'use-credentials';
+  }
+
+  interface VideoAttributes extends MediaAttributes {
+    width?: number | string;
+    height?: number | string;
+    poster?: string;
+    playsinline?: boolean;
+  }
+
+  interface AudioAttributes extends MediaAttributes {}
+
+  interface IframeAttributes extends GlobalAttributes {
+    src?: string;
+    srcdoc?: string;
+    name?: string;
+    width?: number | string;
+    height?: number | string;
+    allow?: string;
+    allowfullscreen?: boolean;
+    allowpaymentrequest?: boolean;
+    loading?: 'lazy' | 'eager';
+    referrerpolicy?: string;
+    sandbox?: string;
+  }
+
+  interface TableCellAttributes extends GlobalAttributes {
+    colspan?: number;
+    rowspan?: number;
+    headers?: string;
+  }
+
+  // SVG Attributes
+  interface SVGAttributes extends GlobalAttributes {
+    // Core SVG attributes
+    viewBox?: string;
+    preserveAspectRatio?: string;
+    xmlns?: string;
+    xmlnsXlink?: string;
+    version?: string;
+    baseProfile?: string;
+    x?: number | string;
+    y?: number | string;
+    width?: number | string;
+    height?: number | string;
+    // Presentation attributes
+    fill?: string;
+    fillOpacity?: number | string;
+    fillRule?: 'nonzero' | 'evenodd';
+    stroke?: string;
+    strokeWidth?: number | string;
+    strokeOpacity?: number | string;
+    strokeLinecap?: 'butt' | 'round' | 'square';
+    strokeLinejoin?: 'miter' | 'round' | 'bevel';
+    strokeDasharray?: string;
+    strokeDashoffset?: number | string;
+    opacity?: number | string;
+    transform?: string;
+    vectorEffect?: string;
+    shapeRendering?: string;
+    pathLength?: number;
+    // Common SVG attributes
+    d?: string;
+    points?: string;
+    cx?: number | string;
+    cy?: number | string;
+    r?: number | string;
+    rx?: number | string;
+    ry?: number | string;
+    x1?: number | string;
+    y1?: number | string;
+    x2?: number | string;
+    y2?: number | string;
+    href?: string;
+    xlinkHref?: string;
+    id?: string;
+    clipPath?: string;
+    mask?: string;
+    filter?: string;
+    markerStart?: string;
+    markerMid?: string;
+    markerEnd?: string;
+    // Animation attributes
+    attributeName?: string;
+    from?: string | number;
+    to?: string | number;
+    dur?: string;
+    repeatCount?: number | 'indefinite';
+    // Gradient attributes
+    gradientUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    gradientTransform?: string;
+    fx?: number | string;
+    fy?: number | string;
+    offset?: string;
+    stopColor?: string;
+    stopOpacity?: number | string;
+    // Text attributes
+    textAnchor?: 'start' | 'middle' | 'end';
+    dominantBaseline?: string;
+    fontSize?: number | string;
+    fontFamily?: string;
+    fontWeight?: number | string;
+    letterSpacing?: number | string;
+    textDecoration?: string;
+    // Pattern attributes
+    patternUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    patternTransform?: string;
+    patternContentUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+  }
+
+  // Element type functions
+  type ElementFunction<T = GlobalAttributes> = (attributes?: T, children?: Children) => Node;
+
+  // HTML Elements
+  export const A: ElementFunction<AnchorAttributes>;
+  export const Abbr: ElementFunction<GlobalAttributes>;
+  export const Address: ElementFunction<GlobalAttributes>;
+  export const Area: ElementFunction<GlobalAttributes & { alt?: string; coords?: string; shape?: string; href?: string; target?: string; rel?: string; }>;
+  export const Article: ElementFunction<GlobalAttributes>;
+  export const Aside: ElementFunction<GlobalAttributes>;
+  export const Audio: ElementFunction<AudioAttributes>;
+  export const B: ElementFunction<GlobalAttributes>;
+  export const Base: ElementFunction<GlobalAttributes & { href?: string; target?: string; }>;
+  export const Bdi: ElementFunction<GlobalAttributes>;
+  export const Bdo: ElementFunction<GlobalAttributes>;
+  export const Blockquote: ElementFunction<GlobalAttributes & { cite?: string; }>;
+  export const Body: ElementFunction<GlobalAttributes>;
+  export const Br: ElementFunction<GlobalAttributes>;
+  export const Button: ElementFunction<ButtonAttributes>;
+  export const Canvas: ElementFunction<GlobalAttributes & { width?: number | string; height?: number | string; }>;
+  export const Caption: ElementFunction<GlobalAttributes>;
+  export const Cite: ElementFunction<GlobalAttributes>;
+  export const Code: ElementFunction<GlobalAttributes>;
+  export const Col: ElementFunction<GlobalAttributes & { span?: number; }>;
+  export const Colgroup: ElementFunction<GlobalAttributes & { span?: number; }>;
+  export const Data: ElementFunction<GlobalAttributes & { value?: string; }>;
+  export const Datalist: ElementFunction<GlobalAttributes>;
+  export const Dd: ElementFunction<GlobalAttributes>;
+  export const Del: ElementFunction<GlobalAttributes & { cite?: string; datetime?: string; }>;
+  export const Details: ElementFunction<GlobalAttributes & { open?: boolean; }>;
+  export const Dfn: ElementFunction<GlobalAttributes>;
+  export const Dialog: ElementFunction<GlobalAttributes & { open?: boolean; }>;
+  export const Div: ElementFunction<GlobalAttributes>;
+  export const Dl: ElementFunction<GlobalAttributes>;
+  export const Dt: ElementFunction<GlobalAttributes>;
+  export const Em: ElementFunction<GlobalAttributes>;
+  export const Embed: ElementFunction<GlobalAttributes & { src?: string; type?: string; width?: number | string; height?: number | string; }>;
+  export const Fieldset: ElementFunction<GlobalAttributes & { disabled?: boolean; form?: string; name?: string; }>;
+  export const Figcaption: ElementFunction<GlobalAttributes>;
+  export const Figure: ElementFunction<GlobalAttributes>;
+  export const Footer: ElementFunction<GlobalAttributes>;
+  export const Form: ElementFunction<FormAttributes>;
+  export const H1: ElementFunction<GlobalAttributes>;
+  export const H2: ElementFunction<GlobalAttributes>;
+  export const H3: ElementFunction<GlobalAttributes>;
+  export const H4: ElementFunction<GlobalAttributes>;
+  export const H5: ElementFunction<GlobalAttributes>;
+  export const H6: ElementFunction<GlobalAttributes>;
+  export const Head: ElementFunction<GlobalAttributes>;
+  export const Header: ElementFunction<GlobalAttributes>;
+  export const Hgroup: ElementFunction<GlobalAttributes>;
+  export const Hr: ElementFunction<GlobalAttributes>;
+  export const Html: ElementFunction<GlobalAttributes & { lang?: string; }>;
+  export const I: ElementFunction<GlobalAttributes>;
+  export const Iframe: ElementFunction<IframeAttributes>;
+  export const Img: ElementFunction<ImageAttributes>;
+  export const Input: ElementFunction<InputAttributes>;
+  export const Ins: ElementFunction<GlobalAttributes & { cite?: string; datetime?: string; }>;
+  export const Kbd: ElementFunction<GlobalAttributes>;
+  export const Label: ElementFunction<LabelAttributes>;
+  export const Legend: ElementFunction<GlobalAttributes>;
+  export const Li: ElementFunction<GlobalAttributes & { value?: number; }>;
+  export const Link: ElementFunction<LinkAttributes>;
+  export const Main: ElementFunction<GlobalAttributes>;
+  export const Map: ElementFunction<GlobalAttributes & { name?: string; }>;
+  export const Mark: ElementFunction<GlobalAttributes>;
+  export const Menu: ElementFunction<GlobalAttributes>;
+  export const Meta: ElementFunction<MetaAttributes>;
+  export const Meter: ElementFunction<GlobalAttributes & { value?: number; min?: number; max?: number; low?: number; high?: number; optimum?: number; }>;
+  export const Nav: ElementFunction<GlobalAttributes>;
+  export const Noscript: ElementFunction<GlobalAttributes>;
+  export const Object: ElementFunction<GlobalAttributes & { data?: string; type?: string; name?: string; form?: string; width?: number | string; height?: number | string; }>;
+  export const Ol: ElementFunction<GlobalAttributes & { reversed?: boolean; start?: number; type?: '1' | 'a' | 'A' | 'i' | 'I'; }>;
+  export const Optgroup: ElementFunction<GlobalAttributes & { disabled?: boolean; label?: string; }>;
+  export const Option: ElementFunction<OptionAttributes>;
+  export const Output: ElementFunction<GlobalAttributes & { for?: string; form?: string; name?: string; }>;
+  export const P: ElementFunction<GlobalAttributes>;
+  export const Param: ElementFunction<GlobalAttributes & { name?: string; value?: string; }>;
+  export const Picture: ElementFunction<GlobalAttributes>;
+  export const Pre: ElementFunction<GlobalAttributes>;
+  export const Progress: ElementFunction<GlobalAttributes & { value?: number; max?: number; }>;
+  export const Q: ElementFunction<GlobalAttributes & { cite?: string; }>;
+  export const Rp: ElementFunction<GlobalAttributes>;
+  export const Rt: ElementFunction<GlobalAttributes>;
+  export const Ruby: ElementFunction<GlobalAttributes>;
+  export const S: ElementFunction<GlobalAttributes>;
+  export const Samp: ElementFunction<GlobalAttributes>;
+  export const Script: ElementFunction<ScriptAttributes>;
+  export const Section: ElementFunction<GlobalAttributes>;
+  export const Select: ElementFunction<SelectAttributes>;
+  export const Slot: ElementFunction<GlobalAttributes & { name?: string; }>;
+  export const Small: ElementFunction<GlobalAttributes>;
+  export const Source: ElementFunction<GlobalAttributes & { src?: string; type?: string; srcset?: string; sizes?: string; media?: string; }>;
+  export const Span: ElementFunction<GlobalAttributes>;
+  export const Strong: ElementFunction<GlobalAttributes>;
+  export const Style: ElementFunction<GlobalAttributes & { type?: string; media?: string; nonce?: string; }>;
+  export const Sub: ElementFunction<GlobalAttributes>;
+  export const Summary: ElementFunction<GlobalAttributes>;
+  export const Sup: ElementFunction<GlobalAttributes>;
+  export const Table: ElementFunction<GlobalAttributes>;
+  export const Tbody: ElementFunction<GlobalAttributes>;
+  export const Td: ElementFunction<TableCellAttributes>;
+  export const Template: ElementFunction<GlobalAttributes>;
+  export const Textarea: ElementFunction<TextAreaAttributes>;
+  export const Tfoot: ElementFunction<GlobalAttributes>;
+  export const Th: ElementFunction<TableCellAttributes & { scope?: 'row' | 'col' | 'rowgroup' | 'colgroup'; abbr?: string; }>;
+  export const Thead: ElementFunction<GlobalAttributes>;
+  export const Time: ElementFunction<GlobalAttributes & { datetime?: string; }>;
+  export const Title: ElementFunction<GlobalAttributes>;
+  export const Tr: ElementFunction<GlobalAttributes>;
+  export const Track: ElementFunction<GlobalAttributes & { kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata'; src?: string; srclang?: string; label?: string; default?: boolean; }>;
+  export const U: ElementFunction<GlobalAttributes>;
+  export const Ul: ElementFunction<GlobalAttributes>;
+  export const Var: ElementFunction<GlobalAttributes>;
+  export const Video: ElementFunction<VideoAttributes>;
+  export const Wbr: ElementFunction<GlobalAttributes>;
+
+  // SVG Elements
+  export const Svg: ElementFunction<SVGAttributes>;
+  export const Animate: ElementFunction<SVGAttributes>;
+  export const AnimateMotion: ElementFunction<SVGAttributes & { path?: string; }>;
+  export const AnimateTransform: ElementFunction<SVGAttributes & { type?: string; }>;
+  export const Circle: ElementFunction<SVGAttributes>;
+  export const ClipPath: ElementFunction<SVGAttributes>;
+  export const Defs: ElementFunction<SVGAttributes>;
+  export const Desc: ElementFunction<SVGAttributes>;
+  export const Ellipse: ElementFunction<SVGAttributes>;
+  export const Filter: ElementFunction<SVGAttributes>;
+  export const ForeignObject: ElementFunction<SVGAttributes>;
+  export const G: ElementFunction<SVGAttributes>;
+  export const Image: ElementFunction<SVGAttributes>;
+  export const Line: ElementFunction<SVGAttributes>;
+  export const LinearGradient: ElementFunction<SVGAttributes>;
+  export const Marker: ElementFunction<SVGAttributes & { markerWidth?: number | string; markerHeight?: number | string; refX?: number | string; refY?: number | string; orient?: string | number; }>;
+  export const Mask: ElementFunction<SVGAttributes>;
+  export const Metadata: ElementFunction<SVGAttributes>;
+  export const Path: ElementFunction<SVGAttributes>;
+  export const Pattern: ElementFunction<SVGAttributes>;
+  export const Polygon: ElementFunction<SVGAttributes>;
+  export const Polyline: ElementFunction<SVGAttributes>;
+  export const RadialGradient: ElementFunction<SVGAttributes>;
+  export const Rect: ElementFunction<SVGAttributes>;
+  export const Set: ElementFunction<SVGAttributes>;
+  export const Stop: ElementFunction<SVGAttributes>;
+  export const Switch: ElementFunction<SVGAttributes>;
+  export const Symbol: ElementFunction<SVGAttributes>;
+  export const Text: ElementFunction<SVGAttributes>;
+  export const TextPath: ElementFunction<SVGAttributes>;
+  export const Tspan: ElementFunction<SVGAttributes>;
+  export const Use: ElementFunction<SVGAttributes>;
+  export const View: ElementFunction<SVGAttributes>;
+
+  // Special elements
+  export function Doctype(attributes?: { html?: boolean }): Node;
+
+  // Utility functions
+  export function escape(text: string): string;
+  export function raw(html: string): { html: string };
+  export function tag(name: string, attributes?: Record<string, any>, children?: Children): Node;
+
+  // Asset loaders
+  export function css(path: string): { css: Node };
+  export function js(path: string): { js: Node };
+  export function json(path: string): any;
+
+  // Component system
+  interface ComponentOptions {
+    styles?: string | string[] | { css: Node } | { css: Node }[];
+    scripts?: string | string[] | { js: Node } | { js: Node }[];
+  }
+
+  export function component<T = ComponentProps>(
+    fn: Component<T> | ComponentWithI18n<T>,
+    options?: ComponentOptions
+  ): Component<T>;
+
+  // CSS utilities
+  export function classes(...args: Array<string | Record<string, boolean> | undefined | null | false>): string;
+
+  // Internationalization
+  export function i18n<T = ComponentProps>(
+    fn: ComponentWithI18n<T>,
+    translations: Record<string, Record<string, string>>
+  ): Component<T>;
+
+  // Compile function
+  interface CompileResult {
+    template(...args: any[]): string;
+  }
+
+  export function compile(path: string): CompileResult;
+
+  // Error types
+  export class CompileError extends Error {
+    constructor(message: string);
+  }
+
+  export class SecurityError extends Error {
+    constructor(message: string);
+  }
+
+  export class TranslationError extends Error {
+    constructor(message: string);
+  }
+}

package/index.js

@@ -5,7 +5,8 @@ const csstree = require("css-tree")
 function compile(path) {
   const fn = require(path)
   return {
-    template() {
+    template(options) {
+      const nonce = options && options.nonce
       const tree = fn(...arguments)
       const nodes = {}
       const styles = []
@@ -65,24 +66,36 @@ function compile(path) {
       walk(tree)
       if (nodes.head) {
         if (styles.length > 0) {
-          nodes.head.children.push({
+          const styleNode = {
             name: "style",
             children: styles.join(""),
-          })
+          }
+          if (nonce) {
+            styleNode.attributes = { nonce }
+          }
+          nodes.head.children.push(styleNode)
         }
         if (scripts.head.length > 0) {
-          nodes.head.children.push({
+          const scriptNode = {
             name: "script",
             children: scripts.head.join(""),
-          })
+          }
+          if (nonce) {
+            scriptNode.attributes = { nonce }
+          }
+          nodes.head.children.push(scriptNode)
         }
       }
       if (nodes.body) {
         if (scripts.body.length > 0) {
-          nodes.body.children.push({
+          const scriptNode = {
             name: "script",
             children: scripts.body.join(""),
-          })
+          }
+          if (nonce) {
+            scriptNode.attributes = { nonce }
+          }
+          nodes.body.children.push(scriptNode)
         }
       }
       return render(tree)
@@ -90,20 +103,61 @@ function compile(path) {
   }
 }
 
-const ENTITIES = {
-  "&": "&",
-  "<": "&lt;",
-  ">": "&gt;",
-  "'": "&#39;",
-  '"': "&quot;",
-}
+const escapeHTML = (string) => {
+  // Convert to string to handle non-string inputs safely
+  string = String(string)
 
-const REGEXP = /[&<>'"]/g
+  // Fast path: if no special characters, return as-is
+  if (
+    !string.includes("&") &&
+    !string.includes("<") &&
+    !string.includes(">") &&
+    !string.includes("'") &&
+    !string.includes('"')
+  ) {
+    return string
+  }
 
-const escapeHTML = (string) => {
-  return String.prototype.replace.call(string, REGEXP, function (character) {
-    return ENTITIES[character]
-  })
+  const len = string.length
+  let result = ""
+  let lastIndex = 0
+
+  for (let i = 0; i < len; i++) {
+    const char = string[i]
+    let replacement
+
+    switch (char) {
+      case "&":
+        replacement = "&amp;"
+        break
+      case "<":
+        replacement = "&lt;"
+        break
+      case ">":
+        replacement = "&gt;"
+        break
+      case "'":
+        replacement = "&#39;"
+        break
+      case '"':
+        replacement = "&quot;"
+        break
+      default:
+        continue
+    }
+
+    if (lastIndex !== i) {
+      result += string.slice(lastIndex, i)
+    }
+    result += replacement
+    lastIndex = i + 1
+  }
+
+  if (lastIndex !== len) {
+    result += string.slice(lastIndex)
+  }
+
+  return result
 }
 
 const normalizePath = (path) => path.replace(/\\/g, "/").replace(/\/+$/, "")
@@ -186,7 +240,7 @@ function readFile(path, encoding) {
   }
 }
 
-const BOOLEAN_ATTRIBUTES = [
+const BOOLEAN_ATTRIBUTES = new Set([
   "async",
   "autofocus",
   "autoplay",
@@ -223,14 +277,16 @@ const BOOLEAN_ATTRIBUTES = [
   "sortable",
   "spellcheck",
   "translate",
-]
+])
 
 const ALIASES = {
   className: "class",
   htmlFor: "for",
 }
 
-const isKeyValid = (key) => /^[a-zA-Z0-9\-_]+$/.test(key)
+// Pre-compiled regex for better performance
+const KEY_VALIDATION_REGEX = /^[a-zA-Z0-9\-_]+$/
+const isKeyValid = (key) => KEY_VALIDATION_REGEX.test(key)
 
 const attributes = (options) => {
   if (!options) {
@@ -248,13 +304,13 @@ const attributes = (options) => {
       value === true ||
       Array.isArray(value)
     ) {
-      if (BOOLEAN_ATTRIBUTES.includes(key)) {
+      if (BOOLEAN_ATTRIBUTES.has(key)) {
         result.push(key)
       } else {
         const name = ALIASES[key] || key
         const value = options[key]
         const content = Array.isArray(value) ? classes(...value) : value
-        result.push(name + "=" + '"' + escapeHTML(content) + '"')
+        result.push(`${name}="${escapeHTML(content)}"`)
       }
     } else if (key === "style" && typeof value === "object") {
       const styles = []
@@ -276,7 +332,7 @@ const attributes = (options) => {
   return result.join(" ")
 }
 
-const SELF_CLOSING_TAGS = [
+const SELF_CLOSING_TAGS = new Set([
   "area",
   "base",
   "br",
@@ -294,54 +350,60 @@ const SELF_CLOSING_TAGS = [
   "track",
   "wbr",
   "!DOCTYPE html",
-]
+])
 
-const isUnescapedTag = (name) => {
-  return !["script", "style", "template"].includes(name)
-}
+const UNESCAPED_TAGS = new Set(["script", "style", "template"])
 
 const render = (input, escape = true) => {
+  // Most common case: string (~50% of nodes)
+  if (typeof input === "string") {
+    return escape ? escapeHTML(input) : input
+  }
+
+  // Second most common: arrays (~20% of nodes)
+  if (Array.isArray(input)) {
+    let result = ""
+    for (let i = 0; i < input.length; i++) {
+      result += render(input[i])
+    }
+    return result
+  }
+
+  // Early exit for null/undefined/false/true
   if (
-    typeof input === "undefined" ||
-    typeof input === "boolean" ||
     input === null ||
-    input.ignore
+    input === undefined ||
+    input === false ||
+    input === true
   ) {
     return ""
   }
+
+  // Numbers (~5% of nodes)
   if (typeof input === "number") {
     return input.toString()
   }
-  if (typeof input === "string") {
-    if (escape) {
-      return escapeHTML(input)
-    }
-    return input
-  }
-  if (Array.isArray(input)) {
-    return input.map((input) => render(input)).join("")
+
+  // Objects (elements) - check ignore flag first
+  if (input.ignore) {
+    return ""
   }
 
   if (input.name === "raw") {
     return render(input.children, false)
   }
-  if (SELF_CLOSING_TAGS.includes(input.name)) {
-    if (input.attributes) {
-      return `<${input.name} ` + attributes(input.attributes) + ">"
-    }
-    return `<${input.name}>`
+
+  if (SELF_CLOSING_TAGS.has(input.name)) {
+    const attrs = input.attributes ? attributes(input.attributes) : ""
+    return attrs ? `<${input.name} ${attrs}>` : `<${input.name}>`
   }
 
-  const string = input.attributes ? attributes(input.attributes) : ""
-  const attrs = string ? " " + string : ""
+  const attrs = input.attributes ? attributes(input.attributes) : ""
+  const children = render(input.children, !UNESCAPED_TAGS.has(input.name))
 
-  return (
-    `<${input.name}` +
-    attrs +
-    ">" +
-    render(input.children, isUnescapedTag(input.name)) +
-    `</${input.name}>`
-  )
+  return attrs
+    ? `<${input.name} ${attrs}>${children}</${input.name}>`
+    : `<${input.name}>${children}</${input.name}>`
 }
 
 const raw = (children) => {
@@ -431,9 +493,14 @@ const tag = (a, b, c) => {
   }
 }
 
-let number = 1
-function sequence() {
-  return number++
+// DJB2 hash algorithm for CSS class names
+function hashDJB2(str) {
+  let hash = 5381
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash * 33) ^ str.charCodeAt(i)
+  }
+  // Convert to positive number and base36 for shorter string
+  return (hash >>> 0).toString(36)
 }
 
 function decamelize(string) {
@@ -475,12 +542,13 @@ function css(inputs) {
       result += input
     }
   }
-  const hash = sequence()
   const tree = csstree.parse(result)
   const classes = {}
 
   csstree.walk(tree, (node) => {
     if (node.type === "ClassSelector") {
+      // Generate hash based on the CSS content and class name
+      const hash = hashDJB2(result + node.name).slice(0, 6)
       const name = `${node.name}_${hash}`
       classes[node.name] = name
       node.name = name
@@ -605,12 +673,15 @@ js.load = function (path, options = {}) {
 }
 
 const node = (name) => (options, children) => tag(name, options, children)
-const doctype = node("!DOCTYPE html")
+const Doctype = node("!DOCTYPE html")
 
 const nodes = [
   "a",
   "abbr",
   "address",
+  "animate",
+  "animateMotion",
+  "animateTransform",
   "area",
   "article",
   "aside",
@@ -625,14 +696,18 @@ const nodes = [
   "button",
   "canvas",
   "caption",
+  "circle",
   "cite",
+  "clipPath",
   "code",
   "col",
   "colgroup",
   "data",
   "datalist",
   "dd",
+  "defs",
   "del",
+  "desc",
   "details",
   "dfn",
   "dialog",
@@ -640,12 +715,16 @@ const nodes = [
   "dl",
   "dt",
   "em",
+  "ellipse",
   "embed",
   "fieldset",
   "figcaption",
   "figure",
+  "filter",
   "footer",
+  "foreignObject",
   "form",
+  "g",
   "h1",
   "h2",
   "h3",
@@ -654,10 +733,12 @@ const nodes = [
   "h6",
   "head",
   "header",
+  "hgroup",
   "hr",
   "html",
   "i",
   "iframe",
+  "image",
   "img",
   "input",
   "ins",
@@ -665,11 +746,17 @@ const nodes = [
   "label",
   "legend",
   "li",
+  "line",
+  "linearGradient",
   "link",
   "main",
   "map",
   "mark",
+  "marker",
+  "mask",
+  "menu",
   "meta",
+  "metadata",
   "meter",
   "nav",
   "noscript",
@@ -680,10 +767,16 @@ const nodes = [
   "output",
   "p",
   "param",
+  "path",
+  "pattern",
   "picture",
+  "polygon",
+  "polyline",
   "pre",
   "progress",
   "q",
+  "radialGradient",
+  "rect",
   "rp",
   "rt",
   "ruby",
@@ -692,20 +785,27 @@ const nodes = [
   "script",
   "section",
   "select",
+  "set",
+  "slot",
   "small",
   "source",
   "span",
+  "stop",
   "strong",
   "style",
   "sub",
   "summary",
   "sup",
   "svg",
+  "switch",
+  "symbol",
   "table",
   "tbody",
   "td",
   "template",
+  "text",
   "textarea",
+  "textPath",
   "tfoot",
   "th",
   "thead",
@@ -713,13 +813,17 @@ const nodes = [
   "title",
   "tr",
   "track",
+  "tspan",
   "u",
   "ul",
+  "use",
   "var",
   "video",
+  "view",
   "wbr",
 ].reduce((result, name) => {
-  result[name] = node(name)
+  const pascalName = name.charAt(0).toUpperCase() + name.slice(1)
+  result[pascalName] = node(name)
   return result
 }, {})
 
@@ -740,7 +844,7 @@ function base64({ content, path }) {
   return `data:${media(path)};base64,${content}`
 }
 
-nodes.img.load = function (path) {
+nodes.Img.load = function (path) {
   const type = extension(path)
   if (!ALLOWED_IMAGE_EXTENSIONS.includes(type)) {
     throw new Error(
@@ -749,7 +853,7 @@ nodes.img.load = function (path) {
   }
   const content = readFile(path, "base64")
   return (options) => {
-    return nodes.img({ src: base64({ content, path }), ...options })
+    return nodes.Img({ src: base64({ content, path }), ...options })
   }
 }
 
@@ -795,7 +899,7 @@ const sanitizeSVG = (content) => {
  * Should not be used for user-generated content.
  */
 
-nodes.svg.load = function (path, options = {}) {
+nodes.Svg.load = function (path, options = {}) {
   const type = extension(path)
   if (type !== "svg") {
     throw new Error(
@@ -933,7 +1037,7 @@ module.exports = {
   compile,
   component,
   classes,
-  doctype,
+  Doctype,
   escape: escapeHTML,
   raw,
   css,

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "boxwood",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Compile HTML templates into JS",
   "main": "index.js",
+  "types": "index.d.ts",
   "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\"",