retold 4.0.3 → 4.0.7

package/docs/architecture/templating/ref-template.md

@@ -0,0 +1,40 @@
+# Reference: Template (T)
+
+Renders a registered template by its hash.
+
+**Tags:** `{~Template:HASH~}` `{~T:HASH~}` or `{~T:HASH:DATA_ADDRESS~}`
+
+**Source:** `pict/source/templates/Pict-Template-Template.js`
+
+## Syntax
+
+```
+{~T:TEMPLATE_HASH~}
+{~T:TEMPLATE_HASH:DATA_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Hash of a registered template |
+| DATA_ADDRESS | No | Address to resolve and pass as Record |
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('Badge',
+	'<span class="badge">{~D:Record.Label~}</span>');
+
+_Pict.parseTemplate('{~T:Badge:AppData.User~}');
+// Renders Badge with AppData.User as Record
+
+_Pict.parseTemplate('{~T:Badge~}', { Label: 'Admin' });
+// Renders Badge with the current Record
+```
+
+## Related
+
+- [TBR](architecture/templating/ref-tbr.md) -- Template hash from data
+- [TBDA](architecture/templating/ref-tbda.md) -- Template content from data
+- [TS](architecture/templating/ref-ts.md) -- Render for each item in a collection

package/docs/architecture/templating/ref-tfa.md

