@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,197 @@
|
|
|
1
|
+
import type { Palette, PaletteSlot, ThemeId } from "./theme.js";
|
|
2
|
+
/**
|
|
3
|
+
* The contrast bar, as a function a host can run against its own palettes (0074).
|
|
4
|
+
*
|
|
5
|
+
* A palette slot that primitives put text in meets 4.5:1 against every
|
|
6
|
+
* background they pair it with, and the three starter palettes clear it because
|
|
7
|
+
* a test iterating `STARTER_PALETTES` says so. `createThemeRegistry({ palettes })`
|
|
8
|
+
* *replaces* that list (0049), so a host supplying its own gets `paletteSchema` —
|
|
9
|
+
* which checks that every slot holds a colour and has no idea which slots are
|
|
10
|
+
* read as text on which others — and nothing else. A host palette with a 2:1
|
|
11
|
+
* subtle registers, resolves, re-themes and renders.
|
|
12
|
+
*
|
|
13
|
+
* This is the cheap half of the answer and deliberately the whole of it (0076):
|
|
14
|
+
* an audit a host runs in its own tests, not a refusal at registration. The
|
|
15
|
+
* expensive half would decide whether Loom *enforces* accessibility on a host or
|
|
16
|
+
* merely meets it itself, and it would reject palettes that are legal today.
|
|
17
|
+
*
|
|
18
|
+
* It reports; it does not decide — the same bargain `auditRegistry` makes, for
|
|
19
|
+
* the same reason.
|
|
20
|
+
*/
|
|
21
|
+
/** WCAG AA for body text — the bar this module holds every text slot to (0074). */
|
|
22
|
+
export declare const TEXT_CONTRAST_MINIMUM = 4.5;
|
|
23
|
+
/**
|
|
24
|
+
* The grounds every ink in the text ramp has to be readable on (0089).
|
|
25
|
+
*
|
|
26
|
+
* The one thing `registryPairings` cannot derive, and the reason it takes this
|
|
27
|
+
* as an argument. A probe can see that `loom.action` puts children on `accent`
|
|
28
|
+
* and that `loom.page` puts them on `bg-canvas`; nothing in either component
|
|
29
|
+
* says the first is a filled control that answers its own ink with
|
|
30
|
+
* `fg-on-accent` while the second is a page surface where a child brings
|
|
31
|
+
* whichever ink it likes. Both set a colour beside the ground and only one of
|
|
32
|
+
* them means it.
|
|
33
|
+
*
|
|
34
|
+
* So the four are declared here. A ground on this list is one where a palette
|
|
35
|
+
* owes the reader every ink in the ramp; a ground off it is one where the
|
|
36
|
+
* primitive painting it has already answered what colour the text is, and
|
|
37
|
+
* holding a palette to `fg-muted` on `accent` would be a bar no palette can
|
|
38
|
+
* pass — it is 1.00:1 in some palette however the palette is written.
|
|
39
|
+
*/
|
|
40
|
+
export declare const PALETTE_TEXT_GROUNDS: readonly PaletteSlot[];
|
|
41
|
+
/**
|
|
42
|
+
* How a pairing comes about, which decides what a failure means (0089).
|
|
43
|
+
*
|
|
44
|
+
* **`painted`** — one primitive sets both ends. A palette that fails one has a
|
|
45
|
+
* page in it nobody can read, and no tree can avoid it, so this is the bar.
|
|
46
|
+
*
|
|
47
|
+
* **`composed`** — a primitive sets an ink and leaves the ground to whatever it
|
|
48
|
+
* is placed in. Reachable in a legal tree and reported, not asserted: see
|
|
49
|
+
* `PaletteAudit.composedFailures` for why the two are counted apart.
|
|
50
|
+
*/
|
|
51
|
+
export type PairingBasis = "painted" | "composed";
|
|
52
|
+
/**
|
|
53
|
+
* A foreground slot read on a background slot, and where they meet.
|
|
54
|
+
*
|
|
55
|
+
* Read off `src/primitives` rather than imagined, which is what makes the check
|
|
56
|
+
* worth failing over: every pairing here is one some component actually
|
|
57
|
+
* renders, so a palette that fails one has a page in it that a reader cannot
|
|
58
|
+
* read. A pairing nothing renders would be a bar chosen for its own sake.
|
|
59
|
+
*
|
|
60
|
+
* That was a promise a person kept by hand until it was nine pairings out of
|
|
61
|
+
* date. Both halves of it are now checked against the components themselves —
|
|
62
|
+
* `registryPairings` derives what the library renders, and `pairings.test.ts`
|
|
63
|
+
* fails if this list is missing any of it or carries a row nothing renders.
|
|
64
|
+
*
|
|
65
|
+
* **What the derivation does not see, so this list does not claim it.** The
|
|
66
|
+
* probe renders each primitive with nothing configured but its closed choices,
|
|
67
|
+
* so an element a component draws only when an optional prop is given never
|
|
68
|
+
* exists, and the ink it would paint is never derived. That is not a gap the
|
|
69
|
+
* check can close — the alternative is a probe that invents a price and a date,
|
|
70
|
+
* and a pairing derived from an invented value is a fact about the invention —
|
|
71
|
+
* so `RegistryPairings.unprobedProps` names where it stops instead. A row here
|
|
72
|
+
* may therefore be `painted` on the strength of a component read by a person
|
|
73
|
+
* where the probe could only reach `composed`; the checks allow that direction
|
|
74
|
+
* and refuse the other, because declaring a stricter bar than the derivation
|
|
75
|
+
* found is safe and declaring a softer one is how a real failure goes quiet.
|
|
76
|
+
*/
|
|
77
|
+
export type TextPairing = {
|
|
78
|
+
readonly foreground: PaletteSlot;
|
|
79
|
+
readonly background: PaletteSlot;
|
|
80
|
+
readonly basis: PairingBasis;
|
|
81
|
+
/** Where it happens, so a failure names a page rather than two slot ids. */
|
|
82
|
+
readonly where: string;
|
|
83
|
+
};
|
|
84
|
+
export declare const PALETTE_TEXT_PAIRINGS: readonly TextPairing[];
|
|
85
|
+
/**
|
|
86
|
+
* The colour as three 0–255 channels, or nothing when it is a form this cannot
|
|
87
|
+
* measure.
|
|
88
|
+
*
|
|
89
|
+
* `colourSchema` accepts more than hex — `rgb()`, `hsl()`, a named colour, and
|
|
90
|
+
* eight-digit hex with an alpha. Only three- and six-digit hex are measured
|
|
91
|
+
* here, and the rest answer `undefined` rather than a guess:
|
|
92
|
+
*
|
|
93
|
+
* - a named colour needs the CSS colour table, which is 148 entries of vocabulary
|
|
94
|
+
* this module would then own
|
|
95
|
+
* - `hsl()` and modern `rgb()` syntax are a parser, and a parser that is subtly
|
|
96
|
+
* wrong reports a passing ratio for a failing pair, which is worse than
|
|
97
|
+
* reporting nothing
|
|
98
|
+
* - an alpha composites against whatever is behind it, so its contrast is not a
|
|
99
|
+
* property of the two slots at all
|
|
100
|
+
*
|
|
101
|
+
* Answering "I could not measure this" is the same move `not-probeable` makes in
|
|
102
|
+
* the conformance probe: a check that cannot answer says so, rather than passing.
|
|
103
|
+
*
|
|
104
|
+
* Exported because `separation.ts` measures the same palette in a different
|
|
105
|
+
* colour space and has to decline the same forms for the same reasons. Two
|
|
106
|
+
* parsers would be two answers to "is this measurable".
|
|
107
|
+
*/
|
|
108
|
+
export declare const channelsOf: (colour: string) => readonly [number, number, number] | undefined;
|
|
109
|
+
/**
|
|
110
|
+
* Relative luminance, or `undefined` for a form `channelsOf` declines to guess
|
|
111
|
+
* at.
|
|
112
|
+
*
|
|
113
|
+
* A ratio is a question about two colours; **how dark is this** is a question
|
|
114
|
+
* about one, and `measure.ts` has to ask it — a scrim is asked to darken what is
|
|
115
|
+
* under it, and darkening is a property of the wash rather than of a pair. It is
|
|
116
|
+
* computed here, with WCAG's curve, rather than a second time somewhere else
|
|
117
|
+
* against a curve half a rounding away from this one.
|
|
118
|
+
*/
|
|
119
|
+
export declare const relativeLuminance: (colour: string) => number | undefined;
|
|
120
|
+
/**
|
|
121
|
+
* The WCAG contrast ratio between two colours, or `undefined` when either is a
|
|
122
|
+
* form `channelsOf` declines to guess at.
|
|
123
|
+
*/
|
|
124
|
+
export declare const contrastRatio: (a: string, b: string) => number | undefined;
|
|
125
|
+
/** A pairing that was measured, whether or not it cleared the bar. */
|
|
126
|
+
export type MeasuredPairing = {
|
|
127
|
+
readonly pairing: TextPairing;
|
|
128
|
+
readonly ratio: number;
|
|
129
|
+
readonly meets: boolean;
|
|
130
|
+
};
|
|
131
|
+
/** A pairing whose colours could not be measured, and which colour stopped it. */
|
|
132
|
+
export type UnmeasuredPairing = {
|
|
133
|
+
readonly pairing: TextPairing;
|
|
134
|
+
readonly foreground: string;
|
|
135
|
+
readonly background: string;
|
|
136
|
+
};
|
|
137
|
+
/** What the bar found in one palette: what was measured, what failed, what could not be. */
|
|
138
|
+
export type PaletteAudit = {
|
|
139
|
+
readonly palette: ThemeId;
|
|
140
|
+
readonly measured: readonly MeasuredPairing[];
|
|
141
|
+
/**
|
|
142
|
+
* Measured, `painted`, and under the bar. The list a host asserts empty.
|
|
143
|
+
*
|
|
144
|
+
* Painted only, because a painted failure is a page nobody can read and no
|
|
145
|
+
* tree can avoid it — both ends are one primitive's own. That is a defect in
|
|
146
|
+
* the palette with one fix, and asserting it empty is a promise a palette can
|
|
147
|
+
* keep.
|
|
148
|
+
*/
|
|
149
|
+
readonly failures: readonly MeasuredPairing[];
|
|
150
|
+
/**
|
|
151
|
+
* Measured, `composed`, and under the bar — reported rather than asserted.
|
|
152
|
+
*
|
|
153
|
+
* The split is not a softer bar for the same fault, and it is worth being
|
|
154
|
+
* plain about why, because a second list is exactly where an inconvenient
|
|
155
|
+
* failure would go to be forgotten.
|
|
156
|
+
*
|
|
157
|
+
* A composed pairing needs a tree that puts the two together. It is reachable
|
|
158
|
+
* — `loom.perk` inside a `loom.section tone="accent"` is an ordinary page —
|
|
159
|
+
* but whether a given deployment reaches it depends on trees nobody has
|
|
160
|
+
* written yet, and the fix is not always the palette's: an ink that fails on
|
|
161
|
+
* one ground and clears the other three may be a panel that wants moving.
|
|
162
|
+
* Loom measures and reports, and imposing is the host's call — the bargain
|
|
163
|
+
* the contrast bar already makes, applied here one level in (0076).
|
|
164
|
+
*
|
|
165
|
+
* What keeps it honest is that nothing may be *demoted* into it. A pairing
|
|
166
|
+
* any primitive paints is `painted` in the declared list whatever else also
|
|
167
|
+
* composes it, and `library.test.ts` fails if the declared basis is softer
|
|
168
|
+
* than the derivation's.
|
|
169
|
+
*/
|
|
170
|
+
readonly composedFailures: readonly MeasuredPairing[];
|
|
171
|
+
/**
|
|
172
|
+
* Neither a pass nor a failure. Separate from `failures` for the reason
|
|
173
|
+
* `notProbeable` is separate in the registry audit: a host that wants the
|
|
174
|
+
* guarantee asserts both empty, and a host whose palette is written in `hsl()`
|
|
175
|
+
* can tell "unreadable" from "unmeasurable".
|
|
176
|
+
*/
|
|
177
|
+
readonly unmeasured: readonly UnmeasuredPairing[];
|
|
178
|
+
};
|
|
179
|
+
/**
|
|
180
|
+
* Measures every pairing the primitives render, in one palette. Refuses nothing.
|
|
181
|
+
*
|
|
182
|
+
* `pairings` defaults to the list Loom's own library renders. A host passes its
|
|
183
|
+
* own — `registryPairings(registry, PALETTE_TEXT_GROUNDS)` derives it from the
|
|
184
|
+
* components rather than asking anyone to keep a list — and gets the bar held
|
|
185
|
+
* to the primitives it actually registered rather than to ours.
|
|
186
|
+
*/
|
|
187
|
+
export declare const auditPalette: (palette: Palette, pairings?: readonly TextPairing[]) => PaletteAudit;
|
|
188
|
+
/**
|
|
189
|
+
* One line per problem, for a CLI or a failing test's message. Empty when clean.
|
|
190
|
+
*
|
|
191
|
+
* Composed failures are printed too, and said to be composed. A description
|
|
192
|
+
* that showed only what is asserted would let a reader take an empty string for
|
|
193
|
+
* a clean palette, and on eight of the palettes in this library that would be
|
|
194
|
+
* false.
|
|
195
|
+
*/
|
|
196
|
+
export declare const describePaletteAudit: (audit: PaletteAudit) => string;
|
|
197
|
+
//# sourceMappingURL=contrast.d.ts.map
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The contrast bar, as a function a host can run against its own palettes (0074).
|
|
3
|
+
*
|
|
4
|
+
* A palette slot that primitives put text in meets 4.5:1 against every
|
|
5
|
+
* background they pair it with, and the three starter palettes clear it because
|
|
6
|
+
* a test iterating `STARTER_PALETTES` says so. `createThemeRegistry({ palettes })`
|
|
7
|
+
* *replaces* that list (0049), so a host supplying its own gets `paletteSchema` —
|
|
8
|
+
* which checks that every slot holds a colour and has no idea which slots are
|
|
9
|
+
* read as text on which others — and nothing else. A host palette with a 2:1
|
|
10
|
+
* subtle registers, resolves, re-themes and renders.
|
|
11
|
+
*
|
|
12
|
+
* This is the cheap half of the answer and deliberately the whole of it (0076):
|
|
13
|
+
* an audit a host runs in its own tests, not a refusal at registration. The
|
|
14
|
+
* expensive half would decide whether Loom *enforces* accessibility on a host or
|
|
15
|
+
* merely meets it itself, and it would reject palettes that are legal today.
|
|
16
|
+
*
|
|
17
|
+
* It reports; it does not decide — the same bargain `auditRegistry` makes, for
|
|
18
|
+
* the same reason.
|
|
19
|
+
*/
|
|
20
|
+
/** WCAG AA for body text — the bar this module holds every text slot to (0074). */
|
|
21
|
+
export const TEXT_CONTRAST_MINIMUM = 4.5;
|
|
22
|
+
/**
|
|
23
|
+
* The grounds every ink in the text ramp has to be readable on (0089).
|
|
24
|
+
*
|
|
25
|
+
* The one thing `registryPairings` cannot derive, and the reason it takes this
|
|
26
|
+
* as an argument. A probe can see that `loom.action` puts children on `accent`
|
|
27
|
+
* and that `loom.page` puts them on `bg-canvas`; nothing in either component
|
|
28
|
+
* says the first is a filled control that answers its own ink with
|
|
29
|
+
* `fg-on-accent` while the second is a page surface where a child brings
|
|
30
|
+
* whichever ink it likes. Both set a colour beside the ground and only one of
|
|
31
|
+
* them means it.
|
|
32
|
+
*
|
|
33
|
+
* So the four are declared here. A ground on this list is one where a palette
|
|
34
|
+
* owes the reader every ink in the ramp; a ground off it is one where the
|
|
35
|
+
* primitive painting it has already answered what colour the text is, and
|
|
36
|
+
* holding a palette to `fg-muted` on `accent` would be a bar no palette can
|
|
37
|
+
* pass — it is 1.00:1 in some palette however the palette is written.
|
|
38
|
+
*/
|
|
39
|
+
export const PALETTE_TEXT_GROUNDS = [
|
|
40
|
+
"bg-canvas",
|
|
41
|
+
"bg-surface",
|
|
42
|
+
"bg-surface-muted",
|
|
43
|
+
"accent-subtle",
|
|
44
|
+
/**
|
|
45
|
+
* The fifth, and the one that had to be found rather than chosen. This list
|
|
46
|
+
* was settled when nothing in the library painted `bg-overlay` at all, and
|
|
47
|
+
* the record settling it provided for exactly this case (0089): a new ground
|
|
48
|
+
* turning up in `groundsOutsideTheRamp` means either a primitive is painting
|
|
49
|
+
* somewhere unconsidered or this list has fallen behind the library.
|
|
50
|
+
* `loom.overlay` shipped on 15 September and puts arbitrary children on its
|
|
51
|
+
* scrim, so the second is what happened — six days of it, seen by nobody,
|
|
52
|
+
* because the derivation could not follow a ground painted by a stacked
|
|
53
|
+
* sibling until today.
|
|
54
|
+
*
|
|
55
|
+
* It is on this list rather than beside `accent` because the primitive has
|
|
56
|
+
* *not* answered the ink. `loom.action` fills `accent` and writes
|
|
57
|
+
* `fg-on-accent` on it, and holding a palette to `fg-muted` there is a bar no
|
|
58
|
+
* palette can pass. An overlay sets `fg-default` at its root and then takes
|
|
59
|
+
* whatever a model puts inside it, the way a card does.
|
|
60
|
+
*/
|
|
61
|
+
"bg-overlay",
|
|
62
|
+
];
|
|
63
|
+
export const PALETTE_TEXT_PAIRINGS = [
|
|
64
|
+
// Painted: one primitive sets the ink and the ground beneath it.
|
|
65
|
+
{ foreground: "fg-default", background: "bg-canvas", basis: "painted", where: "loom.page body copy" },
|
|
66
|
+
{ foreground: "fg-default", background: "bg-surface", basis: "painted", where: "loom.card body copy" },
|
|
67
|
+
{ foreground: "fg-default", background: "bg-surface-muted", basis: "painted", where: "loom.callout body, loom.code panel" },
|
|
68
|
+
{ foreground: "fg-default", background: "accent-subtle", basis: "painted", where: "loom.section tone accent" },
|
|
69
|
+
{ foreground: "fg-muted", background: "bg-surface", basis: "painted", where: "loom.feature body" },
|
|
70
|
+
{ foreground: "fg-muted", background: "bg-surface-muted", basis: "painted", where: "loom.form hint, loom.badge neutral" },
|
|
71
|
+
{ foreground: "fg-on-accent", background: "accent", basis: "painted", where: "loom.action primary label" },
|
|
72
|
+
{ foreground: "accent", background: "bg-surface", basis: "painted", where: "loom.quote attribution" },
|
|
73
|
+
{ foreground: "accent-strong", background: "accent-subtle", basis: "painted", where: "loom.badge accent, loom.icon soft" },
|
|
74
|
+
/**
|
|
75
|
+
* Painted, and the derivation cannot see it. `loom.offering` sets its price in
|
|
76
|
+
* `accent-strong` on the `bg-surface` of the card it drew, so both ends are
|
|
77
|
+
* one primitive's — but the price element exists only when the optional
|
|
78
|
+
* `price` prop is given, and the probe gives it nothing. It was declared
|
|
79
|
+
* `composed` for exactly that reason, which meant a palette failing it would
|
|
80
|
+
* have been reported rather than refused, on a page nobody can read.
|
|
81
|
+
*
|
|
82
|
+
* `loom.field` reaches the same pairing the other way, by floating its ink
|
|
83
|
+
* into a card, and is kept in the `where` because it is the case a reader is
|
|
84
|
+
* more likely to hit.
|
|
85
|
+
*/
|
|
86
|
+
{
|
|
87
|
+
foreground: "accent-strong",
|
|
88
|
+
background: "bg-surface",
|
|
89
|
+
basis: "painted",
|
|
90
|
+
where: "loom.offering price, loom.field inside a card",
|
|
91
|
+
},
|
|
92
|
+
/**
|
|
93
|
+
* `fg-subtle` is held to the body-text bar like the rest (0074). The
|
|
94
|
+
* slot recedes and none of what it carries is reliably large — a `loom.footer`
|
|
95
|
+
* note row and a `loom.tier` note are ordinary small text — so a threshold of
|
|
96
|
+
* 3:1 would be a bar chosen to fit the colours rather than the reader.
|
|
97
|
+
*/
|
|
98
|
+
/**
|
|
99
|
+
* Painted across a stack rather than down a chain: `loom.overlay` sets the ink
|
|
100
|
+
* on its root, paints `bg-overlay` on a scrim in grid cell `1 / 1`, and lays
|
|
101
|
+
* the words over it in the same cell one layer up. Read as an ancestor chain
|
|
102
|
+
* the two ends never meet, which is why this row was missing for the six days
|
|
103
|
+
* between the primitive shipping and the probe learning to see a sibling.
|
|
104
|
+
*
|
|
105
|
+
* `painted` and not `composed`: both ends are the primitive's own and no
|
|
106
|
+
* container can change either. The scrim is drawn at 0.78 or 0.92 opacity over
|
|
107
|
+
* a ground the author supplied, so clearing this is necessary and not
|
|
108
|
+
* sufficient — an unreadable photograph is `loom.overlay`'s own standing
|
|
109
|
+
* finding and not a thing a palette can answer.
|
|
110
|
+
*/
|
|
111
|
+
{ foreground: "fg-default", background: "bg-overlay", basis: "painted", where: "loom.overlay content over its scrim" },
|
|
112
|
+
{ foreground: "fg-subtle", background: "bg-surface", basis: "painted", where: "loom.footer note row" },
|
|
113
|
+
{ foreground: "fg-subtle", background: "bg-surface-muted", basis: "painted", where: "loom.perk excluded marker" },
|
|
114
|
+
/**
|
|
115
|
+
* Composed: the ink is set here and the ground comes from whatever the
|
|
116
|
+
* primitive is placed in. Every ink that floats, on every ground the ramp is
|
|
117
|
+
* held to — which is the full set rather than the ones somebody pictured,
|
|
118
|
+
* because a tree may nest any of them inside any other (0008).
|
|
119
|
+
*/
|
|
120
|
+
{ foreground: "fg-muted", background: "bg-canvas", basis: "composed", where: "loom.prose tone muted" },
|
|
121
|
+
{ foreground: "fg-muted", background: "accent-subtle", basis: "composed", where: "loom.feature body inside an accent section" },
|
|
122
|
+
{ foreground: "fg-subtle", background: "bg-canvas", basis: "composed", where: "loom.footer note, loom.link-list group label" },
|
|
123
|
+
{ foreground: "accent", background: "bg-canvas", basis: "composed", where: "loom.section eyebrow, loom.link current" },
|
|
124
|
+
{ foreground: "accent", background: "bg-surface-muted", basis: "composed", where: "loom.faq marker inside a muted well" },
|
|
125
|
+
{ foreground: "accent-strong", background: "bg-canvas", basis: "composed", where: "loom.field validation message" },
|
|
126
|
+
{ foreground: "accent-strong", background: "bg-surface-muted", basis: "composed", where: "loom.field inside a muted well" },
|
|
127
|
+
/**
|
|
128
|
+
* The overlay's content is whatever a model put in it, so every ink that
|
|
129
|
+
* floats lands here the way it lands on a card. Under all twenty-one starter
|
|
130
|
+
* palettes `bg-overlay` holds the same value as `bg-surface`, so these four
|
|
131
|
+
* measure what their `bg-surface` rows already measure — which is the point:
|
|
132
|
+
* a host is free to give the slot its own value, and until now nothing would
|
|
133
|
+
* have read it.
|
|
134
|
+
*/
|
|
135
|
+
{ foreground: "fg-muted", background: "bg-overlay", basis: "composed", where: "loom.prose tone muted over a photograph" },
|
|
136
|
+
{ foreground: "fg-subtle", background: "bg-overlay", basis: "composed", where: "loom.footer note inside an overlay" },
|
|
137
|
+
{ foreground: "accent", background: "bg-overlay", basis: "composed", where: "loom.section eyebrow over a photograph" },
|
|
138
|
+
{ foreground: "accent-strong", background: "bg-overlay", basis: "composed", where: "loom.field validation message inside an overlay" },
|
|
139
|
+
/**
|
|
140
|
+
* The two the library does not clear. Both are an ink placed on the tinted
|
|
141
|
+
* panel, both are reachable in an ordinary tree — a perk list inside a
|
|
142
|
+
* `loom.section tone="accent"` is the whole of it — and neither is a bar
|
|
143
|
+
* chosen to fit the colours: `accent` is 4.43:1 on `plum` and `fg-subtle` is
|
|
144
|
+
* 3.76:1 on `carbon`, against a 4.5 that every other pairing here clears.
|
|
145
|
+
*
|
|
146
|
+
* They are listed rather than omitted because the alternative is an audit
|
|
147
|
+
* that is silent about the pairings it would fail, which is the exact fault
|
|
148
|
+
* this list was rewritten to fix. What to move — the panel toward the canvas,
|
|
149
|
+
* or the ink toward `fg-muted` — costs something either way, both costs are
|
|
150
|
+
* measured, and until the choice is made `composedFailures` carries these two
|
|
151
|
+
* in the open (0089).
|
|
152
|
+
*/
|
|
153
|
+
{ foreground: "accent", background: "accent-subtle", basis: "composed", where: "loom.faq marker inside an accent section" },
|
|
154
|
+
{ foreground: "fg-subtle", background: "accent-subtle", basis: "composed", where: "loom.perk note inside an accent section" },
|
|
155
|
+
];
|
|
156
|
+
/** sRGB channel, linearised. WCAG's own curve. */
|
|
157
|
+
const channel = (value) => {
|
|
158
|
+
const c = value / 255;
|
|
159
|
+
return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
|
|
160
|
+
};
|
|
161
|
+
/**
|
|
162
|
+
* The colour as three 0–255 channels, or nothing when it is a form this cannot
|
|
163
|
+
* measure.
|
|
164
|
+
*
|
|
165
|
+
* `colourSchema` accepts more than hex — `rgb()`, `hsl()`, a named colour, and
|
|
166
|
+
* eight-digit hex with an alpha. Only three- and six-digit hex are measured
|
|
167
|
+
* here, and the rest answer `undefined` rather than a guess:
|
|
168
|
+
*
|
|
169
|
+
* - a named colour needs the CSS colour table, which is 148 entries of vocabulary
|
|
170
|
+
* this module would then own
|
|
171
|
+
* - `hsl()` and modern `rgb()` syntax are a parser, and a parser that is subtly
|
|
172
|
+
* wrong reports a passing ratio for a failing pair, which is worse than
|
|
173
|
+
* reporting nothing
|
|
174
|
+
* - an alpha composites against whatever is behind it, so its contrast is not a
|
|
175
|
+
* property of the two slots at all
|
|
176
|
+
*
|
|
177
|
+
* Answering "I could not measure this" is the same move `not-probeable` makes in
|
|
178
|
+
* the conformance probe: a check that cannot answer says so, rather than passing.
|
|
179
|
+
*
|
|
180
|
+
* Exported because `separation.ts` measures the same palette in a different
|
|
181
|
+
* colour space and has to decline the same forms for the same reasons. Two
|
|
182
|
+
* parsers would be two answers to "is this measurable".
|
|
183
|
+
*/
|
|
184
|
+
export const channelsOf = (colour) => {
|
|
185
|
+
const hex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(colour)?.[1];
|
|
186
|
+
if (hex === undefined)
|
|
187
|
+
return undefined;
|
|
188
|
+
const pairs = hex.length === 3 ? [...hex].map((digit) => `${digit}${digit}`) : [0, 2, 4].map((at) => hex.slice(at, at + 2));
|
|
189
|
+
const [r, g, b] = pairs.map((pair) => Number.parseInt(pair, 16));
|
|
190
|
+
return r === undefined || g === undefined || b === undefined ? undefined : [r, g, b];
|
|
191
|
+
};
|
|
192
|
+
const luminance = ([r, g, b]) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
|
|
193
|
+
/**
|
|
194
|
+
* Relative luminance, or `undefined` for a form `channelsOf` declines to guess
|
|
195
|
+
* at.
|
|
196
|
+
*
|
|
197
|
+
* A ratio is a question about two colours; **how dark is this** is a question
|
|
198
|
+
* about one, and `measure.ts` has to ask it — a scrim is asked to darken what is
|
|
199
|
+
* under it, and darkening is a property of the wash rather than of a pair. It is
|
|
200
|
+
* computed here, with WCAG's curve, rather than a second time somewhere else
|
|
201
|
+
* against a curve half a rounding away from this one.
|
|
202
|
+
*/
|
|
203
|
+
export const relativeLuminance = (colour) => {
|
|
204
|
+
const channels = channelsOf(colour);
|
|
205
|
+
return channels === undefined ? undefined : luminance(channels);
|
|
206
|
+
};
|
|
207
|
+
/**
|
|
208
|
+
* The WCAG contrast ratio between two colours, or `undefined` when either is a
|
|
209
|
+
* form `channelsOf` declines to guess at.
|
|
210
|
+
*/
|
|
211
|
+
export const contrastRatio = (a, b) => {
|
|
212
|
+
const [first, second] = [a, b].map(channelsOf);
|
|
213
|
+
if (!first || !second)
|
|
214
|
+
return undefined;
|
|
215
|
+
const [high, low] = [luminance(first), luminance(second)].sort((x, y) => y - x);
|
|
216
|
+
return ((high ?? 0) + 0.05) / ((low ?? 0) + 0.05);
|
|
217
|
+
};
|
|
218
|
+
/**
|
|
219
|
+
* Measures every pairing the primitives render, in one palette. Refuses nothing.
|
|
220
|
+
*
|
|
221
|
+
* `pairings` defaults to the list Loom's own library renders. A host passes its
|
|
222
|
+
* own — `registryPairings(registry, PALETTE_TEXT_GROUNDS)` derives it from the
|
|
223
|
+
* components rather than asking anyone to keep a list — and gets the bar held
|
|
224
|
+
* to the primitives it actually registered rather than to ours.
|
|
225
|
+
*/
|
|
226
|
+
export const auditPalette = (palette, pairings = PALETTE_TEXT_PAIRINGS) => {
|
|
227
|
+
const results = pairings.map((pairing) => {
|
|
228
|
+
const foreground = palette.slots[pairing.foreground] ?? "";
|
|
229
|
+
const background = palette.slots[pairing.background] ?? "";
|
|
230
|
+
const ratio = contrastRatio(foreground, background);
|
|
231
|
+
return ratio === undefined
|
|
232
|
+
? { pairing, unmeasured: { pairing, foreground, background } }
|
|
233
|
+
: { pairing, measured: { pairing, ratio, meets: ratio >= TEXT_CONTRAST_MINIMUM } };
|
|
234
|
+
});
|
|
235
|
+
const measured = results.flatMap((result) => (result.measured ? [result.measured] : []));
|
|
236
|
+
const under = measured.filter((entry) => !entry.meets);
|
|
237
|
+
return {
|
|
238
|
+
palette: palette.id,
|
|
239
|
+
measured,
|
|
240
|
+
failures: under.filter((entry) => entry.pairing.basis === "painted"),
|
|
241
|
+
composedFailures: under.filter((entry) => entry.pairing.basis === "composed"),
|
|
242
|
+
unmeasured: results.flatMap((result) => (result.unmeasured ? [result.unmeasured] : [])),
|
|
243
|
+
};
|
|
244
|
+
};
|
|
245
|
+
const describePairing = (pairing) => `${pairing.foreground} on ${pairing.background} (${pairing.where})`;
|
|
246
|
+
/**
|
|
247
|
+
* One line per problem, for a CLI or a failing test's message. Empty when clean.
|
|
248
|
+
*
|
|
249
|
+
* Composed failures are printed too, and said to be composed. A description
|
|
250
|
+
* that showed only what is asserted would let a reader take an empty string for
|
|
251
|
+
* a clean palette, and on eight of the palettes in this library that would be
|
|
252
|
+
* false.
|
|
253
|
+
*/
|
|
254
|
+
export const describePaletteAudit = (audit) => [
|
|
255
|
+
...audit.failures.map((entry) => `${audit.palette}: ${describePairing(entry.pairing)} is ${entry.ratio.toFixed(2)}:1, under ${TEXT_CONTRAST_MINIMUM}:1`),
|
|
256
|
+
...audit.composedFailures.map((entry) => `${audit.palette}: ${describePairing(entry.pairing)} is ${entry.ratio.toFixed(2)}:1, under ${TEXT_CONTRAST_MINIMUM}:1 — composed, reported not asserted`),
|
|
257
|
+
...audit.unmeasured.map((entry) => `${audit.palette}: ${describePairing(entry.pairing)} could not be measured — "${entry.foreground}" on "${entry.background}" is not hex`),
|
|
258
|
+
].join("\n");
|
|
259
|
+
//# sourceMappingURL=contrast.js.map
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { type Palette } from "./theme.js";
|
|
2
|
+
export type PaletteMode = "light" | "dark";
|
|
3
|
+
export type HueSpec = {
|
|
4
|
+
/** 0–360. */
|
|
5
|
+
readonly hue: number;
|
|
6
|
+
/** 0–100. Zero gives a neutral grey, which is how the monochrome palettes are built. */
|
|
7
|
+
readonly saturation: number;
|
|
8
|
+
};
|
|
9
|
+
export type PaletteSpec = {
|
|
10
|
+
readonly id: string;
|
|
11
|
+
readonly name: string;
|
|
12
|
+
readonly description: string;
|
|
13
|
+
readonly mode: PaletteMode;
|
|
14
|
+
/** The page itself. Its hue tints every neutral, which is what stops a palette looking like grey with colour on top. */
|
|
15
|
+
readonly canvas: HueSpec;
|
|
16
|
+
/** The colour that carries meaning as text. Darkened, or lightened, until it can. */
|
|
17
|
+
readonly accent: HueSpec;
|
|
18
|
+
/** The second colour. Never carries text, so it keeps its chroma — this is what `loom.hero`'s aurora paints. */
|
|
19
|
+
readonly secondary: HueSpec;
|
|
20
|
+
/**
|
|
21
|
+
* Lightness of the canvas, the surface behind a card, and the muted well, in
|
|
22
|
+
* that order. Defaults suit most palettes; a deeper dark mode or a warmer
|
|
23
|
+
* paper is where you would change them.
|
|
24
|
+
*/
|
|
25
|
+
readonly levels?: readonly [number, number, number];
|
|
26
|
+
/**
|
|
27
|
+
* Forces `accent` to the end of the range rather than to the lightest value
|
|
28
|
+
* that clears the bar. A palette with no chroma has nothing to solve for, and
|
|
29
|
+
* solving anyway leaves a mid-grey primary button that reads as a disabled
|
|
30
|
+
* one.
|
|
31
|
+
*/
|
|
32
|
+
readonly extremeAccent?: boolean;
|
|
33
|
+
};
|
|
34
|
+
/** HSL to a six-digit hex, which is the only form `contrastRatio` measures. */
|
|
35
|
+
export declare const hslHex: (hue: number, saturation: number, lightness: number) => string;
|
|
36
|
+
/**
|
|
37
|
+
* The lightest ink (or darkest, on a dark palette) at this hue that still clears
|
|
38
|
+
* `target` against `on`.
|
|
39
|
+
*
|
|
40
|
+
* Lightest rather than merely sufficient, because a colour dragged further than
|
|
41
|
+
* it needs to go loses its hue: an accent solved to 8% lightness is black
|
|
42
|
+
* whatever its hue said, and a palette of five of those is five identical
|
|
43
|
+
* palettes. Twenty-four bisection steps put it within about 0.000006 of the
|
|
44
|
+
* boundary, which is far finer than the 1/255 the hex can express.
|
|
45
|
+
*/
|
|
46
|
+
export declare const solveLightness: (hue: number, saturation: number, on: string, target: number, darkening: boolean) => string;
|
|
47
|
+
/**
|
|
48
|
+
* Derives a palette. Total: it always returns one, and `auditPalette` on the
|
|
49
|
+
* result is the check that it worked — see `derivePaletteChecked` for the pair.
|
|
50
|
+
*/
|
|
51
|
+
export declare const derivePalette: (spec: PaletteSpec) => Palette;
|
|
52
|
+
/**
|
|
53
|
+
* The palette and its audit together, which is how a host should call this: the
|
|
54
|
+
* derivation is a rule and the audit is the check on it, and a rule that has
|
|
55
|
+
* never been checked is a rule that will eventually be wrong at one hue.
|
|
56
|
+
*
|
|
57
|
+
* **`clean` means legible, not distinguishable.** It is `auditPalette` and
|
|
58
|
+
* nothing else: every ink clears the contrast bar on every ground it is
|
|
59
|
+
* rendered on. Whether two slots a reader is meant to tell apart are far enough
|
|
60
|
+
* apart to be told apart is `auditSeparation`, and a host that wants both runs
|
|
61
|
+
* both — five of the palettes this function derived collapse a pair that one
|
|
62
|
+
* measures and the other does not.
|
|
63
|
+
*/
|
|
64
|
+
export declare const derivePaletteChecked: (spec: PaletteSpec) => {
|
|
65
|
+
readonly palette: Palette;
|
|
66
|
+
readonly clean: boolean;
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* Whether a brand colour can carry text on a given ground.
|
|
70
|
+
*
|
|
71
|
+
* The question a host actually has, and the one they are usually answering
|
|
72
|
+
* wrongly: *can we put our orange in `accent`?* If this says no, the honest
|
|
73
|
+
* places for it are `border-accent` and `brand-secondary` — a rule, a ring, a
|
|
74
|
+
* tinted field — and `accent` takes a near-neutral ink instead.
|
|
75
|
+
*/
|
|
76
|
+
export declare const canCarryText: (colour: string, on: string) => boolean;
|
|
77
|
+
//# sourceMappingURL=derive.d.ts.map
|