pict-section-form 1.0.197 → 1.0.199

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +31 -31
  2. package/docs/Comprehensions.md +1 -1
  3. package/docs/Comprehensions_Advanced.md +3 -3
  4. package/docs/Configuration.md +17 -0
  5. package/docs/Layouts.md +170 -0
  6. package/docs/Pict_Section_Form_Architecture.md +33 -51
  7. package/docs/README.md +0 -7
  8. package/docs/Solvers.md +34 -0
  9. package/docs/Templates.md +20 -28
  10. package/docs/_cover.md +11 -0
  11. package/docs/_playground.json +47 -0
  12. package/docs/_sidebar.md +12 -8
  13. package/docs/_version.json +3 -3
  14. package/docs/examples/README.md +33 -36
  15. package/docs/examples/change_tracking/README.md +191 -0
  16. package/docs/examples/change_tracking/change_tracking.js +6685 -0
  17. package/docs/examples/change_tracking/index.html +65 -0
  18. package/docs/examples/dynamic_analysis/README.md +205 -0
  19. package/docs/examples/dynamic_analysis/dynamic_analysis_application.js +5738 -0
  20. package/docs/examples/dynamic_analysis/index.html +128 -0
  21. package/docs/examples/gradebook/README.md +303 -150
  22. package/docs/examples/gradebook/gradebook_application.min.js +1 -0
  23. package/docs/examples/gradebook/index.html +95 -0
  24. package/docs/examples/ndt_field_test/README.md +212 -0
  25. package/docs/examples/ndt_field_test/index.html +436 -0
  26. package/docs/examples/ndt_field_test/ndt_field_test.js +6725 -0
  27. package/docs/examples/scope_mathematics/README.md +171 -0
  28. package/docs/examples/scope_mathematics/index.html +65 -0
  29. package/docs/examples/scope_mathematics/scope_mathematics.js +6685 -0
  30. package/docs/examples/simple_table/README.md +174 -99
  31. package/docs/examples/simple_table/index.html +65 -0
  32. package/docs/examples/simple_table/simple_tabular_application.min.js +1 -0
  33. package/docs/index.html +2 -2
  34. package/docs/input_providers/009-chart.md +2 -2
  35. package/docs/playground/app.json +4 -0
  36. package/docs/playground/appdata.json +9 -0
  37. package/docs/playground/application.js +58 -0
  38. package/docs/playground/manifest.json +57 -0
  39. package/docs/playground/pict.json +4 -0
  40. package/docs/playground/runtime/pict-application.min.js +2 -0
  41. package/docs/playground/runtime/pict-section-form.min.js +2 -0
  42. package/docs/playground/runtime/pict-section-modal.min.js +2 -0
  43. package/docs/playground/runtime/pict.min.js +12 -0
  44. package/docs/playground.md +93 -0
  45. package/docs/retold-catalog.json +218 -384
  46. package/docs/retold-keyword-index.json +23415 -8129
  47. package/example_applications/change_tracking/package.json +9 -1
  48. package/example_applications/dynamic_analysis/package.json +8 -0
  49. package/example_applications/gradebook/.quackage.json +9 -0
  50. package/example_applications/gradebook/Gradebook-Application.js +441 -0
  51. package/example_applications/gradebook/GradebookData.json +44 -0
  52. package/example_applications/gradebook/html/index.html +95 -0
  53. package/example_applications/gradebook/package.json +34 -0
  54. package/example_applications/ndt_field_test/package.json +8 -0
  55. package/example_applications/scope_mathematics/package.json +9 -1
  56. package/example_applications/simple_table/package.json +9 -1
  57. package/package.json +4 -4
  58. package/source/providers/Pict-Provider-DynamicFormSolverBehaviors.js +200 -1
  59. package/source/providers/Pict-Provider-DynamicTemplates.js +4 -0
  60. package/source/providers/dynamictemplates/Pict-DynamicTemplates-DefaultFormTemplates-ReadOnly.js +4 -4
  61. package/source/providers/dynamictemplates/Pict-DynamicTemplates-DefaultFormTemplates.js +54 -4
  62. package/source/providers/layouts/Pict-Layout-Tabular.js +936 -4
  63. package/source/services/ManifestFactory.js +276 -0
  64. package/source/templates/Pict-Template-TabularEditingControls.js +58 -0
  65. package/source/templates/Pict-Template-TabularRowLabels.js +60 -0
  66. package/test/PictSectionForm-Tabular-Features_tests.js +960 -0
  67. package/docs/examples/complex_table/README.md +0 -163
  68. package/docs/examples/complex_tuigrid/README.md +0 -202
  69. package/docs/examples/manyfest_editor/README.md +0 -200
  70. package/docs/examples/simple_distill/README.md +0 -176
  71. package/docs/examples/simple_form/README.md +0 -143
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # PICT Forms Section
2
2
 
