pict-section-form 1.0.196 → 1.0.198

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/Configuration.md

@@ -85,6 +85,23 @@ Groups organize inputs within a section.
 | `CSSClasses` | array | No | CSS classes to apply |
 | `Visible` | boolean | No | Initial visibility (default: true) |
 
+#### Tabular Group Properties
+
+These additional properties apply only to groups with `Layout: "Tabular"`.
+See [Layouts](Layouts.md) for full details and examples.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `RecordManifest` | string | Reference manifest naming the columns |
+| `Headers` | array | Extra stacked / clustered header rows above the prime header |
+| `RowLabels` | array | Left-side label columns (template / row-number / pre-slotted; clusterable) |
+| `DynamicColumns` | array | Generators that build columns at runtime from another array |
+| `EditingControlsPosition` | string | `"right"` (default), `"left"`, or `"hidden"` |
+| `SuppressDefaultColumnHeaderRow` | boolean | Omit the prime column-name header row |
+| `RowSelection` | boolean/object | Add row checkboxes; selection persists in form data |
+| `ColumnSelection` | boolean/object | Add column checkboxes; selection persists in form data |
+| `ColumnSorting` | boolean | Add clickable sort controls to the prime header cells (default off) |
+
 ### Layout Types
 
 - `Record` - Standard form layout with rows and columns

package/docs/Layouts.md

