boxwood 2.18.1 → 2.19.0

package/README.md

@@ -194,6 +194,32 @@ Content-Security-Policy: script-src 'nonce-rAnd0m123' 'strict-dynamic';
 
 ## Features
 
+### Prose - markdown with templating
+
+Render markdown content with safe interpolation, conditionals, loops,
+tables, heading anchors and custom components:
+
+```js
+const { Prose } = require("boxwood/ui")
+
+Prose({ data, components: { Gallery } }, `
+# {title}
+
+Published {date.toLocaleDateString('en-US')}
+
+{#each posts.slice(0, limit) as post, i}
+Part {i + 1}: **{post.title ?? 'Untitled'}**
+{/each}
+
+<Gallery images="{images.slice(0, 3)}" />
+`)
+```
+
+Templates never execute arbitrary code - expressions resolve against `data`
+with a whitelist of non-mutating methods, and `Prose.validate` reports
+unknown variables, unsafe methods and malformed blocks with line numbers.
+See the full [Prose syntax reference](docs/prose.md).
+
 ### Components with CSS
 
 ```js

package/index.js

@@ -79,6 +79,10 @@ function compile(path) {
         head: [],
         body: [],
       }
+      // JSON-LD scripts are collected, deduplicated by content and moved
+      // to head - a component rendering structured data can be used many
+      // times without emitting duplicate entries
+      const schemas = { keys: new Set(), nodes: [] }
       const walk = (node) => {
         if (!node) {
           return
@@ -98,14 +102,19 @@ function compile(path) {
         }
         if (node.name === "script") {
           const attributes = node.attributes || {}
-          if (
-            attributes.src ||
-            ["application/json", "application/ld+json"].includes(
-              attributes.type,
-            )
-          ) {
+          if (attributes.src || attributes.type === "application/json") {
             node.ignore = false
             return
+          } else if (attributes.type === "application/ld+json") {
+            const key = render(node.children, false)
+            if (schemas.keys.has(key)) {
+              // Duplicate structured data - drop it
+              node.ignore = true
+            } else {
+              schemas.keys.add(key)
+              schemas.nodes.push(node)
+            }
+            return
           } else {
             const script = node.children
             if (script) {
@@ -150,6 +159,19 @@ function compile(path) {
           }
           nodes.head.children.push(scriptNode)
         }
+        // Move JSON-LD scripts into head, keeping their attributes
+        // Without a head node the first occurrence stays in place
+        for (const scriptNode of schemas.nodes) {
+          scriptNode.ignore = true
+          const copy = {
+            name: "script",
+            children: scriptNode.children,
+          }
+          if (scriptNode.attributes) {
+            copy.attributes = scriptNode.attributes
+          }
+          nodes.head.children.push(copy)
+        }
       }
       if (nodes.body) {
         if (scripts.body.length > 0) {

package/package.json

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

package/ui/markdown/index.js

@@ -18,6 +18,7 @@ const BASIC_HTML_COMPONENTS = {
   code: nodes.Code,
   strong: nodes.Strong,
   em: nodes.Em,
+  del: nodes.Del,
   p: nodes.P,
   ul: nodes.Ul,
   ol: nodes.Ol,
@@ -25,6 +26,12 @@ const BASIC_HTML_COMPONENTS = {
   pre: nodes.Pre,
   blockquote: nodes.Blockquote,
   hr: nodes.Hr,
+  table: nodes.Table,
+  thead: nodes.Thead,
+  tbody: nodes.Tbody,
+  tr: nodes.Tr,
+  th: nodes.Th,
+  td: nodes.Td,
 }
 
 function Markdown(params, children) {

package/ui/prose/index.js

@@ -145,6 +145,13 @@ function Prose(params, children) {
   // no templating pass (comments, loops, conditionals, interpolation) may touch it
   const { text: maskedChildren, tokens } = maskCodeSegments(children)
 
+  // Inherit tokens from the outer Prose call (nested component content is
+  // masked by the outer call) so heading anchors can restore code text
+  const outerTokens = params && params.__codeTokens
+  const codeTokens = outerTokens
+    ? new Map([...outerTokens, ...tokens])
+    : tokens
+
   // Remove {!-- ... --} author comments
   let processedChildren = stripComments(maskedChildren)
 
@@ -159,9 +166,12 @@ function Prose(params, children) {
   const items = parseMarkdownLines(processedChildren, allComponents, data)
 
   // Convert parsed items into final node tree
+  // __codeTokens travels with params so recursive Prose calls (multi-line
+  // component children) can also restore code text in heading anchors
+  // __headingAnchors opts into anchor ids - a Prose feature, not plain Markdown
   const nodes = convertItemsToNodes(
     items,
-    params,
+    { ...params, __codeTokens: codeTokens, __headingAnchors: true },
     htmlParams,
     data,
     allComponents,

package/ui/prose/utilities/processConditionals.js

@@ -1,4 +1,8 @@
-const { resolvePath } = require("../../utilities/replaceVariables")
+const {
+  resolveExpression,
+  splitLogicalOr,
+  splitLogicalAnd,
+} = require("../../utilities/replaceVariables")
 
 /**
  * Check if a value is truthy for conditional rendering
@@ -33,12 +37,28 @@ function isTruthy(value) {
 /**
  * Evaluate a condition expression
  * Supports: variable, variable > value, variable < value, etc.
- * Also supports negation with ! prefix
+ * Also supports negation with ! prefix and logical || and && operators
+ * with JS precedence (&& binds tighter than ||),
+ * e.g. "articles.length == 0 || user.role == 'admin'"
+ * Both comparison sides and bare conditions accept full expressions:
+ * ?? fallbacks, arithmetic ("items.length - 1 > 0") and array literals
  * @param {string} condition - The condition to evaluate
  * @param {Object} data - Data object with variable values
  * @returns {boolean} - Whether the condition is true
  */
 function evaluateCondition(condition, data) {
+  // Logical operators, || first so && binds tighter (JS precedence)
+  // Each operand is evaluated recursively, including its own ! negation
+  const orOperands = splitLogicalOr(condition)
+  if (orOperands.length > 1) {
+    return orOperands.some((operand) => evaluateCondition(operand, data))
+  }
+
+  const andOperands = splitLogicalAnd(condition)
+  if (andOperands.length > 1) {
+    return andOperands.every((operand) => evaluateCondition(operand, data))
+  }
+
   // Check for negation operator at the start
   let negated = false
   let conditionToEvaluate = condition.trim()
@@ -50,16 +70,16 @@ function evaluateCondition(condition, data) {
 
   let result
 
-  // Check for comparison operators
+  // Check for comparison operators - longest first so === wins over ==
   const comparisonMatch = conditionToEvaluate.match(
-    /^(.+?)\s*(>=|<=|>|<|==|!=)\s*(.+)$/,
+    /^(.+?)\s*(===|!==|>=|<=|>|<|==|!=)\s*(.+)$/,
   )
 
   if (comparisonMatch) {
     const [, leftExpr, operator, rightExpr] = comparisonMatch
 
-    // Resolve left side (variable or path)
-    const leftValue = resolvePath(data, leftExpr.trim())
+    // Resolve left side - any expression, e.g. "items.length - 1"
+    const leftValue = resolveExpression(data, leftExpr.trim())
 
     // Resolve right side (could be a number, string, or variable)
     let rightValue = rightExpr.trim()
@@ -81,9 +101,9 @@ function evaluateCondition(condition, data) {
     ) {
       rightValue = rightValue.slice(1, -1)
     }
-    // Otherwise treat as a variable path
+    // Otherwise treat as an expression
     else {
-      rightValue = resolvePath(data, rightValue)
+      rightValue = resolveExpression(data, rightValue)
     }
 
     // Perform comparison
@@ -106,12 +126,19 @@ function evaluateCondition(condition, data) {
       case "!=":
         result = leftValue != rightValue
         break
+      case "===":
+        result = leftValue === rightValue
+        break
+      case "!==":
+        result = leftValue !== rightValue
+        break
       default:
         result = false
     }
   } else {
     // No comparison operator, just evaluate truthiness
-    const value = resolvePath(data, conditionToEvaluate)
+    // Expressions are supported, e.g. "title ?? subtitle"
+    const value = resolveExpression(data, conditionToEvaluate)
     result = isTruthy(value)
   }
 

package/ui/prose/utilities/processLoops.js

@@ -1,7 +1,4 @@
-const {
-  resolvePath,
-  resolveExpression,
-} = require("../../utilities/replaceVariables")
+const { resolveExpression } = require("../../utilities/replaceVariables")
 const { processConditionals } = require("./processConditionals")
 
 // Upper bound for expanded loop output - {#each} blocks nested over large
@@ -17,6 +14,8 @@ const MAX_EXPANSION_LENGTH = 1000000
  * - {#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
+ * - {#each posts.slice(0, 3) as post} - any expression producing an array,
+ *   including array literals, spread and ?? fallbacks
  * @param {string} text - Text containing loop blocks
  * @param {Object} data - Data object with variable values
  * @returns {string} - Text with loops expanded
@@ -41,8 +40,9 @@ function processLoops(text, data) {
 
     // Find the next {#each} block
     // Matches: {#each items}, {#each items as item}, {#each items as item, index}
+    // The array part is any expression, e.g. {#each posts.slice(0, 3) as post}
     const eachMatch = result.match(
-      /\{#each\s+([a-zA-Z0-9_.[\]]+)(?:\s+as\s+([a-zA-Z0-9_]+)(?:\s*,\s*([a-zA-Z0-9_]+))?)?\}/,
+      /\{#each\s+(.+?)(?:\s+as\s+([a-zA-Z0-9_]+)(?:\s*,\s*([a-zA-Z0-9_]+))?)?\}/,
     )
     if (!eachMatch) break
 
@@ -86,8 +86,9 @@ function processLoops(text, data) {
     // 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)
+    // Resolve the array - expressions are supported, e.g. "posts.slice(0, 3)",
+    // "[...featured, ...latest]" or "posts ?? []"
+    const array = resolveExpression(data, arrayPath)
 
     // Generate repeated content
     let expandedContent = ""

package/ui/prose/utilities/validate.js

@@ -1,18 +1,25 @@
 const {
   SAFE_METHODS,
+  FORBIDDEN_KEYS,
+  MAX_EXPRESSION_LENGTH,
   parseArgument,
   parsePathSegments,
   splitNullishCoalescing,
+  splitLogicalOr,
+  splitLogicalAnd,
+  splitArithmetic,
   isArrayLiteral,
   splitArrayElements,
 } = require("../../utilities/replaceVariables")
+const { scanUnquotedGt } = require("../../utilities/parseBlock")
 
 // Matches the {#each} header accepted by processLoops
+// The array part is any expression, e.g. "posts.slice(0, 3)"
 const EACH_HEADER_REGEXP =
-  /^#each\s+([a-zA-Z0-9_.[\]]+)(?:\s+as\s+([a-zA-Z0-9_]+)(?:\s*,\s*([a-zA-Z0-9_]+))?)?$/
+  /^#each\s+(.+?)(?:\s+as\s+([a-zA-Z0-9_]+)(?:\s*,\s*([a-zA-Z0-9_]+))?)?$/
 
 // Matches the comparison conditions accepted by processConditionals
-const CONDITION_REGEXP = /^(.+?)\s*(>=|<=|>|<|==|!=)\s*(.+)$/
+const CONDITION_REGEXP = /^(.+?)\s*(===|!==|>=|<=|>|<|==|!=)\s*(.+)$/
 
 const INLINE_CODE_REGEXP = /(`+)([^`]+)\1/g
 const BRACE_REGEXP = /\{([^{}]*)\}/g
@@ -60,13 +67,28 @@ function validate(text, options = {}) {
       return
     }
     for (const segment of segments) {
-      if (segment.type === "method" && !SAFE_METHODS.has(segment.name)) {
+      if (FORBIDDEN_KEYS.has(segment.name)) {
         report(
           line,
-          "unsafe-method",
-          `Method not allowed: ${segment.name}() - allowed methods: ${[...SAFE_METHODS].join(", ")}`,
+          "forbidden-property",
+          `Property not allowed: ${segment.name} - prototype access is blocked`,
         )
       }
+      if (segment.type === "method") {
+        if (!SAFE_METHODS.has(segment.name)) {
+          report(
+            line,
+            "unsafe-method",
+            `Method not allowed: ${segment.name}() - allowed methods: ${[...SAFE_METHODS].join(", ")}`,
+          )
+        }
+        // Path arguments are full expressions, e.g. "slice(0, n - 1)"
+        for (const arg of segment.args) {
+          if (arg.type === "path") {
+            validateExpression(arg.path, line)
+          }
+        }
+      }
     }
     const root = segments[0]
     if (
@@ -85,7 +107,80 @@ function validate(text, options = {}) {
     const trimmed = expression.trim()
     if (!trimmed) return
 
-    for (const operand of splitNullishCoalescing(trimmed)) {
+    // Oversized expressions are rejected by the resolver too - report and
+    // stop before the recursive scanners run on a pathological input
+    if (expression.length > MAX_EXPRESSION_LENGTH) {
+      report(
+        line,
+        "malformed-expression",
+        `Expression too long (over ${MAX_EXPRESSION_LENGTH} characters)`,
+      )
+      return
+    }
+
+    const nullishOperands = splitNullishCoalescing(trimmed)
+    const orOperands = splitLogicalOr(trimmed)
+    const andOperands = splitLogicalAnd(trimmed)
+
+    // Mixing ?? with || or && without parentheses is invalid, same as in JS
+    if (
+      nullishOperands.length > 1 &&
+      (orOperands.length > 1 || andOperands.length > 1)
+    ) {
+      report(
+        line,
+        "malformed-expression",
+        `Cannot mix ?? with || or && in one expression: {${trimmed}}`,
+      )
+      return
+    }
+
+    // || first so && binds tighter (JS precedence) - operands of || may
+    // contain && and recurse through validateExpression
+    const operands =
+      orOperands.length > 1
+        ? orOperands
+        : andOperands.length > 1
+          ? andOperands
+          : nullishOperands
+
+    if (operands.length > 1) {
+      for (const operand of operands) {
+        const raw = operand.trim()
+        if (!raw) {
+          report(
+            line,
+            "malformed-expression",
+            `Malformed expression: {${trimmed}}`,
+          )
+          continue
+        }
+        validateExpression(raw, line)
+      }
+      return
+    }
+
+    // Arithmetic operands validate recursively, e.g. {i + 1}
+    const sums = splitArithmetic(trimmed, ["+", "-"])
+    const arithmetic =
+      sums.operators.length > 0 ? sums : splitArithmetic(trimmed, ["*", "/"])
+    if (arithmetic.operators.length > 0) {
+      for (const operand of arithmetic.operands) {
+        const raw = operand.trim()
+        if (!raw) {
+          report(
+            line,
+            "malformed-expression",
+            `Malformed expression: {${trimmed}}`,
+          )
+          continue
+        }
+        validateExpression(raw, line)
+      }
+      return
+    }
+
+    for (const operand of operands) {
       const raw = operand.trim()
       if (!raw) {
         report(
@@ -100,7 +195,12 @@ function validate(text, options = {}) {
       }
       if (isArrayLiteral(raw)) {
         for (const element of splitArrayElements(raw.substring(1, raw.length - 1))) {
-          validateExpression(element, line)
+          // Spread elements validate the spread expression itself
+          const rawElement = element.trim()
+          validateExpression(
+            rawElement.startsWith("...") ? rawElement.substring(3) : rawElement,
+            line,
+          )
         }
         continue
       }
@@ -109,6 +209,25 @@ function validate(text, options = {}) {
   }
 
   const validateCondition = (condition, line) => {
+    // Logical operators - validate each operand on its own
+    const orOperands = splitLogicalOr(condition)
+    const operands =
+      orOperands.length > 1 ? orOperands : splitLogicalAnd(condition)
+    if (operands.length > 1) {
+      for (const operand of operands) {
+        if (!operand.trim()) {
+          report(
+            line,
+            "malformed-expression",
+            `Malformed condition: {#if ${condition.trim()}}`,
+          )
+          continue
+        }
+        validateCondition(operand, line)
+      }
+      return
+    }
+
     let expr = condition.trim()
     if (expr.startsWith("!")) {
       expr = expr.substring(1).trim()
@@ -157,7 +276,12 @@ function validate(text, options = {}) {
           "{#elseif} without a matching {#if}",
         )
       }