3
+ > **[▶ Read the Pict-Section-Form Documentation](https://stevenvelozo.github.io/pict-section-form/)** — an interactive guide with live, runnable examples and the full API reference.
4
+
3
5
  A Form Section with programmatically definable content. Simple, extensible
4
6
  function APIs for adding groups, rows, entry elements and documentation or
5
7
  user workflow guidance.
@@ -269,33 +271,31 @@ of data in your application.
269
271
 
270
272
  ## Documentation
271
273
 
272
- Comprehensive documentation is available in the [docs](docs/) folder:
274
+ The complete documentation — an interactive guide with live examples — is hosted at **[stevenvelozo.github.io/pict-section-form](https://stevenvelozo.github.io/pict-section-form/)**:
273
275
 
274
276
  | Document | Description |
275
277
  |----------|-------------|
276
- | [Getting Started](docs/Getting_Started.md) | Quick start guide for new users |
277
- | [Architecture](docs/Pict_Section_Form_Architecture.md) | System architecture and design |
278
- | [Configuration](docs/Configuration.md) | Complete configuration reference |
279
- | [Input Types](docs/Input_Types.md) | Available input types |
280
- | [Templates](docs/Templates.md) | Template customization and macros |
281
- | [Solvers](docs/Solvers.md) | Expression solver system |
282
- | [Providers](docs/Providers.md) | Provider reference |
283
- | [Layouts](docs/Layouts.md) | Layout types and customization |
278
+ | [Getting Started](https://stevenvelozo.github.io/pict-section-form/#/page/Getting_Started) | Quick start guide for new users |
279
+ | [Architecture](https://stevenvelozo.github.io/pict-section-form/#/page/Pict_Section_Form_Architecture) | System architecture and design |
280
+ | [Configuration](https://stevenvelozo.github.io/pict-section-form/#/page/Configuration) | Complete configuration reference |
281
+ | [Input Types](https://stevenvelozo.github.io/pict-section-form/#/page/Input_Types) | Available input types |
282
+ | [Templates](https://stevenvelozo.github.io/pict-section-form/#/page/Templates) | Template customization and macros |
283
+ | [Solvers](https://stevenvelozo.github.io/pict-section-form/#/page/Solvers) | Expression solver system |
284
+ | [Providers](https://stevenvelozo.github.io/pict-section-form/#/page/Providers) | Provider reference |
285
+ | [Layouts](https://stevenvelozo.github.io/pict-section-form/#/page/Layouts) | Layout types and customization |
284
286
 
285
287
  ### Example Applications
286
288
 
287
- Working examples demonstrating various features:
289
+ Live, runnable example applications — click to open one in your browser:
288
290
 
289
291
  | Example | Description |
290
292
  |---------|-------------|
291
- | [simple_form](docs/examples/simple_form/) | Basic form with solvers and visibility control |
292
- | [simple_table](docs/examples/simple_table/) | Minimal tabular layout example |
293
- | [simple_distill](docs/examples/simple_distill/) | Entity bundles and trigger groups |
294
- | [gradebook](docs/examples/gradebook/) | Multi-table app with localStorage |
295
- | [postcard_example](docs/examples/postcard_example/) | Theme switching and navigation |
296
- | [complex_table](docs/examples/complex_table/) | Full-featured with charts and entity bundles |
297
- | [complex_tuigrid](docs/examples/complex_tuigrid/) | TuiGrid with aggregations |
298
- | [manyfest_editor](docs/examples/manyfest_editor/) | Meta-configuration editor |
293
+ | [Simple Table](https://stevenvelozo.github.io/pict-section-form/examples/simple_table/) | Tabular layout, reference manifests, and dot-notation access into nested data |
294
+ | [Gradebook](https://stevenvelozo.github.io/pict-section-form/examples/gradebook/) | Stacked headers, row labels, dynamic columns, row/column selection, and sorting |
295
+ | [Scope Mathematics](https://stevenvelozo.github.io/pict-section-form/examples/scope_mathematics/) | Solvers that reach across sections and the global form scope |
296
+ | [Change Tracking](https://stevenvelozo.github.io/pict-section-form/examples/change_tracking/) | A change-detecting solver state machine with bidirectional recompute |
297
+ | [NDT Field Test](https://stevenvelozo.github.io/pict-section-form/examples/ndt_field_test/) | Offline persistence, pick lists, pass/fail row solvers, and charts |
298
+ | [Dynamic Analysis](https://stevenvelozo.github.io/pict-section-form/examples/dynamic_analysis/) | Runtime section injection, solver rewriting, and solver-driven charts |
299
299
 
300
300
  ### Input Providers
301
301
 
@@ -303,19 +303,19 @@ Specialized input handlers for different data types:
303
303
 
304
304
  | Provider | Description |
305
305
  |----------|-------------|
306
- | [Select](docs/input_providers/001-select.md) | Dropdown lists with static/dynamic options |
307
- | [DateTime](docs/input_providers/002-datetime.md) | Date and time picker |
308
- | [Markdown](docs/input_providers/003-markdown.md) | Markdown content display |
309
- | [HTML](docs/input_providers/004-html.md) | Raw HTML content display |
310
- | [PreciseNumber](docs/input_providers/005-precise-number.md) | Formatted numbers with precision |
311
- | [Link](docs/input_providers/006-link.md) | Hyperlink inputs |
312
- | [Templated](docs/input_providers/007-templated.md) | Dynamic template rendering |
313
- | [TemplatedEntityLookup](docs/input_providers/008-templated-entity-lookup.md) | Entity fetch with template display |
314
- | [Chart](docs/input_providers/009-chart.md) | Chart.js visualizations |
315
- | [EntityBundleRequest](docs/input_providers/010-entity-bundle-request.md) | Cascading entity fetches |
316
- | [AutofillTriggerGroup](docs/input_providers/011-autofill-trigger-group.md) | Trigger-based autofill |
317
- | [TabGroupSelector](docs/input_providers/012-tab-group-selector.md) | Tab navigation for groups |
318
- | [TabSectionSelector](docs/input_providers/013-tab-section-selector.md) | Tab navigation for sections |
306
+ | [Select](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/001-select) | Dropdown lists with static/dynamic options |
307
+ | [DateTime](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/002-datetime) | Date and time picker |
308
+ | [Markdown](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/003-markdown) | Markdown content display |
309
+ | [HTML](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/004-html) | Raw HTML content display |
310
+ | [PreciseNumber](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/005-precise-number) | Formatted numbers with precision |
311
+ | [Link](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/006-link) | Hyperlink inputs |
312
+ | [Templated](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/007-templated) | Dynamic template rendering |
313
+ | [TemplatedEntityLookup](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/008-templated-entity-lookup) | Entity fetch with template display |
314
+ | [Chart](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/009-chart) | Chart.js visualizations |
315
+ | [EntityBundleRequest](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/010-entity-bundle-request) | Cascading entity fetches |
316
+ | [AutofillTriggerGroup](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/011-autofill-trigger-group) | Trigger-based autofill |
317
+ | [TabGroupSelector](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/012-tab-group-selector) | Tab navigation for groups |
318
+ | [TabSectionSelector](https://stevenvelozo.github.io/pict-section-form/#/page/input_providers/013-tab-section-selector) | Tab navigation for sections |
319
319
 
320
320
  ## Installation
321
321
 
@@ -175,7 +175,7 @@ upserts, idempotency.
175
175
  addresses, computed contexts, per-row `MAP VAR` generation, customized
176
176
  destinations.
177
177
  - [Solvers](Solvers.md) — full solver function reference.
178
- - The [Complex Table example](../example_applications/complex_table/Complex-Tabular-Application.js)
178
+ - The Complex Table example (`example_applications/complex_table/Complex-Tabular-Application.js`)
179
179
  builds a complete `RecipeWorkflowComprehensions` tree with `OnSave` and
180
180
  `OnApprovalAction.{Submit,Approve}` contexts off the Recipe section and the
181
181
  FruitGrid recordset.
@@ -13,7 +13,7 @@ This document goes deeper than [Comprehensions](Comprehensions.md):
13
13
  - **Resetting between solves**.
14
14
 
15
15
  The complete worked example for everything here lives at
16
- [`example_applications/complex_table/Complex-Tabular-Application.js`](../example_applications/complex_table/Complex-Tabular-Application.js)
16
+ `example_applications/complex_table/Complex-Tabular-Application.js`
17
17
  — if you only read one thing, read that file. This page explains the *why* behind
18
18
  the patterns it uses.
19
19
 
@@ -147,7 +147,7 @@ mirroring the existing `viewMarshalDestination` knob — that controls where
147
147
 
148
148
  ### Option 1: in the application constructor
149
149
 
150
- This is what the [complex_table example](../example_applications/complex_table/Complex-Tabular-Application.js)
150
+ This is what the complex_table example (`example_applications/complex_table/Complex-Tabular-Application.js`)
151
151
  does. After `super()` (which registers the metacontroller view via
152
152
  `PictFormApplication`), set the destination directly:
153
153
 
@@ -240,7 +240,7 @@ missing-or-emptied destination by re-materializing it on the next write.
240
240
 
241
241
  ## Full reference: the complex_table sample config
242
242
 
243
- The [complex_table example](../example_applications/complex_table/Complex-Tabular-Application.js)
243
+ The complex_table example (`example_applications/complex_table/Complex-Tabular-Application.js`)
244
244
  exercises every pattern on this page in one application. The relevant pieces:
245
245
 
246
246
  ```js
@@ -85,6 +85,23 @@ Groups organize inputs within a section.
85
85
  | `CSSClasses` | array | No | CSS classes to apply |
86
86
  | `Visible` | boolean | No | Initial visibility (default: true) |
87
87
 
88
+ #### Tabular Group Properties
89
+
90
+ These additional properties apply only to groups with `Layout: "Tabular"`.
91
+ See [Layouts](Layouts.md) for full details and examples.
92
+
93
+ | Property | Type | Description |
94
+ |----------|------|-------------|
95
+ | `RecordManifest` | string | Reference manifest naming the columns |
96
+ | `Headers` | array | Extra stacked / clustered header rows above the prime header |
97
+ | `RowLabels` | array | Left-side label columns (template / row-number / pre-slotted; clusterable) |
98
+ | `DynamicColumns` | array | Generators that build columns at runtime from another array |
99
+ | `EditingControlsPosition` | string | `"right"` (default), `"left"`, or `"hidden"` |
100
+ | `SuppressDefaultColumnHeaderRow` | boolean | Omit the prime column-name header row |
101
+ | `RowSelection` | boolean/object | Add row checkboxes; selection persists in form data |
102
+ | `ColumnSelection` | boolean/object | Add column checkboxes; selection persists in form data |
103
+ | `ColumnSorting` | boolean | Add clickable sort controls to the prime header cells (default off) |
104
+
88
105
  ### Layout Types
89
106
 
90
107
  - `Record` - Standard form layout with rows and columns
package/docs/Layouts.md CHANGED
@@ -160,6 +160,176 @@ TabularTemplate-RowPostfix
160
160
  TabularTemplate-TablePostfix
161
161
  ```
162
162
 
163
+ ### Stacked & Clustered Headers
164
+
165
+ By default a tabular group has a single header row, one cell per column. The
166
+ optional `Headers` property adds **extra header rows stacked above** that
167
+ default ("prime") row. Each entry in `Headers` is one header row; each row is
168
+ an array of cells.
169
+
170
+ | Cell property | Type | Description |
171
+ |---------------|------|-------------|
172
+ | `Label` | string | Header text |
173
+ | `ColumnSpan` | number | Number of data columns this cell spans (default 1) — this is how you "cluster" |
174
+ | `CSSClass` | string | Optional class applied to the `<th>` |
175
+
176
+ ```json
177
+ {
178
+ "Hash": "GradebookGrid",
179
+ "Layout": "Tabular",
180
+ "RecordSetAddress": "Grades",
181
+ "RecordManifest": "GradeRowEditor",
182
+ "Headers": [
183
+ [
184
+ { "Label": "First Semester", "ColumnSpan": 3, "CSSClass": "term-banner" },
185
+ { "Label": "Second Semester", "ColumnSpan": 4, "CSSClass": "term-banner" }
186
+ ]
187
+ ]
188
+ }
189
+ ```
190
+
191
+ Each header row's `ColumnSpan` total should equal the number of data columns;
192
+ a mismatch is logged as a warning and the header will visually misalign.
193
+ Header rows render top-to-bottom in array order, directly above the prime
194
+ column-name row.
195
+
196
+ ### Row Label Columns
197
+
198
+ The `RowLabels` property adds one or more **label columns down the left side**
199
+ of the table (before the data columns). Each entry describes one label column.
200
+
201
+ | Property | Type | Description |
202
+ |----------|------|-------------|
203
+ | `Name` | string | Header text for the label column |
204
+ | `Template` | string | A Pict template resolved per row — the row record is at `Record.Value`, the row index at `Record.Key` |
205
+ | `RowNumber` | boolean | When `true`, the label is the 1-based row number |
206
+ | `SourceAddress` | string | An app-data address of a pre-slotted array; element `[rowIndex]` is the label |
207
+ | `Cluster` | boolean | When `true`, consecutive equal labels collapse into one cell with `rowspan` |
208
+ | `CSSClass` | string | Optional class applied to the label `<td>` |
209
+
210
+ Provide exactly one of `Template`, `RowNumber`, or `SourceAddress` per entry.
211
+
212
+ ```json
213
+ "RowLabels": [
214
+ { "Name": "Section", "Template": "{~D:Record.Value.Section~}", "Cluster": true },
215
+ { "Name": "Student", "Template": "{~D:Record.Value.StudentName~}" },
216
+ { "Name": "#", "RowNumber": true }
217
+ ]
218
+ ```
219
+
220
+ `Cluster: true` is what produces the "merged cell" look — a column of repeated
221
+ values (e.g. a class section) renders as a single tall cell spanning its run
222
+ of rows. Any label column may be clustered; there is no "prime" label column.
223
+
224
+ ### Dynamic Columns
225
+
226
+ `DynamicColumns` generates table columns at runtime from **another array** in
227
+ the form data — for example, one grade column per assignment. Each entry is a
228
+ generator:
229
+
230
+ | Property | Type | Description |
231
+ |----------|------|-------------|
232
+ | `SourceAddress` | string | App-data address of the array driving the columns |
233
+ | `HashTemplate` | string | Template producing each column's unique descriptor hash |
234
+ | `NameTemplate` | string | Template producing each column's header text |
235
+ | `InformaryDataAddressTemplate` | string | Template producing the per-row data address the cell binds to |
236
+ | `HeaderGroupTemplate` | string | Optional — template producing a cluster label; auto-adds a clustered super-header row |
237
+ | `DataType` | string | Data type for the generated descriptors |
238
+ | `PictForm` | object | `PictForm` block merged onto each generated descriptor (e.g. `InputType`) |
239
+ | `InsertAt` | string/object | `"End"` (default), `"Start"`, or `{ "After": "<hash>" }` |
240
+
241
+ Inside each template the **source row** is the record (`Record.Field`).
242
+
243
+ ```json
244
+ "DynamicColumns": [
245
+ {
246
+ "SourceAddress": "Assignments",
247
+ "HashTemplate": "Grade_{~D:Record.IDAssignment~}",
248
+ "NameTemplate": "{~D:Record.Title~}",
249
+ "InformaryDataAddressTemplate": "Grades.{~D:Record.IDAssignment~}",
250
+ "HeaderGroupTemplate": "{~D:Record.Topic~}",
251
+ "DataType": "Number",
252
+ "PictForm": { "InputType": "Number" }
253
+ }
254
+ ]
255
+ ```
256
+
257
+ Dynamic columns are **non-destructive**: when a source row is removed the
258
+ generated column disappears, but the underlying row data at the
259
+ `InformaryDataAddress` is left untouched — re-adding the source row brings the
260
+ column back with its data intact. The columns re-resolve automatically as the
261
+ source array changes; no manual refresh call is needed.
262
+
263
+ When `HeaderGroupTemplate` is set, an extra clustered super-header row is
264
+ synthesized automatically: consecutive generated columns sharing the same
265
+ header-group value merge into one spanning cell (e.g. assignments clustered by
266
+ topic).
267
+
268
+ ### Editing Controls Position
269
+
270
+ Tabular rows render del / up / down controls. `EditingControlsPosition`
271
+ controls where:
272
+
273
+ | Value | Behavior |
274
+ |-------|----------|
275
+ | `"right"` | Default — controls in a trailing column |
276
+ | `"left"` | Controls in a leading column, before the data columns |
277
+ | `"hidden"` | No editing controls (read-only style table) |
278
+
279
+ ```json
280
+ { "Layout": "Tabular", "EditingControlsPosition": "hidden" }
281
+ ```
282
+
283
+ ### Suppressing the Default Header Row
284
+
285
+ Set `SuppressDefaultColumnHeaderRow: true` to omit the prime column-name row
286
+ entirely — useful when custom `Headers` rows fully describe the columns.
287
+
288
+ ### Selectable Rows & Columns
289
+
290
+ `RowSelection` and `ColumnSelection` add checkboxes that let the user pick
291
+ rows / columns. The selected state is **stored in the form data**, so it
292
+ persists with a save and can be read by solvers.
293
+
294
+ Set either to `true` for defaults, or to an object:
295
+
296
+ | Property | Type | Description |
297
+ |----------|------|-------------|
298
+ | `Enabled` | boolean | Set `false` to disable (same as omitting) |
299
+ | `DataAddress` | string | Where the boolean selection array is stored (default `<GroupHash>_RowSelection` / `_ColumnSelection`) |
300
+ | `HighlightClass` | string | Class auto-applied to selected rows/columns; set to `""` for solver-driven highlighting only |
301
+ | `HeaderLabel` | string | Header text for the row-selection column |
302
+
303
+ ```json
304
+ {
305
+ "Layout": "Tabular",
306
+ "RecordSetAddress": "Grades",
307
+ "RowSelection": true,
308
+ "ColumnSelection": true
309
+ }
310
+ ```
311
+
312
+ Checking a row (or column) highlights every cell across (or down) it and
313
+ writes `true` into the selection array at the configured address. Because the
314
+ array lives in the marshalled form data it round-trips with save / load.
315
+
316
+ ### Column Sorting
317
+
318
+ `ColumnSorting: true` (off by default) injects a clickable sort control — a
319
+ `<span>` carrying a sort SVG glyph from Pict's icon registry — into every
320
+ prime header cell.
321
+
322
+ ```json
323
+ { "Layout": "Tabular", "RecordSetAddress": "Students", "ColumnSorting": true }
324
+ ```
325
+
326
+ Clicking a column's control sorts the record set ascending; clicking the
327
+ active column again toggles to descending. The glyph reflects state: a neutral
328
+ double-arrow on idle columns, an up / down arrow on the active column. Sorting
329
+ works for both static and dynamic columns (dynamic columns sort by their
330
+ `InformaryDataAddress` value). Values that parse as numbers sort numerically;
331
+ others sort lexically.
332
+
163
333
  ## RecordSet Layout
164
334
 
165
335
  Similar to tabular but renders each record as a full form section rather
@@ -32,24 +32,11 @@ The framework follows several key principles:
32
32
 
33
33
  The view layer consists of two primary classes:
34
34
 
35
- ```
36
- ┌─────────────────────────────────────────────────────────────────┐
37
- PictFormMetacontroller
38
- │ - Manages multiple form sections │
39
- │ - Orchestrates data marshaling │
40
- │ - Controls solver execution │
41
- │ - Handles initial bundle loading │
42
- └─────────────────────────────────────────────────────────────────┘
43
-
44
- │ manages
45
-
46
- ┌─────────────────────────────────────────────────────────────────┐
47
- │ PictViewDynamicForm │
48
- │ - Represents a single form section │
49
- │ - Maintains section manifest instance │
50
- │ - Handles input provider lifecycle │
51
- │ - Manages group and row structures │
52
- └─────────────────────────────────────────────────────────────────┘
35
+ ```mermaid
36
+ flowchart TD
37
+ MC["PictFormMetacontroller<br/>• Manages multiple form sections<br/>• Orchestrates data marshaling<br/>• Controls solver execution<br/>• Handles initial bundle loading"]
38
+ DF["PictViewDynamicForm<br/>• Represents a single form section<br/>• Maintains section manifest instance<br/>• Handles input provider lifecycle<br/>• Manages group and row structures"]
39
+ MC -->|manages| DF
53
40
  ```
54
41
 
55
42
  **PictViewDynamicForm** extends `pict-view` and represents a single form section.
@@ -95,29 +82,24 @@ for export and editing.
95
82
 
96
83
  ### Rendering Flow
97
84
 
98
- ```
99
- 1. Application instantiates PictFormMetacontroller
100
- 2. For each Section in manifest:
101
- a. PictViewDynamicForm is created
102
- b. ManifestFactory parses descriptors into groups and rows
103
- c. MetatemplateGenerator creates layout templates
104
- 3. Forms are rendered to DOM using template hierarchy
105
- 4. Solvers are executed (expressions resolve values)
106
- 5. Input providers initialize UI controls
107
- 6. Event handlers attach for changes
108
- ```
85
+ 1. The application instantiates the `PictFormMetacontroller`.
86
+ 2. For each section in the manifest, a `PictViewDynamicForm` is created,
87
+ `ManifestFactory` parses its descriptors into groups and rows, and
88
+ `MetatemplateGenerator` builds the layout templates.
89
+ 3. The forms render to the DOM through the template hierarchy.
90
+ 4. Solvers execute expressions resolve their values.
91
+ 5. Input providers initialize the UI controls.
92
+ 6. Event handlers attach for change detection.
109
93
 
110
94
  ### Data Change Flow
111
95
 
112
- ```
113
- 1. User modifies input value
114
- 2. dataChanged() called on PictViewDynamicForm
115
- 3. Informary marshals specific input from DOM to AppData
116
- 4. Input providers run onDataChange hooks
117
- 5. Application.solve() executes all solvers
118
- 6. Metacontroller marshals all sections back to view
119
- 7. Input providers run onDataMarshalToForm hooks
120
- ```
96
+ 1. The user modifies an input value.
97
+ 2. `dataChanged()` is called on the `PictViewDynamicForm`.
98
+ 3. Informary marshals that input from the DOM into `AppData`.
99
+ 4. Input providers run their `onDataChange` hooks.
100
+ 5. `Application.solve()` executes all solvers.
101
+ 6. The metacontroller marshals every section back to the view.
102
+ 7. Input providers run their `onDataMarshalToForm` hooks.
121
103
 
122
104
  ### Marshal Operations
123
105
 
@@ -131,19 +113,19 @@ to map form elements to their corresponding data addresses.
131
113
 
132
114
  Templates are rendered in a strict hierarchy:
133
115
 
134
- ```
135
- Form Container
136
- └── Section (for each)
137
- ├── Section Prefix
138
- └── Group (for each)
139
- ├── Group Prefix
140
- └── Row (for each)
141
- ├── Row Prefix
142
- ├── Input (for each)
143
- │ └── Input Template (by InputType or DataType)
144
- └── Row Postfix
145
- └── Group Postfix
146
- └── Section Postfix
116
+ ```mermaid
117
+ flowchart TD
118
+ FC["Form Container"] --> S["Section (for each)"]
119
+ S --> SP["Section Prefix"]
120
+ S --> G["Group (for each)"]
121
+ S --> SX["Section Postfix"]
122
+ G --> GP["Group Prefix"]
123
+ G --> R["Row (for each)"]
124
+ G --> GX["Group Postfix"]
125
+ R --> RP["Row Prefix"]
126
+ R --> I["Input (for each)"]
127
+ R --> RX["Row Postfix"]
128
+ I --> IT["Input Template (by InputType or DataType)"]
147
129
  ```
148
130
 
149
131
  Templates support three levels of customization:
package/docs/README.md CHANGED
@@ -73,13 +73,6 @@ npm install pict-section-form
73
73
  - [Providers](Providers.md) - Provider reference
74
74
  - [Layouts](Layouts.md) - Layout types and customization
75
75
 
76
- ## Example Applications
77
-
78
- - [simple_form](examples/simple_form/) - Basic form with solvers and visibility control
79
- - [simple_table](examples/simple_table/) - Minimal tabular layout example
80
- - [gradebook](examples/gradebook/) - Multi-table app with localStorage
81
- - [complex_table](examples/complex_table/) - Full-featured with charts and entity bundles
82
-
83
76
  ## Related Packages
84
77
 
85
78
  - [pict](https://github.com/stevenvelozo/pict) - Core application framework
package/docs/Solvers.md CHANGED
@@ -211,6 +211,40 @@ aggregate values from arrays:
211
211
  ]
212
212
  ```
213
213
 
214
+ ### Tabular Row & Column Styling
215
+
216
+ These functions style a whole row or whole column of a tabular group — every
217
+ cell across or down. The highlight pair toggles a CSS class on a `1` / `0`
218
+ flag; the color pair sets (`1`) or clears (`0`) an inline background color.
219
+ None of them touch form data — they are purely presentational and re-applied
220
+ on each solve.
221
+
222
+ | Function | Description |
223
+ |----------|-------------|
224
+ | `HighlightTabularRow(sectionHash, groupHash, rowIndex, flag)` | Add (`1`) / remove (`0`) the `pict-tabular-row-highlight` class on every cell of a row |
225
+ | `HighlightTabularColumn(sectionHash, groupHash, columnIndex, flag)` | Add (`1`) / remove (`0`) the `pict-tabular-column-highlight` class on every cell of a column |
226
+ | `ColorTabularRow(sectionHash, groupHash, rowIndex, color, flag)` | Set (`1`) / clear (`0`) the background color on every cell of a row |
227
+ | `ColorTabularColumn(sectionHash, groupHash, columnIndex, color, flag)` | Set (`1`) / clear (`0`) the background color on every cell of a column |
228
+
229
+ `rowIndex` is the zero-based row. `columnIndex` is the column's input index
230
+ (its position among the group's descriptors). The highlight classes are
231
+ defined by pict-section-form; their tint follows the
232
+ `--pict-tabular-highlight-color` CSS custom property.
233
+
234
+ #### Tabular Styling Examples
235
+
236
+ ```json
237
+ "Solvers": [
238
+ "ColorTabularRow('Performance', 'PerformanceGrid', 0, IF(getSectionTabularFormData('Performance', 'PerformanceGrid', 0, 'Average'), '>=', 85, '#BFE3BF', '#EBB8B8'), 1)",
239
+ "HighlightTabularColumn('Gradebook', 'GradebookGrid', 4, 1)"
240
+ ]
241
+ ```
242
+
243
+ These pair naturally with the `RowSelection` / `ColumnSelection` tabular
244
+ options (see [Layouts](Layouts.md)): the selection state is stored in the form
245
+ data, and a solver can read it and call the highlight/color functions to drive
246
+ presentation.
247
+
214
248
  ### Solver Control Functions
215
249
 
216
250
  | Function | Description |
package/docs/Templates.md CHANGED
@@ -7,34 +7,26 @@ Templates can be customized at multiple levels to achieve any desired appearance
7
7
 
8
8
  Templates are rendered in a strict hierarchical order:
9
9
 
10
- ```
11
- Form Level
12
- ├── -Template-Form-Container-Header
13
- ├── -Template-Form-Container-Wrap-Prefix
14
-
15
- └── For each Section:
16
- ├── -Template-Form-Container
17
-
18
- └── -Template-Wrap-Prefix
19
- ├── -Template-Section-Prefix
20
-
21
- └── For each Group:
22
- ├── -Template-Group-Prefix
23
-
24
- └── For each Row:
25
- ├── -Template-Row-Prefix
26
- │ ├── For each Input:
27
- │ │ └── -Template-Input-InputType-{type}
28
- │ │ OR -Template-Input-DataType-{type}
29
- │ │ OR -TabularTemplate-*
30
- │ └── -Template-Row-Postfix
31
-
32
- └── -Template-Group-Postfix
33
-
34
- └── -Template-Section-Postfix
35
- └── -Template-Wrap-Postfix
36
-
37
- └── -Template-Form-Container-Wrap-Postfix
10
+ ```mermaid
11
+ flowchart TD
12
+ F["Form Level"]
13
+ F --> FH["-Template-Form-Container-Header"]
14
+ F --> FWP["-Template-Form-Container-Wrap-Prefix"]
15
+ F --> SEC["For each Section"]
16
+ F --> FWX["-Template-Form-Container-Wrap-Postfix"]
17
+ SEC --> TFC["-Template-Form-Container"]
18
+ SEC --> WP["-Template-Wrap-Prefix"]
19
+ SEC --> WX["-Template-Wrap-Postfix"]
20
+ WP --> SP["-Template-Section-Prefix"]
21
+ WP --> GRP["For each Group"]
22
+ WP --> SX["-Template-Section-Postfix"]
23
+ GRP --> GP["-Template-Group-Prefix"]
24
+ GRP --> ROW["For each Row"]
25
+ GRP --> GX["-Template-Group-Postfix"]
26
+ ROW --> RP["-Template-Row-Prefix"]
27
+ ROW --> INP["For each Input"]
28
+ ROW --> RX["-Template-Row-Postfix"]
29
+ INP --> IT["-Template-Input-InputType-… or<br/>-Template-Input-DataType-… or<br/>-TabularTemplate-…"]
38
30
  ```
39
31
 
40
32
  ## Template Resolution
package/docs/_cover.md CHANGED
@@ -9,3 +9,14 @@
9
9
 
10
10
  [GitHub](https://github.com/stevenvelozo/pict-section-form)
11
11
  [Get Started](#pict-section-form)
12
+
13
+ <!-- docuserve:examples:start -->
14
+ | Example | Complexity | Launch |
15
+ |---------|------------|--------|
16
+ | [Change Tracking](examples/change%5Ftracking/README.md) | Intermediate | [&#9654; Launch](examples/change%5Ftracking/index.html) |
17
+ | [Dynamic Analysis](examples/dynamic%5Fanalysis/README.md) | Advanced | [&#9654; Launch](examples/dynamic%5Fanalysis/index.html) |
18
+ | [Gradebook](examples/gradebook/README.md) | Intermediate | [&#9654; Launch](examples/gradebook/index.html) |
19
+ | [NDT Field Test](examples/ndt%5Ffield%5Ftest/README.md) | Advanced | [&#9654; Launch](examples/ndt%5Ffield%5Ftest/index.html) |
20
+ | [Scope Mathematics](examples/scope%5Fmathematics/README.md) | Intermediate | [&#9654; Launch](examples/scope%5Fmathematics/index.html) |
21
+ | [Simple Table](examples/simple%5Ftable/README.md) | Basic | [&#9654; Launch](examples/simple%5Ftable/index.html) |
22
+ <!-- docuserve:examples:end -->
@@ -0,0 +1,47 @@
1
+ {
2
+ "Kind": "section",
3
+ "SectionType": "pict-section-form",
4
+ "ApplicationModule": "PictSectionForm",
5
+ "ApplicationGlobal": "PictFormApplication",
6
+ "ManifestKey": "DefaultFormManifest",
7
+ "Editors":
8
+ [
9
+ {
10
+ "Hash": "manifest",
11
+ "Label": "Form Manifest",
12
+ "Language": "json",
13
+ "DefaultPath": "playground/manifest.json"
14
+ },
15
+ {
16
+ "Hash": "pictConfig",
17
+ "Label": "Pict Config",
18
+ "Language": "json",
19
+ "DefaultPath": "playground/pict.json"
20
+ },
21
+ {
22
+ "Hash": "appConfig",
23
+ "Label": "App Config",
24
+ "Language": "json",
25
+ "DefaultPath": "playground/app.json"
26
+ },
27
+ {
28
+ "Hash": "appData",
29
+ "Label": "Initial AppData",
30
+ "Language": "json",
31
+ "DefaultPath": "playground/appdata.json"
32
+ },
33
+ {
34
+ "Hash": "application",
35
+ "Label": "Application Code",
36
+ "Language": "javascript",
37
+ "DefaultPath": "playground/application.js"
38
+ }
39
+ ],
40
+ "Imports":
41
+ [
42
+ { "Name": "pict", "Source": "local", "Path": "playground/runtime/pict.min.js" },
43
+ { "Name": "pict-application", "Source": "local", "Path": "playground/runtime/pict-application.min.js" },
44
+ { "Name": "pict-section-modal", "Source": "local", "Path": "playground/runtime/pict-section-modal.min.js" },
45
+ { "Name": "pict-section-form", "Source": "local", "Path": "playground/runtime/pict-section-form.min.js" }
46
+ ]
47
+ }