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.
- package/docs/Injection_Conformance.md +137 -0
- package/docs/Providers.md +12 -7
- package/docs/_sidebar.md +3 -0
- package/docs/input_providers/016-facet-filter.md +106 -0
- package/docs/input_providers/README.md +1 -0
- package/example_applications/README.md +6 -0
- package/example_applications/facet_filter/.quackage.json +9 -0
- package/example_applications/facet_filter/Facet-Filter-Application.js +210 -0
- package/example_applications/facet_filter/Facet-Filter-Server.js +233 -0
- package/example_applications/facet_filter/Facet-Filter-Smoke-Runner.js +101 -0
- package/example_applications/facet_filter/FacetFilterData.json +44 -0
- package/example_applications/facet_filter/README-FacetFilter.md +70 -0
- package/example_applications/facet_filter/html/Facet-Filter-Smoke.js +128 -0
- package/example_applications/facet_filter/html/index.html +74 -0
- package/example_applications/facet_filter/package.json +27 -0
- package/example_applications/nested_distill_sandbox/Sandbox-Driver-Headlight.js +17 -0
- package/example_applications/nested_distill_sandbox/Sandbox-Driver.js +369 -0
- package/example_applications/nested_distill_sandbox/Sandbox-Runner.js +372 -0
- package/example_applications/nested_distill_sandbox/approaches/A1-tabular-trigger-group.js +67 -0
- package/example_applications/nested_distill_sandbox/approaches/A3-crossmap-selectoptionsrefresh.js +61 -0
- package/example_applications/nested_distill_sandbox/approaches/A4-graph-solvers-flat-list.js +53 -0
- package/example_applications/nested_distill_sandbox/approaches/A5-facet-filter.js +75 -0
- package/example_applications/nested_distill_sandbox/approaches/A5b-facet-filter-symmetric.js +15 -0
- package/example_applications/nested_distill_sandbox/approaches/A5h-facet-filter-headlight-picker.js +15 -0
- package/example_applications/nested_distill_sandbox/approaches/R0-original-jmf-manifest-headlight.js +27 -0
- package/example_applications/nested_distill_sandbox/approaches/R1-real-jmf-manifest-headlight.js +136 -0
- package/example_applications/nested_distill_sandbox/approaches/_Common.js +344 -0
- package/example_applications/nested_distill_sandbox/approaches/_Scenarios.js +262 -0
- package/package.json +6 -5
- package/source/providers/Pict-Provider-DynamicFormSolverBehaviors.js +73 -5
- package/source/providers/Pict-Provider-DynamicSolver.js +22 -2
- package/source/providers/Pict-Provider-ListDistilling.js +266 -1
- package/source/providers/Pict-Provider-MetaLists.js +16 -2
- package/source/providers/inputs/Pict-Provider-Input-FacetFilter.js +232 -0
- package/source/providers/inputs/Pict-Provider-Input-Select.js +41 -1
- package/source/views/Pict-View-Form-Metacontroller.js +690 -93
- package/test/Pict-Provider-DynamicFormSolverBehaviors-OrdinalScope_tests.js +105 -0
- package/test/Pict-Provider-ListDistilling-Facet_tests.js +375 -0
- package/test/Pict-View-Form-Metacontroller-DistinctManifest_tests.js +410 -0
- package/test/PictSectionForm-Injection-Conformance_tests.js +762 -0
- package/test/browser/Injection-Conformance-Differential-Scenario.js +346 -0
- package/test/browser/Injection-Conformance-EdgeCase-Scenario.js +168 -0
- package/test/browser/Injection-Conformance-Harness-Driver.js +538 -0
- package/test/browser/Injection-Conformance-Harness-Runner.js +487 -0
- package/test/browser/Injection-Conformance-Reconstitution-Scenario.js +191 -0
- package/test/browser/Injection-Conformance-Standalone-Scenario.js +114 -0
- package/test/fixtures/injection/Injection-Fixture-Cases.js +204 -0
- package/test/fixtures/injection/Injection-Fixture-Manifest.json +381 -0
- package/types/source/providers/Pict-Provider-DynamicFormSolverBehaviors.d.ts +110 -1
- package/types/source/providers/Pict-Provider-DynamicFormSolverBehaviors.d.ts.map +1 -1
- package/types/source/providers/Pict-Provider-DynamicSolver.d.ts.map +1 -1
- package/types/source/providers/Pict-Provider-DynamicTabularData.d.ts +17 -1
- package/types/source/providers/Pict-Provider-DynamicTabularData.d.ts.map +1 -1
- package/types/source/providers/Pict-Provider-InputExtension.d.ts +31 -0
- package/types/source/providers/Pict-Provider-InputExtension.d.ts.map +1 -1
- package/types/source/providers/Pict-Provider-ListDistilling.d.ts +90 -1
- package/types/source/providers/Pict-Provider-ListDistilling.d.ts.map +1 -1
- package/types/source/providers/Pict-Provider-MetaLists.d.ts.map +1 -1
- package/types/source/providers/inputs/Pict-Provider-Input-Chart-CSS.d.ts +16 -0
- package/types/source/providers/inputs/Pict-Provider-Input-Chart-CSS.d.ts.map +1 -0
- package/types/source/providers/inputs/Pict-Provider-Input-Chart.d.ts +47 -0
- package/types/source/providers/inputs/Pict-Provider-Input-Chart.d.ts.map +1 -1
- package/types/source/providers/inputs/Pict-Provider-Input-Diagram.d.ts +86 -0
- package/types/source/providers/inputs/Pict-Provider-Input-Diagram.d.ts.map +1 -1
- package/types/source/providers/inputs/Pict-Provider-Input-FacetFilter.d.ts +103 -0
- package/types/source/providers/inputs/Pict-Provider-Input-FacetFilter.d.ts.map +1 -0
- package/types/source/providers/inputs/Pict-Provider-Input-ObjectEditor.d.ts +128 -0
- package/types/source/providers/inputs/Pict-Provider-Input-ObjectEditor.d.ts.map +1 -0
- package/types/source/providers/inputs/Pict-Provider-Input-PreciseNumber.d.ts.map +1 -1
- package/types/source/providers/inputs/Pict-Provider-Input-Select.d.ts +12 -0
- package/types/source/providers/inputs/Pict-Provider-Input-Select.d.ts.map +1 -1
- package/types/source/providers/inputs/Pict-Provider-Input-TabGroupSelector.d.ts +10 -1
- package/types/source/providers/inputs/Pict-Provider-Input-TabGroupSelector.d.ts.map +1 -1
- package/types/source/providers/inputs/Pict-Provider-Input-TabSectionSelector.d.ts +10 -1
- package/types/source/providers/inputs/Pict-Provider-Input-TabSectionSelector.d.ts.map +1 -1
- package/types/source/providers/layouts/Pict-Layout-Tabular.d.ts +76 -4
- package/types/source/providers/layouts/Pict-Layout-Tabular.d.ts.map +1 -1
- package/types/source/views/Pict-View-DynamicForm.d.ts.map +1 -1
- package/types/source/views/Pict-View-Form-Metacontroller.d.ts +63 -2
- 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
|
|
229
|
+
Filters a select input's options by the `ListFilterRules` on its descriptor.
|
|
226
230
|
|
|
227
231
|
**Hash:** `ListDistilling`
|
|
228
232
|
|
|
229
|
-
**
|
|
230
|
-
|
|
231
|
-
-
|
|
232
|
-
|
|
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
|
-
//
|
|
238
|
-
const filtered = pict.providers.ListDistilling.
|
|
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,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
|
+
});
|