boxwood 2.17.0 → 2.18.0

package/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -rn \"js\\\\`\\\\|const js\\\\|export.*js\" /Users/emilos/Projects/buxlabs/boxwood/src --include=\"*.js\" -l)",
+      "Bash(grep -rln \"js\\\\`\" /Users/emilos/Projects/buxlabs/boxwood/ui /Users/emilos/Projects/buxlabs/boxwood/test)",
+      "Bash(grep -rn -A8 \"js\\\\`\" /Users/emilos/Projects/buxlabs/boxwood/ui)",
+      "Bash(node --test ui/prose/utilities/replaceVariables.test.js ui/prose/utilities/parseCustomTag.test.js test/ui/prose/gallery/index.test.js)",
+      "Bash(npm test *)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(node -e ' *)",
+      "Bash(node --test ui/prose/utilities/processLoops.test.js)"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boxwood",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "Compile HTML templates into JS",
   "main": "index.js",
   "types": "index.d.ts",

package/ui/markdown/index.js

@@ -1,9 +1,9 @@
 const nodes = require("../..")
 const { component } = nodes
 
-const { extractHtmlParams, mergeComponents } = require("./utilities/params")
-const { parseMarkdownLines } = require("./utilities/parseBlock")
-const { convertItemsToNodes } = require("./utilities/convertNodes")
+const { extractHtmlParams, mergeComponents } = require("../utilities/params")
+const { parseMarkdownLines } = require("../utilities/parseBlock")
+const { convertItemsToNodes } = require("../utilities/convertNodes")
 
 // Basic HTML components needed for markdown formatting (links, images, code, etc.)
 const BASIC_HTML_COMPONENTS = {

package/ui/prose/README.md

@@ -19,15 +19,19 @@ All standard markdown features:
 ### Templating Features
 
 - **Variable replacement**: `{variable}`, `{user.name}`, `{images[0].src}`
+- **Fallbacks**: `{nickname ?? name ?? "Guest"}` with JS nullish semantics
 - **Method calls**: `{images.slice(0, 2)}`, `{tags.join(', ')}`, `{name.toUpperCase()}`
-- **Conditionals**: `{#if variable}...{/if}` blocks for conditional rendering
-- **Loops**: `{#each items}...{/each}` for iteration over arrays
+- **Array literals**: `<Gallery images="{[images[0], images[2]]}" />`
+- **Conditionals**: `{#if}...{#elseif}...{#else}...{/if}` blocks
+- **Loops**: `{#each items}...{#else}...{/each}` with an empty state
 - **Custom components**: `<Alert type="warning">...</Alert>`
 - **Builtin HTML tags**: `<article>`, `<section>`, `<div>`, etc.
+- **Author comments**: `{!-- never rendered --}`
+- **Literal code**: templating never runs inside code blocks or inline code
+- **Validation**: `Prose.validate(text, { data, components })` reports problems
 
-### Planned Features
-
-None at the moment - all core features are implemented!
+The language is closed by design - see
+[What is deliberately missing](#what-is-deliberately-missing).
 
 ## Usage
 
@@ -133,6 +137,44 @@ Rules:
 - Mutating methods like `push`, `pop` or `splice` are rejected and the placeholder is kept as-is
 - Method calls can be chained with property access: `{gallery.images.slice(1)[0]}`
 
+## Fallbacks with ??
+
+Provide a fallback for missing values with the `??` operator:
+
+```markdown
+Hello {nickname ?? name ?? "Guest"}
+
+Price: {price ?? "TBD"}
+```
+
+The semantics match JavaScript: the fallback applies only when the value is
+`null` or `undefined`. Zero, empty strings and `false` are real values and do
+not trigger the fallback:
+
+```markdown
+Count: {count ?? "none"}
+```
+
+With `count: 0` this renders `Count: 0`, not `Count: none`.
+
+Operands can be paths, literals (`"text"`, `0`, `true`, `null`), method calls
+or array literals, and `??` works in text, in loops and in component
+attributes:
+
+```markdown
+<Gallery images="{gallery ?? ['placeholder.jpg']}" />
+```
+
+## Array Literals
+
+Component attributes accept array literals whose elements are paths or
+literals:
+
+```markdown
+<Gallery images="{[images[0], images[2]]}" />
+<Hero sources="{[cover ?? 'default.jpg', banner]}" />
+```
+
 ## Conditional Rendering
 
 Use `{#if}` blocks to conditionally render content based on data:
@@ -502,22 +544,98 @@ Prose(
 
 Note: Since template literals evaluate expressions like `{i + 1}`, you may need to use alternative approaches if you want to perform calculations. In this case, pre-process your data.
 
-**Empty arrays:**
+### Empty State with {#else}
 
-When an array is empty, the loop content is not rendered:
+When the array is empty or missing, the `{#else}` branch renders instead:
 
-```javascript
-Prose(
-  { data: { items: [] } },
-  `
-{#each items as item}
-- {item}
+```markdown
+{#each products as product}
+- {product.title}
+{#else}
+No products yet.
 {/each}
-`,
-)
-// Renders nothing
 ```
 
+Without an `{#else}` branch, an empty array renders nothing. An `{#else}`
+that belongs to an `{#if}` inside the loop is not confused with the loop's
+own `{#else}`.
+
+### Expansion Limit
+
+Loop expansion is capped at 1,000,000 characters. Nested loops over large
+arrays multiply quickly - exceeding the cap throws a clear error instead of
+freezing the page.
+
+## Author Comments
+
+Notes for editors that never render:
+
+```markdown
+{!-- TODO: replace the photo after the shoot --}
+
+# The Article
+```
+
+Comments can span multiple lines. Templating inside a comment is never
+executed.
+
+## Code Is Literal
+
+Templating never runs inside fenced code blocks or inline code - braces,
+loops and conditionals stay exactly as written:
+
+````markdown
+Inline `{name}` stays literal, and so does everything inside fences:
+
+```js
+const x = {count}
+{#if debug}console.log(x){/if}
+```
+````
+
+## Escaping
+
+Use `\{` to render a literal brace in regular text: `\{name}` renders as
+`{name}`.
+
+## Validation
+
+`Prose.validate` reports the problems the renderer tolerates silently -
+ideal for a CMS preview:
+
+```javascript
+const { Prose } = require("boxwood/ui")
+
+const issues = Prose.validate(text, { data, components })
+// [
+//   { line: 3, type: "unknown-component", message: "Unknown component: <Galery>" },
+//   { line: 3, type: "unknown-variable", message: "Unknown variable: imges" },
+//   { line: 4, type: "unclosed-block", message: "Unclosed {#each} opened on line 4" },
+// ]
+```
+
+Both options are optional: without `data` the unknown-variable check is
+skipped, without `components` the unknown-component check only knows the
+builtin components. Issue types: `unknown-variable`, `unknown-component`,
+`unsafe-method`, `malformed-expression`, `malformed-block`,
+`unmatched-block`, `unclosed-block`, `unclosed-comment`,
+`unclosed-code-block`.
+
+## What Is Deliberately Missing
+
+The language is closed by design. When content needs something more, prepare
+it in the data instead of extending the syntax:
+
+- **Filters/formatters** (`{price | currency}`) - format in JS and pass
+  `priceFormatted` in `data`
+- **Arithmetic** (`{price * 1.23}`) - compute in JS, pass the result
+- **Variable definitions** (`{#set ...}`) - shape the data before rendering
+- **Ternaries** (`{a ? b : c}`) - use `{#if}` blocks or `??`
+- **Logical operators in conditions** (`a && b`) - nest `{#if}` blocks
+
+If a template needs one of these, that is a signal the data is missing a
+field, not that the language is missing a feature.
+
 ## Difference from Markdown Component
 
 - **Markdown**: Pure markdown rendering, no variables or custom components

package/ui/prose/index.js

@@ -7,11 +7,17 @@ const Grid = require("../grid")
 const Group = require("../group")
 const Stack = require("../stack")
 
-const { extractHtmlParams, mergeComponents } = require("./utilities/params")
-const { parseMarkdownLines } = require("./utilities/parseBlock")
-const { convertItemsToNodes } = require("./utilities/convertNodes")
+const { extractHtmlParams, mergeComponents } = require("../utilities/params")
+const { parseMarkdownLines } = require("../utilities/parseBlock")
+const { convertItemsToNodes } = require("../utilities/convertNodes")
 const { processConditionals } = require("./utilities/processConditionals")
 const { processLoops } = require("./utilities/processLoops")
+const {
+  maskCodeSegments,
+  restoreCodeSegments,
+} = require("./utilities/protectCode")
+const { stripComments } = require("./utilities/stripComments")
+const { validate } = require("./utilities/validate")
 
 // Safe builtin HTML tags that can be used as custom components in markdown
 // These are always available and don't need to be explicitly passed in params.components
@@ -135,9 +141,16 @@ function Prose(params, children) {
   const allComponents = mergeComponents(BUILTIN_COMPONENTS, customComponents)
   const htmlParams = extractHtmlParams(params)
 
+  // Mask code blocks and inline code first - code is literal content and
+  // no templating pass (comments, loops, conditionals, interpolation) may touch it
+  const { text: maskedChildren, tokens } = maskCodeSegments(children)
+
+  // Remove {!-- ... --} author comments
+  let processedChildren = stripComments(maskedChildren)
+
   // Process {#each}...{/each} loop blocks first
   // Conditionals within loops are processed during loop expansion
-  let processedChildren = processLoops(children, data)
+  processedChildren = processLoops(processedChildren, data)
 
   // Process any remaining {#if}...{/if} conditional blocks (those outside loops)
   processedChildren = processConditionals(processedChildren, data)
@@ -146,7 +159,7 @@ function Prose(params, children) {
   const items = parseMarkdownLines(processedChildren, allComponents, data)
 
   // Convert parsed items into final node tree
-  return convertItemsToNodes(
+  const nodes = convertItemsToNodes(
     items,
     params,
     htmlParams,
@@ -154,6 +167,24 @@ function Prose(params, children) {
     allComponents,
     Prose,
   )
+
+  // Put the original code content back into the final tree
+  return restoreCodeSegments(nodes, tokens)
 }
 
 module.exports = component(Prose)
+
+/**
+ * Validate a Prose template without rendering it
+ * Reports problems the renderer tolerates silently: unknown variables,
+ * unclosed blocks, unsafe methods, unknown components
+ * @param {string} text - The prose template text
+ * @param {Object} options - { data, components } - both optional
+ * @returns {Array<{line: number, type: string, message: string}>}
+ */
+module.exports.validate = (text, options = {}) => {
+  return validate(text, {
+    ...options,
+    components: mergeComponents(BUILTIN_COMPONENTS, options.components),
+  })
+}

package/ui/prose/utilities/processConditionals.js

@@ -1,4 +1,4 @@
-const { resolvePath } = require("./replaceVariables")
+const { resolvePath } = require("../../utilities/replaceVariables")
 
 /**
  * Check if a value is truthy for conditional rendering

package/ui/prose/utilities/processLoops.js

@@ -1,6 +1,14 @@
-const { resolvePath } = require("./replaceVariables")
+const {
+  resolvePath,
+  resolveExpression,
+} = require("../../utilities/replaceVariables")
 const { processConditionals } = require("./processConditionals")
 
+// Upper bound for expanded loop output - {#each} blocks nested over large
+// arrays multiply, and content authors should get a clear error instead of
+// an unresponsive page
+const MAX_EXPANSION_LENGTH = 1000000
+
 /**
  * Process {#each items}...{/each} blocks in text
  * Repeats content for each item in an array
@@ -8,6 +16,7 @@ const { processConditionals } = require("./processConditionals")
  * - {#each items} - basic iteration, access current item with {item}
  * - {#each items as item} - custom item variable name
  * - {#each items as item, index} - access item and index
+ * - {#each items}...{#else}...{/each} - fallback content for empty arrays
  * @param {string} text - Text containing loop blocks
  * @param {Object} data - Data object with variable values
  * @returns {string} - Text with loops expanded
@@ -17,9 +26,9 @@ function processLoops(text, data) {
     return text
   }
 
-  // If no data, remove all {#each}...{/each} blocks
+  // Without data every array is missing, so loops render their {#else} branch
   if (!data || typeof data !== "object") {
-    return text.replace(/\{#each\s+[^}]+\}[\s\S]*?\{\/each\}/g, "")
+    data = {}
   }
 
   let result = text
@@ -74,6 +83,9 @@ function processLoops(text, data) {
     const blockContent = result.substring(contentStart, endEachStart)
     const endEachEnd = endEachStart + 7 // length of "{/each}"
 
+    // Split the block into the item branch and an optional {#else} branch
+    const { itemBranch, elseBranch } = splitLoopBranches(blockContent)
+
     // Resolve the array
     const array = resolvePath(data, arrayPath)
 
@@ -92,16 +104,30 @@ function processLoops(text, data) {
           loopData[indexName] = idx
         }
 
-        // First, process any conditionals within the loop content using the loop data
-        let itemContent = processConditionals(blockContent, loopData)
+        // First, expand nested loops recursively so they can reference
+        // the current item (e.g. {#each group.members} inside {#each groups as group})
+        let itemContent = processLoops(itemBranch, loopData)
+
+        // Then process any conditionals within the loop content using the loop data
+        itemContent = processConditionals(itemContent, loopData)
 
         // Then replace variables in the block content
         itemContent = replaceLoopVariables(itemContent, loopData)
 
         expandedContent += itemContent
+
+        if (expandedContent.length > MAX_EXPANSION_LENGTH) {
+          throw new Error(
+            `Prose: {#each ${arrayPath}} expanded past ${MAX_EXPANSION_LENGTH} characters - reduce the array size or nesting`,
+          )
+        }
       }
+    } else {
+      // Empty or missing array - render the {#else} branch if present
+      // It is inserted as-is: nested loops are handled by the next iterations
+      // of this while loop, conditionals and variables by the later passes
+      expandedContent = elseBranch
     }
-    // If array is empty or not an array, remove the block
 
     // Replace the entire {#each}...{/each} block
     result =
@@ -113,6 +139,40 @@ function processLoops(text, data) {
   return result
 }
 
+/**
+ * Split loop block content into the item branch and an optional {#else} branch
+ * Only a top-level {#else} splits the block - an {#else} that belongs to a
+ * nested {#each} or {#if} inside the block is ignored
+ * @param {string} blockContent - Content between {#each} and {/each}
+ * @returns {{itemBranch: string, elseBranch: string}} - The two branches
+ */
+function splitLoopBranches(blockContent) {
+  let depth = 0
+  let i = 0
+
+  while (i < blockContent.length) {
+    if (
+      blockContent.substring(i, i + 6) === "{#each" ||
+      blockContent.substring(i, i + 4) === "{#if"
+    ) {
+      depth++
+    } else if (
+      blockContent.substring(i, i + 7) === "{/each}" ||
+      blockContent.substring(i, i + 5) === "{/if}"
+    ) {
+      depth--
+    } else if (depth === 0 && blockContent.substring(i, i + 7) === "{#else}") {
+      return {
+        itemBranch: blockContent.substring(0, i),
+        elseBranch: blockContent.substring(i + 7),
+      }
+    }
+    i++
+  }
+
+  return { itemBranch: blockContent, elseBranch: "" }
+}
+
 /**
  * Replace variables in text with values from loop data
  * @param {string} text - Text containing variable placeholders
@@ -125,7 +185,7 @@ function replaceLoopVariables(text, loopData) {
   }
 
   let result = text
-  const regex = /\{([a-zA-Z0-9_.[\]]+)\}/g
+  const regex = /\{([^{}]+)\}/g
   let match
 
   // Collect all variable matches first to avoid issues with overlapping replacements
@@ -154,8 +214,9 @@ function replaceLoopVariables(text, loopData) {
       continue
     }
 
-    // Resolve the variable value
-    const value = resolvePath(loopData, path)
+    // Resolve the expression (supports paths, safe method calls,
+    // array literals and ?? fallbacks)
+    const value = resolveExpression(loopData, path)
 
     if (value !== undefined && value !== null) {
       result =

package/ui/prose/utilities/protectCode.js

@@ -0,0 +1,111 @@
+// Code is literal content - templating (loops, conditionals, interpolation)
+// must never run inside fenced code blocks or inline code spans.
+// maskCodeSegments swaps code content for opaque tokens before the templating
+// passes run, and restoreCodeSegments swaps the original content back into
+// the final node tree.
+
+// Global counter so tokens never collide across nested Prose calls
+// (a component's children are rendered by a recursive Prose invocation)
+let tokenId = 0
+
+// Tokens are wrapped in NUL characters, which cannot appear in typed content
+const TOKEN_PREFIX = "\u0000code:"
+const TOKEN_SUFFIX = "\u0000"
+const TOKEN_REGEXP = /\u0000code:\d+\u0000/g
+
+// Backslash-escaped backticks (\`) are literal text, not code delimiters
+const INLINE_CODE_REGEXP = /(?<!\\)(`+)([^`]+)\1/g
+
+/**
+ * Replace the content of fenced code blocks and inline code spans with
+ * opaque tokens so templating passes leave it untouched
+ * Fence delimiters and backticks stay in place so markdown parsing still
+ * recognizes the code structure
+ * @param {string} text - The raw prose text
+ * @returns {{text: string, tokens: Map<string, string>}} - Masked text and token map
+ */
+function maskCodeSegments(text) {
+  const tokens = new Map()
+
+  if (!text || typeof text !== "string") {
+    return { text, tokens }
+  }
+
+  const mask = (content) => {
+    const token = `${TOKEN_PREFIX}${tokenId++}${TOKEN_SUFFIX}`
+    tokens.set(token, content)
+    return token
+  }
+
+  const lines = text.split("\n")
+  const result = []
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i]
+
+    if (line.trim().startsWith("```")) {
+      // Fenced code block - mask everything until the closing fence
+      result.push(line)
+      i++
+      const codeLines = []
+      while (i < lines.length && !lines[i].trim().startsWith("```")) {
+        codeLines.push(lines[i])
+        i++
+      }
+      if (codeLines.length > 0) {
+        result.push(mask(codeLines.join("\n")))
+      }
+      if (i < lines.length) {
+        result.push(lines[i]) // closing fence
+        i++
+      }
+      continue
+    }
+
+    // Inline code spans - mask the content between backticks
+    result.push(
+      line.replace(
+        INLINE_CODE_REGEXP,
+        (match, ticks, content) => `${ticks}${mask(content)}${ticks}`,
+      ),
+    )
+    i++
+  }
+
+  return { text: result.join("\n"), tokens }
+}
+
+/**
+ * Restore masked code content in the final node tree
+ * Walks strings, arrays and node objects (children and attributes)
+ * @param {*} node - A node tree, array, string or any other value
+ * @param {Map<string, string>} tokens - Token map from maskCodeSegments
+ * @returns {*} - The tree with original code content restored
+ */
+function restoreCodeSegments(node, tokens) {
+  if (!tokens || tokens.size === 0) {
+    return node
+  }
+
+  if (typeof node === "string") {
+    return node.replace(TOKEN_REGEXP, (token) =>
+      tokens.has(token) ? tokens.get(token) : token,
+    )
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((child) => restoreCodeSegments(child, tokens))
+  }
+
+  if (node && typeof node === "object") {
+    for (const key of Object.keys(node)) {
+      node[key] = restoreCodeSegments(node[key], tokens)
+    }
+    return node
+  }
+
+  return node
+}
+
+module.exports = { maskCodeSegments, restoreCodeSegments }

package/ui/prose/utilities/stripComments.js

@@ -0,0 +1,19 @@
+// Author comments: {!-- note to self --} never renders
+// Comments can span multiple lines and are removed before any other
+// templating pass, so their content is never interpolated or executed
+const COMMENT_REGEXP = /\{!--[\s\S]*?--\}/g
+
+/**
+ * Remove {!-- ... --} author comments from text
+ * An unclosed comment is left as-is (the validator reports it)
+ * @param {string} text - Text possibly containing comments
+ * @returns {string} - Text without comments
+ */
+function stripComments(text) {
+  if (!text || typeof text !== "string") {
+    return text
+  }
+  return text.replace(COMMENT_REGEXP, "")
+}
+
+module.exports = { stripComments, COMMENT_REGEXP }