-      validateCondition(content.substring("#elseif".length), line)
+      const condition = content.substring("#elseif".length)
+      if (!condition.trim()) {
+        report(line, "malformed-block", "Empty condition: {#elseif}")
+        return
+      }
+      validateCondition(condition, line)
       return
     }
 
@@ -173,8 +297,15 @@ function validate(text, options = {}) {
     }
 
     if (content.startsWith("#if")) {
+      // Push before validating so a matching {/if} does not report an error
       stack.push({ type: "if", line })
-      validateCondition(content.substring("#if".length), line)
+      const condition = content.substring("#if".length)
+      if (!condition.trim()) {
+        // The renderer leaves {#if } blocks as literal text
+        report(line, "malformed-block", "Empty condition: {#if}")
+        return
+      }
+      validateCondition(condition, line)
       return
     }
 
@@ -252,6 +383,28 @@ function validate(text, options = {}) {
         )
       }
     }
+    // Multi-line component tags - join the attribute lines so expressions
+    // spanning lines (e.g. multi-line array literals) are validated as one
+    // The tag ends at the first > outside quoted attribute values
+    const gtState = { quote: null }
+    if (componentMatch && !scanUnquotedGt(line, gtState)) {
+      const parts = [line]
+      let j = i + 1
+      // A blank line ends the markdown block - stop joining there
+      while (
+        j < lines.length &&
+        lines[j].trim() &&
+        !scanUnquotedGt(lines[j], gtState)
+      ) {
+        parts.push(lines[j])
+        j++
+      }
+      if (j < lines.length && lines[j].trim()) {
+        parts.push(lines[j])
+        line = parts.join("\n")
+        i = j
+      }
+    }
     // Braced tags and expressions - on component lines this also covers
     // attribute expressions, both whole-value ({expr}) and partial (/p/{id})
     let braceMatch
