boxwood 2.16.0 → 2.17.0

package/package.json

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

package/ui/prose/README.md

@@ -19,6 +19,7 @@ All standard markdown features:
 ### Templating Features
 
 - **Variable replacement**: `{variable}`, `{user.name}`, `{images[0].src}`
+- **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
 - **Custom components**: `<Alert type="warning">...</Alert>`
@@ -99,6 +100,39 @@ Prose(
 )
 ```
 
+## Method Calls
+
+Variable paths can include calls to safe, non-mutating methods. This is especially useful for passing a part of an array to a component:
+
+```javascript
+Prose(
+  {
+    data: { images: ["a.jpg", "b.jpg", "c.jpg", "d.jpg"] },
+    components: { Gallery },
+  },
+  `
+<Gallery images="{images.slice(0, 2)}" />
+
+<Gallery images="{images.slice(2)}" />
+`,
+)
+```
+
+Method calls also work in text content:
+
+```markdown
+**Tags:** {tags.join(', ')}
+
+# {title.toUpperCase()}
+```
+
+Rules:
+
+- Only whitelisted, non-mutating methods are allowed: `slice`, `at`, `concat`, `includes`, `indexOf`, `lastIndexOf`, `join`, `toUpperCase`, `toLowerCase`, `trim`, `charAt`, `substring`, `split`, `padStart`, `padEnd`, `repeat`, `replace`, `replaceAll`, `startsWith`, `endsWith`, `toFixed`, `toString`
+- Arguments must be literals: numbers, quoted strings, `true`, `false` or `null` (variables are not supported as arguments)
+- 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]}`
+
 ## Conditional Rendering
 
 Use `{#if}` blocks to conditionally render content based on data:

package/ui/prose/utilities/replaceVariables.js

@@ -1,7 +1,155 @@
+// Non-mutating methods that can be called inside a path, e.g. {images.slice(0, 2)}
+// Only methods without side effects are allowed - arbitrary code is never evaluated
+const SAFE_METHODS = new Set([
+  // Arrays and strings
+  "slice",
+  "at",
+  "concat",
+  "includes",
+  "indexOf",
+  "lastIndexOf",
+  // Arrays
+  "join",
+  // Strings
+  "toUpperCase",
+  "toLowerCase",
+  "trim",
+  "charAt",
+  "substring",
+  "split",
+  "padStart",
+  "padEnd",
+  "repeat",
+  "replace",
+  "replaceAll",
+  "startsWith",
+  "endsWith",
+  // Numbers
+  "toFixed",
+  // Anything
+  "toString",
+])
+
 /**
- * Resolve a path like "images[0].src" or "user.name" from a data object
+ * Parse a single method argument literal
+ * Supports numbers, quoted strings, booleans and null
+ * @param {string} raw - The raw argument text
+ * @returns {{value: *}|null} - Wrapped value or null if not a valid literal
+ */
+function parseArgument(raw) {
+  const arg = raw.trim()
+  if (/^-?\d+(\.\d+)?$/.test(arg)) {
+    return { value: Number(arg) }
+  }
+  if (
+    arg.length >= 2 &&
+    ((arg.startsWith('"') && arg.endsWith('"')) ||
+      (arg.startsWith("'") && arg.endsWith("'")))
+  ) {
+    return { value: arg.substring(1, arg.length - 1) }
+  }
+  if (arg === "true") return { value: true }
+  if (arg === "false") return { value: false }
+  if (arg === "null") return { value: null }
+  return null
+}
+
+/**
+ * Parse a path into segments of property accesses and method calls
+ * e.g. "images.slice(0, 2)" -> [{type: "property", name: "images"}, {type: "method", name: "slice", args: [0, 2]}]
+ * @param {string} path - The path to parse
+ * @returns {Array|null} - Parsed segments or null if the path is malformed
+ */
+function parsePathSegments(path) {
+  const segments = []
+  let i = 0
+
+  while (i < path.length) {
+    const char = path[i]
+
+    if (char === ".") {
+      i++
+      continue
+    }
+
+    if (char === "[") {
+      const close = path.indexOf("]", i)
+      if (close === -1) return null
+      const index = path.substring(i + 1, close).trim()
+      if (!/^\d+$/.test(index)) return null
+      segments.push({ type: "property", name: index })
+      i = close + 1
+      continue
+    }
+
+    // Read an identifier up to the next separator
+    const start = i
+    while (i < path.length && !/[.\[(]/.test(path[i])) {
+      i++
+    }
+    const name = path.substring(start, i).trim()
+    if (!name) return null
+
+    if (path[i] === "(") {
+      // Method call - collect literal arguments, respecting quoted strings
+      i++
+      const rawArgs = []
+      let current = ""
+      let quote = null
+      let closed = false
+      while (i < path.length) {
+        const c = path[i]
+        if (quote) {
+          current += c
+          if (c === quote) quote = null
+          i++
+          continue
+        }
+        if (c === '"' || c === "'") {
+          quote = c
+          current += c
+          i++
+          continue
+        }
+        if (c === ",") {
+          rawArgs.push(current)
+          current = ""
+          i++
+          continue
+        }
+        if (c === ")") {
+          closed = true
+          i++
+          break
+        }
+        current += c
+        i++
+      }
+      if (!closed) return null
+      if (current.trim() || rawArgs.length > 0) {
+        rawArgs.push(current)
+      }
+
+      const args = []
+      for (const raw of rawArgs) {
+        const parsed = parseArgument(raw)
+        if (!parsed) return null
+        args.push(parsed.value)
+      }
+      segments.push({ type: "method", name, args })
+    } else {
+      segments.push({ type: "property", name })
+    }
+  }
+
+  return segments
+}
+
+/**
+ * Resolve a path like "images[0].src", "user.name" or "images.slice(0, 2)" from a data object
+ * Method calls are restricted to a whitelist of non-mutating methods with literal arguments
  * @param {Object} data - The data object to resolve the path from
- * @param {string} path - The path to resolve (e.g., "images[0].src", "user.name")
+ * @param {string} path - The path to resolve (e.g., "images[0].src", "images.slice(0, 2)")
  * @returns {*} - The resolved value or undefined
  */
 function resolvePath(data, path) {
@@ -11,23 +159,35 @@ function resolvePath(data, path) {
   }
 
   // Handle simple variable names (backwards compatibility)
-  if (!/[.\[]/.test(path)) {
+  if (!/[.\[(]/.test(path)) {
     return data[path]
   }
 
-  // Split the path into parts, handling both dot notation and bracket notation
-  // e.g., "images[0].src" -> ["images", "0", "src"]
-  const parts = path
-    .replace(/\[(\d+)\]/g, ".$1") // Convert [0] to .0
-    .split(".")
-    .filter(Boolean)
+  const segments = parsePathSegments(path)
+  if (!segments) {
+    return undefined
+  }
 
   let current = data
-  for (const part of parts) {
+  for (const segment of segments) {
     if (current === null || current === undefined) {
       return undefined
     }
-    current = current[part]
+    if (segment.type === "method") {
+      if (
+        !SAFE_METHODS.has(segment.name) ||
+        typeof current[segment.name] !== "function"
+      ) {
+        return undefined
+      }
+      try {
+        current = current[segment.name](...segment.args)
+      } catch (error) {
+        return undefined
+      }
+    } else {
+      current = current[segment.name]
+    }
   }
 
   return current