pict-section-form 1.3.14 → 1.3.16

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 (80) hide show
  1. package/docs/Injection_Conformance.md +137 -0
  2. package/docs/Providers.md +12 -7
  3. package/docs/_sidebar.md +3 -0
  4. package/docs/input_providers/016-facet-filter.md +106 -0
  5. package/docs/input_providers/README.md +1 -0
  6. package/example_applications/README.md +6 -0
  7. package/example_applications/facet_filter/.quackage.json +9 -0
  8. package/example_applications/facet_filter/Facet-Filter-Application.js +210 -0
  9. package/example_applications/facet_filter/Facet-Filter-Server.js +233 -0
  10. package/example_applications/facet_filter/Facet-Filter-Smoke-Runner.js +101 -0
  11. package/example_applications/facet_filter/FacetFilterData.json +44 -0
  12. package/example_applications/facet_filter/README-FacetFilter.md +70 -0
  13. package/example_applications/facet_filter/html/Facet-Filter-Smoke.js +128 -0
  14. package/example_applications/facet_filter/html/index.html +74 -0
  15. package/example_applications/facet_filter/package.json +27 -0
  16. package/example_applications/nested_distill_sandbox/Sandbox-Driver-Headlight.js +17 -0
  17. package/example_applications/nested_distill_sandbox/Sandbox-Driver.js +369 -0
  18. package/example_applications/nested_distill_sandbox/Sandbox-Runner.js +372 -0
  19. package/example_applications/nested_distill_sandbox/approaches/A1-tabular-trigger-group.js +67 -0
  20. package/example_applications/nested_distill_sandbox/approaches/A3-crossmap-selectoptionsrefresh.js +61 -0
  21. package/example_applications/nested_distill_sandbox/approaches/A4-graph-solvers-flat-list.js +53 -0
  22. package/example_applications/nested_distill_sandbox/approaches/A5-facet-filter.js +75 -0
  23. package/example_applications/nested_distill_sandbox/approaches/A5b-facet-filter-symmetric.js +15 -0
  24. package/example_applications/nested_distill_sandbox/approaches/A5h-facet-filter-headlight-picker.js +15 -0
  25. package/example_applications/nested_distill_sandbox/approaches/R0-original-jmf-manifest-headlight.js +27 -0
  26. package/example_applications/nested_distill_sandbox/approaches/R1-real-jmf-manifest-headlight.js +136 -0
  27. package/example_applications/nested_distill_sandbox/approaches/_Common.js +344 -0
  28. package/example_applications/nested_distill_sandbox/approaches/_Scenarios.js +262 -0
  29. package/package.json +6 -5
  30. package/source/providers/Pict-Provider-DynamicFormSolverBehaviors.js +73 -5
  31. package/source/providers/Pict-Provider-DynamicSolver.js +22 -2
  32. package/source/providers/Pict-Provider-ListDistilling.js +266 -1
  33. package/source/providers/Pict-Provider-MetaLists.js +16 -2
  34. package/source/providers/inputs/Pict-Provider-Input-FacetFilter.js +232 -0
  35. package/source/providers/inputs/Pict-Provider-Input-Select.js +41 -1
  36. package/source/views/Pict-View-Form-Metacontroller.js +690 -93
  37. package/test/Pict-Provider-DynamicFormSolverBehaviors-OrdinalScope_tests.js +105 -0
  38. package/test/Pict-Provider-ListDistilling-Facet_tests.js +375 -0
  39. package/test/Pict-View-Form-Metacontroller-DistinctManifest_tests.js +410 -0
  40. package/test/PictSectionForm-Injection-Conformance_tests.js +762 -0
  41. package/test/browser/Injection-Conformance-Differential-Scenario.js +346 -0
  42. package/test/browser/Injection-Conformance-EdgeCase-Scenario.js +168 -0
  43. package/test/browser/Injection-Conformance-Harness-Driver.js +538 -0
  44. package/test/browser/Injection-Conformance-Harness-Runner.js +487 -0
  45. package/test/browser/Injection-Conformance-Reconstitution-Scenario.js +191 -0
  46. package/test/browser/Injection-Conformance-Standalone-Scenario.js +114 -0
  47. package/test/fixtures/injection/Injection-Fixture-Cases.js +204 -0
  48. package/test/fixtures/injection/Injection-Fixture-Manifest.json +381 -0
  49. package/types/source/providers/Pict-Provider-DynamicFormSolverBehaviors.d.ts +110 -1
  50. package/types/source/providers/Pict-Provider-DynamicFormSolverBehaviors.d.ts.map +1 -1
  51. package/types/source/providers/Pict-Provider-DynamicSolver.d.ts.map +1 -1
  52. package/types/source/providers/Pict-Provider-DynamicTabularData.d.ts +17 -1
  53. package/types/source/providers/Pict-Provider-DynamicTabularData.d.ts.map +1 -1
  54. package/types/source/providers/Pict-Provider-InputExtension.d.ts +31 -0
  55. package/types/source/providers/Pict-Provider-InputExtension.d.ts.map +1 -1
  56. package/types/source/providers/Pict-Provider-ListDistilling.d.ts +90 -1
  57. package/types/source/providers/Pict-Provider-ListDistilling.d.ts.map +1 -1
  58. package/types/source/providers/Pict-Provider-MetaLists.d.ts.map +1 -1
  59. package/types/source/providers/inputs/Pict-Provider-Input-Chart-CSS.d.ts +16 -0
  60. package/types/source/providers/inputs/Pict-Provider-Input-Chart-CSS.d.ts.map +1 -0
  61. package/types/source/providers/inputs/Pict-Provider-Input-Chart.d.ts +47 -0
  62. package/types/source/providers/inputs/Pict-Provider-Input-Chart.d.ts.map +1 -1
  63. package/types/source/providers/inputs/Pict-Provider-Input-Diagram.d.ts +86 -0
  64. package/types/source/providers/inputs/Pict-Provider-Input-Diagram.d.ts.map +1 -1
  65. package/types/source/providers/inputs/Pict-Provider-Input-FacetFilter.d.ts +103 -0
  66. package/types/source/providers/inputs/Pict-Provider-Input-FacetFilter.d.ts.map +1 -0
  67. package/types/source/providers/inputs/Pict-Provider-Input-ObjectEditor.d.ts +128 -0
  68. package/types/source/providers/inputs/Pict-Provider-Input-ObjectEditor.d.ts.map +1 -0
  69. package/types/source/providers/inputs/Pict-Provider-Input-PreciseNumber.d.ts.map +1 -1
  70. package/types/source/providers/inputs/Pict-Provider-Input-Select.d.ts +12 -0
  71. package/types/source/providers/inputs/Pict-Provider-Input-Select.d.ts.map +1 -1
  72. package/types/source/providers/inputs/Pict-Provider-Input-TabGroupSelector.d.ts +10 -1
  73. package/types/source/providers/inputs/Pict-Provider-Input-TabGroupSelector.d.ts.map +1 -1
  74. package/types/source/providers/inputs/Pict-Provider-Input-TabSectionSelector.d.ts +10 -1
  75. package/types/source/providers/inputs/Pict-Provider-Input-TabSectionSelector.d.ts.map +1 -1
  76. package/types/source/providers/layouts/Pict-Layout-Tabular.d.ts +76 -4
  77. package/types/source/providers/layouts/Pict-Layout-Tabular.d.ts.map +1 -1
  78. package/types/source/views/Pict-View-DynamicForm.d.ts.map +1 -1
  79. package/types/source/views/Pict-View-Form-Metacontroller.d.ts +63 -2
  80. package/types/source/views/Pict-View-Form-Metacontroller.d.ts.map +1 -1