@@ -160,6 +160,176 @@ TabularTemplate-RowPostfix
 TabularTemplate-TablePostfix
 ```
 
+### Stacked & Clustered Headers
+
+By default a tabular group has a single header row, one cell per column. The
+optional `Headers` property adds **extra header rows stacked above** that
+default ("prime") row. Each entry in `Headers` is one header row; each row is
+an array of cells.
+
+| Cell property | Type | Description |
+|---------------|------|-------------|
+| `Label` | string | Header text |
+| `ColumnSpan` | number | Number of data columns this cell spans (default 1) — this is how you "cluster" |
+| `CSSClass` | string | Optional class applied to the `<th>` |
+
+```json
+{
+  "Hash": "GradebookGrid",
+  "Layout": "Tabular",
+  "RecordSetAddress": "Grades",
+  "RecordManifest": "GradeRowEditor",
+  "Headers": [
+    [
+      { "Label": "First Semester", "ColumnSpan": 3, "CSSClass": "term-banner" },
+      { "Label": "Second Semester", "ColumnSpan": 4, "CSSClass": "term-banner" }
+    ]
+  ]
+}
+```
+
+Each header row's `ColumnSpan` total should equal the number of data columns;
+a mismatch is logged as a warning and the header will visually misalign.
+Header rows render top-to-bottom in array order, directly above the prime
+column-name row.
+
+### Row Label Columns
+
+The `RowLabels` property adds one or more **label columns down the left side**
+of the table (before the data columns). Each entry describes one label column.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Name` | string | Header text for the label column |
+| `Template` | string | A Pict template resolved per row — the row record is at `Record.Value`, the row index at `Record.Key` |
+| `RowNumber` | boolean | When `true`, the label is the 1-based row number |
+| `SourceAddress` | string | An app-data address of a pre-slotted array; element `[rowIndex]` is the label |
+| `Cluster` | boolean | When `true`, consecutive equal labels collapse into one cell with `rowspan` |
+| `CSSClass` | string | Optional class applied to the label `<td>` |
+
+Provide exactly one of `Template`, `RowNumber`, or `SourceAddress` per entry.
+
+```json
+"RowLabels": [
+  { "Name": "Section", "Template": "{~D:Record.Value.Section~}", "Cluster": true },
+  { "Name": "Student", "Template": "{~D:Record.Value.StudentName~}" },
+  { "Name": "#", "RowNumber": true }
+]
+```
+
+`Cluster: true` is what produces the "merged cell" look — a column of repeated
+values (e.g. a class section) renders as a single tall cell spanning its run
+of rows. Any label column may be clustered; there is no "prime" label column.
+
+### Dynamic Columns
+
+`DynamicColumns` generates table columns at runtime from **another array** in
+the form data — for example, one grade column per assignment. Each entry is a
+generator:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `SourceAddress` | string | App-data address of the array driving the columns |
+| `HashTemplate` | string | Template producing each column's unique descriptor hash |
+| `NameTemplate` | string | Template producing each column's header text |
+| `InformaryDataAddressTemplate` | string | Template producing the per-row data address the cell binds to |
+| `HeaderGroupTemplate` | string | Optional — template producing a cluster label; auto-adds a clustered super-header row |
+| `DataType` | string | Data type for the generated descriptors |
+| `PictForm` | object | `PictForm` block merged onto each generated descriptor (e.g. `InputType`) |
+| `InsertAt` | string/object | `"End"` (default), `"Start"`, or `{ "After": "<hash>" }` |
+
+Inside each template the **source row** is the record (`Record.Field`).
+
+```json
+"DynamicColumns": [
+  {
+    "SourceAddress": "Assignments",
+    "HashTemplate": "Grade_{~D:Record.IDAssignment~}",
+    "NameTemplate": "{~D:Record.Title~}",
+    "InformaryDataAddressTemplate": "Grades.{~D:Record.IDAssignment~}",
+    "HeaderGroupTemplate": "{~D:Record.Topic~}",
+    "DataType": "Number",
+    "PictForm": { "InputType": "Number" }
+  }
+]
+```
+
+Dynamic columns are **non-destructive**: when a source row is removed the
+generated column disappears, but the underlying row data at the
+`InformaryDataAddress` is left untouched — re-adding the source row brings the
+column back with its data intact. The columns re-resolve automatically as the
+source array changes; no manual refresh call is needed.
+
+When `HeaderGroupTemplate` is set, an extra clustered super-header row is
+synthesized automatically: consecutive generated columns sharing the same
+header-group value merge into one spanning cell (e.g. assignments clustered by
+topic).
+
+### Editing Controls Position
+
+Tabular rows render del / up / down controls. `EditingControlsPosition`
+controls where:
+
+| Value | Behavior |
+|-------|----------|
+| `"right"` | Default — controls in a trailing column |
+| `"left"` | Controls in a leading column, before the data columns |
+| `"hidden"` | No editing controls (read-only style table) |
+
+```json
+{ "Layout": "Tabular", "EditingControlsPosition": "hidden" }
+```
+
+### Suppressing the Default Header Row
+
+Set `SuppressDefaultColumnHeaderRow: true` to omit the prime column-name row
+entirely — useful when custom `Headers` rows fully describe the columns.
+
+### Selectable Rows & Columns
+
+`RowSelection` and `ColumnSelection` add checkboxes that let the user pick
+rows / columns. The selected state is **stored in the form data**, so it
+persists with a save and can be read by solvers.
+
+Set either to `true` for defaults, or to an object:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Enabled` | boolean | Set `false` to disable (same as omitting) |
+| `DataAddress` | string | Where the boolean selection array is stored (default `<GroupHash>_RowSelection` / `_ColumnSelection`) |
+| `HighlightClass` | string | Class auto-applied to selected rows/columns; set to `""` for solver-driven highlighting only |
+| `HeaderLabel` | string | Header text for the row-selection column |
+
+```json
+{
+  "Layout": "Tabular",
+  "RecordSetAddress": "Grades",
+  "RowSelection": true,
+  "ColumnSelection": true
+}
+```
+
+Checking a row (or column) highlights every cell across (or down) it and
+writes `true` into the selection array at the configured address. Because the
+array lives in the marshalled form data it round-trips with save / load.
+
+### Column Sorting
+
+`ColumnSorting: true` (off by default) injects a clickable sort control — a
+`<span>` carrying a sort SVG glyph from Pict's icon registry — into every
+prime header cell.
+
+```json
+{ "Layout": "Tabular", "RecordSetAddress": "Students", "ColumnSorting": true }
+```
+
+Clicking a column's control sorts the record set ascending; clicking the
+active column again toggles to descending. The glyph reflects state: a neutral
+double-arrow on idle columns, an up / down arrow on the active column. Sorting
+works for both static and dynamic columns (dynamic columns sort by their
+`InformaryDataAddress` value). Values that parse as numbers sort numerically;
+others sort lexically.
+
 ## RecordSet Layout
 
 Similar to tabular but renders each record as a full form section rather