pict-section-form 1.0.196 → 1.0.197

package/docs/Comprehensions.md

@@ -0,0 +1,181 @@
+# Comprehensions
+
+The `addComprehensionEntity` solver function builds **multi-context, multi-entity
+comprehensions** from form data — a JSON shape that can be inspected, diffed,
+and pushed to a Meadow REST API via
+[`meadow-integration load_comprehension`](https://github.com/stevenvelozo/meadow-integration).
+
+Think of it as the "save side" of a form: a single function call lays down one
+property of one record under one workflow context, and many calls compose into a
+single nested tree that a downstream pipeline can read in one go.
+
+## Signature
+
+```
+addComprehensionEntity(Context, Entity, GUID, Property, Value)
+```
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `Context` | string (manyfest address) | Workflow bucket — `"OnSave"`, `"OnApprovalAction.Approve"`, etc. Dots create nested branches. |
+| `Entity` | string | The entity name — `"Book"`, `"Recipe"`, `"Fruit"`. Opaque key (not parsed). |
+| `GUID` | string | External GUID for the record. Opaque key (dots are NOT interpreted). |
+| `Property` | string | The field to set on the record. Opaque key. |
+| `Value` | any | The value to write. Strings, numbers, booleans, objects, arrays. |
+
+Successive calls to the same `(Context, Entity, GUID)` **accumulate properties**
+on the same record. Successive calls to the same
+`(Context, Entity, GUID, Property)` **overwrite**.
+
+## The shape it builds
+
+Given these solvers on a Book form:
+
+```js
+"Solvers":
+[
+    `addComprehensionEntity("OnSave", "Book", BookGUID, "Title", BookTitle)`,
+    `addComprehensionEntity("OnSave", "Book", BookGUID, "Author", BookAuthor)`,
+    `addComprehensionEntity("OnSave", "Book", BookGUID, "ISBN", BookISBN)`,
+    `addComprehensionEntity("OnApprovalAction.Submit", "Book", BookGUID, "Status", "Submitted")`,
+    `addComprehensionEntity("OnApprovalAction.Approve", "Book", BookGUID, "Status", "Approved")`
+]
+```
+
+…the destination ends up looking like:
+
+```json
+{
+    "OnSave": {
+        "Book": {
+            "0x73278432987": {
+                "Title": "The Giving Tree",
+                "Author": "Shel Silverstein",
+                "ISBN": "8675309"
+            }
+        }
+    },
+    "OnApprovalAction": {
+        "Submit": {
+            "Book": {
+                "0x73278432987": { "Status": "Submitted" }
+            }
+        },
+        "Approve": {
+            "Book": {
+                "0x73278432987": { "Status": "Approved" }
+            }
+        }
+    }
+}
+```
+
+Every leaf in this tree is a Meadow-shaped record keyed by external GUID — the
+exact format [`load_comprehension`](https://github.com/stevenvelozo/meadow-integration)
+expects.
+
+## Where the result lands
+
+By default the tree is written to `AppData.FormEntityComprehensions`.
+
+The destination is **a manyfest address** resolved against the pict instance, so
+addresses like `AppData.X.Y`, `Bundle.X`, etc. all work. Change it on the
+metacontroller:
+
+```js
+// At any point after the metacontroller is registered (i.e. inside the
+// application's constructor, after super() has run):
+this.pict.views.PictFormMetacontroller.comprehensionDestinationAddress = 'AppData.MyWorkflowComprehensions';
+```
+
+…or pass it in the metacontroller view options if you're constructing the
+metacontroller manually:
+
+```js
+pict.addView('PictFormMetacontroller', { ComprehensionDestinationAddress: 'AppData.MyWorkflowComprehensions' },
+    libPictSectionForm.PictFormMetacontroller);
+```
+
+If the address resolves to nothing, the function materializes an object there on
+the first write. If it resolves to a non-object scalar, the call logs a warning
+and bails (it won't overwrite a number with an object).
+
+## Basic example — flat OnSave context
+
+```js
+"Sections":
+[
+    {
+        "Hash": "BookEditor",
+        "Solvers":
+        [
+            `addComprehensionEntity("OnSave", "Book", BookGUID, "Title", BookTitle)`,
+            `addComprehensionEntity("OnSave", "Book", BookGUID, "Author", BookAuthor)`,
+            `addComprehensionEntity("OnSave", "Book", BookGUID, "Status", "New")`
+        ]
+    }
+]
+```
+
+After a solve, `AppData.FormEntityComprehensions.OnSave.Book[<BookGUID>]` holds
+the three properties.
+
+## Quick gotchas
+
+1. **Empty GUIDs bail.** If any of `Context`, `Entity`, `GUID`, or `Property`
+   resolves to `null`, `undefined`, or the empty string, the call logs a warning
+   and returns `undefined`. Recipes with an empty `RecipeName` will not silently
+   create a `""` bucket — they just no-op until the user fills the name in.
+2. **Solver ordinals.** Solvers run in ascending ordinal order. Put your
+   `addComprehensionEntity` calls *after* any solvers they depend on (e.g. after
+   the `TotalCalories = SUM(...)` aggregate they read from). The complex_table
+   example uses ordinals 200–220 to keep them after the default-ordinal compute
+   solvers.
+3. **Re-solves overwrite.** Each solve re-runs every solver, so each
+   `addComprehensionEntity` call overwrites the property it wrote last time
+   with the current value. This is what you want — the comprehension always
+   reflects the current form state.
+4. **The destination is *not* cleared between solves.** If your form removes a
+   record (e.g. deletes a row from a grid), the previous comprehension for that
+   record stays behind. If that matters for your workflow, reset the destination
+   at the start of the solve cycle (`AppData.FormEntityComprehensions = {}`) or
+   in `marshalFromView` before the comprehension solvers fire.
+
+## Pushing the result
+
+Once the comprehension is built, push it via meadow-integration:
+
+```js
+// Browser-side -- POST the AppData blob directly to the Comprehension/Push REST endpoint.
+fetch('/1.0/Comprehension/Push',
+{
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(
+    {
+        Comprehension: pict.AppData.FormEntityComprehensions.OnSave,
+        GUIDPrefix: 'MYAPP'
+    })
+});
+```
+
+Or write to a file and push from a CLI:
+
+```bash
+npx meadow-integration load_comprehension out.json --prefix MYAPP
+```
+
+See [meadow-integration: Comprehensions](https://github.com/stevenvelozo/meadow-integration/blob/main/docs/comprehensions.md)
+for the full push semantics — GUID marshaling, foreign-key resolution, batch
+upserts, idempotency.
+
+## See also
+
+- [Advanced patterns](Comprehensions_Advanced.md) — mixing hashes and direct
+  addresses, computed contexts, per-row `MAP VAR` generation, customized
+  destinations.
+- [Solvers](Solvers.md) — full solver function reference.
+- The [Complex Table example](../example_applications/complex_table/Complex-Tabular-Application.js)
+  builds a complete `RecipeWorkflowComprehensions` tree with `OnSave` and
+  `OnApprovalAction.{Submit,Approve}` contexts off the Recipe section and the
+  FruitGrid recordset.

package/docs/Comprehensions_Advanced.md

@@ -0,0 +1,295 @@
+# Comprehensions — Advanced patterns
+
+This document goes deeper than [Comprehensions](Comprehensions.md):
+
+- **Hash vs. address arguments** — when to write `BookGUID` (bare symbol),
+  `"AppData.Bundle.BookGUID"` (string address), `getvalue("...")` (explicit
+  lookup), and when to mix them.
+- **Computed contexts** — `IF`/ternary results as the `Context` argument so a
+  single solver routes between `OnApprovalAction.Submit` and
+  `OnApprovalAction.Approve`.
+- **Per-row generation** with `MAP VAR` over a recordset.
+- **Customized destinations** at the metacontroller level.
+- **Resetting between solves**.
+
+The complete worked example for everything here lives at
+[`example_applications/complex_table/Complex-Tabular-Application.js`](../example_applications/complex_table/Complex-Tabular-Application.js)
+— if you only read one thing, read that file. This page explains the *why* behind
+the patterns it uses.
+
+## Argument resolution — hashes, addresses, and quoted strings
+
+The solver expression parser treats each argument to `addComprehensionEntity`
+the same way it would treat any other function argument:
+
+| Argument form | What happens |
+|---|---|
+| `BookGUID` | **Bare symbol** — resolved from the form's manifest. Looked up first by descriptor hash, then by address against the marshal destination. |
+| `Record.GUID` / `AppData.Bundle.X` | **Dotted symbol** — resolved as an address (the parser does NOT need quotes around addresses). |
+| `"OnSave"` / `"Book"` | **Quoted string** — taken literally, no resolution. |
+| `getvalue("AppData.X.Y")` | **Explicit lookup** — useful when you want to force address-resolution semantics on a value built up from other solvers. |
+| `IF(...)` / `CONCAT(...)` | **Nested function call** — the inner function's return value becomes the argument. |
+
+In practice you mix freely:
+
+```js
+"Solvers":
+[
+    // Context and Property are literals; Entity is a literal; GUID and Value
+    // are resolved from form data.
+    `addComprehensionEntity("OnSave", "Book", BookGUID, "Title", BookTitle)`,
+
+    // Same shape, but the GUID and Value come from absolute addresses rather
+    // than descriptor hashes.  Useful if the descriptor hashes haven't been
+    // wired up or the data lives outside the form.
+    `addComprehensionEntity("OnSave", "Book", AppData.SelectedBook.IDBook, "Status", AppData.SelectedBook.Status)`,
+
+    // Pull a value through a getvalue() call -- equivalent to the line above
+    // but with explicit resolution syntax.  Use this form when an inner
+    // expression already produces an address string and you want to evaluate it.
+    `addComprehensionEntity("OnSave", "Book", getvalue("AppData.SelectedBook.IDBook"), "Status", getvalue("AppData.SelectedBook.Status"))`,
+
+    // The property name itself is computed.  CONCAT returns a string, which
+    // becomes the Property argument.
+    `addComprehensionEntity("OnSave", "Book", BookGUID, CONCAT("Field_", FieldType), FieldValue)`
+]
+```
+
+**Rule of thumb:** quote when you want a literal, leave unquoted when you want
+the parser to look the symbol up. The first three arguments are almost always
+literal strings (Context, Entity name) plus one resolved value (GUID); the
+fourth is almost always a literal Property; the fifth is almost always resolved.
+
+## Computed contexts — routing with `IF`
+
+The `Context` argument is a manyfest address. It's also just a string that the
+function uses to walk a nested object — which means a *computed* string works
+fine. The complex_table example routes between `OnApprovalAction.Submit` and
+`OnApprovalAction.Approve` based on a `Proprietary` boolean:
+
+```js
+{ Ordinal: 220, Expression:
+    `addComprehensionEntity(
+        IF(Proprietary, "==", 1, "OnApprovalAction.Submit", "OnApprovalAction.Approve"),
+        "Recipe",
+        RecipeName,
+        "Status",
+        IF(Proprietary, "==", 1, "Submitted", "Approved")
+    )`
+}
+```
+
+Both `Submit` and `Approve` branches sit under `OnApprovalAction`, which lets
+downstream code key off `Object.keys(comprehension.OnApprovalAction)` to discover
+which actions fired this solve.
+
+The same trick scales to richer routing — e.g. context-per-environment:
+
+```js
+`addComprehensionEntity(
+    CONCAT("OnSave.", EnvironmentName),
+    "Recipe", RecipeName, "Status", "Saved"
+)`
+```
+
+This produces `OnSave.Production.Recipe.<name>.Status` or
+`OnSave.Staging.Recipe.<name>.Status` depending on the value of
+`EnvironmentName`.
+
+## Per-row generation with `MAP VAR`
+
+`MAP VAR` iterates a recordset and fires the body expression once per row, with
+the row bound to a name you choose (`row` is the convention). Combined with
+`addComprehensionEntity`, this fans one solver across an entire grid:
+
+```js
+// From complex_table -- the Recipe section's solvers reach into the FruitGrid
+// recordset and emit one OnSave.Fruit.<name>.<property> entry per (fruit, property)
+// pair.  Three MAP VARs produce 3 * N comprehension writes in a single solve.
+{ Ordinal: 210, Expression: `MAP VAR row FROM FruitData.FruityVice : addComprehensionEntity("OnSave", "Fruit", row.name, "Family", row.family)` },
+{ Ordinal: 210, Expression: `MAP VAR row FROM FruitData.FruityVice : addComprehensionEntity("OnSave", "Fruit", row.name, "Order", row.order)` },
+{ Ordinal: 210, Expression: `MAP VAR row FROM FruitData.FruityVice : addComprehensionEntity("OnSave", "Fruit", row.name, "Calories", row.nutritions.calories)` }
+```
+
+Inside the body, `row.X.Y` resolves against each row in turn — so you get
+deep-property access without writing per-row solvers.
+
+After the solve runs against the bundled FruityVice data, the comprehension at
+`AppData.RecipeWorkflowComprehensions.OnSave.Fruit` looks like:
+
+```json
+{
+    "Apple":    { "Family": "Rosaceae",  "Order": "Rosales",  "Calories": "52" },
+    "Banana":   { "Family": "Musaceae",  "Order": "Zingiberales", "Calories": "96" },
+    "Mango":    { "Family": "Anacardiaceae", "Order": "Sapindales",  "Calories": "60" },
+    ...
+}
+```
+
+(49 fruits total in the complex_table dataset.)
+
+If you need one comprehension write per row that touches *every* property of the
+row, you have two reasonable options:
+
+1. Multiple `MAP VAR` solvers, one per property (as above). Clear and easy to
+   audit.
+2. A single helper solver function registered on
+   `DynamicFormSolverBehaviors` that takes a row + property list and calls
+   `addComprehensionEntity` internally. Worth the indirection only if you have
+   many entities with many properties; otherwise just write the explicit
+   `MAP VAR`s.
+
+## Customizing the destination
+
+Each metacontroller has a `comprehensionDestinationAddress` property —
+mirroring the existing `viewMarshalDestination` knob — that controls where
+`addComprehensionEntity` writes. The default is `AppData.FormEntityComprehensions`.
+
+### Option 1: in the application constructor
+
+This is what the [complex_table example](../example_applications/complex_table/Complex-Tabular-Application.js)
+does. After `super()` (which registers the metacontroller view via
+`PictFormApplication`), set the destination directly:
+
+```js
+class MyWorkflowApplication extends libPictSectionForm.PictFormApplication
+{
+    constructor(pFable, pOptions, pServiceHash)
+    {
+        super(pFable, pOptions, pServiceHash);
+        this.pict.views.PictFormMetacontroller.comprehensionDestinationAddress = 'AppData.WorkflowComprehensions';
+    }
+}
+```
+
+### Option 2: via metacontroller options
+
+If you're registering the metacontroller view yourself (no `PictFormApplication`
+parent), pass `ComprehensionDestinationAddress` in the options:
+
+```js
+pict.addView(
+    'PictFormMetacontroller',
+    { ComprehensionDestinationAddress: 'Bundle.PendingWrites' },
+    libPictSectionForm.PictFormMetacontroller
+);
+```
+
+### Option 3: change it mid-flight
+
+The property is a plain string -- reassign whenever you need different
+destinations for different phases:
+
+```js
+// Before fanning the form's solvers, redirect to a transient staging slot.
+this.pict.views.PictFormMetacontroller.comprehensionDestinationAddress = 'TempData.PendingComprehension';
+this.pict.PictApplication.solve();
+const tmpPending = this.pict.TempData.PendingComprehension;
+
+// Promote / discard / inspect tmpPending however you like.
+
+// Switch back to the canonical destination for the next solve.
+this.pict.views.PictFormMetacontroller.comprehensionDestinationAddress = 'AppData.WorkflowComprehensions';
+```
+
+The destination address is resolved against the pict instance, so any subtree
+works (`AppData.*`, `Bundle.*`, `TempData.*`, ...).
+
+## Resetting the tree between solves
+
+`addComprehensionEntity` never deletes keys -- it only writes / overwrites. If
+your form workflow expects "only emit comprehensions for *currently visible*
+records," you need to clear the destination at the start of the solve cycle.
+Two patterns:
+
+### Pattern A: low-ordinal reset solver
+
+```js
+"Solvers":
+[
+    // Runs before any addComprehensionEntity calls because of the explicit
+    // low ordinal.  `getvalue` returns a reference to the live AppData branch,
+    // but assigning to `AppData.X` rebinds the address.  In manyfest assignments
+    // we want to nuke the previous tree, so explicitly empty it.
+    { Ordinal: 1, Expression: `AppData.RecipeWorkflowComprehensions = "{}"` },
+    // ...then the addComprehensionEntity calls at higher ordinals
+]
+```
+
+The string `"{}"` becomes `{}` after JSON round-trip on the assignment. If your
+solver dialect doesn't coerce strings to JSON for you, do the reset in
+JavaScript instead:
+
+### Pattern B: JS-side reset
+
+Override `marshalFromView` or `onBeforeSolve` to zero the destination:
+
+```js
+class MyWorkflowApplication extends libPictSectionForm.PictFormApplication
+{
+    onBeforeSolve()
+    {
+        this.pict.AppData.RecipeWorkflowComprehensions = {};
+        return super.onBeforeSolve();
+    }
+}
+```
+
+This is the simplest version. The `addComprehensionEntity` resolver handles a
+missing-or-emptied destination by re-materializing it on the next write.
+
+## Full reference: the complex_table sample config
+
+The [complex_table example](../example_applications/complex_table/Complex-Tabular-Application.js)
+exercises every pattern on this page in one application. The relevant pieces:
+
+```js
+// Constructor sets a customized destination.
+this.pict.views.PictFormMetacontroller.comprehensionDestinationAddress = 'AppData.RecipeWorkflowComprehensions';
+```
+
+```js
+// Recipe section solvers -- mix of bare-symbol GUID (RecipeName) and address
+// arguments, multiple OnSave properties, MAP VAR fanning over a recordset,
+// and IF-routed OnApprovalAction.
+Solvers:
+[
+    // ...prior compute solvers...
+
+    // OnSave.Recipe.<RecipeName>.<Property> for the recipe-level facts.
+    { Ordinal: 200, Expression: `addComprehensionEntity("OnSave", "Recipe", RecipeName, "Name", RecipeName)` },
+    { Ordinal: 200, Expression: `addComprehensionEntity("OnSave", "Recipe", RecipeName, "Type", RecipeType)` },
+    { Ordinal: 200, Expression: `addComprehensionEntity("OnSave", "Recipe", RecipeName, "Description", RecipeDescription)` },
+    { Ordinal: 200, Expression: `addComprehensionEntity("OnSave", "Recipe", RecipeName, "Inventor", Inventor)` },
+    { Ordinal: 200, Expression: `addComprehensionEntity("OnSave", "Recipe", RecipeName, "TotalCalories", TotalFruitCalories)` },
+    { Ordinal: 200, Expression: `addComprehensionEntity("OnSave", "Recipe", RecipeName, "AverageFatPercent", AverageFatPercent)` },
+
+    // OnSave.Fruit.<fruit>.<Property> -- per-row via MAP VAR over the FruitGrid recordset.
+    { Ordinal: 210, Expression: `MAP VAR row FROM FruitData.FruityVice : addComprehensionEntity("OnSave", "Fruit", row.name, "Family", row.family)` },
+    { Ordinal: 210, Expression: `MAP VAR row FROM FruitData.FruityVice : addComprehensionEntity("OnSave", "Fruit", row.name, "Order", row.order)` },
+    { Ordinal: 210, Expression: `MAP VAR row FROM FruitData.FruityVice : addComprehensionEntity("OnSave", "Fruit", row.name, "Calories", row.nutritions.calories)` },
+
+    // OnApprovalAction.{Submit,Approve}.Recipe.<RecipeName> -- computed context.
+    { Ordinal: 220, Expression: `addComprehensionEntity(IF(Proprietary, "==", 1, "OnApprovalAction.Submit", "OnApprovalAction.Approve"), "Recipe", RecipeName, "Status", IF(Proprietary, "==", 1, "Submitted", "Approved"))` },
+    { Ordinal: 220, Expression: `addComprehensionEntity(IF(Proprietary, "==", 1, "OnApprovalAction.Submit", "OnApprovalAction.Approve"), "Recipe", RecipeName, "Reviewer", Inventor)` }
+]
+```
+
+After loading the example, fill in the Recipe section and toggle the
+Proprietary checkbox; inspect `_Pict.AppData.RecipeWorkflowComprehensions` in
+the browser console to see the OnSave / OnApprovalAction subtrees update.
+
+## Where this stops being the right tool
+
+`addComprehensionEntity` is for shaping comprehension trees inside the
+solver. If you're operating outside the solver loop -- e.g. building a
+comprehension from an HTTP response, transforming CSV, or merging two pre-built
+comprehensions -- reach for the meadow-integration toolchain directly:
+
+- `meadow-integration csvtransform` to map columns into entity records.
+- `meadow-integration comprehensionintersect` to merge two comprehensions.
+- The `Comprehension` object's `Object.assign` semantics for in-code merges.
+
+See [meadow-integration: Comprehensions](https://github.com/stevenvelozo/meadow-integration/blob/main/docs/comprehensions.md)
+for those tools. The solver helper is purpose-built for "as I edit this form,
+build the comprehension that will save it."

package/docs/Pict_Section_Form_Architecture.md

@@ -121,8 +121,8 @@ for export and editing.
 
 ### Marshal Operations
 
-- **toView** (`onMarshalToView`): AppData → Form inputs
-- **fromView** (`onMarshalFromView`): Form inputs → AppData
+- **toView** (`onMarshalToView`): AppData -> Form inputs
+- **fromView** (`onMarshalFromView`): Form inputs -> AppData
 
 The Informary provider handles the actual DOM operations, using data attributes
 to map form elements to their corresponding data addresses.

package/docs/Solvers.md

@@ -96,13 +96,13 @@ Standard mathematical operators are supported:
 
 | Function | Description | Example |
 |----------|-------------|---------|
-| `abs(x)` | Absolute value | `abs(-5)` → 5 |
-| `round(x)` | Round to nearest integer | `round(3.7)` → 4 |
-| `floor(x)` | Round down | `floor(3.7)` → 3 |
-| `ceil(x)` | Round up | `ceil(3.2)` → 4 |
-| `min(a, b)` | Minimum value | `min(5, 3)` → 3 |
-| `max(a, b)` | Maximum value | `max(5, 3)` → 5 |
-| `sqrt(x)` | Square root | `sqrt(16)` → 4 |
+| `abs(x)` | Absolute value | `abs(-5)` -> 5 |
+| `round(x)` | Round to nearest integer | `round(3.7)` -> 4 |
+| `floor(x)` | Round down | `floor(3.7)` -> 3 |
+| `ceil(x)` | Round up | `ceil(3.2)` -> 4 |
+| `min(a, b)` | Minimum value | `min(5, 3)` -> 3 |
+| `max(a, b)` | Maximum value | `max(5, 3)` -> 5 |
+| `sqrt(x)` | Square root | `sqrt(16)` -> 4 |
 
 ### String Functions
 
@@ -111,7 +111,7 @@ Standard mathematical operators are supported:
 | `concat(a, b, ...)` | Concatenate values into a string | `concat('Hello', ' World')` |
 | `join(separator, a, b, ...)` | Join values with a separator | `join(', ', 'a', 'b', 'c')` |
 | `stringgetsegments(s, delimiter)` | Split string into segments | `stringgetsegments('a,b,c', ',')` |
-| `stringcountsegments(s, delimiter)` | Count segments in string | `stringcountsegments('a,b,c', ',')` → 3 |
+| `stringcountsegments(s, delimiter)` | Count segments in string | `stringcountsegments('a,b,c', ',')` -> 3 |
 | `resolvehtmlentities(s)` | Resolve HTML entities in string | `resolvehtmlentities('&')` |
 
 ### Array Aggregation
@@ -222,6 +222,28 @@ aggregate values from arrays:
 | `SetTabularRowLength(hash, length)` | Set the row count for a tabular data set |
 | `RefreshTabularSection(hash)` | Refresh a tabular section display |
 
+### Comprehension Generation
+
+| Function | Description |
+|----------|-------------|
+| `addComprehensionEntity(Context, Entity, GUID, Property, Value)` | Writes a single Property/Value into a nested comprehension tree at `Context -> Entity -> GUID -> Property` in the configured destination (default `AppData.FormEntityComprehensions`). |
+
+The `Context` argument is treated as a manyfest address, so dotted contexts
+like `"OnApprovalAction.Approve"` produce nested context branches. Successive
+calls accumulate properties on the same record. See [Comprehensions](Comprehensions.md)
+for the basic walkthrough and [Comprehensions — Advanced](Comprehensions_Advanced.md)
+for computed contexts, `MAP VAR` patterns, and customized destinations.
+
+#### Comprehension Example
+
+```json
+"Solvers": [
+  "addComprehensionEntity(\"OnSave\", \"Book\", BookGUID, \"Title\", BookTitle)",
+  "addComprehensionEntity(\"OnSave\", \"Book\", BookGUID, \"Author\", BookAuthor)",
+  "addComprehensionEntity(\"OnApprovalAction.Approve\", \"Book\", BookGUID, \"Status\", \"Approved\")"
+]
+```
+
 ### Logging
 
 | Function | Description |
@@ -365,3 +387,5 @@ Use in solvers:
 - [Configuration](Configuration.md) - Solver configuration options
 - [Architecture](Pict_Section_Form_Architecture.md) - Solver system internals
 - [Input Types](Input_Types.md) - Input visibility control
+- [Comprehensions](Comprehensions.md) - `addComprehensionEntity` basics
+- [Comprehensions — Advanced](Comprehensions_Advanced.md) - Computed contexts, `MAP VAR`, customized destinations

package/docs/_brand.json

@@ -0,0 +1,18 @@
+{
+	"Hash": "pict-section-form",
+	"Name": "Pict Section Form",
+	"Tagline": "Configuration-driven dynamic forms with 13+ input types, data marshaling, and mathematical solving",
+	"Palette": "mix",
+	"Icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"frame-pict-section-form-filled-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\" fill=\"#ccb526\"/>\n\t\t<g clip-path=\"url(#frame-pict-section-form-filled-light)\"><defs><mask id=\"_cr_34122\"><rect x=\"0\" y=\"0\" width=\"96\" height=\"96\" fill=\"#fff\"/>\n\t\t\t\t\t\t<circle cx=\"64\" cy=\"48\" r=\"32\" fill=\"#000\"/></mask></defs>\n\t\t\t\t\t<circle cx=\"48\" cy=\"48\" r=\"32\" fill=\"rgba(255,255,255,0.18)\" mask=\"url(#_cr_34122)\"/>\n\t\t\t\t\t<circle cx=\"64\" cy=\"48\" r=\"26\" fill=\"#4bacbc\" opacity=\"0.7\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"28\" font-weight=\"700\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">PSF</text>\n\t</svg>",
+	"IconType": "svg",
+	"Favicon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-pict-section-form-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\" fill=\"#ccb526\"/>\n\t\t<g clip-path=\"url(#fav-pict-section-form-light)\"><circle cx=\"48\" cy=\"48\" r=\"36\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">P</text>\n\t</svg>",
+	"FaviconDark": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-pict-section-form-dark\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\" fill=\"#dece70\"/>\n\t\t<g clip-path=\"url(#fav-pict-section-form-dark)\"><circle cx=\"48\" cy=\"48\" r=\"36\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#101418\" letter-spacing=\"-1\">P</text>\n\t</svg>",
+	"Colors": {
+		"Primary": "#ccb526",
+		"Secondary": "#4bacbc",
+		"PrimaryLight": "#ccb526",
+		"PrimaryDark": "#dece70",
+		"SecondaryLight": "#4bacbc",
+		"SecondaryDark": "#92c8d0"
+	}
+}

package/docs/_cover.md

@@ -1,4 +1,4 @@
-# Pict-Section-Form <small>1</small>
+# Pict-Section-Form
 
 > A dynamic, configuration-driven forms framework built on the Pict application platform
 

package/docs/_sidebar.md

@@ -14,6 +14,8 @@
 - Advanced
 
   - [Solvers](Solvers.md)
+  - [Comprehensions](Comprehensions.md)
+  - [Comprehensions — Advanced](Comprehensions_Advanced.md)
   - [Providers](Providers.md)
 
 - Input Providers

package/docs/_version.json

@@ -0,0 +1,7 @@
+{
+	"Name": "pict-section-form",
+	"Version": "1.0.197",
+	"Description": "Pict dynamic form sections",
+	"GeneratedAt": "2026-05-21T02:52:57.836Z",
+	"GitCommit": "29398f7"
+}

package/docs/examples/README.md

@@ -94,17 +94,17 @@ node ServeExamples.js
 
 | Feature | simple_form | simple_table | simple_distill | gradebook | postcard | complex_table | complex_tuigrid | manyfest_editor |
 |---------|:-----------:|:------------:|:--------------:|:---------:|:--------:|:-------------:|:---------------:|:---------------:|
-| Basic Inputs | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Tabular Layout | | ✓ | | ✓ | | ✓ | | ✓ |
-| TuiGrid | | | | | | | ✓ | ✓ |
-| Solvers | ✓ | | ✓ | | | ✓ | ✓ | |
-| Row Solvers | | | | | | ✓ | ✓ | |
-| Pick Lists | | | ✓ | | | ✓ | ✓ | |
-| Entity Bundles | | | ✓ | | | ✓ | | |
-| Trigger Groups | | | ✓ | | | ✓ | | |
-| localStorage | | | | ✓ | | | | ✓ |
-| Custom Themes | | | | | ✓ | | | |
-| Navigation | | | | | ✓ | | | ✓ |
-| Charts | | | | | | ✓ | | |
-| DateTime | | | | | | ✓ | ✓ | |
-| JSON Editor | | | | | | | | ✓ |
+| Basic Inputs | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
+| Tabular Layout | | [x] | | [x] | | [x] | | [x] |
+| TuiGrid | | | | | | | [x] | [x] |
+| Solvers | [x] | | [x] | | | [x] | [x] | |
+| Row Solvers | | | | | | [x] | [x] | |
+| Pick Lists | | | [x] | | | [x] | [x] | |
+| Entity Bundles | | | [x] | | | [x] | | |
+| Trigger Groups | | | [x] | | | [x] | | |
+| localStorage | | | | [x] | | | | [x] |
+| Custom Themes | | | | | [x] | | | |
+| Navigation | | | | | [x] | | | [x] |
+| Charts | | | | | | [x] | | |
+| DateTime | | | | | | [x] | [x] | |
+| JSON Editor | | | | | | | | [x] |