@jam-overture/loom 0.1.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/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- package/package.json +160 -0
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
import type { ZodType, ZodTypeDef } from "zod";
|
|
2
|
+
import { type CataloguedProp, type ClosedChoice } from "../catalogue.js";
|
|
3
|
+
import type { InteractiveWhen } from "../interactivity.js";
|
|
4
|
+
import type { JsonObject, JsonObjectView } from "../json.js";
|
|
5
|
+
import type { BehaviourName } from "../render/behaviour.js";
|
|
6
|
+
import type { LoomPrimitive } from "../render/primitive.js";
|
|
7
|
+
import type { PropsVerdict } from "../render/props.js";
|
|
8
|
+
import type { BindingDeclaration } from "../render/reads.js";
|
|
9
|
+
import { type PrimitiveText } from "../render/text.js";
|
|
10
|
+
import type { PrimitiveRole } from "../role.js";
|
|
11
|
+
/**
|
|
12
|
+
* The registration contract: what an author declares to make a component
|
|
13
|
+
* something a Loom tree may name.
|
|
14
|
+
*
|
|
15
|
+
* Four things, and each one exists because something downstream cannot work
|
|
16
|
+
* without it:
|
|
17
|
+
*
|
|
18
|
+
* - `type` — the identifier a tree addresses it by. Validated at registration,
|
|
19
|
+
* not here, because a raw string is what an author writes and the registry is
|
|
20
|
+
* the boundary.
|
|
21
|
+
* - `description` — one line, for the catalogue. A model choosing between
|
|
22
|
+
* `loom.card` and `loom.panel` has nothing else to go on.
|
|
23
|
+
* - `props` — the schema the render seam enforces (0009). Required, with no
|
|
24
|
+
* "unvalidated" option: props in a tree are AI-authored, and a primitive that
|
|
25
|
+
* declines to say what it accepts is asking the deployment to trust a model's
|
|
26
|
+
* guess about its own internals.
|
|
27
|
+
* - `slots` — the named regions it projects into, so a proposal can be told
|
|
28
|
+
* where children may go rather than discovering it by being refused.
|
|
29
|
+
* - `text` — the strings the primitive owns rather than reads from the tree, in
|
|
30
|
+
* the author's own language, so a deployment has something to translate and a
|
|
31
|
+
* model has nothing to write. Optional: most primitives own no strings at all.
|
|
32
|
+
* - `interactive` — whether it renders a target the reader aims at, so the Gate
|
|
33
|
+
* can refuse a change that puts one inside another (0064). Optional, and the
|
|
34
|
+
* only field here that is read by nothing at render time: it exists so the
|
|
35
|
+
* author who knows the component emits an anchor is the one who says so.
|
|
36
|
+
* - `submits` — whether it posts, so a deployment can be told that a primitive
|
|
37
|
+
* which needs a destination is registered and that the seam feeding it is
|
|
38
|
+
* wired (0065). Optional, read by nothing at render time, and the one
|
|
39
|
+
* declaration the audit checks against behaviour rather than taking on trust.
|
|
40
|
+
* - `frames` — which of its props reach an `iframe`, so the render seam can
|
|
41
|
+
* hold each one against the origins the deployment permits (0095). Optional,
|
|
42
|
+
* and unlike `submits` it is read at render time: nothing else in the system
|
|
43
|
+
* can tell a `src` bound for a frame from a `src` bound for an image.
|
|
44
|
+
* - `role` — what part it plays, so a consumer can ask the registry a
|
|
45
|
+
* categorical question instead of matching on the type string (0114).
|
|
46
|
+
* Optional, read by nothing in the runtime, and one of two declarations here
|
|
47
|
+
* whose whole audience is outside this package.
|
|
48
|
+
* - `copy` — which of its props a reader reads as words, so a preview, a review
|
|
49
|
+
* queue or a search can say what a node says (0122). Optional, read by
|
|
50
|
+
* nothing in the runtime, and the one declaration where leaving it out and
|
|
51
|
+
* declaring it empty are different answers.
|
|
52
|
+
* - `reads` — which binding names it reads an answer under, so a model can be
|
|
53
|
+
* told them and the walk can say when a tree asked under a name this
|
|
54
|
+
* primitive never reads (0181). Each entry is a fixed name or the name a prop
|
|
55
|
+
* gives (0184). Optional, and the second declaration where leaving it out and
|
|
56
|
+
* declaring it empty differ.
|
|
57
|
+
*/
|
|
58
|
+
export type PrimitiveDefinition<TProps extends JsonObjectView = JsonObject, TText extends string = never, TBehaviour extends BehaviourName = never> = {
|
|
59
|
+
readonly type: string;
|
|
60
|
+
readonly description: string;
|
|
61
|
+
readonly props: ZodType<TProps, ZodTypeDef, unknown>;
|
|
62
|
+
readonly slots?: readonly string[];
|
|
63
|
+
/**
|
|
64
|
+
* Declared strings, by key. The keys are inferred, so the component's
|
|
65
|
+
* `loom.text` is typed to exactly what was declared here — an author who
|
|
66
|
+
* reads a key they did not declare finds out at the declaration, which is the
|
|
67
|
+
* same bargain the props schema makes.
|
|
68
|
+
*/
|
|
69
|
+
readonly text?: Readonly<Record<TText, string>>;
|
|
70
|
+
/**
|
|
71
|
+
* `"always"` for a primitive that is a target however it is configured, or
|
|
72
|
+
* `{ whenProps }` naming the props that make it one — `href` on a card, which
|
|
73
|
+
* is a plain surface without it. The named props must be props the schema
|
|
74
|
+
* declares; the registry refuses a declaration that names one it does not, so
|
|
75
|
+
* a renamed prop cannot leave this quietly pointing at nothing.
|
|
76
|
+
*/
|
|
77
|
+
readonly interactive?: InteractiveWhen;
|
|
78
|
+
/**
|
|
79
|
+
* `true` for a primitive whose job includes sending what it collected. It
|
|
80
|
+
* takes no conditional form, unlike `interactive`: a card is a target only
|
|
81
|
+
* when the tree gives it an `href`, but a form is a form, and a primitive
|
|
82
|
+
* that posts under one prop value and not another is two primitives.
|
|
83
|
+
*
|
|
84
|
+
* Nothing reads it at render time and nothing needs it to render — a
|
|
85
|
+
* component is handed `loom.submit` whenever its node declared one, declared
|
|
86
|
+
* or not. What it buys is that the audit can tell the two silent failures
|
|
87
|
+
* apart: a primitive that says it posts and places no address, and one that
|
|
88
|
+
* places an address without ever having said it posts.
|
|
89
|
+
*/
|
|
90
|
+
readonly submits?: boolean;
|
|
91
|
+
/**
|
|
92
|
+
* The props whose values this primitive puts in an `iframe` — `["src"]` on an
|
|
93
|
+
* embed. Empty for everything else, which is every other primitive there is.
|
|
94
|
+
*
|
|
95
|
+
* A list of prop names rather than a `true`, because the runtime has to know
|
|
96
|
+
* *which* string to check and there is nothing it could infer that from: a
|
|
97
|
+
* `src` reaching an `iframe` and a `src` reaching an `img` are the same JSON.
|
|
98
|
+
* The named props must be props the schema declares; the registry refuses a
|
|
99
|
+
* declaration that names one it does not, the same way it refuses an
|
|
100
|
+
* `interactive` trigger that has been renamed out from under it — the drift
|
|
101
|
+
* that actually happens is a prop renamed and a declaration left pointing at
|
|
102
|
+
* nothing, which would silently stop checking the URL rather than fail.
|
|
103
|
+
*/
|
|
104
|
+
readonly frames?: readonly string[];
|
|
105
|
+
/**
|
|
106
|
+
* The controls this primitive takes from the runtime's closed behaviour
|
|
107
|
+
* vocabulary — `["copy"]` on a code panel. Optional, and empty for almost
|
|
108
|
+
* everything: a Loom page is data, and a behaviour is the exception that has
|
|
109
|
+
* to be asked for by name.
|
|
110
|
+
*
|
|
111
|
+
* Declaring one is a claim with two consequences the registry checks. The
|
|
112
|
+
* strings the control needs become strings this primitive must declare, so it
|
|
113
|
+
* has a name in every language the deployment serves; and a control is a
|
|
114
|
+
* target the reader aims at, so this primitive must also declare itself
|
|
115
|
+
* `interactive` or the Gate will let one sit inside an anchor.
|
|
116
|
+
*/
|
|
117
|
+
readonly behaviours?: readonly TBehaviour[];
|
|
118
|
+
/**
|
|
119
|
+
* What part this primitive plays — `"heading"` on anything a reader takes as
|
|
120
|
+
* the title of what follows, whatever it is called. Optional, and absent on
|
|
121
|
+
* almost everything: most primitives are an arrangement or a surface and play
|
|
122
|
+
* no part a consumer asks about categorically.
|
|
123
|
+
*
|
|
124
|
+
* A role travels in the opposite direction from every other declaration here.
|
|
125
|
+
* `interactive` and `frames` are read by the runtime and constrain what a tree
|
|
126
|
+
* may do; a role is read by a *host* and constrains nothing. It is here rather
|
|
127
|
+
* than in a host's own table for the same reason `description` is: the author
|
|
128
|
+
* of the component is the one who knows, and a table maintained beside the
|
|
129
|
+
* registry goes stale the day somebody registers a second heading.
|
|
130
|
+
*
|
|
131
|
+
* Typed rather than free — see `role.ts` for why the vocabulary is closed and
|
|
132
|
+
* why it currently has one member. A host writing JavaScript can still hand
|
|
133
|
+
* over a string the runtime does not know, so the registry refuses one rather
|
|
134
|
+
* than letting a misspelling read as "declares no role".
|
|
135
|
+
*/
|
|
136
|
+
readonly role?: PrimitiveRole;
|
|
137
|
+
/**
|
|
138
|
+
* The props whose values a reader reads as words — `["value", "label",
|
|
139
|
+
* "caption"]` on a stat, `[]` on an arrangement that shows none of its own.
|
|
140
|
+
*
|
|
141
|
+
* Optional, and the distinction between `[]` and leaving it out is the whole
|
|
142
|
+
* of what it buys (0122). `[]` says *this primitive shows no words of its
|
|
143
|
+
* own*; absence says *nobody has said*, and `copyIn` reports the second and
|
|
144
|
+
* trusts the first. A default would collapse them, which is why there is
|
|
145
|
+
* none.
|
|
146
|
+
*
|
|
147
|
+
* Read by nothing in the runtime, like `role` and `submits`: it changes no
|
|
148
|
+
* render and constrains no tree. The named props must be props the schema
|
|
149
|
+
* declares, and the registry refuses a declaration that names one it does
|
|
150
|
+
* not — the same drift `frames` and `interactive` are checked for, with less
|
|
151
|
+
* riding on it and the same silence when it happens.
|
|
152
|
+
*/
|
|
153
|
+
readonly copy?: readonly string[];
|
|
154
|
+
/**
|
|
155
|
+
* The binding names this primitive reads an answer under — `["entries"]` on a
|
|
156
|
+
* feed, `[]` on everything that draws only what the tree wrote.
|
|
157
|
+
*
|
|
158
|
+
* A tree's `loom:data` maps a *name* to a source, and the name is how the
|
|
159
|
+
* primitive reading the answer finds it. Until this existed, the name
|
|
160
|
+
* was the one thing in that declaration nothing could check: an unregistered
|
|
161
|
+
* source is refused and a param the source did not declare is refused, but a
|
|
162
|
+
* name nothing reads resolves cleanly and is then read by nobody. Declaring
|
|
163
|
+
* the names is what lets something say so.
|
|
164
|
+
*
|
|
165
|
+
* An entry is either a name or `{ fromProp, default }`, which says *under
|
|
166
|
+
* whichever name this prop gives, and this one when it gives none* (0184).
|
|
167
|
+
* The second form is what a primitive that takes its binding name from a prop
|
|
168
|
+
* has to declare, because a fixed list could only say something untrue about
|
|
169
|
+
* it.
|
|
170
|
+
*
|
|
171
|
+
* Optional, and — like `copy`, and for the same reason — leaving it out and
|
|
172
|
+
* declaring it empty are different answers. `[]` says *this primitive reads
|
|
173
|
+
* no data*; absence says *nobody has said*, and the seam reports the second
|
|
174
|
+
* and trusts the first. A default would collapse them into a claim no author
|
|
175
|
+
* made, and the claim would be wrong for every bound primitive written before
|
|
176
|
+
* anyone thought to declare one.
|
|
177
|
+
*
|
|
178
|
+
* A name is checked against the binding grammar rather than against the props
|
|
179
|
+
* schema, because it is not a prop name. The one half that *is* a prop name —
|
|
180
|
+
* `fromProp` — is checked against the schema the way `copy` and `frames` are,
|
|
181
|
+
* so a declaration cannot go on naming a prop that was renamed away.
|
|
182
|
+
*/
|
|
183
|
+
readonly reads?: readonly BindingDeclaration[];
|
|
184
|
+
readonly component: LoomPrimitive<TProps, TText, TBehaviour>;
|
|
185
|
+
};
|
|
186
|
+
/**
|
|
187
|
+
* A definition with its prop type erased, which is what a heterogeneous
|
|
188
|
+
* registry can hold. `definePrimitive` is the only way to build one, so the
|
|
189
|
+
* erasure happens exactly once, in the one place that still has both the schema
|
|
190
|
+
* and the component type in hand and can prove they agree.
|
|
191
|
+
*/
|
|
192
|
+
export type PrimitiveEntry = {
|
|
193
|
+
readonly type: string;
|
|
194
|
+
readonly description: string;
|
|
195
|
+
readonly slots: readonly string[];
|
|
196
|
+
readonly component: LoomPrimitive;
|
|
197
|
+
readonly declaredProps: readonly CataloguedProp[] | undefined;
|
|
198
|
+
/**
|
|
199
|
+
* The props whose accepted values can be listed, so the conformance probe can
|
|
200
|
+
* ask the primitive what it does under each one rather than under whichever
|
|
201
|
+
* shape it happens to take with no props at all (0075). Empty for the
|
|
202
|
+
* primitive whose rendering does not turn on a closed choice, which is most.
|
|
203
|
+
*/
|
|
204
|
+
readonly choices: readonly ClosedChoice[];
|
|
205
|
+
/** Declared strings, keys erased alongside the props type. Empty when none. */
|
|
206
|
+
readonly text: PrimitiveText<string>;
|
|
207
|
+
/** Absent for the ordinary primitive, which is not a target at all. */
|
|
208
|
+
readonly interactive: InteractiveWhen | undefined;
|
|
209
|
+
/** `false` for the ordinary primitive, which sends nothing anywhere. */
|
|
210
|
+
readonly submits: boolean;
|
|
211
|
+
/** Declared framable prop names, still raw: the registry is what checks them. */
|
|
212
|
+
readonly frames: readonly string[];
|
|
213
|
+
/** Declared behaviour names, still raw: the registry is what checks them. */
|
|
214
|
+
readonly behaviours: readonly string[];
|
|
215
|
+
/**
|
|
216
|
+
* The declared role, still raw: the registry is what checks it, for the same
|
|
217
|
+
* reason it checks a behaviour name. `undefined` for the primitive that plays
|
|
218
|
+
* no part a consumer asks about, which is most of them.
|
|
219
|
+
*/
|
|
220
|
+
readonly role: string | undefined;
|
|
221
|
+
/**
|
|
222
|
+
* Declared copy prop names, still raw: the registry is what checks them.
|
|
223
|
+
* `undefined` is carried through rather than defaulted to `[]`, because the
|
|
224
|
+
* two mean different things here and all the way out to `copyIn`.
|
|
225
|
+
*/
|
|
226
|
+
readonly copy: readonly string[] | undefined;
|
|
227
|
+
/**
|
|
228
|
+
* Declared binding names, still raw: the registry is what checks them.
|
|
229
|
+
* `undefined` is carried through rather than defaulted to `[]`, because the
|
|
230
|
+
* two mean different things here and all the way out to the render walk.
|
|
231
|
+
*/
|
|
232
|
+
readonly reads: readonly BindingDeclaration[] | undefined;
|
|
233
|
+
readonly validate: (props: JsonObject) => PropsVerdict;
|
|
234
|
+
};
|
|
235
|
+
/**
|
|
236
|
+
* Declares a primitive. The generic parameter is inferred from the schema, so
|
|
237
|
+
* the component is checked against what its own schema produces at the point of
|
|
238
|
+
* declaration rather than at the point of registration — an author who reads
|
|
239
|
+
* `props.titel` finds out here.
|
|
240
|
+
*/
|
|
241
|
+
export declare const definePrimitive: <TProps extends JsonObjectView, TText extends string = never, TBehaviour extends BehaviourName = never>(definition: PrimitiveDefinition<TProps, TText, TBehaviour>) => PrimitiveEntry;
|
|
242
|
+
//# sourceMappingURL=definition.d.ts.map
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { catalogueFields, closedChoices } from "../catalogue.js";
|
|
2
|
+
import { NO_TEXT } from "../render/text.js";
|
|
3
|
+
/**
|
|
4
|
+
* Declared text, copied into a frozen null-prototype map at declaration.
|
|
5
|
+
*
|
|
6
|
+
* Copied because the caller keeps a reference to the literal it passed and an
|
|
7
|
+
* entry that shares it is one mutation away from a deployment's strings changing
|
|
8
|
+
* under a rendered page. Null-prototype for the reason `NO_TEXT` gives.
|
|
9
|
+
*/
|
|
10
|
+
const freezeText = (text) => {
|
|
11
|
+
if (!text)
|
|
12
|
+
return NO_TEXT;
|
|
13
|
+
const copy = Object.create(null);
|
|
14
|
+
for (const [key, value] of Object.entries(text))
|
|
15
|
+
copy[key] = value;
|
|
16
|
+
return Object.freeze(copy);
|
|
17
|
+
};
|
|
18
|
+
const toIssue = (issue) => ({
|
|
19
|
+
path: issue.path.length === 0 ? "props" : issue.path.map(String).join("."),
|
|
20
|
+
message: issue.message,
|
|
21
|
+
});
|
|
22
|
+
const verdictFor = (schema, props) => {
|
|
23
|
+
const parsed = schema.safeParse(props);
|
|
24
|
+
/**
|
|
25
|
+
* The parse output is discarded on purpose — see `render/props.ts`. What the
|
|
26
|
+
* primitive receives is the tree's props, so the page is a function of the
|
|
27
|
+
* tree alone and not of which schema version this deployment happens to run.
|
|
28
|
+
*/
|
|
29
|
+
return parsed.success
|
|
30
|
+
? { outcome: "valid" }
|
|
31
|
+
: { outcome: "invalid", issues: parsed.error.issues.map(toIssue) };
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* Declares a primitive. The generic parameter is inferred from the schema, so
|
|
35
|
+
* the component is checked against what its own schema produces at the point of
|
|
36
|
+
* declaration rather than at the point of registration — an author who reads
|
|
37
|
+
* `props.titel` finds out here.
|
|
38
|
+
*/
|
|
39
|
+
export const definePrimitive = (definition) => ({
|
|
40
|
+
type: definition.type,
|
|
41
|
+
description: definition.description,
|
|
42
|
+
slots: definition.slots ?? [],
|
|
43
|
+
text: freezeText(definition.text),
|
|
44
|
+
interactive: definition.interactive,
|
|
45
|
+
submits: definition.submits ?? false,
|
|
46
|
+
frames: definition.frames ?? [],
|
|
47
|
+
behaviours: definition.behaviours ?? [],
|
|
48
|
+
role: definition.role,
|
|
49
|
+
copy: definition.copy,
|
|
50
|
+
reads: definition.reads,
|
|
51
|
+
/**
|
|
52
|
+
* The one narrowing cast in the SDK, and the invariant that makes it sound:
|
|
53
|
+
* a registry hands the renderer this component and the validator built from
|
|
54
|
+
* the same definition's schema, and the renderer only renders a node whose
|
|
55
|
+
* props that validator accepted. Widening the props type here without the
|
|
56
|
+
* validator beside it would be unsound, which is why the registry is what
|
|
57
|
+
* exposes both and why neither is exported alone.
|
|
58
|
+
*/
|
|
59
|
+
component: definition.component,
|
|
60
|
+
declaredProps: catalogueFields(definition.props),
|
|
61
|
+
choices: closedChoices(definition.props),
|
|
62
|
+
validate: (props) => verdictFor(definition.props, props),
|
|
63
|
+
});
|
|
64
|
+
//# sourceMappingURL=definition.js.map
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What an author uses to give Loom a component to render.
|
|
3
|
+
*
|
|
4
|
+
* A primitive is defined with a schema, a description and a component, collected
|
|
5
|
+
* into a registry, and checked at registration rather than at request time.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./audit.js";
|
|
8
|
+
export * from "./catalogue.js";
|
|
9
|
+
export * from "./conformance.js";
|
|
10
|
+
export * from "./copy.js";
|
|
11
|
+
export * from "./definition.js";
|
|
12
|
+
export * from "./interactivity.js";
|
|
13
|
+
export * from "./pairings.js";
|
|
14
|
+
export * from "./registry.js";
|
|
15
|
+
export * from "./selection.js";
|
|
16
|
+
export * from "../role.js";
|
|
17
|
+
export * from "./text.js";
|
|
18
|
+
export * from "./vocabulary.js";
|
|
19
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What an author uses to give Loom a component to render.
|
|
3
|
+
*
|
|
4
|
+
* A primitive is defined with a schema, a description and a component, collected
|
|
5
|
+
* into a registry, and checked at registration rather than at request time.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./audit.js";
|
|
8
|
+
export * from "./catalogue.js";
|
|
9
|
+
export * from "./conformance.js";
|
|
10
|
+
export * from "./copy.js";
|
|
11
|
+
export * from "./definition.js";
|
|
12
|
+
export * from "./interactivity.js";
|
|
13
|
+
export * from "./pairings.js";
|
|
14
|
+
export * from "./registry.js";
|
|
15
|
+
export * from "./selection.js";
|
|
16
|
+
export * from "../role.js";
|
|
17
|
+
export * from "./text.js";
|
|
18
|
+
export * from "./vocabulary.js";
|
|
19
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { InteractiveTypes } from "../interactivity.js";
|
|
2
|
+
import type { PrimitiveRegistry } from "./registry.js";
|
|
3
|
+
/**
|
|
4
|
+
* How a library tells the gate which of its primitives a reader aims at.
|
|
5
|
+
*
|
|
6
|
+
* The declaration is made once, on the primitive, and read here into the
|
|
7
|
+
* vocabulary a policy uses to refuse a change that would nest one target inside
|
|
8
|
+
* another.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* A registry's interactivity declarations, in the shape a Gate policy takes.
|
|
12
|
+
*
|
|
13
|
+
* This is the whole reason the declaration lives on the primitive rather than
|
|
14
|
+
* in a policy file. A host that hand-wrote `{ "loom.card": { whenProps:
|
|
15
|
+
* ["href"] } }` would be maintaining, in a second place, a fact that is only
|
|
16
|
+
* knowable in the first — and the day someone gives `loom.feature` an `href`,
|
|
17
|
+
* the hand-written copy is wrong and nothing says so. Here the library grows
|
|
18
|
+
* and the policy grows with it.
|
|
19
|
+
*
|
|
20
|
+
* `textCatalogue` is the same move for the same reason: derive what a
|
|
21
|
+
* deployment must configure from what its primitives already declare, so the
|
|
22
|
+
* configuration cannot describe a library that is not the one installed.
|
|
23
|
+
*
|
|
24
|
+
* Deriving it is still the host's explicit call, not something a registry
|
|
25
|
+
* imposes. A deployment that wants the check off leaves this out of its policy,
|
|
26
|
+
* and a deployment with a second registry composes two of these.
|
|
27
|
+
*/
|
|
28
|
+
export declare const interactiveTypesFor: (registry: PrimitiveRegistry) => InteractiveTypes;
|
|
29
|
+
//# sourceMappingURL=interactivity.d.ts.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a library tells the gate which of its primitives a reader aims at.
|
|
3
|
+
*
|
|
4
|
+
* The declaration is made once, on the primitive, and read here into the
|
|
5
|
+
* vocabulary a policy uses to refuse a change that would nest one target inside
|
|
6
|
+
* another.
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* A registry's interactivity declarations, in the shape a Gate policy takes.
|
|
10
|
+
*
|
|
11
|
+
* This is the whole reason the declaration lives on the primitive rather than
|
|
12
|
+
* in a policy file. A host that hand-wrote `{ "loom.card": { whenProps:
|
|
13
|
+
* ["href"] } }` would be maintaining, in a second place, a fact that is only
|
|
14
|
+
* knowable in the first — and the day someone gives `loom.feature` an `href`,
|
|
15
|
+
* the hand-written copy is wrong and nothing says so. Here the library grows
|
|
16
|
+
* and the policy grows with it.
|
|
17
|
+
*
|
|
18
|
+
* `textCatalogue` is the same move for the same reason: derive what a
|
|
19
|
+
* deployment must configure from what its primitives already declare, so the
|
|
20
|
+
* configuration cannot describe a library that is not the one installed.
|
|
21
|
+
*
|
|
22
|
+
* Deriving it is still the host's explicit call, not something a registry
|
|
23
|
+
* imposes. A deployment that wants the check off leaves this out of its policy,
|
|
24
|
+
* and a deployment with a second registry composes two of these.
|
|
25
|
+
*/
|
|
26
|
+
export const interactiveTypesFor = (registry) => {
|
|
27
|
+
const types = {};
|
|
28
|
+
for (const primitive of registry.primitives) {
|
|
29
|
+
if (primitive.interactive)
|
|
30
|
+
types[primitive.type] = primitive.interactive;
|
|
31
|
+
}
|
|
32
|
+
return types;
|
|
33
|
+
};
|
|
34
|
+
//# sourceMappingURL=interactivity.js.map
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import type { PrimitiveType } from "../primitive-type.js";
|
|
2
|
+
import type { PaletteSlot } from "../theme/theme.js";
|
|
3
|
+
import type { PrimitiveRegistry } from "./registry.js";
|
|
4
|
+
/**
|
|
5
|
+
* Every foreground-on-background a registry can put on a page, read off the
|
|
6
|
+
* components rather than listed by hand.
|
|
7
|
+
*
|
|
8
|
+
* `PALETTE_TEXT_PAIRINGS` is the list the contrast bar measures, and its own
|
|
9
|
+
* comment claims it is read off `src/primitives`. It was — once, by a person,
|
|
10
|
+
* and then five primitives landed. The gap that opens is quiet in the worst
|
|
11
|
+
* way: the audit reports no failures because it never looked, and a host
|
|
12
|
+
* asserting `failures` empty gets a green tick for a pairing nobody measured.
|
|
13
|
+
* This closes that by deriving the list, so a primitive that renders a new
|
|
14
|
+
* pairing brings the pairing with it.
|
|
15
|
+
*
|
|
16
|
+
* ## The two bases, and why they are not the same claim
|
|
17
|
+
*
|
|
18
|
+
* **`painted`** — one primitive sets the ink and the ground beneath it.
|
|
19
|
+
* `loom.callout` puts `fg-default` on the `bg-surface-muted` it painted. Both
|
|
20
|
+
* ends are the primitive's own and no container can change either, so this is a
|
|
21
|
+
* fact about the component with no judgement in it at all.
|
|
22
|
+
*
|
|
23
|
+
* **`composed`** — a primitive sets an ink and paints no ground under it, so
|
|
24
|
+
* the ground is whatever it was placed in. `loom.perk` writes its excluded note
|
|
25
|
+
* in `fg-subtle` and leaves the surface to its parent;
|
|
26
|
+
* [0008](../../decisions/0008-the-renderer-is-a-total-pure-projection.md)
|
|
27
|
+
* forbids the renderer from enforcing parentage, so any ground the text ramp is
|
|
28
|
+
* held to is a place that note can land. A perk list inside an accent-toned
|
|
29
|
+
* section is an ordinary tree, and this set is strictly larger than the one
|
|
30
|
+
* anybody was maintaining by hand.
|
|
31
|
+
*
|
|
32
|
+
* ## The one thing this cannot derive
|
|
33
|
+
*
|
|
34
|
+
* Which grounds the text ramp is *meant* to work on. The probe can see that
|
|
35
|
+
* `loom.action` puts children on `accent` and that `loom.page` puts them on
|
|
36
|
+
* `bg-canvas`, and nothing in either component says that the first is a filled
|
|
37
|
+
* control carrying its own `fg-on-accent` while the second is a page surface
|
|
38
|
+
* that every ink in the ramp has to be readable on. Both set an ink beside the
|
|
39
|
+
* ground; only one of them means it.
|
|
40
|
+
*
|
|
41
|
+
* That is a palette decision rather than a component fact —
|
|
42
|
+
* [0089](../../decisions/0089-the-text-ramp-is-held-to-four-grounds.md) makes
|
|
43
|
+
* it, and `PALETTE_TEXT_GROUNDS` is where it is written down. Passing it in is
|
|
44
|
+
* what keeps this function free of a rule it would otherwise have to guess:
|
|
45
|
+
* derive everything, declare the grounds, and a host with its own surfaces
|
|
46
|
+
* declares its own. There were four of them until `bg-overlay` joined on
|
|
47
|
+
* 21 September, which is why the list is a value rather than a number in a
|
|
48
|
+
* sentence.
|
|
49
|
+
*/
|
|
50
|
+
/** Whether one primitive set both ends of a pairing, or only the ink. */
|
|
51
|
+
export type PairingBasis = "painted" | "composed";
|
|
52
|
+
/** One foreground-on-background the library can put on a page, and what produces it. */
|
|
53
|
+
export type DerivedPairing = {
|
|
54
|
+
readonly foreground: PaletteSlot;
|
|
55
|
+
readonly background: PaletteSlot;
|
|
56
|
+
readonly basis: PairingBasis;
|
|
57
|
+
/** The primitives that produce it, so a failure names components rather than two slot ids. */
|
|
58
|
+
readonly types: readonly PrimitiveType[];
|
|
59
|
+
};
|
|
60
|
+
/** A ground a primitive puts its declared children and slots on. */
|
|
61
|
+
export type ChildGround = {
|
|
62
|
+
readonly ground: PaletteSlot;
|
|
63
|
+
readonly types: readonly PrimitiveType[];
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* The props a primitive declares that no probe configuration sets, and which
|
|
67
|
+
* therefore mark the edge of what this derivation can see.
|
|
68
|
+
*
|
|
69
|
+
* It is not that the prop is unset — the probe sets nothing but closed choices,
|
|
70
|
+
* so a *required* prop is unset too. It is that a component written as
|
|
71
|
+
* `given.price === undefined ? null : …` produces no element at all under an
|
|
72
|
+
* absent optional prop, so any ink that element paints is invisible here, while
|
|
73
|
+
* a required prop's element still renders and still shows its colour. Optional
|
|
74
|
+
* and not a closed choice is exactly the set a component guards on and the probe
|
|
75
|
+
* cannot open.
|
|
76
|
+
*
|
|
77
|
+
* `undefined` for a primitive whose schema is not an object schema and whose
|
|
78
|
+
* props therefore cannot be enumerated — "I cannot tell you", which is not the
|
|
79
|
+
* same claim as "there are none", and the same distinction `declaredProps`
|
|
80
|
+
* makes.
|
|
81
|
+
*/
|
|
82
|
+
export type UnprobedProps = {
|
|
83
|
+
readonly type: PrimitiveType;
|
|
84
|
+
readonly props: readonly string[] | undefined;
|
|
85
|
+
};
|
|
86
|
+
/** What a registry's components paint, as the contrast bar needs to hear it. */
|
|
87
|
+
export type RegistryPairings = {
|
|
88
|
+
readonly pairings: readonly DerivedPairing[];
|
|
89
|
+
/** Inks a primitive sets without painting a ground of its own. */
|
|
90
|
+
readonly floating: readonly PaletteSlot[];
|
|
91
|
+
/** Every ground a primitive places children on, whether or not the ramp is held to it. */
|
|
92
|
+
readonly childGrounds: readonly ChildGround[];
|
|
93
|
+
/**
|
|
94
|
+
* Grounds children land on that the text ramp is not held to. Not a failure:
|
|
95
|
+
* `accent` is here because `loom.action` fills it and answers the ink itself.
|
|
96
|
+
* It is reported because a *new* ground appearing here is the signal that
|
|
97
|
+
* either a primitive is painting somewhere unconsidered or the declared list
|
|
98
|
+
* has fallen behind the library — the same drift this module exists to catch,
|
|
99
|
+
* one level up.
|
|
100
|
+
*/
|
|
101
|
+
readonly groundsOutsideTheRamp: readonly ChildGround[];
|
|
102
|
+
/** The probe could not answer — neither a pass nor a failure. */
|
|
103
|
+
readonly notProbeable: readonly PrimitiveType[];
|
|
104
|
+
/**
|
|
105
|
+
* Where this derivation stops seeing, by primitive. Only primitives with at
|
|
106
|
+
* least one such prop appear, so an empty list is a real claim: nothing in
|
|
107
|
+
* this registry hides an element behind a prop the probe cannot set.
|
|
108
|
+
*
|
|
109
|
+
* Reported rather than fixed, because the alternative is a probe that invents
|
|
110
|
+
* a price, a date and a URL — and a pairing derived from an invented value is
|
|
111
|
+
* a fact about the invention. A list that says it is read off the components
|
|
112
|
+
* should be able to say which part of them it read.
|
|
113
|
+
*/
|
|
114
|
+
readonly unprobedProps: readonly UnprobedProps[];
|
|
115
|
+
};
|
|
116
|
+
/**
|
|
117
|
+
* Probes every primitive in a registry and assembles what they paint.
|
|
118
|
+
*
|
|
119
|
+
* Pass `PALETTE_TEXT_GROUNDS` unless the host has its own surfaces to declare.
|
|
120
|
+
* Like `auditRegistry`, this calls every registered component, so it belongs in
|
|
121
|
+
* a test or a build step rather than on a request.
|
|
122
|
+
*/
|
|
123
|
+
export declare const registryPairings: (registry: PrimitiveRegistry, textGrounds: readonly PaletteSlot[]) => RegistryPairings;
|
|
124
|
+
//# sourceMappingURL=pairings.d.ts.map
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import { probeColourPairings, probeConfigurations, probeStates } from "./conformance.js";
|
|
2
|
+
const record = (seen, foreground, background, type) => {
|
|
3
|
+
const at = `${foreground}|${background}`;
|
|
4
|
+
const existing = seen.get(at);
|
|
5
|
+
if (existing)
|
|
6
|
+
existing.types.add(type);
|
|
7
|
+
else
|
|
8
|
+
seen.set(at, { foreground, background, types: new Set([type]) });
|
|
9
|
+
};
|
|
10
|
+
const asPairings = (seen, basis) => [...seen.entries()]
|
|
11
|
+
.sort(([a], [b]) => a.localeCompare(b))
|
|
12
|
+
.map(([, entry]) => ({
|
|
13
|
+
foreground: entry.foreground,
|
|
14
|
+
background: entry.background,
|
|
15
|
+
basis,
|
|
16
|
+
types: [...entry.types].sort(),
|
|
17
|
+
}));
|
|
18
|
+
/**
|
|
19
|
+
* The declared props no configuration sets: optional, and not a closed choice.
|
|
20
|
+
* `undefined` props enumerate to `undefined` rather than to nothing.
|
|
21
|
+
*/
|
|
22
|
+
const unprobed = (primitive) => {
|
|
23
|
+
if (primitive.declaredProps === undefined)
|
|
24
|
+
return undefined;
|
|
25
|
+
const varied = new Set(primitive.choices.map((choice) => choice.name));
|
|
26
|
+
return primitive.declaredProps
|
|
27
|
+
.filter((prop) => !prop.required && !varied.has(prop.name))
|
|
28
|
+
.map((prop) => prop.name);
|
|
29
|
+
};
|
|
30
|
+
const asGrounds = (grounds) => [...grounds.entries()]
|
|
31
|
+
.sort(([a], [b]) => a.localeCompare(b))
|
|
32
|
+
.map(([ground, types]) => ({ ground, types: [...types].sort() }));
|
|
33
|
+
/**
|
|
34
|
+
* Probes every primitive in a registry and assembles what they paint.
|
|
35
|
+
*
|
|
36
|
+
* Pass `PALETTE_TEXT_GROUNDS` unless the host has its own surfaces to declare.
|
|
37
|
+
* Like `auditRegistry`, this calls every registered component, so it belongs in
|
|
38
|
+
* a test or a build step rather than on a request.
|
|
39
|
+
*/
|
|
40
|
+
export const registryPairings = (registry, textGrounds) => {
|
|
41
|
+
const probed = registry.primitives.map((primitive) => ({
|
|
42
|
+
type: primitive.type,
|
|
43
|
+
verdict: probeColourPairings(primitive.component, primitive.slots, primitive.text, probeStates(probeConfigurations(primitive.choices))),
|
|
44
|
+
}));
|
|
45
|
+
const painted = new Map();
|
|
46
|
+
const floating = new Map();
|
|
47
|
+
const grounds = new Map();
|
|
48
|
+
for (const { type, verdict } of probed) {
|
|
49
|
+
if (verdict.outcome !== "probed")
|
|
50
|
+
continue;
|
|
51
|
+
for (const pairing of verdict.painted)
|
|
52
|
+
record(painted, pairing.foreground, pairing.background, type);
|
|
53
|
+
for (const ink of verdict.floating) {
|
|
54
|
+
floating.set(ink, (floating.get(ink) ?? new Set()).add(type));
|
|
55
|
+
}
|
|
56
|
+
for (const ground of verdict.childGrounds) {
|
|
57
|
+
grounds.set(ground, (grounds.get(ground) ?? new Set()).add(type));
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
const held = new Set(textGrounds);
|
|
61
|
+
const composed = new Map();
|
|
62
|
+
for (const [ink, types] of floating) {
|
|
63
|
+
for (const ground of textGrounds) {
|
|
64
|
+
if (ink === ground)
|
|
65
|
+
continue;
|
|
66
|
+
for (const type of types)
|
|
67
|
+
record(composed, ink, ground, type);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return {
|
|
71
|
+
pairings: [...asPairings(painted, "painted"), ...asPairings(composed, "composed")],
|
|
72
|
+
floating: [...floating.keys()].sort(),
|
|
73
|
+
childGrounds: asGrounds(grounds),
|
|
74
|
+
groundsOutsideTheRamp: asGrounds(new Map([...grounds].filter(([ground]) => !held.has(ground)))),
|
|
75
|
+
notProbeable: probed.filter(({ verdict }) => verdict.outcome === "not-probeable").map(({ type }) => type),
|
|
76
|
+
unprobedProps: registry.primitives
|
|
77
|
+
.map((primitive) => ({ type: primitive.type, props: unprobed(primitive) }))
|
|
78
|
+
.filter((entry) => entry.props === undefined || entry.props.length > 0),
|
|
79
|
+
};
|
|
80
|
+
};
|
|
81
|
+
//# sourceMappingURL=pairings.js.map
|