pict-section-form 1.0.197 → 1.0.198

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

package/docs/README.md

@@ -77,7 +77,7 @@ npm install pict-section-form
 
 - [simple_form](examples/simple_form/) - Basic form with solvers and visibility control
 - [simple_table](examples/simple_table/) - Minimal tabular layout example
-- [gradebook](examples/gradebook/) - Multi-table app with localStorage
+- [gradebook](examples/gradebook/) - Advanced tabular recordsets: stacked headers, row labels, dynamic columns, selection, sorting
 - [complex_table](examples/complex_table/) - Full-featured with charts and entity bundles
 
 ## Related Packages

package/docs/Solvers.md

@@ -211,6 +211,40 @@ aggregate values from arrays:
 ]
 ```
 
+### Tabular Row & Column Styling
+
+These functions style a whole row or whole column of a tabular group — every
+cell across or down. The highlight pair toggles a CSS class on a `1` / `0`
+flag; the color pair sets (`1`) or clears (`0`) an inline background color.
+None of them touch form data — they are purely presentational and re-applied
+on each solve.
+
+| Function | Description |
+|----------|-------------|
+| `HighlightTabularRow(sectionHash, groupHash, rowIndex, flag)` | Add (`1`) / remove (`0`) the `pict-tabular-row-highlight` class on every cell of a row |
+| `HighlightTabularColumn(sectionHash, groupHash, columnIndex, flag)` | Add (`1`) / remove (`0`) the `pict-tabular-column-highlight` class on every cell of a column |
+| `ColorTabularRow(sectionHash, groupHash, rowIndex, color, flag)` | Set (`1`) / clear (`0`) the background color on every cell of a row |
+| `ColorTabularColumn(sectionHash, groupHash, columnIndex, color, flag)` | Set (`1`) / clear (`0`) the background color on every cell of a column |
+
+`rowIndex` is the zero-based row. `columnIndex` is the column's input index
+(its position among the group's descriptors). The highlight classes are
+defined by pict-section-form; their tint follows the
+`--pict-tabular-highlight-color` CSS custom property.
+
+#### Tabular Styling Examples
+
+```json
+"Solvers": [
+  "ColorTabularRow('Performance', 'PerformanceGrid', 0, IF(getSectionTabularFormData('Performance', 'PerformanceGrid', 0, 'Average'), '>=', 85, '#BFE3BF', '#EBB8B8'), 1)",
+  "HighlightTabularColumn('Gradebook', 'GradebookGrid', 4, 1)"
+]
+```
+
+These pair naturally with the `RowSelection` / `ColumnSelection` tabular
+options (see [Layouts](Layouts.md)): the selection state is stored in the form
+data, and a solver can read it and call the highlight/color functions to drive
+presentation.
+
 ### Solver Control Functions
 
 | Function | Description |

package/docs/_version.json

@@ -1,7 +1,7 @@
 {
 	"Name": "pict-section-form",
-	"Version": "1.0.197",
+	"Version": "1.0.198",
 	"Description": "Pict dynamic form sections",
-	"GeneratedAt": "2026-05-21T02:52:57.836Z",
-	"GitCommit": "29398f7"
+	"GeneratedAt": "2026-05-22T01:39:07.526Z",
+	"GitCommit": "6af8e90"
 }

package/docs/examples/README.md

@@ -11,7 +11,7 @@ and patterns.
 | [simple_form](simple_form/) | Basic | Calculated fields, visibility control, solvers |
 | [simple_table](simple_table/) | Basic | Tabular layout, nested data, reference manifests |
 | [simple_distill](simple_distill/) | Intermediate | Entity bundles, trigger groups, templated inputs |
-| [gradebook](gradebook/) | Intermediate | Multiple tables, localStorage persistence |
+| [gradebook](gradebook/) | Intermediate | Stacked headers, row labels, dynamic columns, selection, sorting |
 | [postcard_example](postcard_example/) | Intermediate | Theme switching, navigation, custom providers |
 | [complex_table](complex_table/) | Advanced | Charts, row solvers, entity requests, pick lists |
 | [complex_tuigrid](complex_tuigrid/) | Advanced | TuiGrid, aggregations, DateTime inputs |
@@ -26,7 +26,8 @@ and patterns.
    manifests
 
 ### Intermediate Patterns
-3. **[gradebook](gradebook/)** - Multiple tables with localStorage persistence
+3. **[gradebook](gradebook/)** - Advanced tabular recordsets: stacked headers,
+   row labels, dynamic columns, selection, sorting, and styling solvers
 4. **[postcard_example](postcard_example/)** - Theme system and navigation patterns
 5. **[simple_distill](simple_distill/)** - Entity relationships and trigger groups
 
@@ -97,14 +98,19 @@ node ServeExamples.js
 | 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] | |
+| Solvers | [x] | | [x] | [x] | | [x] | [x] | |
+| Row Solvers | | | | [x] | | [x] | [x] | |
 | Pick Lists | | | [x] | | | [x] | [x] | |
 | Entity Bundles | | | [x] | | | [x] | | |
 | Trigger Groups | | | [x] | | | [x] | | |
-| localStorage | | | | [x] | | | | [x] |
+| localStorage | | | | | | | | [x] |
 | Custom Themes | | | | | [x] | | | |
-| Navigation | | | | | [x] | | | [x] |
+| Navigation | | | | [x] | [x] | | | [x] |
 | Charts | | | | | | [x] | | |
 | DateTime | | | | | | [x] | [x] | |
 | JSON Editor | | | | | | | | [x] |
+| Stacked Headers | | | | [x] | | | | |
+| Row Labels | | | | [x] | | | | |
+| Dynamic Columns | | | | [x] | | | | |
+| Row/Column Selection | | | | [x] | | | | |
+| Column Sorting | | | | [x] | | | | |