@@ -261,7 +414,16 @@ function validate(text, options = {}) {
         continue
       }
       const content = braceMatch[1].trim()
-      if (!content) continue
+      if (!content) {
+        // A forgotten value - the renderer keeps {} as literal text,
+        // and an attribute value "{}" is passed through as a string
+        report(
+          lineNumber,
+          "malformed-expression",
+          "Empty expression: {} - escape with \\{ for literal braces",
+        )
+        continue
+      }
 
       if (content.startsWith("#") || content.startsWith("/")) {
         handleControlTag(content, lineNumber)

package/ui/utilities/convertNodes.js

@@ -1,6 +1,22 @@
+const { Input } = require("../..")
 const { resolveAttributes } = require("./parseCustomTag")
 const { replaceVariables } = require("./replaceVariables")
 const { format } = require("./format")
+const { slugify } = require("./slugify")
+const { restoreCodeSegments } = require("../prose/utilities/protectCode")
+
+const HEADING_TYPES = new Set(["h1", "h2", "h3", "h4", "h5", "h6"])
+
+/**
+ * Strip inline markdown syntax so anchor slugs come from the visible text,
+ * e.g. "## [Link](https://x.com)" -> slug "link"
+ */
+function stripInlineMarkdown(text) {
+  return text
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[`*_~]/g, "")
+}
 
 /**
  * Recursively parses nested lists with proper indentation handling
@@ -36,6 +52,16 @@ function parseList(
     // Process current list item
     const processedContent = replaceVariables(item.content, data)
     const content = [format(processedContent, allComponents)]
+
+    // Task list items get a disabled checkbox: - [x] done
+    if (item.task) {
+      const checkbox = { type: "checkbox", disabled: true }
+      if (item.checked) {
+        checkbox.checked = true
+      }
+      content.unshift(Input(checkbox), " ")
+    }
+
     currentIndex++
 
     // Check for nested lists
@@ -112,6 +138,42 @@ function processBlockquotes(
   return { node: blockquote, nextIndex: i }
 }
 
+/**
+ * Converts a table item into table/thead/tbody nodes
+ * Column alignment renders as an inline text-align style
+ */
+function processTable(item, htmlParams, data, allComponents) {
+  const cellParams = (index) => {
+    const align = item.aligns[index]
+    return align ? { ...htmlParams, style: { textAlign: align } } : htmlParams
+  }
+  const cellContent = (cell) =>
+    format(replaceVariables(cell, data), allComponents)
+
+  const head = allComponents.thead(
+    htmlParams,
+    allComponents.tr(
+      htmlParams,
+      item.header.map((cell, index) =>
+        allComponents.th(cellParams(index), cellContent(cell)),
+      ),
+    ),
+  )
+  const body = allComponents.tbody(
+    htmlParams,
+    item.rows.map((row) =>
+      allComponents.tr(
+        htmlParams,
+        row.map((cell, index) =>
+          allComponents.td(cellParams(index), cellContent(cell)),
+        ),
+      ),
+    ),
+  )
+
+  return allComponents.table(htmlParams, [head, body])
+}
+
 /**
  * Converts parsed items into final node tree
  */
@@ -124,6 +186,14 @@ function convertItemsToNodes(
   markdownRenderer,
 ) {
   const result = []
+  // Anchor slugs used so far - repeated headings get -2, -3 suffixes
+  const slugs = new Map()
+  // Masked-code tokens from Prose - restored in anchor slug sources so
+  // "## Title with `code`" slugs from the real code text, not the mask
+  const codeTokens = params && params.__codeTokens
+  // Heading anchors are opt-in - Prose enables them, plain Markdown stays a
+  // faithful GFM renderer with untouched headings
+  const headingAnchors = params && params.__headingAnchors
   let i = 0
 
   while (i < items.length) {
@@ -158,6 +228,9 @@ function convertItemsToNodes(
     } else if (item.type === "hr") {
       result.push(allComponents.hr(htmlParams))
       i++
+    } else if (item.type === "table") {
+      result.push(processTable(item, htmlParams, data, allComponents))
+      i++
     } else if (item.type === "pre") {
       // Code blocks - wrap in <pre><code>
       const codeParams = item.language
@@ -175,8 +248,32 @@ function convertItemsToNodes(
       const { type, content } = item
       const Component = allComponents[type] || allComponents.p
       const processedContent = replaceVariables(content, data)
+      let elementParams = htmlParams
+
+      // Headings get an anchor id derived from their text,
+      // e.g. "## Mój tytuł" -> <h2 id="moj-tytul">
+      if (headingAnchors && HEADING_TYPES.has(type) && !htmlParams.id) {
+        // Tokens can chain across nested Prose calls (an inner call masks
+        // the outer call's token again) - restore until stable
+        let slugSource = processedContent
+        if (codeTokens) {
+          let previous
+          do {
+            previous = slugSource
+            slugSource = restoreCodeSegments(slugSource, codeTokens)
+          } while (slugSource !== previous)
+        }
+        const slug = slugify(stripInlineMarkdown(slugSource))
+        if (slug) {
+          const count = slugs.get(slug) || 0
+          slugs.set(slug, count + 1)
+          const id = count === 0 ? slug : `${slug}-${count + 1}`
+          elementParams = { ...htmlParams, id }
+        }
+      }
+
       result.push(
-        Component(htmlParams, format(processedContent, allComponents)),
+        Component(elementParams, format(processedContent, allComponents)),
       )
       i++
     }
@@ -189,5 +286,6 @@ module.exports = {
   parseList,
   processCustomComponentItem,
   processBlockquotes,
+  processTable,
   convertItemsToNodes,
 }