@@ -0,0 +1,137 @@
1
+ # Injection Conformance
2
+
3
+ A manifest can be injected into a running form more than once. `PictFormMetacontroller.createDistinctManifest()`
4
+ salts each copy -- section, group and input hashes get the salt appended, data addresses get nested under it --
5
+ so that every copy owns its own data. Every reference the manifest makes to itself has to be translated with
6
+ it, and every reference it makes to something outside itself has to be left alone.
7
+
8
+ The injection conformance fixture is how that stays true. It is one manifest that uses every construct the
9
+ injector has to translate, injected twice into a host form that deliberately holds same-named data at the
10
+ unsalted root, so a copy that reads or writes the wrong place is visible immediately.
11
+
12
+ ## The two tiers
13
+
14
+ | | Data tier | Browser tier |
15
+ |---|---|---|
16
+ | File | `test/PictSectionForm-Injection-Conformance_tests.js` | `test/browser/` |
17
+ | Runs with | `npm test` (always) | `npm run test:injection` |
18
+ | Needs | nothing beyond the test dependencies | a chrome-family browser (`CHROME_BIN` overrides) |
19
+ | Asserts | fixture coverage, that a salted copy names nothing of its own by its unsalted name, and a data round trip through the view API: data in, solve, read back, write through the view, re-render | what needs a painted page: charts, tab switching, solver-driven visibility, templated rendering, trigger groups driven by real change events, the unsalted root after all of it, and that a form rebuilt from its saved data matches the one that was filled in |
20
+
21
+ `browser-env` gives the data tier a DOM object model but does not paint: views render, macros and selectors
22
+ are built, but no input elements land in the document. That is why the always-on tier round trips through the
23
+ view data API (`setDataByInput`, `marshalToView`, `render`) and the browser tier owns everything that needs
24
+ real elements and real events.
25
+
26
+ The browser tier runs three scenarios. The edge case scenario injects the fixture twice with two salts that
27
+ share a prefix (`alpha`, `alphabeta`) and asserts what each copy should hold. The differential scenario needs
28
+ no expected values and works for any manifest: it loads the same manifest as a pair of copies, then each copy
29
+ alone, and compares -- a copy that reads or writes outside its own subtree computes differently next to a
30
+ sibling than it does alone. The reconstitution scenario answers a different question: it fills the copies in,
31
+ publishes the data a host would save, then boots a second page from nothing but that saved data and injects
32
+ the same copies again, the way reopening a saved form does. The two runs have to agree on every copy's data,
33
+ on what is hidden, on chart contents and on what each input displays; a disagreement means a saved form reads
34
+ back differently from the one that was filled in.
35
+
36
+ Both scenarios take either one `Manifest` for every salt, or a `Manifests` array carrying a different manifest
37
+ per salt -- so a form holding several different injected manifests is exercised the same way as one holding
38
+ two copies of a single manifest. Manifests that share input names (as sibling manifests generated from one
39
+ template usually do) are the interesting case, because that is where a copy can reach into its neighbour.
40
+
41
+ Both are also libraries: `require()` the runner and call `runDifferential` / `runReconstitution` with any
42
+ manifest, which is how a host application runs its own manifests through the same checks without those
43
+ manifests having to live here.
44
+
45
+ ## Adding a case
46
+
47
+ 1. Add the input to `test/fixtures/injection/Injection-Fixture-Manifest.json`, in the `Inputs` or `Composed`
48
+ section, configured the way the input type is meant to be used.
49
+ 2. Add a case to `INPUT_CASES` in `test/fixtures/injection/Injection-Fixture-Cases.js`:
50
+
51
+ ```js
52
+ { Registry: 'InputType:TextArea', Hash: 'NoteText', Tier: 'data', Marshals: true, Accepts: true, Value: 'a crate note' },
53
+ ```
54
+
55
+ * `Registry` is `InputType:<name>` for a type the metatemplates dispatch on, or `Provider:<name>` for an
56
+ input provider an input opts into through `PictForm.Providers`.
57
+ * `Tier` is `data` when the round trip can be asserted without a browser, `browser` when it needs a painted
58
+ page, and `expression` when the input cannot round trip at all in a test (it gathers from a server, or
59
+ needs a third party editing surface) -- then only its salted configuration is asserted. A case that is
60
+ not on the data tier carries a `Note` saying why.
61
+ * `Marshals` is whether data reaches the control, `Accepts` whether a write through the control reaches the
62
+ data, and `Value` is what the round trip writes.
63
+ 3. If the input type genuinely needs no case, add it to `EXCLUDED_REGISTRY_ENTRIES` with the reason. An input
64
+ type that is only reached through another one (`Select` through `InputType:Option`) belongs here.
65
+
66
+ Keep the fixture's vocabulary neutral: it is a crate of fruit, not anything from a product that uses the
67
+ library.
68
+
69
+ ## What a coverage failure means
70
+
71
+ The coverage suite measures the fixture against the library's own registries rather than against a list
72
+ someone has to remember to update.
73
+
74
+ **"every input type and input provider in the library has a fixture case"** -- the metatemplates
75
+ (`source/providers/dynamictemplates/`) dispatch on an `InputType` that no case names, or a provider file
76
+ appeared in `source/providers/inputs/`. Add a case, or an explained exclusion.
77
+
78
+ **"every construct the injector translates appears in the fixture manifest"** -- `createDistinctManifest`
79
+ translates a `PictForm` property the fixture never uses. The list comes from `InjectionTranslation`, exported
80
+ by `source/views/Pict-View-Form-Metacontroller.js`, which is the same list the translation itself runs off; if
81
+ you taught the injector about a new property, the fixture has to exercise it.
82
+
83
+ **"every solver directive is used by the fixture manifest"** -- the fixture has no solver using a directive
84
+ the injector knows how to scope (`SERIES`, `MAP`, `MULTIROWMAP`, `MONTECARLO`). A directive that cannot be
85
+ asserted in a fixture (`MONTECARLO` samples at random) is declared in `EXCLUDED_SOLVER_DIRECTIVES` with the
86
+ reason and is asserted at the expression level instead.
87
+
88
+ **"every reference shape ... appears in the fixture manifest"** -- `REFERENCE_SHAPES` lists the ways a solver
89
+ can name something of its own: an exact symbol, a state address, `X.length`, `X[0]`, `X[].Column`, a nested
90
+ property, a marshal-destination-prefixed string, a hash passed as a string parameter, a string literal that
91
+ merely looks like a hash, and a reference to something outside the manifest. Each has to appear in a fixture
92
+ solver.
93
+
94
+ **"no section, group or input of an injected copy holds an untranslated reference"** -- this is the check that
95
+ catches a construct nobody thought about. It walks the salted copy, reads solver expressions with the
96
+ expression parser (so an iteration variable a directive declares, a string literal that is not an address
97
+ parameter, and the columns a record set solver reads are not mistaken for references) and scans every other
98
+ string for a name the manifest owns. When it fails, either translate the construct in `createDistinctManifest`,
99
+ or -- if the property is prose or presentation and cannot name anything -- add it to `LABEL_PROPERTIES` in the
100
+ cases file.
101
+
102
+ ## Known open behavior
103
+
104
+ These are properties of injection itself rather than of the translation. They are declared in `KNOWN_OPEN` in
105
+ the cases file and both tiers print them rather than failing on them:
106
+
107
+ * **Undeclared solver targets.** A solver can assign to a name no descriptor declares, and the expression
108
+ parser assigns an expression that has no assignment of its own to `Result`. Neither is nested into the copy,
109
+ so copies share them.
110
+
111
+ ## Trigger groups
112
+
113
+ A trigger group hash is salted with the rest of the copy, so a change in one copy runs only that copy's
114
+ trigger groups. Every carrier is salted together -- a group configuration (`AutofillTriggerGroup`,
115
+ `TemplatedEntityLookup`, `TabularTriggerGroup`) and a bare hash (`TriggerGroupHash`,
116
+ `EntityBundleTriggerGroup`) -- because both sides of a trigger read the hash from their own configuration, so
117
+ salting one side and not the other leaves the group silently dead.
118
+
119
+ A manifest that means to hear the form it is injected into lists those hashes in `SharedTriggerGroups` at its
120
+ root, and they are left unsalted:
121
+
122
+ ```json
123
+ { "Scope": "Crate", "SharedTriggerGroups": [ "HostCrateChange" ], "Sections": [] }
124
+ ```
125
+
126
+ A host with input providers of its own carries its trigger group hashes in properties this library knows
127
+ nothing about. It adds them to the carrier lists on the metacontroller, before anything is injected:
128
+
129
+ ```javascript
130
+ pict.views.PictFormMetacontroller.injectionTriggerGroupProperties.push('MyGroupConfiguration');
131
+ pict.views.PictFormMetacontroller.injectionTriggerGroupHashProperties.push('MyTriggerGroupHash');
132
+ ```
133
+
134
+ Not declared in `KNOWN_OPEN`, because neither tier exercises it: the library has no way to remove an injected
135
+ copy. Injection appends the copy's sections, descriptors and (translated, de-duplicated) `ValidationSolvers`
136
+ to the form's manifest; a host that tears a copy down again has to take its validation solvers out of
137
+ `manifestDescription.ValidationSolvers` too, or they keep running against the removed copy's data.
package/docs/Providers.md CHANGED
@@ -207,6 +207,10 @@ Manages dynamic list definitions for select inputs.
207
207
  - Provides dynamic list generation
