boxwood 2.13.0 → 2.15.0

package/ui/prose/README.md

@@ -0,0 +1,492 @@
+# Prose Component
+
+The `Prose` component is an enhanced content component for blog systems, documentation, and other content-heavy use cases. It extends basic markdown with templating features.
+
+## Features
+
+### Markdown Support
+
+All standard markdown features:
+
+- Headings (`#`, `##`, etc.)
+- Lists (ordered and unordered)
+- Links and images
+- Code blocks
+- Bold, italic, and inline code
+- Blockquotes
+- Horizontal rules
+
+### Templating Features
+
+- **Variable replacement**: `{variable}`, `{user.name}`, `{images[0].src}`
+- **Conditionals**: `{#if variable}...{/if}` blocks for conditional rendering
+- **Loops**: `{#each items}...{/each}` for iteration over arrays
+- **Custom components**: `<Alert type="warning">...</Alert>`
+- **Builtin HTML tags**: `<article>`, `<section>`, `<div>`, etc.
+
+### Planned Features
+
+None at the moment - all core features are implemented!
+
+## Usage
+
+```javascript
+const { Prose } = require("boxwood/ui")
+
+// Basic usage with variables
+Prose(
+  { data: { title: "Hello", author: "John" } },
+  `
+# {title}
+
+Written by {author}
+`,
+)
+
+// With conditionals
+Prose(
+  { data: { image: "hero.jpg", showAuthor: true, author: "Jane" } },
+  `
+{#if image}
+![Featured Image]({image})
+{/if}
+
+# My Blog Post
+
+{#if showAuthor}
+Written by {author}
+{/if}
+`,
+)
+
+// With custom components
+Prose(
+  {
+    data: { message: "Important!" },
+    components: { Alert },
+  },
+  `
+<Alert type="warning">{message}</Alert>
+`,
+)
+
+// Blog post example
+Prose(
+  {
+    data: {
+      title: "Getting Started",
+      author: "Alice",
+      bio: "Software Engineer",
+      image: "cover.jpg",
+      tags: ["tutorial", "beginner"],
+    },
+  },
+  `
+# {title}
+
+{#if image}
+![Cover]({image})
+{/if}
+
+{#if bio}
+**About the author:** {bio}
+{/if}
+
+{#if tags.length > 0}
+**Tags:** {tags[0]}, {tags[1]}
+{/if}
+`,
+)
+```
+
+## Conditional Rendering
+
+Use `{#if}` blocks to conditionally render content based on data:
+
+```markdown
+{#if premium}
+Access premium content here
+{/if}
+
+{#if items[0]}
+First item: {items[0].name}
+{/if}
+```
+
+### Negation
+
+You can negate conditions using the `!` operator:
+
+```markdown
+{#if !hidden}
+This content is visible
+{/if}
+
+{#if !user.verified}
+Please verify your email
+{/if}
+
+{#if !premium}
+Upgrade to access premium features
+{/if}
+```
+
+The `!` operator inverts the condition, making it true when the value is falsy.
+
+### Comparison Operators
+
+You can use comparison operators in conditions:
+
+```markdown
+{#if tags.length > 0}
+**Tags:** {tags[0]}, {tags[1]}
+{/if}
+
+{#if age >= 18}
+You can vote
+{/if}
+
+{#if count < 10}
+Limited quantity remaining
+{/if}
+
+{#if status == 'published'}
+This post is live
+{/if}
+
+{#if temperature != 0}
+Temperature: {temperature}°C
+{/if}
+```
+
+Supported operators:
+
+- `>` - Greater than
+- `<` - Less than
+- `>=` - Greater than or equal
+- `<=` - Less than or equal
+- `==` - Equals
+- `!=` - Not equals
+
+You can compare with:
+
+- **Numbers**: `{#if count > 5}`
+- **Strings**: `{#if status == 'active'}` or `{#if status == "active"}`
+- **Booleans**: `{#if verified == true}`
+- **Variables**: `{#if current > previous}`
+
+### Simple Conditions
+
+Conditions support:
+
+- Simple variables: `{#if show}`
+- Nested properties: `{#if user.verified}`
+- Array indexing: `{#if images[0]}`
+
+Falsy values (removes content):
+
+- `null`, `undefined`
+- `false`
+- `0`
+- `""` (empty string)
+- `[]` (empty array)
+
+### Else Blocks
+
+Use `{#else}` to provide alternative content when a condition is false:
+
+```markdown
+{#if isPremium}
+**Premium Content**
+
+Access exclusive features
+{#else}
+**Standard Content**
+
+Upgrade for more features
+{/if}
+```
+
+```markdown
+{#if age >= 18}
+You can vote
+{#else}
+You cannot vote yet
+{/if}
+```
+
+```markdown
+{#if items.length > 0}
+You have {items.length} items
+{#else}
+Your cart is empty
+{/if}
+```
+
+Else blocks work with all conditional features:
+
+- Simple conditions: `{#if show}...{#else}...{/if}`
+- Comparison operators: `{#if count > 5}...{#else}...{/if}`
+- Negation: `{#if !hidden}...{#else}...{/if}`
+- Nested conditions: `{#if outer}{#if inner}...{#else}...{/if}{#else}...{/if}`
+- Inside loops: Conditionally render content for each item
+
+### Else-If Chains
+
+Use `{#elseif}` to test multiple conditions in sequence:
+
+```markdown
+{#if score >= 90}
+Grade: A - Excellent!
+{#elseif score >= 80}
+Grade: B - Good job!
+{#elseif score >= 70}
+Grade: C - Passing
+{#elseif score >= 60}
+Grade: D - Needs improvement
+{#else}
+Grade: F - Failed
+{/if}
+```
+
+```markdown
+{#if role == 'admin'}
+
+# Admin Dashboard
+
+Welcome, administrator!
+{#elseif role == 'moderator'}
+
+# Moderator Panel
+
+Welcome, moderator!
+{#elseif role == 'user'}
+
+# User Profile
+
+Welcome, user!
+{#else}
+
+# Guest Access
+
+Please log in.
+{/if}
+```
+
+Else-if features:
+
+- **Multiple branches**: Chain as many `{#elseif}` blocks as needed
+- **Short-circuit evaluation**: First matching condition wins, remaining branches are skipped
+- **Optional else**: The final `{#else}` block is optional
+- **All comparison operators**: Use `==`, `!=`, `>`, `<`, `>=`, `<=` in elseif conditions
+- **Negation support**: Use `!` to negate elseif conditions
+- **Nested conditionals**: Place if/else blocks inside elseif branches
+
+Example with real-world blog scenario:
+
+```javascript
+Prose(
+  {
+    data: {
+      status: "draft",
+      publishedAt: null,
+      scheduledAt: "2026-07-10",
+    },
+  },
+  `
+# My Blog Post
+
+{#if publishedAt}
+*Published on {publishedAt}*
+{#elseif scheduledAt}
+*Scheduled for {scheduledAt}*
+{#else}
+*Draft - not yet published*
+{/if}
+
+## Content
+
+...
+`,
+)
+```
+
+## Loops
+
+Use `{#each}` blocks to iterate over arrays and render content for each item:
+
+### Basic Loop Syntax
+
+```markdown
+{#each items}
+
+- {item}
+  {/each}
+```
+
+By default, the current item is available as `{item}`. For arrays of primitives (strings, numbers, etc.), this is the value itself.
+
+### Custom Variable Names
+
+You can specify a custom variable name for better clarity:
+
+```markdown
+{#each users as user}
+
+- {user.name} ({user.email})
+  {/each}
+```
+
+### Loop with Index
+
+Access the current index by providing a second variable name:
+
+```markdown
+{#each items as item, i}
+{i}. {item}
+{/each}
+```
+
+The index is zero-based (starts at 0).
+
+### Nested Properties
+
+Loop items can be objects with nested properties:
+
+```markdown
+{#each products as product}
+**{product.name}**
+
+Price: ${product.price}
+{/each}
+```
+
+### Accessing External Variables
+
+Variables from outside the loop are still accessible:
+
+```markdown
+{#each items as item}
+
+- {prefix}{item}{suffix}
+  {/each}
+```
+
+### Nested Loops
+
+Loops can be nested to create complex structures:
+
+```markdown
+{#each categories as category}
+
+## {category.name}
+
+{#each category.items as item}
+
+- {item}
+  {/each}
+  {/each}
+```
+
+### Combining Loops with Conditionals
+
+You can use conditionals inside loops to filter or conditionally render content:
+
+```markdown
+{#each users as user}
+**{user.name}**
+
+{#if user.verified}
+✓ Verified user
+{/if}
+
+{#if user.role == 'admin'}
+👑 Administrator
+{/if}
+{/each}
+```
+
+### Loop Examples
+
+**Simple list:**
+
+```javascript
+Prose(
+  { data: { fruits: ["Apple", "Banana", "Cherry"] } },
+  `
+{#each fruits as fruit}
+- {fruit}
+{/each}
+`,
+)
+```
+
+**User cards with conditionals:**
+
+```javascript
+Prose(
+  {
+    data: {
+      users: [
+        { name: "Alice", verified: true, role: "admin" },
+        { name: "Bob", verified: false, role: "user" },
+        { name: "Charlie", verified: true, role: "user" },
+      ],
+    },
+  },
+  `
+{#each users as user}
+### {user.name}
+
+{#if user.verified}
+✓ Verified
+{/if}
+
+{#if user.role == 'admin'}
+**Role:** Administrator
+{/if}
+
+---
+
+{/each}
+`,
+)
+```
+
+**Numbered list with index:**
+
+```javascript
+Prose(
+  { data: { steps: ["Create account", "Verify email", "Complete profile"] } },
+  `
+{#each steps as step, i}
+**Step {i + 1}:** {step}
+{/each}
+`,
+)
+```
+
+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:**
+
+When an array is empty, the loop content is not rendered:
+
+```javascript
+Prose(
+  { data: { items: [] } },
+  `
+{#each items as item}
+- {item}
+{/each}
+`,
+)
+// Renders nothing
+```
+
+## Difference from Markdown Component
+
+- **Markdown**: Pure markdown rendering, no variables or custom components
+- **Prose**: Markdown + templating (variables, custom components, conditionals, loops)
+
+Use `Markdown` for simple, static content. Use `Prose` for dynamic content in blogs, CMS, or documentation systems.

package/ui/prose/index.js

@@ -0,0 +1,159 @@
+const nodes = require("../..")
+const { component } = nodes
+
+const Center = require("../center")
+const Container = require("../container")
+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 { processConditionals } = require("./utilities/processConditionals")
+const { processLoops } = require("./utilities/processLoops")
+
+// 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
+const SAFE_TAG_NAMES = [
+  // Containers
+  "div",
+  "span",
+  // Semantic structure
+  "article",
+  "section",
+  "header",
+  "footer",
+  "main",
+  "aside",
+  "nav",
+  // Headings
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  // Text formatting
+  "p",
+  "strong",
+  "em",
+  "b",
+  "i",
+  "u",
+  "s",
+  "small",
+  "mark",
+  "sub",
+  "sup",
+  "br",
+  "wbr",
+  "abbr",
+  "cite",
+  "q",
+  "kbd",
+  "samp",
+  "var",
+  "del",
+  "ins",
+  "dfn",
+  // Lists
+  "ul",
+  "ol",
+  "li",
+  "dl",
+  "dt",
+  "dd",
+  // Links & media
+  "a",
+  "img",
+  "picture",
+  "source",
+  // Code
+  "code",
+  "pre",
+  // Tables
+  "table",
+  "thead",
+  "tbody",
+  "tfoot",
+  "tr",
+  "th",
+  "td",
+  "caption",
+  "colgroup",
+  "col",
+  // Block elements
+  "blockquote",
+  "hr",
+  // Figures
+  "figure",
+  "figcaption",
+  // Interactive
+  "details",
+  "summary",
+  // Other semantic
+  "address",
+  "time",
+  "data",
+]
+
+// Build BUILTIN_HTML_TAGS dynamically from tag names
+const BUILTIN_HTML_TAGS = SAFE_TAG_NAMES.reduce((acc, tagName) => {
+  const componentName = tagName.charAt(0).toUpperCase() + tagName.slice(1)
+  if (nodes[componentName]) {
+    acc[tagName] = nodes[componentName]
+  }
+  return acc
+}, {})
+
+// Add built-in UI components
+const BUILTIN_UI_COMPONENTS = {
+  Center,
+  Container,
+  Grid,
+  Group,
+  Stack,
+}
+
+// Merge HTML tags and UI components
+const BUILTIN_COMPONENTS = { ...BUILTIN_HTML_TAGS, ...BUILTIN_UI_COMPONENTS }
+
+function Prose(params, children) {
+  // Handle array of children recursively
+  if (Array.isArray(children)) {
+    return children.map((child) => Prose(params, child))
+  }
+
+  // Only process string content
+  if (typeof children !== "string") {
+    return null
+  }
+
+  const customComponents = params && params.components
+  const data = params && params.data
+  const allComponents = mergeComponents(BUILTIN_COMPONENTS, customComponents)
+  const htmlParams = extractHtmlParams(params)
+
+  // Process {#each}...{/each} loop blocks first
+  // Conditionals within loops are processed during loop expansion
+  let processedChildren = processLoops(children, data)
+
+  // Process any remaining {#if}...{/if} conditional blocks (those outside loops)
+  processedChildren = processConditionals(processedChildren, data)
+
+  // Parse all markdown lines into structured items
+  const items = parseMarkdownLines(processedChildren, allComponents, data)
+
+  // Convert parsed items into final node tree
+  return convertItemsToNodes(
+    items,
+    params,
+    htmlParams,
+    data,
+    allComponents,
+    Prose,
+  )
+}
+
+module.exports = component(Prose)

package/ui/prose/utilities/brackets.js

@@ -0,0 +1,21 @@
+// Find the matching closing bracket, accounting for nested brackets
+function findMatchingBracket(text, startPos) {
+  let depth = 1
+  let i = startPos + 1
+
+  while (i < text.length && depth > 0) {
+    if (text[i] === "[" && text[i - 1] !== "\\") {
+      depth++
+    } else if (text[i] === "]" && text[i - 1] !== "\\") {
+      depth--
+      if (depth === 0) {
+        return i
+      }
+    }
+    i++
+  }
+
+  return -1
+}
+
+module.exports = { findMatchingBracket }