@jam-overture/loom 0.1.0 → 0.2.0
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/README.md +3 -1
- package/dist/application/application.d.ts +109 -0
- package/dist/application/application.js +97 -0
- package/dist/application/memory.d.ts +20 -0
- package/dist/application/memory.js +79 -0
- package/dist/application/store.d.ts +101 -0
- package/dist/application/store.js +25 -0
- package/dist/audience/audience.d.ts +36 -0
- package/dist/audience/audience.js +41 -0
- package/dist/cli/templates.js +19 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +30 -3
- package/dist/data/resolve.js +11 -3
- package/dist/ids.d.ts +10 -0
- package/dist/ids.js +11 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/patch.d.ts +54 -0
- package/dist/patch.js +44 -0
- package/dist/project/closing.d.ts +51 -0
- package/dist/project/closing.js +53 -0
- package/dist/project/memory.d.ts +20 -0
- package/dist/project/memory.js +97 -0
- package/dist/project/project.d.ts +90 -0
- package/dist/project/project.js +91 -0
- package/dist/project/store.d.ts +135 -0
- package/dist/project/store.js +41 -0
- package/dist/registered.d.ts +64 -0
- package/dist/registered.js +118 -0
- package/dist/render/behaviour-adjust.d.ts +11 -19
- package/dist/render/behaviour-adjust.js +75 -21
- package/dist/render/behaviour-present.d.ts +8 -0
- package/dist/render/behaviour-present.js +57 -6
- package/dist/render/behaviour.d.ts +98 -17
- package/dist/render/behaviour.js +91 -26
- package/dist/render/control-name.d.ts +68 -0
- package/dist/render/control-name.js +37 -0
- package/dist/render/diagnostics.d.ts +72 -0
- package/dist/render/diagnostics.js +7 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.js +102 -7
- package/dist/render/slots.d.ts +52 -0
- package/dist/render/slots.js +24 -0
- package/dist/render/theme.d.ts +54 -1
- package/dist/render/theme.js +23 -1
- package/dist/render/unshown.d.ts +152 -0
- package/dist/render/unshown.js +80 -0
- package/dist/runtime/analysis.d.ts +94 -9
- package/dist/runtime/analysis.js +54 -9
- package/dist/runtime/assessment.d.ts +36 -2
- package/dist/runtime/assessment.js +27 -2
- package/dist/runtime/checks.d.ts +148 -0
- package/dist/runtime/checks.js +112 -0
- package/dist/runtime/disposition.d.ts +96 -0
- package/dist/runtime/disposition.js +46 -0
- package/dist/runtime/gate.js +22 -0
- package/dist/runtime/index.d.ts +3 -0
- package/dist/runtime/index.js +3 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- package/dist/runtime/pipeline.d.ts +43 -0
- package/dist/runtime/pipeline.js +10 -2
- package/dist/runtime/policy-change.d.ts +93 -0
- package/dist/runtime/policy-change.js +299 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -0
- package/dist/runtime/reversibility.d.ts +11 -9
- package/dist/runtime/stakes.d.ts +129 -1
- package/dist/runtime/stakes.js +240 -26
- package/dist/runtime/vocabulary.d.ts +164 -7
- package/dist/runtime/vocabulary.js +181 -8
- package/dist/sdk/audit.d.ts +174 -3
- package/dist/sdk/audit.js +176 -17
- package/dist/sdk/catalogue.d.ts +9 -1
- package/dist/sdk/conformance.d.ts +37 -3
- package/dist/sdk/conformance.js +25 -4
- package/dist/sdk/definition.d.ts +65 -0
- package/dist/sdk/definition.js +22 -0
- package/dist/sdk/registry.d.ts +29 -2
- package/dist/sdk/registry.js +63 -1
- package/dist/signals/action-change.d.ts +507 -0
- package/dist/signals/action-change.js +265 -0
- package/dist/signals/action.d.ts +331 -0
- package/dist/signals/action.js +182 -0
- package/dist/signals/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -0
- package/dist/signals/arriving.d.ts +210 -0
- package/dist/signals/arriving.js +133 -0
- package/dist/signals/audiences.d.ts +528 -0
- package/dist/signals/audiences.js +255 -0
- package/dist/signals/broadcast.d.ts +8 -2
- package/dist/signals/broadcast.js +58 -8
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +41 -0
- package/dist/signals/collect.js +88 -7
- package/dist/signals/copy-change.d.ts +553 -0
- package/dist/signals/copy-change.js +377 -0
- package/dist/signals/copy.d.ts +337 -0
- package/dist/signals/copy.js +211 -0
- package/dist/signals/counters.d.ts +46 -0
- package/dist/signals/counters.js +102 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +371 -0
- package/dist/signals/deployment-change.js +268 -0
- package/dist/signals/deployment.d.ts +265 -0
- package/dist/signals/deployment.js +152 -0
- package/dist/signals/door.d.ts +92 -0
- package/dist/signals/door.js +53 -0
- package/dist/signals/fold.d.ts +10 -0
- package/dist/signals/fold.js +5 -1
- package/dist/signals/form-action.d.ts +302 -0
- package/dist/signals/form-action.js +169 -0
- package/dist/signals/form-copy.d.ts +523 -0
- package/dist/signals/form-copy.js +346 -0
- package/dist/signals/forms.d.ts +247 -0
- package/dist/signals/forms.js +147 -0
- package/dist/signals/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -0
- package/dist/signals/funnel.d.ts +532 -0
- package/dist/signals/funnel.js +216 -0
- package/dist/signals/health.d.ts +497 -0
- package/dist/signals/health.js +361 -0
- package/dist/signals/index.d.ts +41 -0
- package/dist/signals/index.js +41 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- package/dist/signals/journal.d.ts +11 -0
- package/dist/signals/kinds.d.ts +8 -6
- package/dist/signals/kinds.js +14 -6
- package/dist/signals/library-action.d.ts +430 -0
- package/dist/signals/library-action.js +336 -0
- package/dist/signals/library-change.d.ts +477 -0
- package/dist/signals/library-change.js +335 -0
- package/dist/signals/library-copy-change.d.ts +498 -0
- package/dist/signals/library-copy-change.js +476 -0
- package/dist/signals/library-pace.d.ts +319 -0
- package/dist/signals/library-pace.js +305 -0
- package/dist/signals/library-reach-change.d.ts +636 -0
- package/dist/signals/library-reach-change.js +534 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- package/dist/signals/library-word-reach-change.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +568 -0
- package/dist/signals/library.d.ts +306 -0
- package/dist/signals/library.js +178 -0
- package/dist/signals/memory.d.ts +9 -0
- package/dist/signals/memory.js +105 -14
- package/dist/signals/migrate.d.ts +17 -2
- package/dist/signals/migrate.js +122 -5
- package/dist/signals/notice.d.ts +334 -0
- package/dist/signals/notice.js +228 -0
- package/dist/signals/pace-change.d.ts +501 -0
- package/dist/signals/pace-change.js +310 -0
- package/dist/signals/pace.d.ts +296 -0
- package/dist/signals/pace.js +291 -0
- package/dist/signals/page-views.d.ts +365 -0
- package/dist/signals/page-views.js +218 -0
- package/dist/signals/parts.d.ts +344 -0
- package/dist/signals/parts.js +273 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +390 -87
- package/dist/signals/progress.d.ts +212 -0
- package/dist/signals/progress.js +150 -0
- package/dist/signals/ratios.d.ts +108 -0
- package/dist/signals/ratios.js +40 -0
- package/dist/signals/reach.d.ts +309 -0
- package/dist/signals/reach.js +93 -0
- package/dist/signals/readable.d.ts +34 -0
- package/dist/signals/readable.js +34 -0
- package/dist/signals/readership.d.ts +381 -0
- package/dist/signals/readership.js +308 -0
- package/dist/signals/region-pages.d.ts +173 -0
- package/dist/signals/region-pages.js +62 -0
- package/dist/signals/region.d.ts +287 -0
- package/dist/signals/region.js +198 -0
- package/dist/signals/retention.d.ts +141 -0
- package/dist/signals/retention.js +58 -0
- package/dist/signals/rollup.d.ts +67 -3
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +432 -1
- package/dist/signals/schema.js +157 -3
- package/dist/signals/signal.d.ts +237 -11
- package/dist/signals/signal.js +70 -10
- package/dist/signals/silence-census.d.ts +205 -0
- package/dist/signals/silence-census.js +87 -0
- package/dist/signals/silences.d.ts +848 -0
- package/dist/signals/silences.js +753 -0
- package/dist/signals/tally.d.ts +140 -11
- package/dist/signals/window-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -0
- package/dist/signals/window.d.ts +866 -0
- package/dist/signals/window.js +693 -0
- package/dist/signals/words.d.ts +24 -0
- package/dist/signals/words.js +24 -0
- package/dist/store/index.d.ts +19 -0
- package/dist/store/index.js +19 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +80 -0
- package/dist/store/migrate.js +259 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -0
- package/dist/store/postgres-holds.d.ts +10 -1
- package/dist/store/postgres-holds.js +116 -101
- package/dist/store/postgres-policy-log.d.ts +14 -0
- package/dist/store/postgres-policy-log.js +240 -0
- package/dist/store/postgres-projects.d.ts +4 -0
- package/dist/store/postgres-projects.js +217 -0
- package/dist/store/postgres.d.ts +16 -1
- package/dist/store/postgres.js +59 -9
- package/dist/store/replay.d.ts +102 -1
- package/dist/store/replay.js +190 -19
- package/dist/store/reseed.d.ts +238 -0
- package/dist/store/reseed.js +308 -0
- package/dist/store/schema.d.ts +450 -2
- package/dist/store/schema.js +141 -5
- package/dist/store/store.d.ts +29 -6
- package/dist/submit/resolve.js +2 -1
- package/dist/telemetry/calibration.d.ts +25 -0
- package/dist/telemetry/calibration.js +27 -1
- package/dist/telemetry/event.d.ts +391 -33
- package/dist/telemetry/event.js +84 -20
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +72 -3
- package/dist/telemetry/journal.js +9 -0
- package/dist/telemetry/lookup.d.ts +27 -0
- package/dist/telemetry/lookup.js +18 -0
- package/dist/telemetry/memory.js +23 -0
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +172 -90
- package/dist/telemetry/remeasure.d.ts +78 -0
- package/dist/telemetry/remeasure.js +83 -0
- package/dist/telemetry/retention.d.ts +2 -2
- package/dist/telemetry/schema.d.ts +17 -0
- package/dist/telemetry/schema.js +27 -1
- package/dist/telemetry/sink.d.ts +2 -2
- package/dist/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -0
- package/dist/testing/contracts.d.ts +12 -7
- package/dist/testing/contracts.js +12 -7
- package/dist/testing/definitions.d.ts +78 -0
- package/dist/testing/definitions.js +134 -9
- package/dist/testing/doubles.d.ts +103 -0
- package/dist/testing/doubles.js +143 -0
- package/dist/testing/index.d.ts +2 -2
- package/dist/testing/index.js +2 -2
- package/dist/testing/journal-contract.js +140 -2
- package/dist/testing/model-contract.d.ts +110 -0
- package/dist/testing/model-contract.js +150 -0
- package/dist/testing/policy-log-contract.d.ts +26 -0
- package/dist/testing/policy-log-contract.js +344 -0
- package/dist/testing/project-contract.d.ts +14 -0
- package/dist/testing/project-contract.js +266 -0
- package/dist/testing/reader-signal-contract.d.ts +27 -2
- package/dist/testing/reader-signal-contract.js +475 -5
- package/dist/testing/store-contract.d.ts +7 -1
- package/dist/testing/store-contract.js +84 -3
- package/dist/theme/apply.d.ts +20 -1
- package/dist/theme/apply.js +5 -3
- package/dist/theme/derive.d.ts +22 -0
- package/dist/theme/derive.js +54 -1
- package/dist/theme/library.js +1 -1
- package/dist/theme/measure.d.ts +34 -0
- package/dist/theme/measure.js +30 -1
- package/dist/theme/palettes.js +7 -7
- package/dist/theme/ramp.d.ts +64 -0
- package/dist/theme/ramp.js +114 -0
- package/dist/theme/registry.d.ts +9 -0
- package/dist/theme/registry.js +11 -1
- package/dist/theme/separation.d.ts +97 -3
- package/dist/theme/separation.js +75 -0
- package/dist/tree/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -0
- package/dist/write/computed.d.ts +60 -0
- package/dist/write/computed.js +61 -0
- package/dist/write/held.d.ts +59 -0
- package/dist/write/index.d.ts +5 -2
- package/dist/write/index.js +5 -2
- package/dist/write/reseed.d.ts +151 -0
- package/dist/write/reseed.js +184 -0
- package/dist/write/revert.js +2 -16
- package/package.json +98 -19
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import type { Result } from "../result.js";
|
|
2
|
+
import type { Project, ProjectId } from "./project.js";
|
|
3
|
+
/**
|
|
4
|
+
* Custody of the projects a deployment has — the grouping, not the thing
|
|
5
|
+
* grouped.
|
|
6
|
+
*
|
|
7
|
+
* A project holds applications and nothing else, which is what makes this the
|
|
8
|
+
* shorter of the two stores: there is no host, because a project is not
|
|
9
|
+
* deployed anywhere, and no scope type, because nothing is stored *under* a
|
|
10
|
+
* project — the five scoped tables name their application, and the application
|
|
11
|
+
* names its project.
|
|
12
|
+
*
|
|
13
|
+
* It has the same four methods and the same refusal to delete, for a reason
|
|
14
|
+
* that is one step removed but no weaker: deleting a project would orphan or
|
|
15
|
+
* cascade through every application in it, and each of those owns a governance
|
|
16
|
+
* record. *The project says it was closed* beats *the project is gone* here too.
|
|
17
|
+
*/
|
|
18
|
+
export type ProjectStoreError =
|
|
19
|
+
/** No project under this id. */
|
|
20
|
+
{
|
|
21
|
+
readonly code: "not-found";
|
|
22
|
+
readonly projectId: ProjectId;
|
|
23
|
+
} | {
|
|
24
|
+
readonly code: "already-exists";
|
|
25
|
+
readonly projectId: ProjectId;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Another project already names this repository (0292).
|
|
29
|
+
*
|
|
30
|
+
* Its own code rather than `already-exists`, because the thing that is taken
|
|
31
|
+
* is not the thing the caller named: they asked for a new project and the
|
|
32
|
+
* collision is on a field. A screen can put this fault on the repository
|
|
33
|
+
* input, where `already-exists` has no input to point at.
|
|
34
|
+
*/
|
|
35
|
+
| {
|
|
36
|
+
readonly code: "repository-taken";
|
|
37
|
+
readonly repository: string;
|
|
38
|
+
}
|
|
39
|
+
/** A row the current code cannot parse, which is a row an older one wrote. */
|
|
40
|
+
| {
|
|
41
|
+
readonly code: "unreadable";
|
|
42
|
+
readonly projectId: ProjectId;
|
|
43
|
+
readonly detail: string;
|
|
44
|
+
} | {
|
|
45
|
+
readonly code: "unavailable";
|
|
46
|
+
readonly detail: string;
|
|
47
|
+
};
|
|
48
|
+
export type ProjectStoreErrorCode = ProjectStoreError["code"];
|
|
49
|
+
/**
|
|
50
|
+
* The four codes, in the order a deployment meets them, for the same reason
|
|
51
|
+
* `storeErrorCodes` exists: anything that walks the taxonomy rather than
|
|
52
|
+
* reacting to one member otherwise keeps a copy that is silently wrong the day
|
|
53
|
+
* a fifth lands.
|
|
54
|
+
*/
|
|
55
|
+
export declare const projectStoreErrorCodes: readonly ProjectStoreErrorCode[];
|
|
56
|
+
export declare const describeProjectStoreError: (error: ProjectStoreError) => string;
|
|
57
|
+
/**
|
|
58
|
+
* What a listing is asked for (0289).
|
|
59
|
+
*
|
|
60
|
+
* Absent means **open only**, which is what every caller written before closing
|
|
61
|
+
* existed already meant. A listing that defaulted to everything would put a
|
|
62
|
+
* closed row back on the screen that closed it, and a caller that genuinely
|
|
63
|
+
* wants the audit — everything, open or not — says so.
|
|
64
|
+
*/
|
|
65
|
+
export type Listing = {
|
|
66
|
+
/** `true` for closed only, `false` or absent for open only, `"all"` for both. */
|
|
67
|
+
readonly closed?: boolean | "all";
|
|
68
|
+
};
|
|
69
|
+
/**
|
|
70
|
+
* Whether a row belongs in this listing, as one function both stores and both
|
|
71
|
+
* implementations use.
|
|
72
|
+
*
|
|
73
|
+
* Here rather than in each of the four, because *what `closed` means* is the
|
|
74
|
+
* kind of three-case rule that two copies agree about until somebody adds the
|
|
75
|
+
* third case to one of them.
|
|
76
|
+
*/
|
|
77
|
+
export declare const matchesListing: (closedAt: string | undefined, listing?: Listing) => boolean;
|
|
78
|
+
/**
|
|
79
|
+
* Six methods, and still **no delete**.
|
|
80
|
+
*
|
|
81
|
+
* That is the same refusal `TreeStore` makes and for a stronger reason here: a
|
|
82
|
+
* project's rows are its trees, its revisions, its holds, its policy history
|
|
83
|
+
* and its journal, and a delete would either orphan all of them or cascade
|
|
84
|
+
* through the governance record this product exists to keep. *The project says
|
|
85
|
+
* it was closed* is a better answer than *the project is gone* — and closing is
|
|
86
|
+
* not built here either, because nothing can close what nothing has yet opened.
|
|
87
|
+
* When it is wanted it is a column and a filter, not a `DELETE`.
|
|
88
|
+
*/
|
|
89
|
+
export type ProjectStore = {
|
|
90
|
+
/**
|
|
91
|
+
* Record a project. Refuses an id already taken rather than overwriting,
|
|
92
|
+
* because the thing under that id owns rows.
|
|
93
|
+
*/
|
|
94
|
+
readonly create: (project: Project) => Promise<Result<Project, ProjectStoreError>>;
|
|
95
|
+
/** One project. */
|
|
96
|
+
readonly get: (projectId: ProjectId) => Promise<Result<Project, ProjectStoreError>>;
|
|
97
|
+
/**
|
|
98
|
+
* Every project, oldest first.
|
|
99
|
+
*
|
|
100
|
+
* Unpaginated, and that is a judgement rather than an oversight: this is the
|
|
101
|
+
* list a person scans on one screen, and a deployment whose project count
|
|
102
|
+
* needs a cursor has a different screen's problem. `TreeStore.list` takes a
|
|
103
|
+
* limit because pages are unbounded in a way projects are not.
|
|
104
|
+
*/
|
|
105
|
+
readonly list: (listing?: Listing) => Promise<Result<readonly Project[], ProjectStoreError>>;
|
|
106
|
+
/** Change what a person calls it. */
|
|
107
|
+
readonly rename: (projectId: ProjectId, to: {
|
|
108
|
+
readonly name: string;
|
|
109
|
+
}) => Promise<Result<Project, ProjectStoreError>>;
|
|
110
|
+
/**
|
|
111
|
+
* Stop it, without losing it (0289).
|
|
112
|
+
*
|
|
113
|
+
* **This closes the project row and nothing else.** Closing a project also
|
|
114
|
+
* closes the applications in it, and that cascade is `closeProject` in
|
|
115
|
+
* `src/project/closing.ts` rather than a line in here: this store knows
|
|
116
|
+
* nothing about applications, and a store that reached into another one to
|
|
117
|
+
* finish a write would be the coupling both of them are shaped to avoid.
|
|
118
|
+
*
|
|
119
|
+
* Idempotent on a project already closed — the instant is not moved, because
|
|
120
|
+
* the answer to *when did this stop* must not change because somebody pressed
|
|
121
|
+
* the button twice.
|
|
122
|
+
*/
|
|
123
|
+
readonly close: (projectId: ProjectId, at: string) => Promise<Result<Project, ProjectStoreError>>;
|
|
124
|
+
/**
|
|
125
|
+
* The inverse, and **not symmetric**: reopening a project does not reopen its
|
|
126
|
+
* applications.
|
|
127
|
+
*
|
|
128
|
+
* Closing is a statement about the project; reopening one of its applications
|
|
129
|
+
* is a decision about that application. A reopen that revived everything
|
|
130
|
+
* would turn *I want that one back* into *start collecting on all nine
|
|
131
|
+
* again*.
|
|
132
|
+
*/
|
|
133
|
+
readonly reopen: (projectId: ProjectId) => Promise<Result<Project, ProjectStoreError>>;
|
|
134
|
+
};
|
|
135
|
+
//# sourceMappingURL=store.d.ts.map
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The four codes, in the order a deployment meets them, for the same reason
|
|
3
|
+
* `storeErrorCodes` exists: anything that walks the taxonomy rather than
|
|
4
|
+
* reacting to one member otherwise keeps a copy that is silently wrong the day
|
|
5
|
+
* a fifth lands.
|
|
6
|
+
*/
|
|
7
|
+
export const projectStoreErrorCodes = [
|
|
8
|
+
"not-found",
|
|
9
|
+
"already-exists",
|
|
10
|
+
"repository-taken",
|
|
11
|
+
"unreadable",
|
|
12
|
+
"unavailable",
|
|
13
|
+
];
|
|
14
|
+
export const describeProjectStoreError = (error) => {
|
|
15
|
+
switch (error.code) {
|
|
16
|
+
case "not-found":
|
|
17
|
+
return `no project ${error.projectId}`;
|
|
18
|
+
case "already-exists":
|
|
19
|
+
return `project ${error.projectId} already exists`;
|
|
20
|
+
case "repository-taken":
|
|
21
|
+
return `another project already names ${error.repository}`;
|
|
22
|
+
case "unreadable":
|
|
23
|
+
return `project ${error.projectId} could not be read: ${error.detail}`;
|
|
24
|
+
case "unavailable":
|
|
25
|
+
return `the project store is unavailable: ${error.detail}`;
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Whether a row belongs in this listing, as one function both stores and both
|
|
30
|
+
* implementations use.
|
|
31
|
+
*
|
|
32
|
+
* Here rather than in each of the four, because *what `closed` means* is the
|
|
33
|
+
* kind of three-case rule that two copies agree about until somebody adds the
|
|
34
|
+
* third case to one of them.
|
|
35
|
+
*/
|
|
36
|
+
export const matchesListing = (closedAt, listing) => {
|
|
37
|
+
if (listing?.closed === "all")
|
|
38
|
+
return true;
|
|
39
|
+
return listing?.closed === true ? closedAt !== undefined : closedAt === undefined;
|
|
40
|
+
};
|
|
41
|
+
//# sourceMappingURL=store.js.map
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Naming what a deployment registered, to somebody who named something else.
|
|
3
|
+
*
|
|
4
|
+
* Three seams refuse an unknown id the same way — a palette, a data source, a
|
|
5
|
+
* submission endpoint — and each answers by listing what it does have, so that
|
|
6
|
+
* whoever reads the log can see what they should have written. The instinct is
|
|
7
|
+
* right and the list is the wrong shape for it: its length is the deployment's
|
|
8
|
+
* to set rather than the runtime's, so a host with a palette per brand turns one
|
|
9
|
+
* diagnostic into a paragraph, in every log line and every panel that prints it.
|
|
10
|
+
*
|
|
11
|
+
* What this bounds is the sentence and nothing else. A refusal still carries
|
|
12
|
+
* every id it knows where a caller can read it, and a registry still publishes
|
|
13
|
+
* its whole catalogue, so the names past the cap are a lookup away rather than
|
|
14
|
+
* gone. The sentence has the narrower job: put the id the reader probably meant
|
|
15
|
+
* in front of them, and say how many it is standing in for.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* How many names a refusal puts in front of a reader.
|
|
19
|
+
*
|
|
20
|
+
* Five, against a measurement: the twenty-four render diagnostics printed side
|
|
21
|
+
* by side came to a median of 144 characters, and the unresolved-theme sentence
|
|
22
|
+
* came to 284 — of which 172 were this list at twenty-one palettes. Five ids of
|
|
23
|
+
* ordinary length is about fifty, which keeps the clause the smaller half of a
|
|
24
|
+
* sentence it used to be the larger half of.
|
|
25
|
+
*/
|
|
26
|
+
export declare const NEAREST_REGISTERED = 5;
|
|
27
|
+
/**
|
|
28
|
+
* The registered ids closest to the one that was asked for, nearest first.
|
|
29
|
+
*
|
|
30
|
+
* Ranking is what makes a capped list worth reading: the reason to print the
|
|
31
|
+
* registry at all is that the right answer is almost always one of a short
|
|
32
|
+
* list, and the first five in registration order bear no relation to what
|
|
33
|
+
* somebody meant to type.
|
|
34
|
+
*
|
|
35
|
+
* It ranks strings and claims no more than that. Nothing in `sunset` says it
|
|
36
|
+
* and `ember` are both warm, so nothing here will offer `ember`; a seam that
|
|
37
|
+
* wants meaning has to rank on something other than spelling.
|
|
38
|
+
*/
|
|
39
|
+
export declare const nearestRegistered: (wanted: string, available: readonly string[], limit?: number) => readonly string[];
|
|
40
|
+
/**
|
|
41
|
+
* The clause a refusal ends on: what to write instead of what was written.
|
|
42
|
+
*
|
|
43
|
+
* Three forms, and which one appears is a fact about the deployment. An empty
|
|
44
|
+
* registry says so in a word. A registry that fits is printed whole. One that
|
|
45
|
+
* does not is printed to the cap and then says what it is standing in for —
|
|
46
|
+
* `(nearest 5 of 21)` rather than a trailing count alone, because five ids with
|
|
47
|
+
* no explanation read as the first five somebody registered, which would send a
|
|
48
|
+
* reader looking in the wrong place.
|
|
49
|
+
*
|
|
50
|
+
* **Fitting is one more than the cap**, and that is not an off-by-one. Hiding a
|
|
51
|
+
* single id costs more than showing it: `(nearest 5 of 6)` is seventeen
|
|
52
|
+
* characters to withhold a name that would have cost about twelve. Measured on
|
|
53
|
+
* a real case — the six sources a lesson registers — eliding one saved a single
|
|
54
|
+
* character. The cap is there to bound the clause, so it gives way where it
|
|
55
|
+
* would not.
|
|
56
|
+
*
|
|
57
|
+
* **A list printed whole keeps the order it was registered in**, and only a
|
|
58
|
+
* capped one is ranked. Ranking is how the few are *chosen*; where nothing is
|
|
59
|
+
* being chosen it buys nothing and costs the host its own order, and it would
|
|
60
|
+
* make the same registry print in a different order for every id somebody
|
|
61
|
+
* mistyped — output that cannot be compared between two refusals.
|
|
62
|
+
*/
|
|
63
|
+
export declare const describeRegistered: (wanted: string, available: readonly string[]) => string;
|
|
64
|
+
//# sourceMappingURL=registered.d.ts.map
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Naming what a deployment registered, to somebody who named something else.
|
|
3
|
+
*
|
|
4
|
+
* Three seams refuse an unknown id the same way — a palette, a data source, a
|
|
5
|
+
* submission endpoint — and each answers by listing what it does have, so that
|
|
6
|
+
* whoever reads the log can see what they should have written. The instinct is
|
|
7
|
+
* right and the list is the wrong shape for it: its length is the deployment's
|
|
8
|
+
* to set rather than the runtime's, so a host with a palette per brand turns one
|
|
9
|
+
* diagnostic into a paragraph, in every log line and every panel that prints it.
|
|
10
|
+
*
|
|
11
|
+
* What this bounds is the sentence and nothing else. A refusal still carries
|
|
12
|
+
* every id it knows where a caller can read it, and a registry still publishes
|
|
13
|
+
* its whole catalogue, so the names past the cap are a lookup away rather than
|
|
14
|
+
* gone. The sentence has the narrower job: put the id the reader probably meant
|
|
15
|
+
* in front of them, and say how many it is standing in for.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* How many names a refusal puts in front of a reader.
|
|
19
|
+
*
|
|
20
|
+
* Five, against a measurement: the twenty-four render diagnostics printed side
|
|
21
|
+
* by side came to a median of 144 characters, and the unresolved-theme sentence
|
|
22
|
+
* came to 284 — of which 172 were this list at twenty-one palettes. Five ids of
|
|
23
|
+
* ordinary length is about fifty, which keeps the clause the smaller half of a
|
|
24
|
+
* sentence it used to be the larger half of.
|
|
25
|
+
*/
|
|
26
|
+
export const NEAREST_REGISTERED = 5;
|
|
27
|
+
/** One row of the matrix, from the row above it and the character it is for. */
|
|
28
|
+
const nextRow = (fromCharacter, to, previous, rowIndex) => to.reduce((current, toCharacter, column) => current.concat(Math.min((previous[column] ?? 0) + (fromCharacter === toCharacter ? 0 : 1), (previous[column + 1] ?? 0) + 1, (current[column] ?? 0) + 1)), [rowIndex + 1]);
|
|
29
|
+
/**
|
|
30
|
+
* How many single-character edits turn one id into the other.
|
|
31
|
+
*
|
|
32
|
+
* Two rows rather than a whole matrix, because the only thing ever asked of the
|
|
33
|
+
* result is its size, and the row being built is the only one the next row
|
|
34
|
+
* needs.
|
|
35
|
+
*/
|
|
36
|
+
const editDistance = (from, to) => {
|
|
37
|
+
if (from === to)
|
|
38
|
+
return 0;
|
|
39
|
+
const target = [...to];
|
|
40
|
+
const last = [...from].reduce((previous, fromCharacter, rowIndex) => nextRow(fromCharacter, target, previous, rowIndex), Array.from({ length: target.length + 1 }, (_, index) => index));
|
|
41
|
+
return last[target.length] ?? 0;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Whether one id is written inside the other, which outranks distance.
|
|
45
|
+
*
|
|
46
|
+
* The two mistakes that actually happen are not the same shape. A misspelling
|
|
47
|
+
* is a short edit — `sunsset` for `sunset` — and distance finds it. A half-typed
|
|
48
|
+
* name is a long one: `cat` is fifteen edits from `catalogue.services` and nine
|
|
49
|
+
* from `crm.contacts`, so distance on its own answers a truncation with the
|
|
50
|
+
* wrong part of the registry. Containment is checked first for that case alone.
|
|
51
|
+
*/
|
|
52
|
+
const written = (sought, candidate) => sought.length > 0 && (candidate.includes(sought) || sought.includes(candidate)) ? 0 : 1;
|
|
53
|
+
/**
|
|
54
|
+
* The registered ids closest to the one that was asked for, nearest first.
|
|
55
|
+
*
|
|
56
|
+
* Ranking is what makes a capped list worth reading: the reason to print the
|
|
57
|
+
* registry at all is that the right answer is almost always one of a short
|
|
58
|
+
* list, and the first five in registration order bear no relation to what
|
|
59
|
+
* somebody meant to type.
|
|
60
|
+
*
|
|
61
|
+
* It ranks strings and claims no more than that. Nothing in `sunset` says it
|
|
62
|
+
* and `ember` are both warm, so nothing here will offer `ember`; a seam that
|
|
63
|
+
* wants meaning has to rank on something other than spelling.
|
|
64
|
+
*/
|
|
65
|
+
export const nearestRegistered = (wanted, available, limit = NEAREST_REGISTERED) => {
|
|
66
|
+
const sought = wanted.toLowerCase();
|
|
67
|
+
const kept = Math.max(0, limit);
|
|
68
|
+
/** Nothing to be near. Registration order is the only non-arbitrary answer. */
|
|
69
|
+
if (sought.length === 0)
|
|
70
|
+
return available.slice(0, kept);
|
|
71
|
+
return available
|
|
72
|
+
.map((id, index) => {
|
|
73
|
+
const candidate = id.toLowerCase();
|
|
74
|
+
return {
|
|
75
|
+
id,
|
|
76
|
+
index,
|
|
77
|
+
written: written(sought, candidate),
|
|
78
|
+
distance: editDistance(sought, candidate),
|
|
79
|
+
};
|
|
80
|
+
})
|
|
81
|
+
.sort((left, right) => left.written - right.written ||
|
|
82
|
+
left.distance - right.distance ||
|
|
83
|
+
left.index - right.index)
|
|
84
|
+
.slice(0, kept)
|
|
85
|
+
.map((ranked) => ranked.id);
|
|
86
|
+
};
|
|
87
|
+
/**
|
|
88
|
+
* The clause a refusal ends on: what to write instead of what was written.
|
|
89
|
+
*
|
|
90
|
+
* Three forms, and which one appears is a fact about the deployment. An empty
|
|
91
|
+
* registry says so in a word. A registry that fits is printed whole. One that
|
|
92
|
+
* does not is printed to the cap and then says what it is standing in for —
|
|
93
|
+
* `(nearest 5 of 21)` rather than a trailing count alone, because five ids with
|
|
94
|
+
* no explanation read as the first five somebody registered, which would send a
|
|
95
|
+
* reader looking in the wrong place.
|
|
96
|
+
*
|
|
97
|
+
* **Fitting is one more than the cap**, and that is not an off-by-one. Hiding a
|
|
98
|
+
* single id costs more than showing it: `(nearest 5 of 6)` is seventeen
|
|
99
|
+
* characters to withhold a name that would have cost about twelve. Measured on
|
|
100
|
+
* a real case — the six sources a lesson registers — eliding one saved a single
|
|
101
|
+
* character. The cap is there to bound the clause, so it gives way where it
|
|
102
|
+
* would not.
|
|
103
|
+
*
|
|
104
|
+
* **A list printed whole keeps the order it was registered in**, and only a
|
|
105
|
+
* capped one is ranked. Ranking is how the few are *chosen*; where nothing is
|
|
106
|
+
* being chosen it buys nothing and costs the host its own order, and it would
|
|
107
|
+
* make the same registry print in a different order for every id somebody
|
|
108
|
+
* mistyped — output that cannot be compared between two refusals.
|
|
109
|
+
*/
|
|
110
|
+
export const describeRegistered = (wanted, available) => {
|
|
111
|
+
if (available.length === 0)
|
|
112
|
+
return "none";
|
|
113
|
+
if (available.length <= NEAREST_REGISTERED + 1)
|
|
114
|
+
return available.join(", ");
|
|
115
|
+
const nearest = nearestRegistered(wanted, available);
|
|
116
|
+
return `${nearest.join(", ")} (nearest ${nearest.length} of ${available.length})`;
|
|
117
|
+
};
|
|
118
|
+
//# sourceMappingURL=registered.js.map
|
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
import { type ChangeEvent } from "react";
|
|
2
1
|
/**
|
|
3
2
|
* The third control that runs on the client, and the first that hands a value
|
|
4
3
|
* back to the primitive that placed it.
|
|
@@ -20,11 +19,20 @@ import { type ChangeEvent } from "react";
|
|
|
20
19
|
*
|
|
21
20
|
* **It renders nothing until it knows scripting runs**, for the reason the other
|
|
22
21
|
* two give, and here the fallback is the whole point rather than a consolation.
|
|
23
|
-
* A primitive reads the value as `var(--loom-adjust,
|
|
22
|
+
* A primitive reads the value as `var(--loom-adjust, 35)` with its own declared
|
|
24
23
|
* position as the fallback, so a page served with scripting off shows the still
|
|
25
24
|
* comparison at the position the tree asked for — which is what most pages using
|
|
26
25
|
* this actually are. Nothing is hidden behind a control that never arrives.
|
|
27
26
|
*
|
|
27
|
+
* **And it publishes nothing until the reader moves it**, which is the half that
|
|
28
|
+
* had to be learned from a photograph. Appearing is not an instruction: a
|
|
29
|
+
* control that wrote its own resting value the moment it mounted overwrote the
|
|
30
|
+
* fallback it was built to defend, so a band authored at 35 rendered at 35 and
|
|
31
|
+
* jumped to the runtime's midpoint as hydration landed. Where it starts is the
|
|
32
|
+
* primitive's to declare — {@link ADJUST_RESTING_PROPERTY}, read off the
|
|
33
|
+
* element it was placed in — and what it publishes is the reader's alone. See
|
|
34
|
+
* [0226](../../decisions/0226-a-primitive-declares-where-its-control-rests-and-the-control-publishes-nothing-until-the-reader-moves-it.md).
|
|
35
|
+
*
|
|
28
36
|
* **A range input rather than a hand-built handle.** Dragging, arrow keys, Home
|
|
29
37
|
* and End, the announced role and the announced value are all a browser's to get
|
|
30
38
|
* right, and a `role="slider"` div reimplements every one of them worse. The
|
|
@@ -42,21 +50,5 @@ export type AdjustControlProps = {
|
|
|
42
50
|
*/
|
|
43
51
|
readonly label: string;
|
|
44
52
|
};
|
|
45
|
-
export declare const AdjustControl: ({ label }: AdjustControlProps) => import("react").
|
|
46
|
-
ref: import("react").RefObject<HTMLInputElement | null>;
|
|
47
|
-
type: string;
|
|
48
|
-
className: string;
|
|
49
|
-
min: number;
|
|
50
|
-
max: number;
|
|
51
|
-
value: number;
|
|
52
|
-
"aria-label": string;
|
|
53
|
-
onChange: (event: ChangeEvent<HTMLInputElement>) => void;
|
|
54
|
-
style: {
|
|
55
|
-
readonly accentColor: "var(--loom-accent, currentColor)";
|
|
56
|
-
readonly display: string;
|
|
57
|
-
readonly cursor: "grab";
|
|
58
|
-
readonly margin: 0;
|
|
59
|
-
readonly verticalAlign: "middle";
|
|
60
|
-
};
|
|
61
|
-
}, HTMLInputElement> | null;
|
|
53
|
+
export declare const AdjustControl: ({ label }: AdjustControlProps) => import("react").FunctionComponentElement<AdjustControlProps> | null;
|
|
62
54
|
//# sourceMappingURL=behaviour-adjust.d.ts.map
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use client";
|
|
2
|
-
import { createElement, useCallback, useEffect, useRef, useState } from "react";
|
|
3
|
-
import { ADJUST_MAXIMUM, ADJUST_MINIMUM, ADJUST_PROPERTY, ADJUST_RESTING } from "./behaviour.js";
|
|
2
|
+
import { createElement, useCallback, useEffect, useLayoutEffect, useRef, useState, } from "react";
|
|
3
|
+
import { ADJUST_MAXIMUM, ADJUST_MINIMUM, ADJUST_PROPERTY, ADJUST_RESTING, ADJUST_RESTING_PROPERTY, } from "./behaviour.js";
|
|
4
4
|
import { controlClass, controlDisplay } from "./control.js";
|
|
5
5
|
/**
|
|
6
6
|
* `var()` with a fallback rather than the `tokens.ts` helpers, for the reason
|
|
@@ -26,22 +26,65 @@ const INPUT_STYLE = {
|
|
|
26
26
|
margin: 0,
|
|
27
27
|
verticalAlign: "middle",
|
|
28
28
|
};
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
29
|
+
/**
|
|
30
|
+
* Where the primitive asked its control to start, read off the element the
|
|
31
|
+
* control was placed in.
|
|
32
|
+
*
|
|
33
|
+
* The **computed** value rather than the inline one, because a custom property
|
|
34
|
+
* is a cascaded value and a primitive may declare it in a rule as readily as in
|
|
35
|
+
* a style attribute. It inherits, like any custom property, which is the same
|
|
36
|
+
* reach `ADJUST_PROPERTY` has in the other direction.
|
|
37
|
+
*
|
|
38
|
+
* Clamped and rounded rather than trusted. The range is the runtime's (0096), so
|
|
39
|
+
* a number outside it is not a position this control can take, and a fractional
|
|
40
|
+
* one is not a position a step-1 input can hold — state and thumb would disagree
|
|
41
|
+
* from the first frame. Anything unreadable falls back to {@link ADJUST_RESTING},
|
|
42
|
+
* which is also what a primitive declaring nothing gets: a control that refused
|
|
43
|
+
* to render because a stylesheet said `--loom-adjust-resting: thirty` would be a
|
|
44
|
+
* missing comparison, and the still version is right there in the `var()`
|
|
45
|
+
* fallback.
|
|
46
|
+
*/
|
|
47
|
+
const restingIn = (element) => {
|
|
48
|
+
const declared = getComputedStyle(element).getPropertyValue(ADJUST_RESTING_PROPERTY).trim();
|
|
49
|
+
if (declared === "")
|
|
50
|
+
return ADJUST_RESTING;
|
|
51
|
+
const value = Number(declared);
|
|
52
|
+
if (!Number.isFinite(value))
|
|
53
|
+
return ADJUST_RESTING;
|
|
54
|
+
return Math.min(ADJUST_MAXIMUM, Math.max(ADJUST_MINIMUM, Math.round(value)));
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* The input itself, split from the capability check so that the two things that
|
|
58
|
+
* must happen in a browser are not conditioned on each other.
|
|
59
|
+
*
|
|
60
|
+
* It exists for the adoption below. Reading the parent needs the input mounted,
|
|
61
|
+
* which needs the check to have passed — so the read cannot share an effect with
|
|
62
|
+
* the check, and a `useLayoutEffect` in the component that also renders on the
|
|
63
|
+
* server is a warning about a hook that does nothing there. A component that
|
|
64
|
+
* mounts only once scripting is proved has no server render to warn about.
|
|
65
|
+
*/
|
|
66
|
+
const AdjustSlider = ({ label }) => {
|
|
32
67
|
const input = useRef(null);
|
|
68
|
+
const [position, setPosition] = useState(ADJUST_RESTING);
|
|
69
|
+
const [moved, setMoved] = useState(false);
|
|
33
70
|
/**
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
71
|
+
* Before the first paint, not after it. A passive effect here would let the
|
|
72
|
+
* browser paint one frame with the thumb at the runtime's midpoint on a page
|
|
73
|
+
* that declared something else — the whole defect in miniature, a sixtieth of
|
|
74
|
+
* a second long. A layout effect's `setPosition` re-renders synchronously, so
|
|
75
|
+
* the first frame the reader sees is already the declared one.
|
|
39
76
|
*/
|
|
40
|
-
|
|
77
|
+
useLayoutEffect(() => {
|
|
78
|
+
const parent = input.current?.parentElement;
|
|
79
|
+
if (parent)
|
|
80
|
+
setPosition(restingIn(parent));
|
|
81
|
+
}, []);
|
|
41
82
|
/**
|
|
42
|
-
* `
|
|
43
|
-
*
|
|
44
|
-
*
|
|
83
|
+
* `moved` is the whole of the contract this effect keeps: until the reader has
|
|
84
|
+
* moved the control there is nothing to publish, because the primitive's own
|
|
85
|
+
* `var()` fallback already says where the divider is and this agrees with it.
|
|
86
|
+
* Writing the same number anyway would be indistinguishable on a page whose
|
|
87
|
+
* fallback matches and wrong on every page whose fallback does not.
|
|
45
88
|
*
|
|
46
89
|
* The cleanup removes the property rather than leaving the last value behind.
|
|
47
90
|
* A primitive that unmounts its control — a media query that stops offering
|
|
@@ -51,28 +94,39 @@ export const AdjustControl = ({ label }) => {
|
|
|
51
94
|
*/
|
|
52
95
|
useEffect(() => {
|
|
53
96
|
const parent = input.current?.parentElement;
|
|
54
|
-
if (!parent)
|
|
97
|
+
if (!parent || !moved)
|
|
55
98
|
return undefined;
|
|
56
|
-
parent.style.setProperty(ADJUST_PROPERTY, String(
|
|
99
|
+
parent.style.setProperty(ADJUST_PROPERTY, String(position));
|
|
57
100
|
return () => {
|
|
58
101
|
parent.style.removeProperty(ADJUST_PROPERTY);
|
|
59
102
|
};
|
|
60
|
-
}, [
|
|
103
|
+
}, [moved, position]);
|
|
61
104
|
const change = useCallback((event) => {
|
|
62
|
-
|
|
105
|
+
setPosition(Number(event.target.value));
|
|
106
|
+
setMoved(true);
|
|
63
107
|
}, []);
|
|
64
|
-
if (!usable)
|
|
65
|
-
return null;
|
|
66
108
|
return createElement("input", {
|
|
67
109
|
ref: input,
|
|
68
110
|
type: "range",
|
|
69
111
|
className: controlClass("adjust"),
|
|
70
112
|
min: ADJUST_MINIMUM,
|
|
71
113
|
max: ADJUST_MAXIMUM,
|
|
72
|
-
value,
|
|
114
|
+
value: position,
|
|
73
115
|
"aria-label": label,
|
|
74
116
|
onChange: change,
|
|
75
117
|
style: INPUT_STYLE,
|
|
76
118
|
});
|
|
77
119
|
};
|
|
120
|
+
export const AdjustControl = ({ label }) => {
|
|
121
|
+
const [usable, setUsable] = useState(false);
|
|
122
|
+
/**
|
|
123
|
+
* Deliberately an effect rather than a render-time check, for the reason the
|
|
124
|
+
* other two controls give: anything read while rendering would make the
|
|
125
|
+
* server's markup and the browser's first render disagree, and React resolves
|
|
126
|
+
* that by keeping the server's — so the control would be missing exactly where
|
|
127
|
+
* it works. That the effect ran is the whole of the capability check.
|
|
128
|
+
*/
|
|
129
|
+
useEffect(() => setUsable(true), []);
|
|
130
|
+
return usable ? createElement(AdjustSlider, { label }) : null;
|
|
131
|
+
};
|
|
78
132
|
//# sourceMappingURL=behaviour-adjust.js.map
|
|
@@ -22,6 +22,14 @@ import { type MouseEvent } from "react";
|
|
|
22
22
|
* facts about the region and the page around it, which is the half the primitive
|
|
23
23
|
* owns. A primitive that presents a *modal* region has to arrange them and this
|
|
24
24
|
* seam neither helps nor hinders it.
|
|
25
|
+
*
|
|
26
|
+
* **What is here, and is not any of those three.** The trigger's button is this
|
|
27
|
+
* control's, so where a reader is left when the region closes is this control's
|
|
28
|
+
* too ([0237](../../decisions/0237-a-presentation-returns-the-reader-to-its-trigger-and-only-from-inside-the-region-it-closed.md)).
|
|
29
|
+
* A region hidden while a reader stood inside it leaves them on nothing, and the
|
|
30
|
+
* fix is one `focus()` onto a button this file rendered — not a fact about any
|
|
31
|
+
* element the primitive laid out. The three a modal needs are unchanged and
|
|
32
|
+
* still absent.
|
|
25
33
|
*/
|
|
26
34
|
export type PresentControlProps = {
|
|
27
35
|
/**
|
|
@@ -76,6 +76,13 @@ export const PresentControl = ({ label }) => {
|
|
|
76
76
|
* works.
|
|
77
77
|
*/
|
|
78
78
|
useEffect(() => setUsable(true), []);
|
|
79
|
+
/**
|
|
80
|
+
* Whether the close now in flight should put the reader back on the trigger.
|
|
81
|
+
* A ref rather than state because nothing renders from it: it is set by the
|
|
82
|
+
* handler that decided to close and read by the effect that runs after the
|
|
83
|
+
* attribute has been written, which is one render apart and never two.
|
|
84
|
+
*/
|
|
85
|
+
const returning = useRef(false);
|
|
79
86
|
const toggle = useCallback(() => setOpen((was) => !was), []);
|
|
80
87
|
/**
|
|
81
88
|
* The published state, on the parent. `adjust` writes a custom property on the
|
|
@@ -105,26 +112,70 @@ export const PresentControl = ({ label }) => {
|
|
|
105
112
|
const parent = trigger.current?.parentElement;
|
|
106
113
|
if (!parent)
|
|
107
114
|
return;
|
|
108
|
-
const close = () =>
|
|
115
|
+
const close = (returnFocus) => {
|
|
116
|
+
returning.current = returnFocus;
|
|
117
|
+
setOpen(false);
|
|
118
|
+
};
|
|
119
|
+
/**
|
|
120
|
+
* Escape is heard on the document, so the reader may be anywhere — including
|
|
121
|
+
* the page behind an open region, because nothing traps focus there at all
|
|
122
|
+
* (0176). Returning them only when they are still inside the box is the same
|
|
123
|
+
* fact as that limit rather than a separate rule.
|
|
124
|
+
*/
|
|
109
125
|
const onKeyDown = (event) => {
|
|
110
|
-
if (event.key
|
|
111
|
-
|
|
126
|
+
if (event.key !== "Escape")
|
|
127
|
+
return;
|
|
128
|
+
close(parent.contains(document.activeElement));
|
|
112
129
|
};
|
|
130
|
+
/**
|
|
131
|
+
* A press outside is itself a destination, so it never moves the reader. The
|
|
132
|
+
* ordering is the reason this cannot be settled by reading `activeElement`
|
|
133
|
+
* like Escape does: `pointerdown` fires *before* the browser moves focus to
|
|
134
|
+
* what was pressed, so at this instant focus is still inside the region the
|
|
135
|
+
* press is closing, and a control that read it here would pull the reader
|
|
136
|
+
* off the thing they had just clicked.
|
|
137
|
+
*/
|
|
113
138
|
const onPointerDown = (event) => {
|
|
114
139
|
const target = event.target;
|
|
115
140
|
if (target instanceof Node && parent.contains(target))
|
|
116
141
|
return;
|
|
117
|
-
close();
|
|
142
|
+
close(false);
|
|
118
143
|
};
|
|
144
|
+
/**
|
|
145
|
+
* Always, and without asking where focus is. The cross is inside the region
|
|
146
|
+
* by construction — it is the one control whose placement the seam refuses
|
|
147
|
+
* to register anywhere else — so pressing it is a reader asking to leave,
|
|
148
|
+
* whatever the browser did about focusing a button on click. That disagreement
|
|
149
|
+
* is real: Safari does not focus one, every other engine does, and a keyboard
|
|
150
|
+
* press focuses it everywhere. Reading focus here would make the keyboard
|
|
151
|
+
* case work and the Safari case silently not.
|
|
152
|
+
*/
|
|
153
|
+
const onDismiss = () => close(true);
|
|
119
154
|
document.addEventListener("keydown", onKeyDown);
|
|
120
155
|
document.addEventListener("pointerdown", onPointerDown);
|
|
121
|
-
parent.addEventListener(DISMISS_EVENT,
|
|
156
|
+
parent.addEventListener(DISMISS_EVENT, onDismiss);
|
|
122
157
|
return () => {
|
|
123
158
|
document.removeEventListener("keydown", onKeyDown);
|
|
124
159
|
document.removeEventListener("pointerdown", onPointerDown);
|
|
125
|
-
parent.removeEventListener(DISMISS_EVENT,
|
|
160
|
+
parent.removeEventListener(DISMISS_EVENT, onDismiss);
|
|
126
161
|
};
|
|
127
162
|
}, [open]);
|
|
163
|
+
/**
|
|
164
|
+
* The return itself, in its own effect and after the one that writes the
|
|
165
|
+
* attribute, so the region is already hidden when the reader arrives on the
|
|
166
|
+
* button. Declaration order is what guarantees that: React runs an element's
|
|
167
|
+
* effects in the order they were written.
|
|
168
|
+
*
|
|
169
|
+
* The trigger is never the element that gets hidden — it is a child of the box
|
|
170
|
+
* the attribute lands on and the region is another — so there is nothing here
|
|
171
|
+
* that depends on how the primitive wrote its rule.
|
|
172
|
+
*/
|
|
173
|
+
useEffect(() => {
|
|
174
|
+
if (open || !returning.current)
|
|
175
|
+
return;
|
|
176
|
+
returning.current = false;
|
|
177
|
+
trigger.current?.focus();
|
|
178
|
+
}, [open]);
|
|
128
179
|
if (!usable)
|
|
129
180
|
return null;
|
|
130
181
|
return createElement("button", {
|