@jam-overture/loom 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/dist/application/application.d.ts +109 -0
- package/dist/application/application.js +97 -0
- package/dist/application/memory.d.ts +20 -0
- package/dist/application/memory.js +79 -0
- package/dist/application/store.d.ts +101 -0
- package/dist/application/store.js +25 -0
- package/dist/audience/audience.d.ts +36 -0
- package/dist/audience/audience.js +41 -0
- package/dist/cli/templates.js +19 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +30 -3
- package/dist/data/resolve.js +11 -3
- package/dist/ids.d.ts +10 -0
- package/dist/ids.js +11 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/patch.d.ts +54 -0
- package/dist/patch.js +44 -0
- package/dist/project/closing.d.ts +51 -0
- package/dist/project/closing.js +53 -0
- package/dist/project/memory.d.ts +20 -0
- package/dist/project/memory.js +97 -0
- package/dist/project/project.d.ts +90 -0
- package/dist/project/project.js +91 -0
- package/dist/project/store.d.ts +135 -0
- package/dist/project/store.js +41 -0
- package/dist/registered.d.ts +64 -0
- package/dist/registered.js +118 -0
- package/dist/render/behaviour-adjust.d.ts +11 -19
- package/dist/render/behaviour-adjust.js +75 -21
- package/dist/render/behaviour-present.d.ts +8 -0
- package/dist/render/behaviour-present.js +57 -6
- package/dist/render/behaviour.d.ts +98 -17
- package/dist/render/behaviour.js +91 -26
- package/dist/render/control-name.d.ts +68 -0
- package/dist/render/control-name.js +37 -0
- package/dist/render/diagnostics.d.ts +72 -0
- package/dist/render/diagnostics.js +7 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.js +102 -7
- package/dist/render/slots.d.ts +52 -0
- package/dist/render/slots.js +24 -0
- package/dist/render/theme.d.ts +54 -1
- package/dist/render/theme.js +23 -1
- package/dist/render/unshown.d.ts +152 -0
- package/dist/render/unshown.js +80 -0
- package/dist/runtime/analysis.d.ts +94 -9
- package/dist/runtime/analysis.js +54 -9
- package/dist/runtime/assessment.d.ts +36 -2
- package/dist/runtime/assessment.js +27 -2
- package/dist/runtime/checks.d.ts +148 -0
- package/dist/runtime/checks.js +112 -0
- package/dist/runtime/disposition.d.ts +96 -0
- package/dist/runtime/disposition.js +46 -0
- package/dist/runtime/gate.js +22 -0
- package/dist/runtime/index.d.ts +3 -0
- package/dist/runtime/index.js +3 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- package/dist/runtime/pipeline.d.ts +43 -0
- package/dist/runtime/pipeline.js +10 -2
- package/dist/runtime/policy-change.d.ts +93 -0
- package/dist/runtime/policy-change.js +299 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -0
- package/dist/runtime/reversibility.d.ts +11 -9
- package/dist/runtime/stakes.d.ts +129 -1
- package/dist/runtime/stakes.js +240 -26
- package/dist/runtime/vocabulary.d.ts +164 -7
- package/dist/runtime/vocabulary.js +181 -8
- package/dist/sdk/audit.d.ts +174 -3
- package/dist/sdk/audit.js +176 -17
- package/dist/sdk/catalogue.d.ts +9 -1
- package/dist/sdk/conformance.d.ts +37 -3
- package/dist/sdk/conformance.js +25 -4
- package/dist/sdk/definition.d.ts +65 -0
- package/dist/sdk/definition.js +22 -0
- package/dist/sdk/registry.d.ts +29 -2
- package/dist/sdk/registry.js +63 -1
- package/dist/signals/action-change.d.ts +507 -0
- package/dist/signals/action-change.js +265 -0
- package/dist/signals/action.d.ts +331 -0
- package/dist/signals/action.js +182 -0
- package/dist/signals/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -0
- package/dist/signals/arriving.d.ts +210 -0
- package/dist/signals/arriving.js +133 -0
- package/dist/signals/audiences.d.ts +528 -0
- package/dist/signals/audiences.js +255 -0
- package/dist/signals/broadcast.d.ts +8 -2
- package/dist/signals/broadcast.js +58 -8
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +41 -0
- package/dist/signals/collect.js +88 -7
- package/dist/signals/copy-change.d.ts +553 -0
- package/dist/signals/copy-change.js +377 -0
- package/dist/signals/copy.d.ts +337 -0
- package/dist/signals/copy.js +211 -0
- package/dist/signals/counters.d.ts +46 -0
- package/dist/signals/counters.js +102 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +371 -0
- package/dist/signals/deployment-change.js +268 -0
- package/dist/signals/deployment.d.ts +265 -0
- package/dist/signals/deployment.js +152 -0
- package/dist/signals/door.d.ts +92 -0
- package/dist/signals/door.js +53 -0
- package/dist/signals/fold.d.ts +10 -0
- package/dist/signals/fold.js +5 -1
- package/dist/signals/form-action.d.ts +302 -0
- package/dist/signals/form-action.js +169 -0
- package/dist/signals/form-copy.d.ts +523 -0
- package/dist/signals/form-copy.js +346 -0
- package/dist/signals/forms.d.ts +247 -0
- package/dist/signals/forms.js +147 -0
- package/dist/signals/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -0
- package/dist/signals/funnel.d.ts +532 -0
- package/dist/signals/funnel.js +216 -0
- package/dist/signals/health.d.ts +497 -0
- package/dist/signals/health.js +361 -0
- package/dist/signals/index.d.ts +41 -0
- package/dist/signals/index.js +41 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- package/dist/signals/journal.d.ts +11 -0
- package/dist/signals/kinds.d.ts +8 -6
- package/dist/signals/kinds.js +14 -6
- package/dist/signals/library-action.d.ts +430 -0
- package/dist/signals/library-action.js +336 -0
- package/dist/signals/library-change.d.ts +477 -0
- package/dist/signals/library-change.js +335 -0
- package/dist/signals/library-copy-change.d.ts +498 -0
- package/dist/signals/library-copy-change.js +476 -0
- package/dist/signals/library-pace.d.ts +319 -0
- package/dist/signals/library-pace.js +305 -0
- package/dist/signals/library-reach-change.d.ts +636 -0
- package/dist/signals/library-reach-change.js +534 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- package/dist/signals/library-word-reach-change.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +568 -0
- package/dist/signals/library.d.ts +306 -0
- package/dist/signals/library.js +178 -0
- package/dist/signals/memory.d.ts +9 -0
- package/dist/signals/memory.js +105 -14
- package/dist/signals/migrate.d.ts +17 -2
- package/dist/signals/migrate.js +122 -5
- package/dist/signals/notice.d.ts +334 -0
- package/dist/signals/notice.js +228 -0
- package/dist/signals/pace-change.d.ts +501 -0
- package/dist/signals/pace-change.js +310 -0
- package/dist/signals/pace.d.ts +296 -0
- package/dist/signals/pace.js +291 -0
- package/dist/signals/page-views.d.ts +365 -0
- package/dist/signals/page-views.js +218 -0
- package/dist/signals/parts.d.ts +344 -0
- package/dist/signals/parts.js +273 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +390 -87
- package/dist/signals/progress.d.ts +212 -0
- package/dist/signals/progress.js +150 -0
- package/dist/signals/ratios.d.ts +108 -0
- package/dist/signals/ratios.js +40 -0
- package/dist/signals/reach.d.ts +309 -0
- package/dist/signals/reach.js +93 -0
- package/dist/signals/readable.d.ts +34 -0
- package/dist/signals/readable.js +34 -0
- package/dist/signals/readership.d.ts +381 -0
- package/dist/signals/readership.js +308 -0
- package/dist/signals/region-pages.d.ts +173 -0
- package/dist/signals/region-pages.js +62 -0
- package/dist/signals/region.d.ts +287 -0
- package/dist/signals/region.js +198 -0
- package/dist/signals/retention.d.ts +141 -0
- package/dist/signals/retention.js +58 -0
- package/dist/signals/rollup.d.ts +67 -3
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +432 -1
- package/dist/signals/schema.js +157 -3
- package/dist/signals/signal.d.ts +237 -11
- package/dist/signals/signal.js +70 -10
- package/dist/signals/silence-census.d.ts +205 -0
- package/dist/signals/silence-census.js +87 -0
- package/dist/signals/silences.d.ts +848 -0
- package/dist/signals/silences.js +753 -0
- package/dist/signals/tally.d.ts +140 -11
- package/dist/signals/window-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -0
- package/dist/signals/window.d.ts +866 -0
- package/dist/signals/window.js +693 -0
- package/dist/signals/words.d.ts +24 -0
- package/dist/signals/words.js +24 -0
- package/dist/store/index.d.ts +19 -0
- package/dist/store/index.js +19 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +80 -0
- package/dist/store/migrate.js +259 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -0
- package/dist/store/postgres-holds.d.ts +10 -1
- package/dist/store/postgres-holds.js +116 -101
- package/dist/store/postgres-policy-log.d.ts +14 -0
- package/dist/store/postgres-policy-log.js +240 -0
- package/dist/store/postgres-projects.d.ts +4 -0
- package/dist/store/postgres-projects.js +217 -0
- package/dist/store/postgres.d.ts +16 -1
- package/dist/store/postgres.js +59 -9
- package/dist/store/replay.d.ts +102 -1
- package/dist/store/replay.js +190 -19
- package/dist/store/reseed.d.ts +238 -0
- package/dist/store/reseed.js +308 -0
- package/dist/store/schema.d.ts +450 -2
- package/dist/store/schema.js +141 -5
- package/dist/store/store.d.ts +29 -6
- package/dist/submit/resolve.js +2 -1
- package/dist/telemetry/calibration.d.ts +25 -0
- package/dist/telemetry/calibration.js +27 -1
- package/dist/telemetry/event.d.ts +391 -33
- package/dist/telemetry/event.js +84 -20
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +72 -3
- package/dist/telemetry/journal.js +9 -0
- package/dist/telemetry/lookup.d.ts +27 -0
- package/dist/telemetry/lookup.js +18 -0
- package/dist/telemetry/memory.js +23 -0
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +172 -90
- package/dist/telemetry/remeasure.d.ts +78 -0
- package/dist/telemetry/remeasure.js +83 -0
- package/dist/telemetry/retention.d.ts +2 -2
- package/dist/telemetry/schema.d.ts +17 -0
- package/dist/telemetry/schema.js +27 -1
- package/dist/telemetry/sink.d.ts +2 -2
- package/dist/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -0
- package/dist/testing/contracts.d.ts +12 -7
- package/dist/testing/contracts.js +12 -7
- package/dist/testing/definitions.d.ts +78 -0
- package/dist/testing/definitions.js +134 -9
- package/dist/testing/doubles.d.ts +103 -0
- package/dist/testing/doubles.js +143 -0
- package/dist/testing/index.d.ts +2 -2
- package/dist/testing/index.js +2 -2
- package/dist/testing/journal-contract.js +140 -2
- package/dist/testing/model-contract.d.ts +110 -0
- package/dist/testing/model-contract.js +150 -0
- package/dist/testing/policy-log-contract.d.ts +26 -0
- package/dist/testing/policy-log-contract.js +344 -0
- package/dist/testing/project-contract.d.ts +14 -0
- package/dist/testing/project-contract.js +266 -0
- package/dist/testing/reader-signal-contract.d.ts +27 -2
- package/dist/testing/reader-signal-contract.js +475 -5
- package/dist/testing/store-contract.d.ts +7 -1
- package/dist/testing/store-contract.js +84 -3
- package/dist/theme/apply.d.ts +20 -1
- package/dist/theme/apply.js +5 -3
- package/dist/theme/derive.d.ts +22 -0
- package/dist/theme/derive.js +54 -1
- package/dist/theme/library.js +1 -1
- package/dist/theme/measure.d.ts +34 -0
- package/dist/theme/measure.js +30 -1
- package/dist/theme/palettes.js +7 -7
- package/dist/theme/ramp.d.ts +64 -0
- package/dist/theme/ramp.js +114 -0
- package/dist/theme/registry.d.ts +9 -0
- package/dist/theme/registry.js +11 -1
- package/dist/theme/separation.d.ts +97 -3
- package/dist/theme/separation.js +75 -0
- package/dist/tree/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -0
- package/dist/write/computed.d.ts +60 -0
- package/dist/write/computed.js +61 -0
- package/dist/write/held.d.ts +59 -0
- package/dist/write/index.d.ts +5 -2
- package/dist/write/index.js +5 -2
- package/dist/write/reseed.d.ts +151 -0
- package/dist/write/reseed.js +184 -0
- package/dist/write/revert.js +2 -16
- package/package.json +98 -19
|
@@ -17,7 +17,13 @@ import { sampleTree } from "./fixtures.js";
|
|
|
17
17
|
* implementation — how it reports a connection failure, what it exposes beyond
|
|
18
18
|
* the interface — stays in that implementation's own test file.
|
|
19
19
|
*/
|
|
20
|
-
export const appendOf = (delta, proposal = "p_1"
|
|
20
|
+
export const appendOf = (delta, proposal = "p_1",
|
|
21
|
+
/**
|
|
22
|
+
* When the runtime applied it. Defaulted, because almost every case here is
|
|
23
|
+
* about what a store does with a delta rather than when; named by the cases
|
|
24
|
+
* that are, which cannot be written at all if every append shares one stamp.
|
|
25
|
+
*/
|
|
26
|
+
appliedAt = FIXED_INSTANT) => ({
|
|
21
27
|
proposalId: proposal,
|
|
22
28
|
delta,
|
|
23
29
|
provenance: {
|
|
@@ -27,7 +33,7 @@ export const appendOf = (delta, proposal = "p_1") => ({
|
|
|
27
33
|
confidence: 0.9,
|
|
28
34
|
interpretedAt: FIXED_INSTANT,
|
|
29
35
|
},
|
|
30
|
-
appliedAt
|
|
36
|
+
appliedAt,
|
|
31
37
|
});
|
|
32
38
|
export const removalOf = (tree, nodeId, baseRevision = tree.revision) => ({
|
|
33
39
|
deltaId: sequentialIdFactory("s").deltaId(),
|
|
@@ -197,7 +203,10 @@ export const describeTreeStoreContract = (name, makeStore) => {
|
|
|
197
203
|
await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer)));
|
|
198
204
|
expect((await store.list()).ok && (await store.list())).toEqual({
|
|
199
205
|
ok: true,
|
|
200
|
-
value: {
|
|
206
|
+
value: {
|
|
207
|
+
trees: [{ treeId: tree.treeId, revision: 1, changedAt: FIXED_INSTANT }],
|
|
208
|
+
cursor: null,
|
|
209
|
+
},
|
|
201
210
|
});
|
|
202
211
|
});
|
|
203
212
|
it("is empty with a null cursor when nothing is stored", async () => {
|
|
@@ -244,6 +253,78 @@ export const describeTreeStoreContract = (name, makeStore) => {
|
|
|
244
253
|
const page = await store.list({ limit: 0 });
|
|
245
254
|
expect(page.ok && page.value.trees).toHaveLength(1);
|
|
246
255
|
});
|
|
256
|
+
/**
|
|
257
|
+
* The half of the listing's rejected recency ordering that shipped: the
|
|
258
|
+
* fact, not the order (0020, 0277). These five cases are what make it a
|
|
259
|
+
* fact rather than a convenience — the stamp has to be the log's own, and
|
|
260
|
+
* the absence has to mean one thing.
|
|
261
|
+
*/
|
|
262
|
+
describe("when each page last changed", () => {
|
|
263
|
+
it("says nothing about a tree that has never been changed", async () => {
|
|
264
|
+
const store = await freshStore();
|
|
265
|
+
await store.create(treeNamed("a"));
|
|
266
|
+
const page = await store.list();
|
|
267
|
+
const listing = page.ok ? page.value.trees[0] : undefined;
|
|
268
|
+
expect(listing?.revision).toBe(0);
|
|
269
|
+
expect(listing && "changedAt" in listing).toBe(false);
|
|
270
|
+
});
|
|
271
|
+
it("reports the stamp the append was given, not the time of the read", async () => {
|
|
272
|
+
const { tree, ids } = sampleTree();
|
|
273
|
+
const store = await freshStore();
|
|
274
|
+
await store.create(tree);
|
|
275
|
+
await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer), "p_1", "2026-03-02T11:12:13.000Z"));
|
|
276
|
+
const page = await store.list();
|
|
277
|
+
expect(page.ok && page.value.trees[0]?.changedAt).toBe("2026-03-02T11:12:13.000Z");
|
|
278
|
+
});
|
|
279
|
+
it("moves to the newest entry's stamp as the log grows", async () => {
|
|
280
|
+
const { tree, ids } = sampleTree();
|
|
281
|
+
const store = await freshStore();
|
|
282
|
+
await store.create(tree);
|
|
283
|
+
await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer), "p_1", "2026-03-02T11:12:13.000Z"));
|
|
284
|
+
const first = await store.list();
|
|
285
|
+
expect(first.ok && first.value.trees[0]?.changedAt).toBe("2026-03-02T11:12:13.000Z");
|
|
286
|
+
await store.append(tree.treeId, appendOf(removalOf(tree, ids.header, 1), "p_2", "2026-09-09T07:00:00.000Z"));
|
|
287
|
+
const second = await store.list();
|
|
288
|
+
expect(second.ok && second.value.trees[0]?.revision).toBe(2);
|
|
289
|
+
expect(second.ok && second.value.trees[0]?.changedAt).toBe("2026-09-09T07:00:00.000Z");
|
|
290
|
+
});
|
|
291
|
+
/**
|
|
292
|
+
* The reading a surface is allowed to depend on, asserted rather than
|
|
293
|
+
* written down: a stamp is present exactly when there is an entry to
|
|
294
|
+
* take one from. A store that filled this with a creation time would
|
|
295
|
+
* pass every case above and fail this one.
|
|
296
|
+
*/
|
|
297
|
+
it("carries a stamp for exactly the trees whose revision is above zero", async () => {
|
|
298
|
+
const { tree, ids } = sampleTree();
|
|
299
|
+
const store = await freshStore();
|
|
300
|
+
await store.create(tree);
|
|
301
|
+
await store.create(treeNamed("z"));
|
|
302
|
+
await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer)));
|
|
303
|
+
const page = await store.list();
|
|
304
|
+
const trees = page.ok ? page.value.trees : [];
|
|
305
|
+
expect(trees).toHaveLength(2);
|
|
306
|
+
for (const listing of trees) {
|
|
307
|
+
expect("changedAt" in listing).toBe(listing.revision > 0);
|
|
308
|
+
}
|
|
309
|
+
});
|
|
310
|
+
/**
|
|
311
|
+
* The listing and the log are two reads of one fact, so the one thing
|
|
312
|
+
* that must never happen is that they disagree. This compares the
|
|
313
|
+
* listing against what `revisions` says, rather than against a literal
|
|
314
|
+
* the test typed in — the same stamp, reached two ways.
|
|
315
|
+
*/
|
|
316
|
+
it("agrees with the newest entry the log itself hands back", async () => {
|
|
317
|
+
const { tree, ids } = sampleTree();
|
|
318
|
+
const store = await freshStore();
|
|
319
|
+
await store.create(tree);
|
|
320
|
+
await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer), "p_1", "2026-05-05T05:05:05.000Z"));
|
|
321
|
+
const page = await store.list();
|
|
322
|
+
const log = await store.revisions(tree.treeId, { direction: "older" });
|
|
323
|
+
const newest = log.ok ? log.value.revisions.at(-1) : undefined;
|
|
324
|
+
expect(newest?.appliedAt).toBeDefined();
|
|
325
|
+
expect(page.ok && page.value.trees[0]?.changedAt).toBe(newest?.appliedAt);
|
|
326
|
+
});
|
|
327
|
+
});
|
|
247
328
|
});
|
|
248
329
|
/**
|
|
249
330
|
* The log is read a page at a time, from either end (0026). These are the
|
package/dist/theme/apply.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type RampMode } from "./ramp.js";
|
|
1
2
|
import { type ResolvedTheme } from "./theme.js";
|
|
2
3
|
/**
|
|
3
4
|
* A resolved theme, flattened into CSS custom properties.
|
|
@@ -12,6 +13,24 @@ import { type ResolvedTheme } from "./theme.js";
|
|
|
12
13
|
* the tree and touches no primitive. A theme change is one `configure` on the
|
|
13
14
|
* root, and every node below re-reads through the cascade.
|
|
14
15
|
*/
|
|
16
|
+
/**
|
|
17
|
+
* Re-exported rather than published whole: a host selecting a mode needs to
|
|
18
|
+
* name it, and nothing outside this package needs `rampLength` itself.
|
|
19
|
+
*/
|
|
20
|
+
export type { RampMode } from "./ramp.js";
|
|
15
21
|
export type ThemeVariables = Readonly<Record<string, string>>;
|
|
16
|
-
export
|
|
22
|
+
export type ThemeVariableOptions = {
|
|
23
|
+
/**
|
|
24
|
+
* Whether the two ramps may read the width they are rendered at.
|
|
25
|
+
*
|
|
26
|
+
* `"fluid"` is the default and is what a page in a browser wants: a declared
|
|
27
|
+
* step is a maximum, reached at `48rem` and held above it, so a tree built
|
|
28
|
+
* for a laptop is legible on a phone without the tree knowing a phone exists
|
|
29
|
+
* (0283). `"fixed"` emits the pack's numbers as the plain pixel lengths they
|
|
30
|
+
* were before that record, for a medium with no cascade to substitute — see
|
|
31
|
+
* `ramp.ts` for why a `clamp()` is worse than a pixel there.
|
|
32
|
+
*/
|
|
33
|
+
readonly ramp?: RampMode;
|
|
34
|
+
};
|
|
35
|
+
export declare const themeVariables: (theme: ResolvedTheme, options?: ThemeVariableOptions) => ThemeVariables;
|
|
17
36
|
//# sourceMappingURL=apply.d.ts.map
|
package/dist/theme/apply.js
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { chromaValue, paletteMeasures } from "./measure.js";
|
|
2
|
+
import { rampLength } from "./ramp.js";
|
|
2
3
|
import { PALETTE_SLOTS } from "./theme.js";
|
|
3
|
-
export const themeVariables = (theme) => {
|
|
4
|
+
export const themeVariables = (theme, options = {}) => {
|
|
4
5
|
const variables = {};
|
|
6
|
+
const ramp = options.ramp ?? "fluid";
|
|
5
7
|
for (const slot of PALETTE_SLOTS) {
|
|
6
8
|
const value = theme.palette.slots[slot];
|
|
7
9
|
if (value !== undefined)
|
|
@@ -41,7 +43,7 @@ export const themeVariables = (theme) => {
|
|
|
41
43
|
variables["--loom-heading-weight"] = String(theme.fontPack.headingWeight);
|
|
42
44
|
variables["--loom-body-weight"] = String(theme.fontPack.bodyWeight);
|
|
43
45
|
theme.fontPack.scaleRamp.forEach((step, index) => {
|
|
44
|
-
variables[`--loom-scale-${index + 1}`] =
|
|
46
|
+
variables[`--loom-scale-${index + 1}`] = rampLength(step, "type", ramp);
|
|
45
47
|
});
|
|
46
48
|
const { radii, spacingScale, motion, density } = theme.stylePreset;
|
|
47
49
|
variables["--loom-radius-sm"] = `${radii.sm}px`;
|
|
@@ -49,7 +51,7 @@ export const themeVariables = (theme) => {
|
|
|
49
51
|
variables["--loom-radius-lg"] = `${radii.lg}px`;
|
|
50
52
|
variables["--loom-radius-full"] = `${radii.full}px`;
|
|
51
53
|
spacingScale.forEach((step, index) => {
|
|
52
|
-
variables[`--loom-spacing-${index + 1}`] =
|
|
54
|
+
variables[`--loom-spacing-${index + 1}`] = rampLength(step, "space", ramp);
|
|
53
55
|
});
|
|
54
56
|
variables["--loom-motion-fast"] = `${motion.fast}ms`;
|
|
55
57
|
variables["--loom-motion-medium"] = `${motion.medium}ms`;
|
package/dist/theme/derive.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type Palette } from "./theme.js";
|
|
2
|
+
export declare const MARK_SEPARATION_TARGET: number;
|
|
2
3
|
export type PaletteMode = "light" | "dark";
|
|
3
4
|
export type HueSpec = {
|
|
4
5
|
/** 0–360. */
|
|
@@ -44,6 +45,27 @@ export declare const hslHex: (hue: number, saturation: number, lightness: number
|
|
|
44
45
|
* boundary, which is far finer than the 1/255 the hex can express.
|
|
45
46
|
*/
|
|
46
47
|
export declare const solveLightness: (hue: number, saturation: number, on: string, target: number, darkening: boolean) => string;
|
|
48
|
+
/**
|
|
49
|
+
* The lightness *nearest* `from` at this hue whose colour clears `target` ΔE
|
|
50
|
+
* against every one of `grounds`.
|
|
51
|
+
*
|
|
52
|
+
* Nearest rather than furthest, which is the opposite of `solveLightness` and
|
|
53
|
+
* for the mirror of its reason. An ink is dragged as far as the bar allows
|
|
54
|
+
* because a letterform has to be read; a line only has to be **found**, and a
|
|
55
|
+
* border pushed further than it needs to go stops being the subtle tier and
|
|
56
|
+
* becomes the default one. The tiers are a ramp and the gaps between them carry
|
|
57
|
+
* meaning (0204), so the search moves a line the least it can.
|
|
58
|
+
*
|
|
59
|
+
* Both directions are tried at each step and the darker one wins a tie, because
|
|
60
|
+
* on a light palette the grounds are above the border and moving down is the
|
|
61
|
+
* direction that gains separation from all three at once.
|
|
62
|
+
*
|
|
63
|
+
* Falls back to `from` when nothing within 40 points of lightness clears the
|
|
64
|
+
* target, which is a palette whose three grounds surround the tier — the
|
|
65
|
+
* derivation cannot fix that by moving one slot, and `auditMarkGroundings` is
|
|
66
|
+
* what says so.
|
|
67
|
+
*/
|
|
68
|
+
export declare const solveMarkLightness: (hue: number, saturation: number, from: number, grounds: readonly string[], target: number) => string;
|
|
47
69
|
/**
|
|
48
70
|
* Derives a palette. Total: it always returns one, and `auditPalette` on the
|
|
49
71
|
* result is the check that it worked — see `derivePaletteChecked` for the pair.
|
package/dist/theme/derive.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { auditPalette, contrastRatio, TEXT_CONTRAST_MINIMUM } from "./contrast.js";
|
|
2
|
+
import { colourDifference, JUST_NOTICEABLE_DIFFERENCE } from "./separation.js";
|
|
2
3
|
import { paletteSchema } from "./theme.js";
|
|
3
4
|
/**
|
|
4
5
|
* Builds a palette that clears the bar, from three hues and a mode.
|
|
@@ -39,6 +40,18 @@ import { paletteSchema } from "./theme.js";
|
|
|
39
40
|
/** How far above the AA bar a derived colour lands. */
|
|
40
41
|
const MARGIN = 0.25;
|
|
41
42
|
const TARGET = TEXT_CONTRAST_MINIMUM + MARGIN;
|
|
43
|
+
/**
|
|
44
|
+
* How far past the just-noticeable difference a derived line lands, in ΔE.
|
|
45
|
+
*
|
|
46
|
+
* The same reasoning as `MARGIN` and for the same reason it is not zero: a slot
|
|
47
|
+
* solved to exactly the floor drops under it the first time somebody nudges a
|
|
48
|
+
* background by a value. 2.3 is what `separation.ts` asserts, because it is the
|
|
49
|
+
* published threshold; 3.0 is what this aims at, because it is the one a later
|
|
50
|
+
* edit can afford to lose a little of. Written as the floor plus a margin rather
|
|
51
|
+
* than as 3, so moving the published threshold moves this with it.
|
|
52
|
+
*/
|
|
53
|
+
const MARK_MARGIN = 0.7;
|
|
54
|
+
export const MARK_SEPARATION_TARGET = JUST_NOTICEABLE_DIFFERENCE + MARK_MARGIN;
|
|
42
55
|
/** HSL to a six-digit hex, which is the only form `contrastRatio` measures. */
|
|
43
56
|
export const hslHex = (hue, saturation, lightness) => {
|
|
44
57
|
const a = (saturation / 100) * Math.min(lightness / 100, 1 - lightness / 100);
|
|
@@ -86,6 +99,37 @@ const DEFAULT_LEVELS = {
|
|
|
86
99
|
light: [98, 100, 94],
|
|
87
100
|
dark: [10, 14, 8],
|
|
88
101
|
};
|
|
102
|
+
/**
|
|
103
|
+
* The lightness *nearest* `from` at this hue whose colour clears `target` ΔE
|
|
104
|
+
* against every one of `grounds`.
|
|
105
|
+
*
|
|
106
|
+
* Nearest rather than furthest, which is the opposite of `solveLightness` and
|
|
107
|
+
* for the mirror of its reason. An ink is dragged as far as the bar allows
|
|
108
|
+
* because a letterform has to be read; a line only has to be **found**, and a
|
|
109
|
+
* border pushed further than it needs to go stops being the subtle tier and
|
|
110
|
+
* becomes the default one. The tiers are a ramp and the gaps between them carry
|
|
111
|
+
* meaning (0204), so the search moves a line the least it can.
|
|
112
|
+
*
|
|
113
|
+
* Both directions are tried at each step and the darker one wins a tie, because
|
|
114
|
+
* on a light palette the grounds are above the border and moving down is the
|
|
115
|
+
* direction that gains separation from all three at once.
|
|
116
|
+
*
|
|
117
|
+
* Falls back to `from` when nothing within 40 points of lightness clears the
|
|
118
|
+
* target, which is a palette whose three grounds surround the tier — the
|
|
119
|
+
* derivation cannot fix that by moving one slot, and `auditMarkGroundings` is
|
|
120
|
+
* what says so.
|
|
121
|
+
*/
|
|
122
|
+
export const solveMarkLightness = (hue, saturation, from, grounds, target) => {
|
|
123
|
+
const nearestGround = (candidate) => Math.min(...grounds.map((ground) => colourDifference(candidate, ground) ?? 0));
|
|
124
|
+
for (let step = 0; step <= 40; step += 0.125) {
|
|
125
|
+
for (const lightness of step === 0 ? [from] : [from - step, from + step]) {
|
|
126
|
+
const candidate = hslHex(hue, saturation, lightness);
|
|
127
|
+
if (lightness >= 0 && lightness <= 100 && nearestGround(candidate) >= target)
|
|
128
|
+
return candidate;
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
return hslHex(hue, saturation, from);
|
|
132
|
+
};
|
|
89
133
|
/**
|
|
90
134
|
* Derives a palette. Total: it always returns one, and `auditPalette` on the
|
|
91
135
|
* result is the check that it worked — see `derivePaletteChecked` for the pair.
|
|
@@ -134,7 +178,16 @@ export const derivePalette = (spec) => {
|
|
|
134
178
|
"brand-secondary-strong": hslHex(sh, Math.min(ss + 6, 100), ink ? 38 : 48),
|
|
135
179
|
"border-default": hslHex(ch, cs + 4, ink ? 86 : 22),
|
|
136
180
|
"border-strong": hslHex(ch, cs + 4, ink ? 12 : 90),
|
|
137
|
-
|
|
181
|
+
/**
|
|
182
|
+
* The one border tier that is solved rather than picked. At the default
|
|
183
|
+
* levels it lands two points of lightness from the muted well, which is
|
|
184
|
+
* under the just-noticeable difference — so eight of the palettes in
|
|
185
|
+
* `palettes.ts` shipped a card edge a reader could not find, and one of
|
|
186
|
+
* them drew it in the well's own colour. The other two tiers are 4 to 15
|
|
187
|
+
* and 74 to 98 from every ground at every hue this derives, so they are
|
|
188
|
+
* picked; if that ever stops being true, this is the function to reach for.
|
|
189
|
+
*/
|
|
190
|
+
"border-subtle": solveMarkLightness(ch, cs + 3, ink ? 92 : 17, [bgCanvas, bgSurface, bgSurfaceMuted], MARK_SEPARATION_TARGET),
|
|
138
191
|
"border-accent": hslHex(ah, Math.min(as, 70), ink ? 58 : 62),
|
|
139
192
|
},
|
|
140
193
|
});
|
package/dist/theme/library.js
CHANGED
|
@@ -37,7 +37,7 @@ export const editorialPalette = paletteSchema.parse({
|
|
|
37
37
|
"brand-secondary-strong": "#34425a",
|
|
38
38
|
"border-default": "#e5e5e5",
|
|
39
39
|
"border-strong": "#0a0a0a",
|
|
40
|
-
"border-subtle": "#
|
|
40
|
+
"border-subtle": "#e8e8df",
|
|
41
41
|
"border-accent": "#4a5b78",
|
|
42
42
|
},
|
|
43
43
|
});
|
package/dist/theme/measure.d.ts
CHANGED
|
@@ -115,6 +115,35 @@ export declare const slotChroma: (colour: string) => number | undefined;
|
|
|
115
115
|
* pair that might be the wrong way round.
|
|
116
116
|
*/
|
|
117
117
|
export declare const paletteScrim: (palette: Palette) => Scrim | undefined;
|
|
118
|
+
/**
|
|
119
|
+
* Which way round a palette is.
|
|
120
|
+
*
|
|
121
|
+
* Not a colour and not a threshold: the question `color-scheme` asks, which is
|
|
122
|
+
* whether text on this palette's own ground is light-on-dark or dark-on-light.
|
|
123
|
+
* A host that draws a frame standing in for the page needs the answer and has
|
|
124
|
+
* nowhere to get it — `themeStyle` hands over every variable a *primitive*
|
|
125
|
+
* reads, and being light or dark is the one fact the host needs about the
|
|
126
|
+
* palette rather than from it.
|
|
127
|
+
*/
|
|
128
|
+
export type PaletteScheme = "light" | "dark";
|
|
129
|
+
/**
|
|
130
|
+
* Which way round the palette is, or `undefined` when either end of its
|
|
131
|
+
* body-copy pair is a colour `channelsOf` declines to read.
|
|
132
|
+
*
|
|
133
|
+
* **No threshold, deliberately.** A luminance ceiling would be a number this
|
|
134
|
+
* module had to defend, and the one it already has — `SCRIM_DARK_CEILING` — is
|
|
135
|
+
* about whether a wash can darken what is under it, which is a different
|
|
136
|
+
* question with a different answer. Comparing a palette's own ink to its own
|
|
137
|
+
* canvas needs no constant at all: whichever is lighter says which way round the
|
|
138
|
+
* palette is, and it says it for a host palette nobody here has seen.
|
|
139
|
+
*
|
|
140
|
+
* Measured across the twenty-one registered palettes the two groups are canvases
|
|
141
|
+
* at `L > 0.9` and `L < 0.02`, so nothing sits anywhere near a line that does not
|
|
142
|
+
* exist. `measure.test.ts` holds that, and holds this against `paletteScrim`'s
|
|
143
|
+
* reading of the same pair, because two functions comparing one pair of colours
|
|
144
|
+
* must not be able to disagree about it.
|
|
145
|
+
*/
|
|
146
|
+
export declare const paletteScheme: (palette: Palette) => PaletteScheme | undefined;
|
|
118
147
|
/** Everything measurable about one palette that its slots do not say. */
|
|
119
148
|
export type PaletteMeasures = {
|
|
120
149
|
readonly palette: ThemeId;
|
|
@@ -125,6 +154,11 @@ export type PaletteMeasures = {
|
|
|
125
154
|
*/
|
|
126
155
|
readonly chroma: Readonly<Partial<Record<PaletteSlot, number>>>;
|
|
127
156
|
readonly scrim: Scrim | undefined;
|
|
157
|
+
/**
|
|
158
|
+
* Which way round the palette is, and `undefined` on the same terms `scrim`
|
|
159
|
+
* is: a pair this cannot read is reported as unavailable rather than guessed.
|
|
160
|
+
*/
|
|
161
|
+
readonly scheme: PaletteScheme | undefined;
|
|
128
162
|
};
|
|
129
163
|
/** Measures one palette. Refuses nothing, and reports what it could not measure by leaving it out. */
|
|
130
164
|
export declare const paletteMeasures: (palette: Palette) => PaletteMeasures;
|
package/dist/theme/measure.js
CHANGED
|
@@ -119,6 +119,30 @@ export const paletteScrim = (palette) => {
|
|
|
119
119
|
darkens: luminance <= SCRIM_DARK_CEILING,
|
|
120
120
|
};
|
|
121
121
|
};
|
|
122
|
+
/**
|
|
123
|
+
* Which way round the palette is, or `undefined` when either end of its
|
|
124
|
+
* body-copy pair is a colour `channelsOf` declines to read.
|
|
125
|
+
*
|
|
126
|
+
* **No threshold, deliberately.** A luminance ceiling would be a number this
|
|
127
|
+
* module had to defend, and the one it already has — `SCRIM_DARK_CEILING` — is
|
|
128
|
+
* about whether a wash can darken what is under it, which is a different
|
|
129
|
+
* question with a different answer. Comparing a palette's own ink to its own
|
|
130
|
+
* canvas needs no constant at all: whichever is lighter says which way round the
|
|
131
|
+
* palette is, and it says it for a host palette nobody here has seen.
|
|
132
|
+
*
|
|
133
|
+
* Measured across the twenty-one registered palettes the two groups are canvases
|
|
134
|
+
* at `L > 0.9` and `L < 0.02`, so nothing sits anywhere near a line that does not
|
|
135
|
+
* exist. `measure.test.ts` holds that, and holds this against `paletteScrim`'s
|
|
136
|
+
* reading of the same pair, because two functions comparing one pair of colours
|
|
137
|
+
* must not be able to disagree about it.
|
|
138
|
+
*/
|
|
139
|
+
export const paletteScheme = (palette) => {
|
|
140
|
+
const ink = relativeLuminance(palette.slots["fg-default"] ?? "");
|
|
141
|
+
const page = relativeLuminance(palette.slots["bg-canvas"] ?? "");
|
|
142
|
+
if (ink === undefined || page === undefined)
|
|
143
|
+
return undefined;
|
|
144
|
+
return ink > page ? "dark" : "light";
|
|
145
|
+
};
|
|
122
146
|
/** Measures one palette. Refuses nothing, and reports what it could not measure by leaving it out. */
|
|
123
147
|
export const paletteMeasures = (palette) => {
|
|
124
148
|
const chroma = {};
|
|
@@ -127,7 +151,12 @@ export const paletteMeasures = (palette) => {
|
|
|
127
151
|
if (measured !== undefined)
|
|
128
152
|
chroma[slot] = measured;
|
|
129
153
|
}
|
|
130
|
-
return {
|
|
154
|
+
return {
|
|
155
|
+
palette: palette.id,
|
|
156
|
+
chroma,
|
|
157
|
+
scrim: paletteScrim(palette),
|
|
158
|
+
scheme: paletteScheme(palette),
|
|
159
|
+
};
|
|
131
160
|
};
|
|
132
161
|
/**
|
|
133
162
|
* The decimal places a chroma is emitted to.
|
package/dist/theme/palettes.js
CHANGED
|
@@ -56,7 +56,7 @@ export const paperPalette = paletteSchema.parse({
|
|
|
56
56
|
"brand-secondary-strong": "#ac7515",
|
|
57
57
|
"border-default": "#e7dbcf",
|
|
58
58
|
"border-strong": "#291f14",
|
|
59
|
-
"border-subtle": "#
|
|
59
|
+
"border-subtle": "#efe8e0",
|
|
60
60
|
"border-accent": "#d67551",
|
|
61
61
|
},
|
|
62
62
|
});
|
|
@@ -104,7 +104,7 @@ export const sagePalette = paletteSchema.parse({
|
|
|
104
104
|
"brand-secondary-strong": "#56952d",
|
|
105
105
|
"border-default": "#d5e2d5",
|
|
106
106
|
"border-strong": "#192419",
|
|
107
|
-
"border-subtle": "#
|
|
107
|
+
"border-subtle": "#e4ece4",
|
|
108
108
|
"border-accent": "#5ccc90",
|
|
109
109
|
},
|
|
110
110
|
});
|
|
@@ -176,7 +176,7 @@ export const citrusPalette = paletteSchema.parse({
|
|
|
176
176
|
"brand-secondary-strong": "#b6830c",
|
|
177
177
|
"border-default": "#e9e6ce",
|
|
178
178
|
"border-strong": "#2a2813",
|
|
179
|
-
"border-subtle": "#
|
|
179
|
+
"border-subtle": "#f0efde",
|
|
180
180
|
"border-accent": "#b4d058",
|
|
181
181
|
},
|
|
182
182
|
});
|
|
@@ -224,7 +224,7 @@ export const graphitePalette = paletteSchema.parse({
|
|
|
224
224
|
"brand-secondary-strong": "#675b5b",
|
|
225
225
|
"border-default": "#dddada",
|
|
226
226
|
"border-strong": "#201d1d",
|
|
227
|
-
"border-subtle": "#
|
|
227
|
+
"border-subtle": "#e8e6e6",
|
|
228
228
|
"border-accent": "#949494",
|
|
229
229
|
},
|
|
230
230
|
});
|
|
@@ -248,7 +248,7 @@ export const clayPalette = paletteSchema.parse({
|
|
|
248
248
|
"brand-secondary-strong": "#348d6a",
|
|
249
249
|
"border-default": "#e6ddd1",
|
|
250
250
|
"border-strong": "#282015",
|
|
251
|
-
"border-subtle": "#
|
|
251
|
+
"border-subtle": "#ebe4db",
|
|
252
252
|
"border-accent": "#d27356",
|
|
253
253
|
},
|
|
254
254
|
});
|
|
@@ -272,7 +272,7 @@ export const linenPalette = paletteSchema.parse({
|
|
|
272
272
|
"brand-secondary-strong": "#32708f",
|
|
273
273
|
"border-default": "#e5dfd1",
|
|
274
274
|
"border-strong": "#272216",
|
|
275
|
-
"border-subtle": "#
|
|
275
|
+
"border-subtle": "#eae6da",
|
|
276
276
|
"border-accent": "#b49274",
|
|
277
277
|
},
|
|
278
278
|
});
|
|
@@ -416,7 +416,7 @@ export const duskPalette = paletteSchema.parse({
|
|
|
416
416
|
"brand-secondary-strong": "#752acb",
|
|
417
417
|
"border-default": "#2d2c44",
|
|
418
418
|
"border-strong": "#e1e0eb",
|
|
419
|
-
"border-subtle": "#
|
|
419
|
+
"border-subtle": "#252437",
|
|
420
420
|
"border-accent": "#de5e73",
|
|
421
421
|
},
|
|
422
422
|
});
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A ramp step as a CSS length, and the width at which it is what the pack said.
|
|
3
|
+
*
|
|
4
|
+
* A font pack declares eight type sizes and a style preset eight spacing steps,
|
|
5
|
+
* both as plain numbers, and `apply.ts` mounted them as pixels. That is the
|
|
6
|
+
* whole of why a page built in Loom did not fit a phone: `--loom-scale-8` was
|
|
7
|
+
* 72px at every width, so a hero headline on a 390px screen was given three
|
|
8
|
+
* characters a line, and `--loom-spacing-4` plus `--loom-spacing-6` took 35% of
|
|
9
|
+
* that screen in gutter before a word was set. Filed by `Loom marketing` on
|
|
10
|
+
* 13 October against the one surface built entirely in the framework — measured
|
|
11
|
+
* there, because the only instrument that sees it is a camera.
|
|
12
|
+
*
|
|
13
|
+
* **A tree cannot fix it and must not be able to.** There is no prop, no theme
|
|
14
|
+
* and no node that means *smaller on a phone*, and there is not going to be
|
|
15
|
+
* one: a render is a pure function of one node
|
|
16
|
+
* ([0008](../../decisions/0008-the-renderer-is-a-total-pure-projection.md)), so
|
|
17
|
+
* a primitive handed a viewport would make the same tree a different page. The
|
|
18
|
+
* surface's own stylesheet cannot fix it either — a second source of truth for
|
|
19
|
+
* type and spacing is exactly what the re-theme guarantee
|
|
20
|
+
* ([0049](../../decisions/0049-a-theme-is-three-ids-in-the-tree.md)) cannot
|
|
21
|
+
* have.
|
|
22
|
+
*
|
|
23
|
+
* So the width is read where this repository already reads it: in CSS.
|
|
24
|
+
* [0079](../../decisions/0079-a-layout-css-alone-can-express-belongs-in-the-stylesheet.md)
|
|
25
|
+
* drew that line for `loom.mosaic` and drew it in the right place — *no
|
|
26
|
+
* viewport in the render function*, and a rule in a stylesheet is not in the
|
|
27
|
+
* render function. A `clamp()` is the same bargain one step earlier: the markup
|
|
28
|
+
* is unchanged, nothing is interpolated, `themeVariables` is as pure as it was
|
|
29
|
+
* — the same theme yields the same strings — and the browser rather than the
|
|
30
|
+
* render function is what knows how wide the page is.
|
|
31
|
+
*
|
|
32
|
+
* ## What a declared number now means
|
|
33
|
+
*
|
|
34
|
+
* **A maximum, reached at `48rem` and held above it.** Below that a step is
|
|
35
|
+
* compressed toward the largest value its quantity can hold on a phone, and a
|
|
36
|
+
* step already that small is emitted as the plain pixel length it always was.
|
|
37
|
+
* The consequence worth stating is the one that is easy to miss: **nothing
|
|
38
|
+
* changes at or above 768px.** A reader on a laptop sees the ramp the pack
|
|
39
|
+
* declared, to the pixel.
|
|
40
|
+
*/
|
|
41
|
+
/** Which ramp a step belongs to. They differ only in what a phone can hold. */
|
|
42
|
+
export type RampKind = "type" | "space";
|
|
43
|
+
/**
|
|
44
|
+
* Whether the emitted length may read the width.
|
|
45
|
+
*
|
|
46
|
+
* `"fixed"` is for a medium with no cascade and no viewport — an image renderer
|
|
47
|
+
* or an email body, which `inline-variables.ts` substitutes values into. A
|
|
48
|
+
* `clamp()` in container units is not a literal length: it is strictly worse
|
|
49
|
+
* there than the pixel it replaced, because nothing in that medium resolves it.
|
|
50
|
+
* A caller asking for literals gets the pack's declared numbers.
|
|
51
|
+
*/
|
|
52
|
+
export type RampMode = "fluid" | "fixed";
|
|
53
|
+
/**
|
|
54
|
+
* One ramp step, as the length `apply.ts` mounts.
|
|
55
|
+
*
|
|
56
|
+
* The preferred value is `cqi` rather than `vw` for the reason `loom.heading`
|
|
57
|
+
* learned in the same place: with no ancestor declaring containment `cqi` is
|
|
58
|
+
* the small viewport width, so a step on the open page behaves as it always
|
|
59
|
+
* did, and a step inside a `loom.card` or one half of a `loom.split` is held to
|
|
60
|
+
* the column it is actually in because those declare the containment for it to
|
|
61
|
+
* read.
|
|
62
|
+
*/
|
|
63
|
+
export declare const rampLength: (step: number, kind: RampKind, mode: RampMode) => string;
|
|
64
|
+
//# sourceMappingURL=ramp.d.ts.map
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A ramp step as a CSS length, and the width at which it is what the pack said.
|
|
3
|
+
*
|
|
4
|
+
* A font pack declares eight type sizes and a style preset eight spacing steps,
|
|
5
|
+
* both as plain numbers, and `apply.ts` mounted them as pixels. That is the
|
|
6
|
+
* whole of why a page built in Loom did not fit a phone: `--loom-scale-8` was
|
|
7
|
+
* 72px at every width, so a hero headline on a 390px screen was given three
|
|
8
|
+
* characters a line, and `--loom-spacing-4` plus `--loom-spacing-6` took 35% of
|
|
9
|
+
* that screen in gutter before a word was set. Filed by `Loom marketing` on
|
|
10
|
+
* 13 October against the one surface built entirely in the framework — measured
|
|
11
|
+
* there, because the only instrument that sees it is a camera.
|
|
12
|
+
*
|
|
13
|
+
* **A tree cannot fix it and must not be able to.** There is no prop, no theme
|
|
14
|
+
* and no node that means *smaller on a phone*, and there is not going to be
|
|
15
|
+
* one: a render is a pure function of one node
|
|
16
|
+
* ([0008](../../decisions/0008-the-renderer-is-a-total-pure-projection.md)), so
|
|
17
|
+
* a primitive handed a viewport would make the same tree a different page. The
|
|
18
|
+
* surface's own stylesheet cannot fix it either — a second source of truth for
|
|
19
|
+
* type and spacing is exactly what the re-theme guarantee
|
|
20
|
+
* ([0049](../../decisions/0049-a-theme-is-three-ids-in-the-tree.md)) cannot
|
|
21
|
+
* have.
|
|
22
|
+
*
|
|
23
|
+
* So the width is read where this repository already reads it: in CSS.
|
|
24
|
+
* [0079](../../decisions/0079-a-layout-css-alone-can-express-belongs-in-the-stylesheet.md)
|
|
25
|
+
* drew that line for `loom.mosaic` and drew it in the right place — *no
|
|
26
|
+
* viewport in the render function*, and a rule in a stylesheet is not in the
|
|
27
|
+
* render function. A `clamp()` is the same bargain one step earlier: the markup
|
|
28
|
+
* is unchanged, nothing is interpolated, `themeVariables` is as pure as it was
|
|
29
|
+
* — the same theme yields the same strings — and the browser rather than the
|
|
30
|
+
* render function is what knows how wide the page is.
|
|
31
|
+
*
|
|
32
|
+
* ## What a declared number now means
|
|
33
|
+
*
|
|
34
|
+
* **A maximum, reached at `48rem` and held above it.** Below that a step is
|
|
35
|
+
* compressed toward the largest value its quantity can hold on a phone, and a
|
|
36
|
+
* step already that small is emitted as the plain pixel length it always was.
|
|
37
|
+
* The consequence worth stating is the one that is easy to miss: **nothing
|
|
38
|
+
* changes at or above 768px.** A reader on a laptop sees the ramp the pack
|
|
39
|
+
* declared, to the pixel.
|
|
40
|
+
*/
|
|
41
|
+
/**
|
|
42
|
+
* The width at which a ramp is exactly what its pack declared.
|
|
43
|
+
*
|
|
44
|
+
* `48rem` is the library's one width and 0079 set the bar for a second high on
|
|
45
|
+
* purpose. This is not a second one — a `clamp()` has no breakpoint in it, and
|
|
46
|
+
* naming the width the library already switches `loom.mosaic` on is the whole
|
|
47
|
+
* reason to prefer this number to a better-looking one.
|
|
48
|
+
*/
|
|
49
|
+
const FULL_WIDTH_PX = 768;
|
|
50
|
+
/**
|
|
51
|
+
* How much of the distance between the hold and the declared number survives on
|
|
52
|
+
* a narrow screen.
|
|
53
|
+
*
|
|
54
|
+
* **It is not a taste.** `loom.primitives` capped `loom.heading`'s top step at
|
|
55
|
+
* `11cqi` on 20 August, found by measuring which words lost their last letter
|
|
56
|
+
* in a 390px screen. `0.46` is the ratio that reproduces that cap from the
|
|
57
|
+
* pack's own number — a 72px step floors at 42.84px where `11cqi` is 42.90px —
|
|
58
|
+
* so the figure a lane arrived at by photographing one pack is now derived for
|
|
59
|
+
* every step of every pack, including the ones nothing has photographed.
|
|
60
|
+
*/
|
|
61
|
+
const COMPRESSION = 0.46;
|
|
62
|
+
/**
|
|
63
|
+
* The value each ramp is compressed toward, and the reason the two differ.
|
|
64
|
+
*
|
|
65
|
+
* Type holds at 18px because step 3 is body copy in every registered pack and
|
|
66
|
+
* step 4 is 17–20: a ramp that shrank those would be trading a headline that
|
|
67
|
+
* does not fit for paragraphs nobody can read. Space holds at 8px because
|
|
68
|
+
* whitespace has no legibility floor — only a floor at which a gap stops
|
|
69
|
+
* reading as one — and a phone wants less of it, not a little less.
|
|
70
|
+
*/
|
|
71
|
+
const HOLD_PX = { type: 18, space: 8 };
|
|
72
|
+
/**
|
|
73
|
+
* Two decimal places, rounded **up**.
|
|
74
|
+
*
|
|
75
|
+
* Up rather than to nearest, and the preferred value is why. A coefficient
|
|
76
|
+
* rounded down reaches the declared size a little *after* `48rem` rather than
|
|
77
|
+
* at it — `20px` resolved to 19.97 at 768 before this was `ceil`, which is the
|
|
78
|
+
* one property the whole construction promises and the kind of defect only
|
|
79
|
+
* arithmetic over every registered pack finds. On a floor a hundredth of a
|
|
80
|
+
* pixel is beneath anything a reader or a camera can see.
|
|
81
|
+
*/
|
|
82
|
+
const round = (value) => Math.ceil(value * 100) / 100;
|
|
83
|
+
/**
|
|
84
|
+
* The smallest this step is ever rendered.
|
|
85
|
+
*
|
|
86
|
+
* Monotone in `step` by construction — the identity at or below the hold, and
|
|
87
|
+
* affine with a positive slope above it — which is what keeps a ramp a ramp. A
|
|
88
|
+
* narrow screen reorders nothing: if the declared steps ascend, so do these,
|
|
89
|
+
* and so does every width between the two bounds.
|
|
90
|
+
*/
|
|
91
|
+
const rampFloor = (step, kind) => {
|
|
92
|
+
const hold = HOLD_PX[kind];
|
|
93
|
+
return step <= hold ? step : hold + (step - hold) * COMPRESSION;
|
|
94
|
+
};
|
|
95
|
+
/**
|
|
96
|
+
* One ramp step, as the length `apply.ts` mounts.
|
|
97
|
+
*
|
|
98
|
+
* The preferred value is `cqi` rather than `vw` for the reason `loom.heading`
|
|
99
|
+
* learned in the same place: with no ancestor declaring containment `cqi` is
|
|
100
|
+
* the small viewport width, so a step on the open page behaves as it always
|
|
101
|
+
* did, and a step inside a `loom.card` or one half of a `loom.split` is held to
|
|
102
|
+
* the column it is actually in because those declare the containment for it to
|
|
103
|
+
* read.
|
|
104
|
+
*/
|
|
105
|
+
export const rampLength = (step, kind, mode) => {
|
|
106
|
+
if (mode === "fixed")
|
|
107
|
+
return `${step}px`;
|
|
108
|
+
const floor = round(rampFloor(step, kind));
|
|
109
|
+
/** A step a phone already holds is the plain length it has always been. */
|
|
110
|
+
if (floor >= step)
|
|
111
|
+
return `${step}px`;
|
|
112
|
+
return `clamp(${floor}px, ${round((step / FULL_WIDTH_PX) * 100)}cqi, ${step}px)`;
|
|
113
|
+
};
|
|
114
|
+
//# sourceMappingURL=ramp.js.map
|
package/dist/theme/registry.d.ts
CHANGED
|
@@ -24,6 +24,15 @@ export type ThemeError = {
|
|
|
24
24
|
readonly code: "malformed-selection";
|
|
25
25
|
readonly detail: string;
|
|
26
26
|
};
|
|
27
|
+
/**
|
|
28
|
+
* Why a theme did not resolve, and what could have.
|
|
29
|
+
*
|
|
30
|
+
* `available` holds every registered id and this prints the few nearest the one
|
|
31
|
+
* that was asked for, because the sentence lands in a log line whose length is
|
|
32
|
+
* not the deployment's to set. A caller that wants the whole list has it on the
|
|
33
|
+
* error, and a caller that wants it with names and descriptions has
|
|
34
|
+
* `catalogue()`.
|
|
35
|
+
*/
|
|
27
36
|
export declare const describeThemeError: (error: ThemeError) => string;
|
|
28
37
|
export type ThemeCatalogueEntry = {
|
|
29
38
|
readonly id: string;
|