retold 4.0.4 → 4.0.7

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

@@ -0,0 +1,38 @@
+# Reference: HtmlCommentStart (HCS)
+
+Conditionally outputs `<!-- ` to start an HTML comment based on a value's truthiness.
+
+**Tags:** `{~HtmlCommentStart:ADDRESS~}` `{~HCS:ADDRESS~}` or `{~HCS:ADDRESS:POLARITY~}`
+
+**Source:** `pict/source/templates/data/Pict-Template-HtmlCommentStart.js`
+
+## Syntax
+
+```
+{~HCS:ADDRESS~}
+{~HCS:ADDRESS:POLARITY~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to a value to check |
+| POLARITY | No | Default: comment when **falsy**. Set to `1`/`true`/`t` to comment when **truthy**. |
+
+## Examples
+
+```javascript
+// Default: comments out when value is falsy
+_Pict.parseTemplate('{~HCS:Record.Show~}<p>Content</p>{~HCE:Record.Show~}',
+	{ Show: true });
+// '<p>Content</p>'
+
+_Pict.parseTemplate('{~HCS:Record.Show~}<p>Content</p>{~HCE:Record.Show~}',
+	{ Show: false });
+// '<!-- <p>Content</p> -->'
+```
+
+## Related
+
+- [HCE](architecture/templating/ref-hce.md) -- Matching comment end tag

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

@@ -0,0 +1,45 @@
+# Reference: Join (J)
+
+Joins resolved values from multiple addresses with a separator. Skips empty values and flattens arrays.
+
+**Tags:** `{~Join:SEPARATOR^ADDR1^ADDR2^...~}` `{~J:SEPARATOR^ADDR1^ADDR2^...~}`
+
+**Source:** `pict/source/templates/data/Pict-Template-Join.js`
+
+## Syntax
+
+```
+{~J:SEPARATOR^ADDRESS1^ADDRESS2^ADDRESS3~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| SEPARATOR | Yes | String placed between joined values |
+| ADDRESS1..N | Yes | Addresses to resolve and join (separated by `^`) |
+
+## Behavior
+
+- Resolves each address
+- Skips empty or falsy values
+- Flattens any arrays encountered
+- Joins remaining values with the separator
+
+## Examples
+
+```javascript
+_Pict.parseTemplate('{~J:, ^Record.City^Record.State^Record.Country~}',
+	{ City: 'Portland', State: 'Oregon', Country: 'US' });
+// 'Portland, Oregon, US'
+
+// Empty values skipped
+_Pict.parseTemplate('{~J:, ^Record.City^Record.State~}',
+	{ City: 'Portland', State: '' });
+// 'Portland'
+```
+
+## Related
+
+- [JU](architecture/templating/ref-joinunique.md) -- Join with deduplication
+- [PJU](architecture/templating/ref-pluckjoinunique.md) -- Pluck a property from array items, deduplicate, join

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

@@ -0,0 +1,34 @@
+# Reference: JoinUnique (JU)
+
+Joins resolved values, deduplicating before joining.
+
+**Tags:** `{~JoinUnique:SEPARATOR^ADDR1^ADDR2^...~}` `{~JU:SEPARATOR^ADDR1^ADDR2^...~}`
+
+**Source:** `pict/source/templates/data/Pict-Template-JoinUnique.js`
+
+## Syntax
+
+```
+{~JU:SEPARATOR^ADDRESS1^ADDRESS2^ADDRESS3~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| SEPARATOR | Yes | String placed between joined values |
+| ADDRESS1..N | Yes | Addresses to resolve, deduplicate, and join (separated by `^`) |
+
+## Examples
+
+```javascript
+_Pict.AppData = { Tag1: 'js', Tag2: 'node', Tag3: 'js' };
+
+_Pict.parseTemplate('{~JU:, ^AppData.Tag1^AppData.Tag2^AppData.Tag3~}');
+// 'js, node'
+```
+
+## Related
+
+- [J](architecture/templating/ref-join.md) -- Join without deduplication
+- [PJU](architecture/templating/ref-pluckjoinunique.md) -- Pluck from array, deduplicate, join

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

@@ -0,0 +1,37 @@
+# Reference: LogStatement (LS)
+
+Logs a literal message to the trace log. Returns empty string.
+
+**Tags:** `{~LogStatement:MESSAGE~}` `{~LS:MESSAGE~}`
+
+**Source:** `pict/source/templates/debugging/Pict-Template-LogStatement.js`
+
+## Syntax
+
+```
+{~LS:MESSAGE~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| MESSAGE | Yes | Literal string to log |
+
+## Behavior
+
+- Logs the message at trace level
+- Returns empty string
+
+## Examples
+
+```html
+{~LS:Starting render~}
+{~TS:Row:AppData.Items~}
+{~LS:Render complete~}
+```
+
+## Related
+
+- [LV](architecture/templating/ref-lv.md) -- Log a resolved value
+- [LVT](architecture/templating/ref-lvt.md) -- Log an object tree

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

@@ -0,0 +1,38 @@
+# Reference: LogValue (LV)
+
+Resolves a value and logs it with type information. Returns empty string.
+
+**Tags:** `{~LogValue:ADDRESS~}` `{~LV:ADDRESS~}`
+
+**Source:** `pict/source/templates/debugging/Pict-Template-LogValue.js`
+
+## Syntax
+
+```
+{~LV:ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to the value to log |
+
+## Behavior
+
+- Resolves the address
+- Logs the type (`typeof`) and value at trace level
+- Returns empty string
+
+## Examples
+
+```html
+{~LV:AppData.CurrentUser~}
+{~LV:Record.OrderTotal~}
+```
+
+## Related
+
+- [LS](architecture/templating/ref-ls.md) -- Log a literal message
+- [LVT](architecture/templating/ref-lvt.md) -- Log an object tree
+- [DT](architecture/templating/ref-dt.md) -- Render an object as HTML

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

@@ -0,0 +1,33 @@
+# Reference: LogValueTree (LVT)
+
+Recursively logs an object's keys and values to the trace log. Returns empty string.
+
+**Tags:** `{~LogValueTree:ADDRESS~}` `{~LVT:ADDRESS~}` or `{~LVT:ADDRESS^DEPTH~}`
+
+**Source:** `pict/source/templates/debugging/Pict-Template-LogValueTree.js`
+
+## Syntax
+
+```
+{~LVT:ADDRESS~}
+{~LVT:ADDRESS^DEPTH~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to the object to log |
+| DEPTH | No | Maximum traversal depth (default: 1, separated by `^`) |
+
+## Examples
+
+```html
+{~LVT:AppData.Config~}
+{~LVT:AppData.User^3~}
+```
+
+## Related
+
+- [LV](architecture/templating/ref-lv.md) -- Log a single value
+- [DT](architecture/templating/ref-dt.md) -- Render as HTML instead of logging

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

@@ -0,0 +1,40 @@
+# Reference: NotEmpty (NE)
+
+Outputs a literal string if a value is truthy. Otherwise outputs nothing.
+
+**Tags:** `{~NotEmpty:ADDRESS^OUTPUT~}` `{~NE:ADDRESS^OUTPUT~}`
+
+**Source:** `pict/source/templates/logic/Pict-Template-NotEmpty.js`
+
+## Syntax
+
+```
+{~NE:ADDRESS^LITERAL_OUTPUT~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to a value to check for truthiness |
+| LITERAL_OUTPUT | Yes | String to output if truthy (separated by `^`) |
+
+## Examples
+
+```javascript
+_Pict.parseTemplate('{~NE:Record.Name^has name~}', { Name: 'Alice' });
+// 'has name'
+
+_Pict.parseTemplate('{~NE:Record.Name^has name~}', {});
+// ''
+```
+
+```html
+<div class="item{~NE:Record.IsActive^ active~}">
+{~D:Record.AddressLine2~}{~NE:Record.AddressLine2^<br/>~}
+```
+
+## Related
+
+- [TIfAbs](architecture/templating/ref-tifabs.md) -- Full conditional with template rendering
+- [HCS](architecture/templating/ref-hcs.md) / [HCE](architecture/templating/ref-hce.md) -- HTML comment toggling

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

@@ -0,0 +1,41 @@
+# Reference: PascalCaseIdentifier
+
+Converts a string to PascalCase.
+
+**Tags:** `{~PascalCaseIdentifier:ADDRESS~}`
+
+**Source:** `pict/source/templates/data/Pict-Template-PascalCaseIdentifier.js`
+
+## Syntax
+
+```
+{~PascalCaseIdentifier:ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to a string value |
+
+## Behavior
+
+- Capitalizes the first letter of each word
+- Removes non-alphanumeric separators (hyphens, underscores, spaces)
+- Returns the PascalCase result
+
+## Examples
+
+```javascript
+_Pict.parseTemplate('{~PascalCaseIdentifier:Record.Name~}',
+	{ Name: 'meadow-endpoints' });
+// 'MeadowEndpoints'
+
+_Pict.parseTemplate('{~PascalCaseIdentifier:Record.Name~}',
+	{ Name: 'hello world' });
+// 'HelloWorld'
+
+_Pict.parseTemplate('{~PascalCaseIdentifier:Record.Name~}',
+	{ Name: 'some_variable_name' });
+// 'SomeVariableName'
+```

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

@@ -0,0 +1,42 @@
+# Reference: Pict / Self-Reference (P)
+
+Returns the browser-side JavaScript reference to the Pict instance.
+
+**Tags:** `{~Pict~}` `{~P~}`
+
+**Source:** `pict/source/templates/Pict-Template-Self.js`
+
+## Syntax
+
+```
+{~P~}
+```
+
+## Parameters
+
+None.
+
+## Behavior
+
+- Returns `pict.browserAddress` (default: `window._Pict`)
+- Used to wire event handlers in rendered HTML
+
+## Examples
+
+```html
+<button onclick="{~P~}.views['Cart'].add({~D:Record.ID~})">Add</button>
+```
+
+```javascript
+_Pict.parseTemplate('{~P~}');
+// 'window._Pict'
+
+_Pict.browserAddress = 'window._Pict.children[0]';
+_Pict.parseTemplate('{~P~}');
+// 'window._Pict.children[0]'
+```
+
+## Related
+
+- [V](architecture/templating/ref-view.md) -- Render a view inline
+- [DEJS](architecture/templating/ref-dejs.md) -- Escape data for JS strings in handlers

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

@@ -0,0 +1,39 @@
+# Reference: PluckJoinUnique (PJU)
+
+Plucks a property from each object in an array, deduplicates, and joins with a separator.
+
+**Tags:** `{~PluckJoinUnique:SEPARATOR^PROPERTY^ARRAY_ADDRESS~}` `{~PJU:SEPARATOR^PROPERTY^ARRAY_ADDRESS~}`
+
+**Source:** `pict/source/templates/data/Pict-Template-PluckJoinUnique.js`
+
+## Syntax
+
+```
+{~PJU:SEPARATOR^PROPERTY^ARRAY_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| SEPARATOR | Yes | String placed between joined values |
+| PROPERTY | Yes | Property name to extract from each array item |
+| ARRAY_ADDRESS | Yes | Address of the array (separated by `^`) |
+
+## Examples
+
+```javascript
+_Pict.AppData.Files = [
+	{ name: 'photo.jpg', type: 'image' },
+	{ name: 'doc.pdf', type: 'document' },
+	{ name: 'logo.png', type: 'image' }
+];
+
+_Pict.parseTemplate('{~PJU:, ^type^AppData.Files~}');
+// 'image, document'
+```
+
+## Related
+
+- [J](architecture/templating/ref-join.md) -- Join values from addresses
+- [JU](architecture/templating/ref-joinunique.md) -- Join unique values from addresses

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

@@ -0,0 +1,35 @@
+# Reference: RandomNumber (RN)
+
+Generates a random integer between a minimum and maximum value.
+
+**Tags:** `{~RandomNumber:MIN,MAX~}` `{~RN:MIN,MAX~}` or `{~RN:~}`
+
+**Source:** `pict/source/templates/data-generation/Pict-Template-RandomNumber.js`
+
+## Syntax
+
+```
+{~RN:MIN,MAX~}
+{~RN:~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| MIN | No | Minimum value (default: 0) |
+| MAX | No | Maximum value (default: 9999999, separated from MIN by `,`) |
+
+## Examples
+
+```javascript
+_Pict.parseTemplate('{~RN:1,100~}');
+// Random integer 1-100
+
+_Pict.parseTemplate('{~RN:~}');
+// Random integer 0-9999999
+```
+
+## Related
+
+- [RNS](architecture/templating/ref-rns.md) -- Zero-padded random number string

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

@@ -0,0 +1,35 @@
+# Reference: RandomNumberString (RNS)
+
+Generates a zero-padded random numeric string of a specified length.
+
+**Tags:** `{~RandomNumberString:LENGTH~}` `{~RNS:LENGTH~}` or `{~RNS:LENGTH,MAX~}`
+
+**Source:** `pict/source/templates/data-generation/Pict-Template-RandomNumberString.js`
+
+## Syntax
+
+```
+{~RNS:LENGTH~}
+{~RNS:LENGTH,MAX~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| LENGTH | No | Output string length (default: 4) |
+| MAX | No | Maximum numeric value (default: 10^LENGTH - 1, separated by `,`) |
+
+## Examples
+
+```javascript
+_Pict.parseTemplate('{~RNS:6~}');
+// e.g., '003847' (always 6 characters)
+
+_Pict.parseTemplate('{~RNS:4~}');
+// e.g., '0042' (always 4 characters)
+```
+
+## Related
+
+- [RN](architecture/templating/ref-rn.md) -- Random number (not padded)

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

@@ -0,0 +1,36 @@
+# Reference: SolveByReference (SBR)
+
+Resolves an equation string from data and evaluates it.
+
+**Tags:** `{~SolveByReference:EQUATION_ADDR~}` `{~SBR:EQUATION_ADDR~}` or `{~SBR:EQUATION_ADDR:DATA_ADDR:MANIFEST_ADDR~}`
+
+**Source:** `pict/source/templates/Pict-Template-SolveByReference.js`
+
+## Syntax
+
+```
+{~SBR:EQUATION_ADDRESS~}
+{~SBR:EQUATION_ADDRESS:DATA_ADDRESS:MANIFEST_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| EQUATION_ADDRESS | Yes | Address containing the equation string |
+| DATA_ADDRESS | No | Address of data object for variable resolution |
+| MANIFEST_ADDRESS | No | Address of a Manyfest instance for variable mapping |
+
+## Examples
+
+```javascript
+_Pict.AppData.Formula = 'Width * Height';
+_Pict.AppData.Dims = { Width: 100, Height: 50 };
+
+_Pict.parseTemplate('{~SBR:AppData.Formula:AppData.Dims~}');
+// '5000'
+```
+
+## Related
+
+- [S](architecture/templating/ref-solve.md) -- Inline expression evaluation

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

@@ -0,0 +1,46 @@
+# Reference: Solve (S)
+
+Evaluates a mathematical expression with optional variable resolution from data.
+
+**Tags:** `{~Solve:EXPR~}` `{~S:EXPR~}` or `{~S:EXPR:DATA_ADDRESS~}`
+
+**Source:** `pict/source/templates/Pict-Template-Solve.js`
+
+## Syntax
+
+```
+{~S:EXPRESSION~}
+{~S:EXPRESSION:DATA_ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| EXPRESSION | Yes | Math expression string |
+| DATA_ADDRESS | No | Address of object whose properties become variables |
+
+## Built-in Functions
+
+| Function | Description |
+|----------|-------------|
+| `ROUND(value, decimals)` | Round to N decimal places |
+| `PI()` | The constant pi |
+| `CONCAT(a, b, ...)` | String concatenation |
+
+## Examples
+
+```javascript
+_Pict.parseTemplate('{~S:100+55~}');
+// '155'
+
+_Pict.AppData.Order = { Qty: 3, Price: 24.99 };
+_Pict.parseTemplate('{~S:Qty*Price:AppData.Order~}');
+// '74.97'
+
+_Pict.parseTemplate('{~S:ROUND(PI()*R*R,2):AppData~}');
+```
+
+## Related
+
+- [SBR](architecture/templating/ref-sbr.md) -- Equation from data

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

@@ -0,0 +1,41 @@
+# Reference: TemplateByDataAddress (TBDA)
+
+Reads a template string from a data address and parses it inline.
+
+**Tags:** `{~TemplateByDataAddress:ADDRESS~}` `{~TBDA:ADDRESS~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateByDataAddress.js`
+
+## Syntax
+
+```
+{~TBDA:ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to a string containing template content |
+
+## Behavior
+
+- Resolves a template string (the actual markup) from data
+- Fully parses the resolved string for Jellyfish expressions
+- Useful when template content is stored in configuration or database records
+
+## Examples
+
+```javascript
+_Pict.AppData.CustomBanner = '<h1>{~D:AppData.SiteName~}</h1>';
+_Pict.AppData.SiteName = 'My Store';
+
+_Pict.parseTemplate('{~TBDA:AppData.CustomBanner~}');
+// '<h1>My Store</h1>'
+```
+
+## Related
+
+- [T](architecture/templating/ref-template.md) -- Render by hash (pre-registered)
+- [TBR](architecture/templating/ref-tbr.md) -- Resolve hash name from data, then render
+- [TFA](architecture/templating/ref-tfa.md) -- Identical to TBDA

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

@@ -0,0 +1,43 @@
+# Reference: TemplateByReference (TBR)
+
+Reads a template hash (name) from a data address, then renders that registered template.
+
+**Tags:** `{~TemplateByReference:ADDRESS~}` `{~TBR:ADDRESS~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateByReference.js`
+
+## Syntax
+
+```
+{~TBR:ADDRESS~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| ADDRESS | Yes | Path to a string containing a registered template hash |
+
+## Behavior
+
+- Resolves the address to get a template hash string
+- Looks up that hash in the TemplateProvider
+- Renders the registered template
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('CardLayout',
+	'<div class="card">{~D:Record.Content~}</div>');
+_Pict.TemplateProvider.addTemplate('ListLayout',
+	'<li>{~D:Record.Content~}</li>');
+
+_Pict.parseTemplate('{~TBR:Record.Layout~}',
+	{ Layout: 'CardLayout', Content: 'Hello' });
+// '<div class="card">Hello</div>'
+```
+
+## Related
+
+- [T](architecture/templating/ref-template.md) -- Render by a known hash
+- [TBDA](architecture/templating/ref-tbda.md) -- Resolve template content (not hash) from data

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

@@ -0,0 +1,46 @@
+# Reference: TemplateByType (TBT)
+
+Checks a value's JavaScript type and renders a template if the type matches.
+
+**Tags:** `{~TemplateByType:ADDR:TYPE:HASH~}` `{~TBT:ADDR:TYPE:HASH~}` or `{~TBT:ADDR:TYPE:HASH:FALLBACK_ADDR:FALLBACK_HASH~}`
+
+**Source:** `pict/source/templates/Pict-Template-TemplateByTypes.js`
+
+## Syntax
+
+```
+{~TBT:DATA_ADDRESS:TYPE:TEMPLATE_HASH~}
+{~TBT:DATA_ADDRESS:TYPE:TEMPLATE_HASH:FALLBACK_DATA:FALLBACK_TEMPLATE~}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| DATA_ADDRESS | Yes | Address of the value to type-check |
+| TYPE | Yes | Expected JavaScript type (`string`, `number`, `object`, `boolean`, `undefined`) |
+| TEMPLATE_HASH | Yes | Template to render if the type matches |
+| FALLBACK_DATA | No | Data address for fallback rendering |
+| FALLBACK_TEMPLATE | No | Template to render if the type does not match |
+
+## Examples
+
+```javascript
+_Pict.TemplateProvider.addTemplate('ShowText', '<p>{~D:Record.Value~}</p>');
+_Pict.TemplateProvider.addTemplate('ShowNum', '<p>{~Digits:Record.Value~}</p>');
+
+_Pict.AppData.Item = { Value: 'Hello' };
+_Pict.parseTemplate('{~TBT:AppData.Item.Value:string:ShowText~}');
+// '<p>Hello</p>'
+
+// With fallback
+_Pict.AppData.Item = { Value: 42 };
+_Pict.parseTemplate(
+	'{~TBT:AppData.Item.Value:string:ShowText:AppData.Item:ShowNum~}');
+// '<p>42.00</p>'
+```
+
+## Related
+
+- [TIf](architecture/templating/ref-tif.md) -- Conditional by value comparison
+- [TIfAbs](architecture/templating/ref-tifabs.md) -- Conditional by literal comparison