retold 4.0.4 → 4.0.7

package/docs/architecture/templating/data-formatting.md

@@ -0,0 +1,350 @@
+# Data Formatting Expressions
+
+Formatting expressions transform resolved values for display -- numbers, dates, currencies, and string manipulation.
+
+## Digits
+
+Formats a number with two decimal places and thousands separators.
+
+**Tags:** `{~Digits:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a numeric value |
+
+**Examples:**
+
+```html
+<span>{~Digits:Record.Quantity~} units</span>
+<td>{~Digits:Record.Population~}</td>
+```
+
+```javascript
+_Pict.parseTemplate('{~Digits:Record.Value~}', { Value: 1234567.891 });
+// '1,234,567.89'
+
+_Pict.parseTemplate('{~Digits:Record.Value~}', { Value: 42 });
+// '42.00'
+```
+
+---
+
+## Dollars
+
+Formats a number as US currency with a dollar sign, two decimal places, and thousands separators.
+
+**Tags:** `{~Dollars:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a numeric value |
+
+**Examples:**
+
+```html
+<span class="price">{~Dollars:Record.Price~}</span>
+<td>Total: {~Dollars:AppData.Order.Total~}</td>
+```
+
+```javascript
+_Pict.parseTemplate('{~Dollars:Record.Price~}', { Price: 1234.5 });
+// '$1,234.50'
+
+_Pict.parseTemplate('{~Dollars:Record.Price~}', { Price: 9.9 });
+// '$9.90'
+```
+
+---
+
+## PascalCaseIdentifier
+
+Converts a string to PascalCase -- capitalizes the first letter of each word and removes non-alphanumeric characters.
+
+**Tags:** `{~PascalCaseIdentifier:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a string value |
+
+**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'
+```
+
+Useful for generating code identifiers, CSS class names, or display labels from raw strings.
+
+---
+
+## DateTimeYMD
+
+Formats a date-time value as `YYYY-MM-DD`. Timezone-aware -- respects `pict.options.Timezone` when converting.
+
+**Tags:** `{~DateTimeYMD:ADDRESS~}` `{~DateYMD:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a date-time string or value |
+
+**Examples:**
+
+```html
+<time>{~DateTimeYMD:Record.CreateDate~}</time>
+```
+
+```javascript
+_Pict.options.Timezone = 'America/Los_Angeles';
+_Pict.parseTemplate('{~DateTimeYMD:Record.Date~}',
+	{ Date: '2023-05-25T05:54:46.000Z' });
+// '2023-05-24' (adjusted from UTC to Pacific)
+```
+
+---
+
+## DateTimeFormat
+
+Formats a date-time value using a custom DayJS format string. Timezone-aware.
+
+**Tags:** `{~DateTimeFormat:ADDRESS^FORMAT_STRING~}` `{~DateFormat:ADDRESS^FORMAT_STRING~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a date-time string or value |
+| FORMAT_STRING | DayJS format string (separated by `^`) |
+
+**Common Format Tokens:**
+
+| Token | Output | Example |
+|-------|--------|---------|
+| `YYYY` | 4-digit year | 2025 |
+| `MM` | Zero-padded month | 01-12 |
+| `MMMM` | Full month name | January |
+| `DD` | Zero-padded day | 01-31 |
+| `Do` | Ordinal day | 1st, 2nd, 3rd |
+| `dddd` | Full day name | Monday |
+| `HH` | 24-hour hour | 00-23 |
+| `hh` | 12-hour hour | 01-12 |
+| `mm` | Minutes | 00-59 |
+| `A` | AM/PM | AM, PM |
+
+**Examples:**
+
+```html
+<time>{~DateTimeFormat:Record.PublishedDate^MMMM Do, YYYY~}</time>
+<span>{~DateTimeFormat:Record.EventTime^dddd, MMMM D YYYY [at] h:mm A~}</span>
+```
+
+```javascript
+_Pict.options.Timezone = 'America/New_York';
+_Pict.parseTemplate('{~DateTimeFormat:Record.Date^dddd MMMM Do YYYY~}',
+	{ Date: '2023-05-25T05:54:46.000Z' });
+// 'Wednesday May 24th 2023'
+```
+
+---
+
+## DateOnlyYMD
+
+Formats a date-only value (no time component) as `YYYY-MM-DD`. Forces UTC interpretation to avoid timezone shifting.
+
+**Tags:** `{~DateOnlyYMD:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a date string (e.g., `2023-05-25`) |
+
+**Examples:**
+
+```javascript
+_Pict.parseTemplate('{~DateOnlyYMD:Record.BirthDate~}',
+	{ BirthDate: '2023-05-25' });
+// '2023-05-25'
+```
+
+Use this instead of `DateTimeYMD` when working with date-only values. `DateTimeYMD` applies timezone conversion, which can shift a date-only value to the previous or next day. `DateOnlyYMD` forces UTC to prevent this.
+
+---
+
+## DateOnlyFormat
+
+Formats a date-only value using a custom DayJS format string. Forces UTC interpretation.
+
+**Tags:** `{~DateOnlyFormat:ADDRESS^FORMAT_STRING~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a date string |
+| FORMAT_STRING | DayJS format string (separated by `^`) |
+
+**Examples:**
+
+```html
+<span>{~DateOnlyFormat:Record.BirthDate^MMMM Do, YYYY~}</span>
+```
+
+```javascript
+_Pict.parseTemplate('{~DateOnlyFormat:Record.Date^dddd MMMM Do YYYY~}',
+	{ Date: '2023-05-25' });
+// 'Thursday May 25th 2023'
+```
+
+---
+
+## Join (J)
+
+Joins resolved values from multiple addresses with a separator. Skips empty or falsy values. Flattens arrays.
+
+**Tags:** `{~Join:SEPARATOR^ADDRESS1^ADDRESS2^...~}` `{~J:SEPARATOR^ADDRESS1^ADDRESS2^...~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| SEPARATOR | The string to place between joined values |
+| ADDRESS1, ADDRESS2, ... | Addresses to resolve and join (separated by `^`) |
+
+**Examples:**
+
+```html
+<p>{~J:, ^Record.City^Record.State^Record.Country~}</p>
+<span>{~J: - ^AppData.Server1^AppData.Server2~}</span>
+```
+
+```javascript
+_Pict.parseTemplate('{~J:, ^Record.City^Record.State~}',
+	{ City: 'Portland', State: 'Oregon' });
+// 'Portland, Oregon'
+
+// Empty values are skipped
+_Pict.parseTemplate('{~J:, ^Record.City^Record.State^Record.Zip~}',
+	{ City: 'Portland', State: '', Zip: '97201' });
+// 'Portland, 97201'
+```
+
+---
+
+## JoinUnique (JU)
+
+Joins resolved values, deduplicating before joining. Otherwise identical to Join.
+
+**Tags:** `{~JoinUnique:SEPARATOR^ADDRESS1^ADDRESS2^...~}` `{~JU:SEPARATOR^ADDRESS1^ADDRESS2^...~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| SEPARATOR | The string to place between joined values |
+| ADDRESS1, ADDRESS2, ... | Addresses to resolve, deduplicate, and join (separated by `^`) |
+
+**Examples:**
+
+```javascript
+_Pict.AppData = { Tag1: 'javascript', Tag2: 'node', Tag3: 'javascript' };
+
+_Pict.parseTemplate('{~JU:, ^AppData.Tag1^AppData.Tag2^AppData.Tag3~}');
+// 'javascript, node' (duplicate removed)
+```
+
+---
+
+## PluckJoinUnique (PJU)
+
+Plucks a property from each object in an array, deduplicates the values, and joins them with a separator.
+
+**Tags:** `{~PluckJoinUnique:SEPARATOR^PROPERTY^ARRAY_ADDRESS~}` `{~PJU:SEPARATOR^PROPERTY^ARRAY_ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| SEPARATOR | The string to place between joined values |
+| PROPERTY | The property name to pluck from each array item |
+| ARRAY_ADDRESS | Address of the array (separated by `^`) |
+
+**Examples:**
+
+```javascript
+_Pict.AppData.Files = [
+	{ name: 'photo.jpg', source: 'original' },
+	{ name: 'thumb.jpg', source: 'derivative' },
+	{ name: 'meta.xml', source: 'metadata' },
+	{ name: 'large.jpg', source: 'derivative' }
+];
+
+_Pict.parseTemplate('{~PJU:, ^source^AppData.Files~}');
+// 'original, derivative, metadata' (duplicate 'derivative' removed)
+```
+
+Useful for extracting and displaying unique categories, tags, or types from a collection of records.
+
+---
+
+## HtmlCommentStart (HCS)
+
+Conditionally outputs `<!-- ` to start an HTML comment, based on the truthiness of a data value. Paired with HtmlCommentEnd to wrap content in comments for conditional display.
+
+**Tags:** `{~HtmlCommentStart:ADDRESS~}` `{~HCS:ADDRESS~}` or `{~HCS:ADDRESS:POLARITY~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to a value to check for truthiness |
+| POLARITY | Optional. Default: comment when value is **falsy**. Set to `1`, `true`, or `t` to comment when **truthy**. |
+
+---
+
+## HtmlCommentEnd (HCE)
+
+Conditionally outputs ` -->` to close an HTML comment. Must match a corresponding HtmlCommentStart.
+
+**Tags:** `{~HtmlCommentEnd:ADDRESS~}` `{~HCE:ADDRESS~}` or `{~HCE:ADDRESS:POLARITY~}`
+
+**Parameters:** Same as HtmlCommentStart.
+
+**Combined Example:**
+
+```html
+{~HCS:Record.ShowBanner~}
+<div class="banner">Special Offer!</div>
+{~HCE:Record.ShowBanner~}
+```
+
+```javascript
+// When ShowBanner is true, content is visible:
+_Pict.parseTemplate(template, { ShowBanner: true });
+// '<div class="banner">Special Offer!</div>'
+
+// When ShowBanner is false, content is commented out:
+_Pict.parseTemplate(template, { ShowBanner: false });
+// '<!-- <div class="banner">Special Offer!</div> -->'
+
+// Inverted polarity -- comment when true:
+'{~HCS:Record.IsHidden:1~}<p>Content</p>{~HCE:Record.IsHidden:1~}'
+```
+
+This approach is useful for toggling content visibility in server-rendered HTML while keeping the markup in the DOM for debugging.

package/docs/architecture/templating/data-generation.md

@@ -0,0 +1,72 @@
+# Data Generation Expressions
+
+Data generation expressions produce random values for testing, unique IDs, or placeholder content.
+
+## RandomNumber (RN)
+
+Generates a random integer between a minimum and maximum value (inclusive).
+
+**Tags:** `{~RandomNumber:MIN,MAX~}` `{~RN:MIN,MAX~}` or `{~RN:~}` (defaults: 0 to 9999999)
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| MIN | Minimum value (default: 0) |
+| MAX | Maximum value (default: 9999999). Separated from MIN by `,`. |
+
+**Examples:**
+
+```html
+<!-- Random number 1-100 -->
+<span>Score: {~RN:1,100~}</span>
+
+<!-- Random with defaults -->
+<code>ID: {~RN:~}</code>
+
+<!-- Random percentage -->
+<div style="width: {~RN:10,100~}%">Progress</div>
+```
+
+```javascript
+_Pict.parseTemplate('{~RN:1,6~}');
+// A random integer from 1 to 6 (like a die roll)
+
+_Pict.parseTemplate('{~RN:1000,9999~}');
+// A random 4-digit number
+```
+
+---
+
+## RandomNumberString (RNS)
+
+Generates a zero-padded random numeric string of a specified length.
+
+**Tags:** `{~RandomNumberString:LENGTH~}` `{~RNS:LENGTH~}` or `{~RNS:LENGTH,MAX~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| LENGTH | The number of characters in the output string (default: 4) |
+| MAX | Maximum numeric value (default: 10^LENGTH - 1). Separated from LENGTH by `,`. |
+
+**Examples:**
+
+```html
+<!-- 6-character padded random string -->
+<code>REF-{~RNS:6~}</code>
+
+<!-- 10-character padded random string -->
+<span>{~RNS:10~}</span>
+```
+
+```javascript
+_Pict.parseTemplate('{~RNS:4~}');
+// e.g., '0042' or '7831' (always 4 characters, zero-padded)
+
+_Pict.parseTemplate('{~RNS:8~}');
+// e.g., '00384729' (always 8 characters, zero-padded)
+```
+
+RandomNumberString is useful for generating reference codes, order numbers, or temporary identifiers that need a consistent length. The zero-padding ensures the output is always exactly LENGTH characters, which is important for display consistency and sortability.

package/docs/architecture/templating/debugging.md

@@ -0,0 +1,181 @@
+# Debugging Expressions
+
+Debugging expressions help during development by logging values, inserting breakpoints, and rendering object structures as HTML. They produce no visible output in the rendered template (except DataTree, which renders an HTML representation).
+
+## Breakpoint
+
+Inserts a JavaScript `debugger` statement and logs a stack trace. When browser DevTools are open, execution pauses at this point. Returns an empty string.
+
+**Tags:** `{~Breakpoint~}` or `{~Breakpoint:LABEL~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| LABEL | Optional. A label logged with the breakpoint for identification. |
+
+**Examples:**
+
+```html
+<!-- Pause execution here when DevTools are open -->
+<div>{~Breakpoint~}{~D:Record.Title~}</div>
+
+<!-- Labeled breakpoint -->
+{~Breakpoint:before-user-render~}
+{~T:UserCard:AppData.CurrentUser~}
+```
+
+Breakpoint is a development tool. It does not affect the rendered output -- the expression always returns an empty string. Remove breakpoints before deploying to production.
+
+---
+
+## LogStatement (LS)
+
+Logs a literal message to the trace log. Returns an empty string.
+
+**Tags:** `{~LogStatement:MESSAGE~}` `{~LS:MESSAGE~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| MESSAGE | A literal string to log |
+
+**Examples:**
+
+```html
+{~LS:Starting product list render~}
+<ul>{~TS:ProductRow:AppData.Products~}</ul>
+{~LS:Finished product list render~}
+```
+
+```javascript
+_Pict.parseTemplate('{~LS:Processing order data~}');
+// Logs: 'Processing order data' at trace level
+// Returns: ''
+```
+
+LogStatement logs at the **trace** level. You need `LogLevel: 0` in your Pict configuration to see trace messages. Use it to mark execution flow through templates -- which template set started, which branch was taken.
+
+---
+
+## LogValue (LV)
+
+Resolves a value from the address space and logs it with type information. Returns an empty string.
+
+**Tags:** `{~LogValue:ADDRESS~}` `{~LV:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to the value to log |
+
+**Examples:**
+
+```html
+{~LV:AppData.CurrentUser~}
+{~LV:Record.OrderTotal~}
+```
+
+```javascript
+_Pict.AppData.User = { Name: 'Alice', Role: 'admin' };
+_Pict.parseTemplate('{~LV:AppData.User~}');
+// Logs: 'PICT Template Log Value: [AppData.User] is an object.' + the object
+// Returns: ''
+```
+
+The log output includes the address, the JavaScript type (`typeof`), and the resolved value. This helps identify whether a value is the expected type (string vs number vs object vs undefined).
+
+---
+
+## LogValueTree (LVT)
+
+Recursively logs all keys and values of an object to the trace log, up to a specified depth. Returns an empty string.
+
+**Tags:** `{~LogValueTree:ADDRESS~}` `{~LVT:ADDRESS~}` or `{~LVT:ADDRESS^DEPTH~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to the object to log |
+| DEPTH | Optional. Maximum depth to traverse (default: 1). Separated by `^`. |
+
+**Examples:**
+
+```html
+<!-- Log top-level keys -->
+{~LVT:AppData.Config~}
+
+<!-- Log two levels deep -->
+{~LVT:AppData.User^2~}
+```
+
+```javascript
+_Pict.AppData.Config = {
+	database: { host: 'localhost', port: 3306 },
+	cache: { enabled: true, ttl: 300 }
+};
+
+_Pict.parseTemplate('{~LVT:AppData.Config^2~}');
+// Logs all nested keys and values up to 2 levels
+// Returns: ''
+```
+
+LogValueTree is useful when you are unsure of an object's structure. Rather than serializing it with `{~DJ:...~}` (which can be unwieldy for large objects), LVT gives a formatted log output showing the tree structure.
+
+---
+
+## DataTree (DT)
+
+Renders an object tree as interactive HTML `<div>` elements for visual debugging. Unlike the other debugging expressions, DataTree produces visible output.
+
+**Tags:** `{~DataTree:ADDRESS~}` `{~DT:ADDRESS~}` or `{~DT:ADDRESS^DEPTH~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Path to the object to render |
+| DEPTH | Optional. Maximum depth to traverse (default: 1). Separated by `^`. |
+
+**Examples:**
+
+```html
+<!-- Render object tree in the page -->
+<div class="debug-panel">
+	{~DT:AppData.CurrentOrder~}
+</div>
+
+<!-- Two levels deep -->
+{~DT:AppData.UserProfile^2~}
+```
+
+```javascript
+_Pict.AppData.Data = { title: 'Test', count: 42 };
+_Pict.parseTemplate('{~DT:AppData.Data~}');
+// Returns HTML like:
+// <div class="PICT PICTObjectSet">
+//   <div class="PICTObjectBranchDepth_0">
+//     <div class="PICTObjectBranch">title</div>
+//     <div class="PICTObjectBranchValue">Test</div>
+//   </div>
+//   <div class="PICTObjectBranchDepth_0">
+//     <div class="PICTObjectBranch">count</div>
+//     <div class="PICTObjectBranchValue">42</div>
+//   </div>
+// </div>
+```
+
+The rendered HTML uses CSS classes (`PICTObjectSet`, `PICTObjectBranch`, `PICTObjectBranchValue`, `PICTObjectBranchDepth_N`) that you can style for your debugging panel. DataTree uses customizable templates internally -- `PICT-Object-Wrap` and `PICT-Object-Branch` -- which can be overridden by registering templates with those hashes.
+
+### When to Use Each Debugging Expression
+
+| Need | Expression | Produces Output? |
+|------|------------|-----------------|
+| Pause execution in DevTools | `{~Breakpoint~}` | No |
+| Log a message during rendering | `{~LS:message~}` | No |
+| Log a resolved value with type info | `{~LV:address~}` | No |
+| Log an object tree to console | `{~LVT:address~}` | No |
+| Render an object tree as HTML | `{~DT:address~}` | Yes |

package/docs/architecture/templating/entity.md

@@ -0,0 +1,99 @@
+# Entity Expressions
+
+Entity expressions integrate with Pict's Meadow API layer to fetch records from REST endpoints and render them with templates. These are inherently asynchronous.
+
+## Entity (E)
+
+Fetches an entity record from a Meadow REST API by type and ID, then renders a template with the fetched record.
+
+**Tags:** `{~Entity:ENTITY_TYPE^ID^TEMPLATE_HASH~}` `{~E:ENTITY_TYPE^ID^TEMPLATE_HASH~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ENTITY_TYPE | The Meadow entity scope (e.g., `Book`, `User`, `Order`) |
+| ID | A static ID or address that resolves to an ID |
+| TEMPLATE_HASH | Hash of the template to render with the fetched record |
+
+### Static ID
+
+```javascript
+_Pict.TemplateProvider.addTemplate('BookCard',
+	'<div class="book"><h3>{~D:Record.Title~}</h3><p>By {~D:Record.Author~}</p></div>');
+
+_Pict.parseTemplate('{~E:Book^42^BookCard~}', {},
+	(pError, pResult) =>
+	{
+		console.log(pResult);
+		// '<div class="book"><h3>Dune</h3><p>By Frank Herbert</p></div>'
+	});
+```
+
+### Dynamic ID from Data
+
+The ID parameter can be a data address that resolves to the actual ID value.
+
+```javascript
+_Pict.parseTemplate('{~E:Book^Record.IDBook^BookCard~}',
+	{ IDBook: 100 },
+	(pError, pResult) =>
+	{
+		console.log(pResult);
+		// Fetches Book with ID 100 and renders with BookCard
+	});
+```
+
+### How It Works
+
+When the Entity expression encounters `{~E:Book^42^BookCard~}`:
+
+1. It resolves the ID (static `42` or dynamic from a data address)
+2. Calls `pict.EntityProvider.getEntity('Book', 42, callback)` to fetch the record via REST API
+3. On success, renders the template `BookCard` with the fetched record as `Record`
+4. Returns the rendered string through the callback
+
+The EntityProvider uses Pict's configured API base URL and authentication to make the HTTP request. This means templates can transparently reference server-side data without the template author managing API calls.
+
+### Synchronous Fallback
+
+When called synchronously (no callback), the Entity expression returns an empty string. Entity fetching requires a callback because it involves a network request.
+
+```javascript
+// Sync: returns empty string
+let tmpResult = _Pict.parseTemplate('{~E:Book^42^BookCard~}');
+// ''
+
+// Async: returns fetched and rendered content
+_Pict.parseTemplate('{~E:Book^42^BookCard~}', {}, (pError, pResult) =>
+{
+	// pResult contains the rendered content
+});
+```
+
+### Practical Pattern: Related Entity Display
+
+A common pattern is displaying related entities in a list. Each item has a foreign key, and the Entity expression fetches and renders the related record inline.
+
+```javascript
+_Pict.TemplateProvider.addTemplate('AuthorName',
+	'{~D:Record.FirstName~} {~D:Record.LastName~}');
+
+_Pict.TemplateProvider.addTemplate('BookRow',
+	'<tr><td>{~D:Record.Title~}</td><td>{~E:Author^Record.IDAuthor^AuthorName~}</td></tr>');
+
+_Pict.AppData.Books = [
+	{ Title: 'Dune', IDAuthor: 1 },
+	{ Title: 'Neuromancer', IDAuthor: 2 }
+];
+
+_Pict.parseTemplate(
+	'<table>{~TS:BookRow:AppData.Books~}</table>',
+	{},
+	(pError, pResult) =>
+	{
+		// Each row fetches its author by ID and renders the name
+	});
+```
+
+This pattern works because the template engine processes async expressions within template sets correctly -- it waits for all entity fetches to complete before assembling the final output.