208
208
  - Manages list refresh
209
209
 
210
+ **PickList keys:** `Hash`, `ListAddress`, `ListSourceAddress` (read from the form data, or from application
211
+ state with `ListSourceAddressGlobal: true`), `IDTemplate`, `TextTemplate`, `Unique`, `Sorted`, and
212
+ `SkipEmpty` (skip records whose id or text renders empty without logging them).
213
+
210
214
  **Key Methods:**
211
215
 
212
216
  ```javascript
@@ -222,20 +226,20 @@ pict.providers.MetaLists.setList('StatusCodes', [
222
226
 
223
227
  ### ListDistilling
224
228
 
225
- Filters lists based on rules and conditions.
229
+ Filters a select input's options by the `ListFilterRules` on its descriptor.
226
230
 
227
231
  **Hash:** `ListDistilling`
228
232
 
229
- **Responsibilities:**
230
- - Applies filter rules to lists
231
- - Manages dependent list relationships
232
- - Handles cascading list updates
233
+ **Rule types:** `Explicit` (compare each option to one value), `CrossMap` (keep options a join list maps to
234
+ another value), `Facet` (options drawn from a shared record list, narrowed by the other inputs of the same
235
+ row -- see [FacetFilter](input_providers/016-facet-filter.md)), or the hash of a provider with its own
236
+ `filterList`.
233
237
 
234
238
  **Key Methods:**
235
239
 
236
240
  ```javascript