@@ -0,0 +1,32 @@
+# Reference: TemplateFromAddress (TFA)
+
+Reads template content from a data address and parses it. Identical to TBDA.
+
+**Tags:** `{~TemplateFromAddress:ADDRESS~}` `{~TFA:ADDRESS~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateFromAddress.js`
+
+## Syntax
+
+```
+{~TFA:ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to a string containing template content |
+
+## Examples
+
+```javascript
+_Pict.parseTemplate('{~TFA:Record.Markup~}',
+	{ Markup: '<b>{~D:Record.Name~}</b>', Name: 'Alice' });
+// '<b>Alice</b>'
+```
+
+## Related
+
+- [TBDA](architecture/templating/ref-tbda.md) -- Identical behavior
+- [TBR](architecture/templating/ref-tbr.md) -- Resolve a template hash from data

package/docs/architecture/templating/ref-tfm.md

@@ -0,0 +1,43 @@
+# Reference: TemplateFromMap (TFM)
+
+Looks up a key in a map, retrieves the entry, and renders a template with it as Record.
+
+**Tags:** `{~TemplateFromMap:HASH:MAP:KEY~}` `{~TFM:HASH:MAP:KEY~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateFromMap.js`
+
+## Syntax
+
+```
+{~TFM:TEMPLATE_HASH:MAP_ADDRESS:KEY_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Hash of the template to render |
+| MAP_ADDRESS | Yes | Address of the map/object |
+| KEY_ADDRESS | Yes | Address containing the key to look up |
+
+## Examples
+
+```javascript
+_Pict.AppData.Authors = {
+	'A-01': { Name: 'Frank Herbert', Born: 1920 },
+	'A-02': { Name: 'William Gibson', Born: 1948 }
+};
+
+_Pict.TemplateProvider.addTemplate('AuthorLabel',
+	'{~D:Record.Name~} (b. {~D:Record.Born~})');
+
+_Pict.parseTemplate('{~TFM:AuthorLabel:AppData.Authors:Record.IDAuthor~}',
+	{ IDAuthor: 'A-01' });
+// 'Frank Herbert (b. 1920)'
+```
+
+## Related
+
+- [T](architecture/templating/ref-template.md) -- Render with direct data
+- [DVBK](architecture/templating/ref-dvbk.md) -- Simple value lookup by key
+- [TSFM](architecture/templating/ref-tsfm.md) -- Iterate an array from a map

package/docs/architecture/templating/ref-tif.md

@@ -0,0 +1,45 @@
+# Reference: TemplateIf (TIf)
+
+Compares two data-resolved values. Renders a template if the comparison is true.
+
+**Tags:** `{~TemplateIf:HASH:DATA:CONDITION~}` `{~TIf:HASH:DATA:CONDITION~}`
+
+**Source:** `pict/source/templates/logic/Pict-Template-TemplateIf.js`
+
+## Syntax
+
+```
+{~TIf:TEMPLATE_HASH:DATA_ADDRESS:LEFT^OPERATOR^RIGHT~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Template to render if true |
+| DATA_ADDRESS | No | Data to pass as Record (can be empty) |
+| LEFT | Yes | Address for left operand |
+| OPERATOR | Yes | Comparison operator |
+| RIGHT | Yes | Address for right operand |
+
+## Operators
+
+`==`, `===`, `!=`, `!==`, `>`, `>=`, `<`, `<=`, `TRUE`, `FALSE`, `LNGT` (length >), `LNLT` (length <)
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('Match', '<span>Match!</span>');
+
+_Pict.AppData = { Actual: 200, Expected: 200 };
+_Pict.parseTemplate('{~TIf:Match::AppData.Actual^==^AppData.Expected~}');
+// '<span>Match!</span>'
+
+_Pict.parseTemplate('{~TIf:Match::AppData.Actual^>^AppData.Expected~}');
+// '' (200 is not > 200)
+```
+
+## Related
+
+- [TIfAbs](architecture/templating/ref-tifabs.md) -- Compare against a literal value
+- [NE](architecture/templating/ref-ne.md) -- Simple truthiness check

package/docs/architecture/templating/ref-tifabs.md

@@ -0,0 +1,41 @@
+# Reference: TemplateIfAbsolute (TIfAbs)
+
+Compares a data-resolved value against a literal. Renders a template if the comparison is true.
+
+**Tags:** `{~TemplateIfAbsolute:HASH:DATA:CONDITION~}` `{~TIfAbs:HASH:DATA:CONDITION~}`
+
+**Source:** `pict/source/templates/logic/Pict-Template-TemplateIfAbsolute.js`
+
+## Syntax
+
+```
+{~TIfAbs:TEMPLATE_HASH:DATA_ADDRESS:LEFT^OPERATOR^LITERAL~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Template to render if true |
+| DATA_ADDRESS | No | Data to pass as Record (can be empty) |
+| LEFT | Yes | Address for left operand |
+| OPERATOR | Yes | Comparison operator (same as TIf) |
+| LITERAL | Yes | A literal value (not resolved from data) |
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('Admin', '<span>Admin</span>');
+
+_Pict.AppData.User = { Role: 'admin' };
+_Pict.parseTemplate('{~TIfAbs:Admin::AppData.User.Role^==^admin~}');
+// '<span>Admin</span>'
+
+_Pict.parseTemplate('{~TIfAbs:Admin::AppData.User.Role^==^guest~}');
+// ''
+```
+
+## Related
+
+- [TIf](architecture/templating/ref-tif.md) -- Compare two data addresses
+- [NE](architecture/templating/ref-ne.md) -- Simple truthiness output

package/docs/architecture/templating/ref-ts.md

@@ -0,0 +1,41 @@
+# Reference: TemplateSet (TS)
+
+Renders a template once for each item in a collection. Each item becomes Record.
+
+**Tags:** `{~TemplateSet:HASH:COLLECTION~}` `{~TS:HASH:COLLECTION~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateSet.js`
+
+## Syntax
+
+```
+{~TS:TEMPLATE_HASH:COLLECTION_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Hash of the template to render per item |
+| COLLECTION_ADDRESS | Yes | Address of an array or object to iterate |
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('Row',
+	'<tr><td>{~D:Record.Name~}</td></tr>');
+
+_Pict.AppData.Users = [
+	{ Name: 'Alice' },
+	{ Name: 'Bob' }
+];
+
+_Pict.parseTemplate('<table>{~TS:Row:AppData.Users~}</table>');
+// '<table><tr><td>Alice</td></tr><tr><td>Bob</td></tr></table>'
+```
+
+## Related
+
+- [TSFM](architecture/templating/ref-tsfm.md) -- Iterate from a map lookup
+- [TSWP](architecture/templating/ref-tswp.md) -- Iterate with payload
+- [TVS](architecture/templating/ref-tvs.md) -- Iterate over values with key/index metadata

package/docs/architecture/templating/ref-tsfm.md

@@ -0,0 +1,42 @@
+# Reference: TemplateSetFromMap (TSFM)
+
+Looks up a key in a map to get an array, then renders a template for each item.
+
+**Tags:** `{~TemplateSetFromMap:HASH:MAP:KEY~}` `{~TSFM:HASH:MAP:KEY~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateSetFromMap.js`
+
+## Syntax
+
+```
+{~TSFM:TEMPLATE_HASH:MAP_ADDRESS:KEY_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Hash of the template to render per item |
+| MAP_ADDRESS | Yes | Address of a map whose values are arrays |
+| KEY_ADDRESS | Yes | Address containing the key to look up |
+
+## Examples
+
+```javascript
+_Pict.AppData.Teams = {
+	'Engineering': [{ Name: 'Alice' }, { Name: 'Bob' }],
+	'Design': [{ Name: 'Carol' }]
+};
+
+_Pict.TemplateProvider.addTemplate('Member', '<li>{~D:Record.Name~}</li>');
+
+_Pict.parseTemplate(
+	'<ul>{~TSFM:Member:AppData.Teams:Record.Dept~}</ul>',
+	{ Dept: 'Engineering' });
+// '<ul><li>Alice</li><li>Bob</li></ul>'
+```
+
+## Related
+
+- [TS](architecture/templating/ref-ts.md) -- Iterate over a direct collection
+- [TFM](architecture/templating/ref-tfm.md) -- Single item from map (not iterated)

package/docs/architecture/templating/ref-tswp.md

@@ -0,0 +1,45 @@
+# Reference: TemplateSetWithPayload (TSWP)
+
+Renders a template for each item, wrapping each as `{ Data, Payload }`.
+
+**Tags:** `{~TemplateSetWithPayload:HASH:COLLECTION:PAYLOAD~}` `{~TSWP:HASH:COLLECTION:PAYLOAD~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateSetWithPayload.js`
+
+## Syntax
+
+```
+{~TSWP:TEMPLATE_HASH:COLLECTION_ADDRESS:PAYLOAD_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Hash of the template to render per item |
+| COLLECTION_ADDRESS | Yes | Address of an array to iterate |
+| PAYLOAD_ADDRESS | Yes | Address of extra data included with each item |
+
+## Behavior
+
+Inside the rendered template, Record has two properties:
+- `Record.Data` -- the current array item
+- `Record.Payload` -- the resolved payload object
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('Item',
+	'<div class="{~D:Record.Payload.cssClass~}">{~D:Record.Data.Name~}</div>');
+
+_Pict.AppData.Items = [{ Name: 'Widget' }, { Name: 'Gadget' }];
+_Pict.AppData.Config = { cssClass: 'product-card' };
+
+_Pict.parseTemplate('{~TSWP:Item:AppData.Items:AppData.Config~}');
+// '<div class="product-card">Widget</div><div class="product-card">Gadget</div>'
+```
+
+## Related
+
+- [TS](architecture/templating/ref-ts.md) -- Iterate without payload
+- [TVS](architecture/templating/ref-tvs.md) -- Iterate over values with metadata

package/docs/architecture/templating/ref-tvs.md

@@ -0,0 +1,48 @@
+# Reference: TemplateValueSet (TVS)
+
+Iterates over values of an object or array. Includes Key, Value, Index, and Count metadata.
+
+**Tags:** `{~TemplateValueSet:HASH:ADDRESS~}` `{~TVS:HASH:ADDRESS~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateValueSet.js`
+
+## Syntax
+
+```
+{~TVS:TEMPLATE_HASH:DATA_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| TEMPLATE_HASH | Yes | Hash of the template to render per value |
+| DATA_ADDRESS | Yes | Address of an object or array |
+
+## Record Properties
+
+| Property | Description |
+|----------|-------------|
+| `Record.Key` | Array index or object key |
+| `Record.Value` | The value at that key |
+| `Record.Index` | Zero-based index |
+| `Record.Count` | Total number of items |
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('Tag', '<span>{~D:Record.Value~}</span>');
+
+_Pict.AppData.Tags = ['js', 'node', 'express'];
+_Pict.parseTemplate('{~TVS:Tag:AppData.Tags~}');
+// '<span>js</span><span>node</span><span>express</span>'
+
+// Object (sorted keys)
+_Pict.AppData.Users = { '2': 'Bob', '1': 'Alice' };
+_Pict.parseTemplate('{~TVS:Tag:AppData.Users~}');
+// '<span>Alice</span><span>Bob</span>'
+```
+
+## Related
+
+- [TS](architecture/templating/ref-ts.md) -- Iterate objects as Record directly

package/docs/architecture/templating/ref-view.md

@@ -0,0 +1,40 @@
+# Reference: View (V)
+
+Renders a registered Pict view inline.
+
+**Tags:** `{~View:VIEW_HASH~}` `{~V:VIEW_HASH~}`
+
+**Source:** `pict/source/templates/Pict-Template-View.js`
+
+## Syntax
+
+```
+{~V:VIEW_HASH~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| VIEW_HASH | Yes | Hash of a registered Pict view |
+
+## Behavior
+
+- Triggers the view's render pipeline
+- Captures output to a virtual render target
+- Returns the rendered string
+
+## Examples
+
+```html
+<div class="page">
+	{~V:HeaderView~}
+	<main>{~D:AppData.Content~}</main>
+	{~V:FooterView~}
+</div>
+```
+
+## Related
+
+- [VRS](architecture/templating/ref-vrs.md) -- View with scope retention
+- [P](architecture/templating/ref-pict.md) -- Pict instance reference

package/docs/architecture/templating/ref-vrs.md

@@ -0,0 +1,39 @@
+# Reference: ViewRetainingScope (VRS)
+
+Renders a Pict view inline, passing the current scope through.
+
+**Tags:** `{~ViewRetainingScope:VIEW_HASH~}` `{~VRS:VIEW_HASH~}`
+
+**Source:** `pict/source/templates/Pict-Template-View-RetainingScope.js`
+
+## Syntax
+
+```
+{~VRS:VIEW_HASH~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| VIEW_HASH | Yes | Hash of a registered Pict view |
+
+## Behavior
+
+- Same as View, but calls `renderWithScope()` on the view
+- The current Scope namespace is available inside the child view's templates
+
+## Examples
+
+```html
+<!-- Parent sets scope, child view reads it -->
+{~VRS:ChildView~}
+
+<!-- Inside ChildView's templates: -->
+<div class="{~D:Scope.theme~}">{~D:Scope.title~}</div>
+```
+
+## Related
+
+- [V](architecture/templating/ref-view.md) -- View without scope retention
+- [P](architecture/templating/ref-pict.md) -- Pict instance reference

package/docs/architecture/templating/solvers.md

@@ -0,0 +1,153 @@
+# Solver Expressions
+
+Solver expressions evaluate mathematical expressions using Fable's expression parser. They support arithmetic, built-in functions, string concatenation, and variable references resolved from data.
+
+## Solve (S)
+
+Evaluates a mathematical expression. Variables in the expression are resolved from the data at the given address.
+
+**Tags:** `{~Solve:EXPRESSION~}` `{~S:EXPRESSION~}` or `{~S:EXPRESSION:DATA_ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| EXPRESSION | A math expression string |
+| DATA_ADDRESS | Optional. Address of an object whose properties become variables in the expression. |
+
+### Basic Arithmetic
+
+```javascript
+_Pict.parseTemplate('{~S:100+55~}');
+// '155'
+
+_Pict.parseTemplate('{~S:2*3+4~}');
+// '10'
+
+_Pict.parseTemplate('{~S:100/3~}');
+// '33.333333333333336'
+```
+
+### Variables from Data
+
+When you provide a data address, property names in the expression resolve against that object.
+
+```javascript
+_Pict.AppData.Order = { Quantity: 3, UnitPrice: 24.99, TaxRate: 0.08 };
+
+_Pict.parseTemplate('{~S:Quantity*UnitPrice:AppData.Order~}');
+// '74.97'
+
+_Pict.parseTemplate('{~S:Quantity*UnitPrice*(1+TaxRate):AppData.Order~}');
+// '80.9892'
+```
+
+### Built-in Functions
+
+The expression parser supports several functions:
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `ROUND(value, decimals)` | Round to N decimal places | `ROUND(3.14159, 2)` = `3.14` |
+| `PI()` | The constant pi | `PI()` = `3.141592653589793` |
+| `CONCAT(a, b, ...)` | String concatenation | `CONCAT("Hello", " ", "World")` = `Hello World` |
+
+**Examples:**
+
+```javascript
+_Pict.AppData.Circle = { Radius: 10 };
+
+// Area of a circle
+_Pict.parseTemplate('{~S:ROUND(PI()*Radius*Radius, 2):AppData.Circle~}');
+// '314.16'
+
+// Formatted output with CONCAT
+_Pict.AppData.Metrics = { Height: 48 };
+_Pict.parseTemplate('{~S:CONCAT("Height is ", Height, " units."):AppData.Metrics~}');
+// 'Height is 48 units.'
+```
+
+### Practical Patterns
+
+**Invoice line totals:**
+
+```javascript
+_Pict.TemplateProvider.addTemplate('LineItem',
+	'<tr><td>{~D:Record.Description~}</td><td>{~S:ROUND(Qty*Price,2):Record~}</td></tr>');
+
+_Pict.AppData.Lines = [
+	{ Description: 'Widget', Qty: 5, Price: 9.99 },
+	{ Description: 'Gadget', Qty: 2, Price: 24.50 }
+];
+
+_Pict.parseTemplate('<table>{~TS:LineItem:AppData.Lines~}</table>');
+```
+
+**Percentage calculations:**
+
+```javascript
+_Pict.AppData.Progress = { Completed: 37, Total: 50 };
+
+_Pict.parseTemplate(
+	'{~S:ROUND(Completed/Total*100,1):AppData.Progress~}% complete');
+// '74% complete'
+```
+
+---
+
+## SolveByReference (SBR)
+
+Resolves an equation string from a data address and evaluates it. The equation itself is stored in data rather than written directly in the template. Optionally resolves a data object and a Manyfest manifest for variable mapping.
+
+**Tags:** `{~SolveByReference:EQUATION_ADDRESS~}` `{~SBR:EQUATION_ADDRESS~}` or `{~SBR:EQUATION_ADDRESS:DATA_ADDRESS:MANIFEST_ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| EQUATION_ADDRESS | Address containing the equation string |
+| DATA_ADDRESS | Optional. Address of the data object for variable resolution |
+| MANIFEST_ADDRESS | Optional. Address of a Manyfest instance for variable name mapping |
+
+### Basic Usage
+
+```javascript
+_Pict.AppData.Formula = 'Width * Height';
+_Pict.AppData.Dimensions = { Width: 100, Height: 50 };
+
+_Pict.parseTemplate('{~SBR:AppData.Formula:AppData.Dimensions~}');
+// '5000'
+```
+
+### With Manyfest Variable Mapping
+
+When data uses nested addresses but the equation uses flat variable names, a Manyfest maps between them.
+
+```javascript
+_Pict.AppData.Equation = 'Area = Width * Height';
+_Pict.AppData.RectangleData = { Size: { Width: 100, Height: 50 } };
+
+// Create a Manyfest that maps nested paths to flat names
+_Pict.AppData.RectangleManifest = _Pict.newManyfest({
+	Scope: 'Rectangle',
+	Descriptors: {
+		'Size.Width': { Hash: 'Width' },
+		'Size.Height': { Hash: 'Height' }
+	}
+});
+
+_Pict.parseTemplate(
+	'{~SBR:AppData.Equation:AppData.RectangleData:AppData.RectangleManifest~}');
+// '5000'
+```
+
+SolveByReference is powerful for data-driven calculations where the formulas themselves are configurable. Pricing rules, scoring algorithms, or derived metrics can be stored as data and evaluated at render time without hardcoding the math in templates.
+
+## When to Use Solve vs SolveByReference
+
+| Scenario | Use |
+|----------|-----|
+| Fixed formula, data varies | `{~S:Qty*Price:Record~}` |
+| Formula stored in data | `{~SBR:AppData.Formula:Record~}` |
+| Nested data with variable mapping | `{~SBR:...^...^ManyfestInstance~}` |
+| Simple constant math | `{~S:100+55~}` |