237
- // Distill a list based on rules
238
- const filtered = pict.providers.ListDistilling.distillList(sourceList, rules, context);
241
+ // Filter a list of { id, text } options for an input; pass the row index for a tabular input.
242
+ const filtered = pict.providers.ListDistilling.filterList(view, input, options, rowIndex);
239
243
  ```
240
244
 
241
245
  ### DataBroker
@@ -293,6 +297,7 @@ Input extension providers handle specific input types. They all extend
293
297
  | `Pict-Input-EntityBundleRequest` | EntityBundleRequest | Entity loading |
294
298
  | `Pict-Input-AutofillTriggerGroup` | AutofillTriggerGroup | Auto-fill |
295
299
  | `Pict-Input-TemplatedEntityLookup` | TemplatedEntityLookup | Entity lookup |
300
+ | `Pict-Input-FacetFilter` | (any select) | Keeps facet dropdowns consistent on change |
296
301
 
297
302
  ## Creating Custom Providers
298
303
 
package/docs/_sidebar.md CHANGED
@@ -17,6 +17,7 @@
17
17
  - [Comprehensions](Comprehensions.md)
18
18
  - [Comprehensions - Advanced](Comprehensions_Advanced.md)
19
19
  - [Providers](Providers.md)
20
+ - [Injection Conformance](Injection_Conformance.md)
20
21
 
21
22
  - Playground
22
23
 
@@ -41,6 +42,8 @@
41
42
  - [RichText](input_providers/014-rich-text.md)
42
43
  - [Diagram](input_providers/015-diagram.md)
43
44
 
45
+ - [FacetFilter](input_providers/016-facet-filter.md)
46
+
44
47
  - Examples
45
48
 
46
49
  - [Simple Table](#/page/examples/simple_table/README)
@@ -0,0 +1,106 @@
1
+ # FacetFilter Input Provider
2
+
3
+ Dropdowns that choose from one shared list of records, each narrowed by what the others hold. Pick a genre
4
+ and the author list shows only authors with books in it; pick a book and its genre and author fill in. In a
5
+ tabular group every row is independent: a row's lists narrow by that row's choices only.
6
+
7
+ Two pieces work together:
8
+
9
+ - a `Facet` rule in the input's `ListFilterRules` narrows what the dropdown offers
10
+ (`ListDistilling.filterList`, applied whenever the list is built for a row), and
11
+ - the `Pict-Input-FacetFilter` provider keeps the row consistent when one of them changes.
12
+
13
+ ## Provider Information
14
+
15
+ | Property | Value |
16
+ |----------|-------|
17
+ | Provider Hash | `Pict-Input-FacetFilter` |
18
+ | Input Type | Any select-style input (`Option`), alongside its own provider |
19
+ | Supports Tabular | Yes (row-scoped) |
20
+
21
+ ## Basic Usage
22
+
23
+ The shared list is any array of records in application state -- typically loaded once by the form's
24
+ `InitialBundle` and flattened with a `ProjectDataset` step. Each dropdown names the record field it holds:
25
+
26
+ ```json
27
+ {
28
+ "PickLists":
29
+ [
30
+ { "Hash": "Genres", "ListAddress": "Genres", "ListSourceAddress": "AppData.Catalog", "ListSourceAddressGlobal": true, "IDTemplate": "{~D:Record.Genre~}", "TextTemplate": "{~D:Record.Genre~}", "Unique": true, "Sorted": true, "SkipEmpty": true },
31
+ { "Hash": "Authors", "ListAddress": "Authors", "ListSourceAddress": "AppData.Catalog", "ListSourceAddressGlobal": true, "IDTemplate": "{~D:Record.Author~}", "TextTemplate": "{~D:Record.Author~}", "Unique": true, "Sorted": true, "SkipEmpty": true },
32
+ { "Hash": "Books", "ListAddress": "Books", "ListSourceAddress": "AppData.Catalog", "ListSourceAddressGlobal": true, "IDTemplate": "{~D:Record.IDBook~}", "TextTemplate": "{~D:Record.Title~}" }
33
+ ]
34
+ }
35
+ ```
36
+
37
+ ```json
38
+ "Genre":
39
+ {
40
+ "Name": "Genre", "Hash": "ShelfGenre", "DataAddress": "Genre", "DataType": "String",
41
+ "PictForm":
42
+ {
43
+ "InputType": "Option",
44
+ "SelectOptionsPickList": "Genres",
45
+ "ListFilterRules": [ { "FilterType": "Facet", "JoinListAddress": "AppData.Catalog", "JoinListAddressGlobal": true, "JoinListValueAddress": "Genre" } ],
46
+ "Providers": [ "Pict-Input-FacetFilter" ]
47
+ }
48
+ }
49
+ ```
50
+
51
+ Give `Author` and `Book` the same rule with `JoinListValueAddress` `Author` and `IDBook`. Inputs that share a
52
+ `JoinListAddress` find each other -- there is no per-pair wiring.
53
+
54
+ ## The Facet rule
55
+
56
+ | Key | Default | Meaning |
57
+ |-----|---------|---------|
58
+ | `JoinListAddress` | -- | Where the shared records are. |
59
+ | `JoinListAddressGlobal` | `false` | Resolve `JoinListAddress` against application state (`AppData.`, `Pict.`, `Bundle.`) rather than the form data. |
60
+ | `JoinListValueAddress` | -- | The record field this input holds; an option is offered when a record agreeing with the other choices has it. |
61
+ | `NarrowBy` | `All` | `All`: narrowed by every other choice. `Preceding`: narrowed only by the inputs before it (column order in a table), so any upstream value can always be picked and the downstream ones adjust. |
62
+ | `Facets` | `[]` | Extra constraints that are not dropdowns in the set: `{ JoinListValueAddress, Value \| ValueAddress, Operator }`. `ValueAddress` reads the form data. `Operator` is `EQ` (default), `NE`, `LT`, `LE`, `GT` or `GE`; numbers compare as numbers, and a bare `YYYY-MM-DD` compares against the date part of an ISO timestamp. An empty value does not constrain. |
63
+ | `KeepCurrentValue` | `true` | Always offer the value the input already holds, so a filter never hides a stored choice (for example one that has since fallen out of a date range). |
64
+ | `ClearInvalid` | `true` | FacetFilter: clear this input when a sibling's change contradicts it. |
65
+ | `AutoFillSingle` | `true` | FacetFilter: fill this input when exactly one value is left for it. |
66
+ | `CarryFields` | -- | FacetFilter: `{ "<row address>": "<record address>" }`. When this input holds a value and the choices identify exactly one record, copy those fields into the row (or the form, outside a table); clear them otherwise. |
67
+
68
+ Narrowing is joint: one record has to agree with every constraint at once, not a different record per
69
+ constraint.
70
+
71
+ ## What FacetFilter does on a change
72
+
73
+ When the user changes a facet input, before the form solves:
74
+
75
+ 1. Walking the other inputs in column order, each one no longer consistent with the change (and the ones
76
+ already kept) is cleared, unless its rule says `ClearInvalid: false`.
77
+ 2. Each empty input left with exactly one possible value takes it, repeated until nothing changes. The input
78
+ the user changed is never filled, so clearing it sticks.
79
+ 3. `CarryFields` are copied from the record the row now identifies, or cleared.
80
+
81
+ Because this runs before the solve, section and record set solvers see the finished row in the same pass.
82
+
83
+ It never runs on load or on marshal, so opening a saved document rewrites nothing -- including carried
84
+ fields, which keep the values they had when the choice was made even if the shared records change later.
85
+
86
+ ## PickList keys used here
87
+
88
+ | Key | Meaning |
89
+ |-----|---------|
90
+ | `ListSourceAddressGlobal` | Read `ListSourceAddress` from application state rather than the form data, so a list can be built from data the form does not save. |
91
+ | `SkipEmpty` | Skip records whose `IDTemplate` / `TextTemplate` render empty without logging each one -- for distinct-value lists over a field some records lack. |
92
+
93
+ ## Injection
94
+
95
+ Injected (salted) copies of a manifest keep a Facet rule as written: the join list is shared application
96
+ state and `JoinListValueAddress` names a field of its records, so neither is translated, and sibling inputs
97
+ are found by position (same row, same view) so copies never mix. A `Facets[].ValueAddress` that points at
98
+ form data is not translated either; use a literal `Value` or an application-state address in a manifest
99
+ that will be injected.
100
+
101
+ ## Related
102
+
103
+ - [Select](001-select.md) -- the dropdown the rule narrows; tabular lists with a Facet rule are refreshed on
104
+ every marshal and only rebuilt when their options change.
105
+ - [AutofillTriggerGroup](011-autofill-trigger-group.md) -- trigger-driven autofill for values outside a
106
+ facet set.
@@ -22,6 +22,7 @@ behavior for different data types and interaction patterns.
22
22
  | 013 | [TabSectionSelector](013-tab-section-selector.md) | TabSectionSelector | Tab navigation for sections |
23
23
  | 014 | [RichText](014-rich-text.md) | RichText | Markdown editor (edit) + rendered markdown (view); pluggable image uploader |
24
24
  | 015 | [Diagram](015-diagram.md) | Diagram | Excalidraw (edit) + inline themed SVG (view); themeify on save |
25
+ | 016 | [FacetFilter](016-facet-filter.md) | (any select) | Dropdowns over one shared record list, each narrowed by the others (row-scoped in tables) |
25
26
 
26
27
  ## Provider Categories
27
28
 
@@ -51,6 +51,12 @@ a product re-renders every table whose columns are generated from it; the hide
51
51
  class lives on an element that render regenerates, so it used to be dropped.
52
52
  Single file, all configuration.
53
53
 
54
+ ### Facet Filter
55
+
56
+ Order lines picking Genre -> Author -> Book from one shared catalog, each dropdown narrowed by the others in
57
+ its row and kept consistent on change (Facet list-filter rules + the FacetFilter provider). Ships a small REST
58
+ server so the catalog loads over HTTP: `npm run build && npm start`. See README-FacetFilter.md.
59
+
54
60
  ## Advanced
55
61
 
56
62
  ### Postcard
@@ -0,0 +1,9 @@
1
+ {
2
+ "GulpExecutions": [
3
+ {
4
+ "Hash": "default",
5
+ "Name": "Default standard build.",
6
+ "BuildFileLabel": "",
7
+ "BrowsersListRC": "since 2022"
8
+ }]
9
+ }
@@ -0,0 +1,210 @@
1
+ const libPictSectionForm = require('../../source/Pict-Section-Form.js');
2
+
3
+ /*
4
+ Facet Filter example: order lines that pick Genre -> Author -> Book from one shared catalog, each dropdown
5
+ narrowed by the others in the same row (a `Facet` ListFilterRule), kept consistent on change and carrying
6
+ the chosen book's price and format into the row (the `Pict-Input-FacetFilter` provider).
7
+
8
+ The catalog is loaded once by the form-level InitialBundle from the example's REST server
9
+ (Facet-Filter-Server.js): active publishers, then their books, then a ProjectDataset step that flattens
10
+ each book's nested Details into one graph row per book. Nothing is fetched when a dropdown changes.
11
+ */
12
+
13
+ const GRAPH_ADDRESS = 'AppData.Catalog.Graph';
14
+
15
+ /**
16
+ * The Facet rule every dropdown in a table shares; only JoinListValueAddress differs per column.
17
+ *
18
+ * @param {string} pJoinListValueAddress - the graph field this column holds
19
+ * @param {string} pNarrowBy - 'Preceding' or 'All'
20
+ * @param {Record<string, string>} [pCarryFields]
21
+ * @return {Record<string, any>}
22
+ */
23
+ function facetColumn(pJoinListValueAddress, pNarrowBy, pCarryFields)
24
+ {
25
+ const tmpRule =
26
+ {
27
+ Filter: 'Catalog graph',
28
+ FilterType: 'Facet',
29
+ JoinListAddress: GRAPH_ADDRESS,
30
+ JoinListAddressGlobal: true,
31
+ JoinListValueAddress: pJoinListValueAddress,
32
+ NarrowBy: pNarrowBy,
33
+ Facets:
34
+ [
35
+ { JoinListValueAddress: 'Language', ValueAddress: 'OrderLanguage' },
36
+ { JoinListValueAddress: 'InPrintFrom', Operator: 'LE', ValueAddress: 'OrderInPrintOn' },
37
+ { JoinListValueAddress: 'InPrintUntil', Operator: 'GE', ValueAddress: 'OrderInPrintOn' }
38
+ ]
39
+ };
40
+ if (pCarryFields)
41
+ {
42
+ tmpRule.CarryFields = pCarryFields;
43
+ }
44
+ return { ListFilterRules: [ tmpRule ], Providers: [ 'Pict-Input-FacetFilter' ] };
45
+ }
46
+
47
+ /**
48
+ * One order-line row manifest; the two tables differ only in how their lists narrow.
49
+ *
50
+ * @param {string} pScope
51
+ * @param {string} pGroup
52
+ * @param {string} pNarrowBy
53
+ * @return {Record<string, any>}
54
+ */
55
+ function orderLineManifest(pScope, pGroup, pNarrowBy)
56
+ {
57
+ const fColumn = (pKey, pName, pDataType, pPictForm) => (
58
+ {
59
+ Name: pName, Hash: `${pScope}${pKey}`, DataAddress: pKey, DataType: pDataType,
60
+ PictForm: Object.assign({ Section: 'Order', Group: pGroup }, pPictForm)
61
+ });
62
+ return (
63
+ {
64
+ Scope: pScope,
65
+ Descriptors:
66
+ {
67
+ Genre: fColumn('Genre', 'Genre', 'String', Object.assign({ InputType: 'Option', SelectOptionsPickList: 'Genres' }, facetColumn('Genre', pNarrowBy))),
68
+ Author: fColumn('Author', 'Author', 'String', Object.assign({ InputType: 'Option', SelectOptionsPickList: 'Authors' }, facetColumn('Author', pNarrowBy))),
69
+ Book: fColumn('Book', 'Book', 'String', Object.assign({ InputType: 'Option', SelectOptionsPickList: 'Books' }, facetColumn('IDBook', pNarrowBy, { Price: 'Price', Format: 'Format' }))),
70
+ Quantity: Object.assign(fColumn('Quantity', 'Qty', 'Number', {}), { Default: 1 }),
71
+ Price: fColumn('Price', 'Price', 'PreciseNumber', { InputType: 'ReadOnly' }),
72
+ Format: fColumn('Format', 'Format', 'String', { InputType: 'ReadOnly' }),
73
+ LineTotal: fColumn('LineTotal', 'Line Total', 'PreciseNumber', { InputType: 'ReadOnly' })
74
+ }
75
+ });
76
+ }
77
+
78
+ const _LineSolvers =
79
+ [
80
+ 'LineTotal = IF(Book, "==", "", 0, Price * Quantity)'
81
+ ];
82
+
83
+ module.exports = libPictSectionForm.PictFormApplication;
84
+
85
+ module.exports.default_configuration.pict_configuration = (
86
+ {
87
+ Product: 'FacetFilterExample',
88
+ DefaultAppData:
89
+ {
90
+ Order:
91
+ {
92
+ Language: '',
93
+ InPrintOn: '',
94
+ // A line saved earlier: its book has since gone out of print, and its price was carried when it
95
+ // was picked (the catalog lists it higher now). Opening the form rewrites neither.
96
+ Lines: [ { Genre: 'Science', Author: 'L. Brandt', Book: '109', Quantity: 2, Price: 18, Format: 'Hardcover' }, { Quantity: 1 }, { Quantity: 1 } ],
97
+ CompareLines: [ { Quantity: 1 }, { Quantity: 1 }, { Quantity: 1 } ]
98
+ }
99
+ },
100
+ DefaultFormManifest:
101
+ {
102
+ Scope: 'FacetFilterExample',
103
+
104
+ InitialBundle:
105
+ [
106
+ { Entity: 'Publisher', Filter: 'FBV~Active~EQ~1', Destination: 'AppData.Catalog.Publishers' },
107
+ // The leading 0 keeps the IN list valid when no publisher is active.
108
+ { Entity: 'Book', Filter: 'FBL~IDPublisher~INN~0,{~PJU:,^IDPublisher^AppData.Catalog.Publishers~}', Destination: 'AppData.Catalog.Books' },
109
+ {
110
+ Type: 'ProjectDataset',
111
+ InputRecordsetAddress: 'AppData.Catalog.Books',
112
+ OutputRecordsetAddress: GRAPH_ADDRESS,
113
+ RecordPrototypeAddress: 'OutputRecordset[]<<~?IDBook,==,{~D:InputRecord.IDBook~}?~>>',
114
+ RecordFieldMapping:
115
+ {
116
+ Default:
117
+ {
118
+ 'InputRecord.IDBook': 'OutputRecord.IDBook',
119
+ 'InputRecord.Title': 'OutputRecord.Title',
120
+ 'InputRecord.IDPublisher': 'OutputRecord.IDPublisher',
121
+ 'InputRecord.InPrintFrom': 'OutputRecord.InPrintFrom',
122
+ 'InputRecord.InPrintUntil': 'OutputRecord.InPrintUntil',
123
+ 'InputRecord.Details.Genre': 'OutputRecord.Genre',
124
+ 'InputRecord.Details.Author': 'OutputRecord.Author',
125
+ 'InputRecord.Details.Language': 'OutputRecord.Language',
126
+ 'InputRecord.Details.Current.Price': 'OutputRecord.Price',
127
+ 'InputRecord.Details.Current.Format': 'OutputRecord.Format'
128
+ }
129
+ }
130
+ }
131
+ ],
132
+
133
+ PickLists:
134
+ [
135
+ { Hash: 'Genres', ListAddress: 'Genres', ListSourceAddress: GRAPH_ADDRESS, ListSourceAddressGlobal: true, IDTemplate: '{~D:Record.Genre~}', TextTemplate: '{~D:Record.Genre~}', Unique: true, Sorted: true, SkipEmpty: true },
136
+ { Hash: 'Authors', ListAddress: 'Authors', ListSourceAddress: GRAPH_ADDRESS, ListSourceAddressGlobal: true, IDTemplate: '{~D:Record.Author~}', TextTemplate: '{~D:Record.Author~}', Unique: true, Sorted: true, SkipEmpty: true },
137
+ { Hash: 'Books', ListAddress: 'Books', ListSourceAddress: GRAPH_ADDRESS, ListSourceAddressGlobal: true, IDTemplate: '{~D:Record.IDBook~}', TextTemplate: '{~D:Record.Title~} ({~D:Record.Language~})', Sorted: true }
138
+ ],
139
+
140
+ Descriptors:
141
+ {
142
+ 'Order.Language':
143
+ {
144
+ Name: 'Language', Hash: 'OrderLanguage', DataType: 'String',
145
+ PictForm:
146
+ {
147
+ Section: 'Order', Group: 'Header', Row: 1, Width: 3, InputType: 'Option',
148
+ SelectOptions: [ { id: '', text: 'Any language' }, { id: 'EN', text: 'English' }, { id: 'FR', text: 'French' }, { id: 'DE', text: 'German' } ]
149
+ }
150
+ },
151
+ 'Order.InPrintOn':
152
+ {
153
+ Name: 'In print on (YYYY-MM-DD)', Hash: 'OrderInPrintOn', DataType: 'String',
154
+ PictForm: { Section: 'Order', Group: 'Header', Row: 1, Width: 3 }
155
+ },
156
+ 'Order.Total':
157
+ {
158
+ Name: 'Order total (left-narrowing table)', Hash: 'OrderTotal', DataType: 'PreciseNumber',
159
+ PictForm: { Section: 'Order', Group: 'Header', Row: 1, Width: 3, InputType: 'ReadOnly' }
160
+ },
161
+ 'Order.CompareTotal':
162
+ {
163
+ Name: 'Order total (symmetric table)', Hash: 'OrderCompareTotal', DataType: 'PreciseNumber',
164
+ PictForm: { Section: 'Order', Group: 'Header', Row: 1, Width: 3, InputType: 'ReadOnly' }
165
+ }
166
+ },
167
+
168
+ Sections:
169
+ [
170
+ {
171
+ Name: 'Book Club Order',
172
+ Hash: 'Order',
173
+ Solvers:
174
+ [
175
+ 'OrderInPrintOn = WHEN(OrderInPrintOn, OrderInPrintOn, DATEFORMAT(NULL, "YYYY-MM-DD"))',
176
+ 'OrderTotal = SUM(Order.Lines[].LineTotal)',
177
+ 'OrderCompareTotal = SUM(Order.CompareLines[].LineTotal)'
178
+ ],
179
+ Groups:
180
+ [
181
+ { Name: 'Order', Hash: 'Header', Rows: [] },
182
+ {
183
+ Name: 'Order lines -- each list narrowed by the columns to its left (NarrowBy: Preceding)',
184
+ Hash: 'Lines',
185
+ Layout: 'Tabular',
186
+ RecordSetAddress: 'Order.Lines',
187
+ RecordManifest: 'OrderLine',
188
+ MinimumRowCount: 3,
189
+ RecordSetSolvers: _LineSolvers
190
+ },
191
+ {
192
+ Name: 'The same, narrowed symmetrically -- each list by every other choice (NarrowBy: All)',
193
+ Hash: 'CompareLines',
194
+ Layout: 'Tabular',
195
+ RecordSetAddress: 'Order.CompareLines',
196
+ RecordManifest: 'CompareLine',
197
+ MinimumRowCount: 3,
198
+ RecordSetSolvers: _LineSolvers
199
+ }
200
+ ]
201
+ }
202
+ ],
203
+
204
+ ReferenceManifests:
205
+ {
206
+ OrderLine: orderLineManifest('OrderLine', 'Lines', 'Preceding'),
207
+ CompareLine: orderLineManifest('CompareLine', 'CompareLines', 'All')
208
+ }
209
+ }
210
+ });