@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.
Files changed (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -15,6 +15,17 @@ const nameRead = (declaration, props) => {
15
15
  const named = props[declaration.fromProp];
16
16
  return typeof named === "string" && named !== "" ? named : declaration.default;
17
17
  };
18
+ /**
19
+ * Every name a node carrying these props reads, one per declaration.
20
+ *
21
+ * Exported because a second instrument asks the same question of a state it is
22
+ * about to probe in rather than of a node — whether an answer it was handed is
23
+ * keyed under a name this primitive will look for — and the resolution has to be
24
+ * the walk's own or the two disagree about one declaration. Unsorted and not
25
+ * deduplicated: it answers *per declaration*, and `unreadBindings` wants a set
26
+ * while a caller reporting what a primitive asked for wants the list as declared.
27
+ */
28
+ export const namesRead = (declared, props) => declared.map((declaration) => nameRead(declaration, props));
18
29
  /**
19
30
  * The names this node asked under that its primitive says it does not read.
20
31
  *
@@ -35,7 +46,7 @@ const nameRead = (declaration, props) => {
35
46
  export const unreadBindings = (asked, declared, props) => {
36
47
  if (declared === undefined)
37
48
  return [];
38
- const reads = new Set(declared.map((declaration) => nameRead(declaration, props)));
49
+ const reads = new Set(namesRead(declared, props));
39
50
  const unread = [];
40
51
  for (const name of asked)
41
52
  if (!reads.has(name))
@@ -6,14 +6,25 @@ import { assertNever } from "../result.js";
6
6
  import { themeVariables } from "../theme/apply.js";
7
7
  import { findNode, textOf } from "../tree/navigation.js";
8
8
  import { createAnchorLedger, resolveAnchor, } from "./anchor.js";
9
- import { isBehaviourResolver, NO_RESOLVED_BEHAVIOURS, resolveBehaviours, } from "./behaviour.js";
9
+ import { isBehaviourResolver, NO_RESOLVED_BEHAVIOURS, NO_CONTROL_NAME_PROPS, resolveBehaviours, resolveControlNames, } from "./behaviour.js";
10
10
  import { literalThemeElement } from "./inline-variables.js";
11
11
  import { editableAttributes } from "./editable.js";
12
12
  import { isFrameResolver, resolveNodeFrames } from "./frame.js";
13
13
  import { NO_SLOTS, } from "./primitive.js";
14
14
  import { isBindingReader, unreadBindings } from "./reads.js";
15
+ import { isSlotPlacer, unplacedSlots } from "./slots.js";
16
+ import { isUnshownReader, readUnshown, unshownRows, } from "./unshown.js";
15
17
  import { isTextResolver, NO_TEXT, overlayText, } from "./text.js";
16
18
  import { partitionReservedProps, resolveTheme, themeStyle, THEME_PROP_KEY } from "./theme.js";
19
+ /**
20
+ * Whether this render's ramps may read the width they are laid out at.
21
+ *
22
+ * A caller asking for literals is feeding a medium with no cascade, which
23
+ * resolves a container unit exactly as poorly as it resolves a `var()` — so the
24
+ * ramps mount as the pack's declared pixels and the root's declarations agree
25
+ * with the values substituted beneath them (0283).
26
+ */
27
+ const rampFor = (options) => options.themeValues === "literals" ? "fixed" : "fluid";
17
28
  const renderChildren = (children, context) => children.length === 0 ? null : children.map((child) => renderNode(child, context));
18
29
  const isRootNode = (node, context) => node.id === context.tree.root.id;
19
30
  const renderElementBody = (node, context) => {
@@ -127,8 +138,36 @@ const nodeDataFor = (node, declared, context) => {
127
138
  context.collect({ code: "data-unresolved", nodeId: node.id, resolution: "unrelated" });
128
139
  }
129
140
  reportUnreadBindings(node, data, context);
141
+ reportUnshownRows(node, data, context);
130
142
  return data;
131
143
  };
144
+ /**
145
+ * A diagnostic for every region this node filled that its primitive places
146
+ * nowhere.
147
+ *
148
+ * Measured on the node's own slot *children* rather than on `body.slots`, which
149
+ * is the same list by construction and is built by walking the subtree. Reading
150
+ * the children keeps this node's diagnostic ahead of its descendants' in the
151
+ * collected order, which is what every other report in this walk does.
152
+ *
153
+ * Silent unless the resolver can say what a primitive places, which is the same
154
+ * bargain `reads` makes: `undefined` is a resolver with no registry behind it,
155
+ * or a type no registry holds, and neither is a primitive claiming it places
156
+ * nothing. A primitive that declared no regions *is* one — `slots` is the one
157
+ * declaration where leaving it out and declaring it empty are the same claim
158
+ * (`sdk/definition.ts`), and 0051 made that claim operational.
159
+ */
160
+ const reportUnplacedSlots = (node, context) => {
161
+ const filled = [];
162
+ for (const child of node.children)
163
+ if (child.kind === "slot")
164
+ filled.push(child.name);
165
+ if (filled.length === 0)
166
+ return;
167
+ for (const name of unplacedSlots(filled, context.placer?.slotsPlacedBy(node.type))) {
168
+ context.collect({ code: "slot-unplaced", nodeId: node.id, type: node.type, name });
169
+ }
170
+ };
132
171
  /**
133
172
  * A diagnostic for every name this node was answered under that its primitive
134
173
  * says it does not read.
@@ -160,6 +199,50 @@ const reportUnreadBindings = (node, data, context) => {
160
199
  context.collect({ code: "data-unread", nodeId: node.id, type: node.type, name });
161
200
  }
162
201
  };
202
+ /**
203
+ * A diagnostic for every answer this node's primitive was given whole and drew
204
+ * part of.
205
+ *
206
+ * The one report in this walk the walk cannot make for itself: whether a row can
207
+ * be read is a question about a shape only the primitive holds, so the primitive
208
+ * declares the reading and this is where it is called (0206). Called with the
209
+ * node's props and its answers because those are what the component gets, so the
210
+ * declaration can be the same function the component calls and the count cannot
211
+ * disagree with the page.
212
+ *
213
+ * Silent unless the primitive has declared, the same bargain `reads` makes: a
214
+ * primitive whose author has said nothing is not a primitive claiming it shows
215
+ * everything it is given.
216
+ *
217
+ * A declaration that cannot be believed is reported as itself and costs the node
218
+ * nothing — it renders exactly as it would have, because a count is bookkeeping
219
+ * about an answer rather than part of drawing it.
220
+ */
221
+ const reportUnshownRows = (node, data, context) => {
222
+ const declaration = context.unshown?.unshownBy(node.type);
223
+ if (declaration === undefined)
224
+ return;
225
+ const readings = readUnshown(declaration, node.props, data);
226
+ if (!readings.ok) {
227
+ context.collect({
228
+ code: "unshown-unreadable",
229
+ nodeId: node.id,
230
+ type: node.type,
231
+ fault: readings.error,
232
+ });
233
+ return;
234
+ }
235
+ for (const reading of unshownRows(readings.value)) {
236
+ context.collect({
237
+ code: "data-unshown",
238
+ nodeId: node.id,
239
+ type: node.type,
240
+ name: reading.name,
241
+ given: reading.given,
242
+ shown: reading.shown,
243
+ });
244
+ }
245
+ };
163
246
  /** Whether the resolution answered this node at all. Early-return rather than
164
247
  * `Object.keys`, because it runs on every bound node of every render and the
165
248
  * question is only ever whether the bag is empty. */
@@ -290,15 +373,22 @@ const nodeAnchorFor = (node, reserved, context) => {
290
373
  * rather than from the markup around it, so a copy button copies what the page
291
374
  * says and not the language label its own primitive rendered beside it.
292
375
  *
376
+ * A control's *name* is read from the tree too, where the primitive named a prop
377
+ * for it (0234), and from nowhere else: a type that named none, or a node that
378
+ * left the prop out, gets the string the primitive declared. Read here rather
379
+ * than in the seam because this is where a node's props are, and a behaviour
380
+ * receives the resolved word rather than the props it came out of.
381
+ *
293
382
  * A behaviour whose name could not be resolved is left out and reported, for
294
383
  * the reason `resolveBehaviours` gives: a control a screen reader announces as
295
384
  * "button" is worse than no control, and this is the only place that can say so.
296
385
  */
297
- const nodeBehavioursFor = (node, text, context) => {
386
+ const nodeBehavioursFor = (node, props, text, context) => {
298
387
  const declared = context.behaviours?.behavioursFor(node.type) ?? [];
299
388
  if (declared.length === 0)
300
389
  return NO_RESOLVED_BEHAVIOURS.behaviours;
301
- const resolved = resolveBehaviours(declared, textOf(node), text);
390
+ const named = resolveControlNames(props, context.behaviours?.controlNamePropsFor?.(node.type) ?? NO_CONTROL_NAME_PROPS);
391
+ const resolved = resolveBehaviours(declared, textOf(node), text, named);
302
392
  for (const { behaviour, key } of resolved.unnamed) {
303
393
  context.collect({ code: "behaviour-unnamed", nodeId: node.id, behaviour, key });
304
394
  }
@@ -381,7 +471,8 @@ const renderElement = (node, context) => {
381
471
  */
382
472
  const anchor = reserved[ANCHOR_PROP_KEY] === undefined ? undefined : nodeAnchorFor(node, reserved, context);
383
473
  const text = context.text?.textFor(node.type) ?? NO_TEXT;
384
- const behaviours = nodeBehavioursFor(node, text, context);
474
+ const behaviours = nodeBehavioursFor(node, props, text, context);
475
+ reportUnplacedSlots(node, context);
385
476
  const body = renderElementBody(node, context);
386
477
  const rendered = {
387
478
  loom: renderContextFor(node, body.slots, data, submit, frames, anchor, text, behaviours, context),
@@ -499,17 +590,21 @@ const renderFrom = (tree, from, options, collect) => {
499
590
  addressed: options.addressed ?? false,
500
591
  slots: options.slots ?? {},
501
592
  tree,
502
- theme: theme ? themeStyle(theme) : undefined,
593
+ theme: theme ? themeStyle(theme, rampFor(options)) : undefined,
503
594
  data: options.data,
504
595
  submissions: options.submissions,
505
596
  origins: options.origins,
506
597
  frames: isFrameResolver(options.resolver) ? options.resolver : undefined,
507
598
  reads: isBindingReader(options.resolver) ? options.resolver : undefined,
599
+ unshown: isUnshownReader(options.resolver) ? options.resolver : undefined,
600
+ placer: isSlotPlacer(options.resolver) ? options.resolver : undefined,
508
601
  text: composeText(options.resolver, options.text),
509
602
  behaviours: isBehaviourResolver(options.resolver) ? options.resolver : undefined,
510
603
  anchors: createAnchorLedger(),
511
604
  decorative: false,
512
- literals: options.themeValues === "literals" && theme ? themeVariables(theme) : undefined,
605
+ literals: options.themeValues === "literals" && theme
606
+ ? themeVariables(theme, { ramp: rampFor(options) })
607
+ : undefined,
513
608
  collect,
514
609
  });
515
610
  return { element, theme };
@@ -562,7 +657,7 @@ export const renderLoomExcerpt = (tree, nodeId, options) => {
562
657
  }
563
658
  const { element, theme } = renderFrom(tree, from, options, collect);
564
659
  return {
565
- element: createElement("div", { style: theme ? themeStyle(theme) : undefined }, element),
660
+ element: createElement("div", { style: theme ? themeStyle(theme, rampFor(options)) : undefined }, element),
566
661
  diagnostics,
567
662
  found: true,
568
663
  ...(theme ? { theme } : {}),
@@ -0,0 +1,52 @@
1
+ import type { PrimitiveType, SlotName } from "../primitive-type.js";
2
+ /**
3
+ * What a primitive says it places, and what a tree filled that it will not.
4
+ *
5
+ * A slot child is a named region of authored content, and the name is how the
6
+ * primitive receiving it decides where it goes
7
+ * ([0051](../../decisions/0051-a-slot-is-a-region-the-primitive-places.md)).
8
+ * 0051 states the cost of that in one line — *a primitive that does not place a
9
+ * region renders nothing for it* — and left it at the cost: the content and
10
+ * everything under it is dropped, the page looks finished, and no diagnostic
11
+ * says it happened.
12
+ *
13
+ * This module is the half that makes it visible. It holds the seam the walk
14
+ * asks, and the comparison it makes; what the walk *calls* the mismatch is the
15
+ * diagnostic vocabulary's business, the same split `reads.ts` makes for the
16
+ * binding nobody reads.
17
+ */
18
+ /**
19
+ * Which regions a primitive says it places, asked per type.
20
+ *
21
+ * Structural, and detected the way `BindingReader` and `FrameResolver` are: a
22
+ * registry built by the SDK satisfies it, and a host resolving from a plain map
23
+ * has registered nothing that could declare a region in the first place — so
24
+ * there is nothing here to wire and nothing that can go missing.
25
+ *
26
+ * `undefined` means *this resolver cannot say*, which is the answer for a type
27
+ * no registry holds. It is not a primitive's own answer, and that is the one
28
+ * asymmetry with `reads`: `slots` is the declaration where leaving it out and
29
+ * declaring it empty are the same claim, said so in `definition.ts` since §4
30
+ * and relied on by the catalogue (0013) and by the conformance probe, which
31
+ * reads the declared list as the complete one. So a primitive that has said
32
+ * nothing has said it places none, and the region a tree fills on it is
33
+ * reported.
34
+ */
35
+ export interface SlotPlacer {
36
+ readonly slotsPlacedBy: (type: PrimitiveType) => readonly SlotName[] | undefined;
37
+ }
38
+ export declare const isSlotPlacer: (value: object) => value is SlotPlacer;
39
+ /**
40
+ * The regions this node filled that its primitive places nowhere.
41
+ *
42
+ * Deduplicated, because two slot children may share a name and both be placed
43
+ * (0051) — which means both are dropped together, by one mistake, and a list
44
+ * that said it twice would make the count a function of how many times the tree
45
+ * spelled it.
46
+ *
47
+ * Name-sorted, because the caller reports one diagnostic per name and a
48
+ * diagnostic list whose order depends on child order is one a test can only
49
+ * assert loosely.
50
+ */
51
+ export declare const unplacedSlots: (filled: Iterable<string>, placed: readonly SlotName[] | undefined) => readonly string[];
52
+ //# sourceMappingURL=slots.d.ts.map
@@ -0,0 +1,24 @@
1
+ export const isSlotPlacer = (value) => typeof value.slotsPlacedBy === "function";
2
+ /**
3
+ * The regions this node filled that its primitive places nowhere.
4
+ *
5
+ * Deduplicated, because two slot children may share a name and both be placed
6
+ * (0051) — which means both are dropped together, by one mistake, and a list
7
+ * that said it twice would make the count a function of how many times the tree
8
+ * spelled it.
9
+ *
10
+ * Name-sorted, because the caller reports one diagnostic per name and a
11
+ * diagnostic list whose order depends on child order is one a test can only
12
+ * assert loosely.
13
+ */
14
+ export const unplacedSlots = (filled, placed) => {
15
+ if (placed === undefined)
16
+ return [];
17
+ const places = new Set(placed);
18
+ const unplaced = new Set();
19
+ for (const name of filled)
20
+ if (!places.has(name))
21
+ unplaced.add(name);
22
+ return [...unplaced].sort();
23
+ };
24
+ //# sourceMappingURL=slots.js.map
@@ -1,5 +1,7 @@
1
1
  import type { CSSProperties } from "react";
2
2
  import type { JsonObject } from "../json.js";
3
+ import { type RampMode } from "../theme/apply.js";
4
+ import { type PaletteScheme } from "../theme/measure.js";
3
5
  import type { ThemeError, ThemeRegistry } from "../theme/registry.js";
4
6
  import type { ResolvedTheme } from "../theme/theme.js";
5
7
  /**
@@ -57,5 +59,56 @@ export declare const resolveTheme: (reserved: JsonObject, registry: ThemeRegistr
57
59
  * types-only step, and it happens once here rather than in every primitive that
58
60
  * has to apply it.
59
61
  */
60
- export declare const themeStyle: (theme: ResolvedTheme) => CSSProperties;
62
+ export declare const themeStyle: (theme: ResolvedTheme, ramp?: RampMode) => CSSProperties;
63
+ /**
64
+ * The ground a host paints when it draws a frame standing in for the page.
65
+ *
66
+ * `themeStyle` hands over every variable a primitive reads, and a host drawing a
67
+ * whole page needs nothing else — the root primitive paints `bg-canvas` itself.
68
+ * A host drawing *part* of a tree is the case this exists for: an excerpt rooted
69
+ * at a band has no root primitive above it, so the frame around it has to paint
70
+ * the ground the excerpt would have sat on, and the frame is the host's rather
71
+ * than the tree's.
72
+ *
73
+ * It was written by hand twice before it was here, by one lane, in one week, and
74
+ * the second copy cost a **1.10:1** contrast ratio on the frame whose whole job
75
+ * was to show a stranger what they were about to lose: a stylesheet carried
76
+ * `background-color` and `color-scheme` as constants, the tree's palette moved
77
+ * from a light one to a dark one, and the two stopped agreeing. Nothing errored,
78
+ * because a stylesheet holding a copy of a decision the tree owns is not a thing
79
+ * any test in either place could see (0049).
80
+ *
81
+ * `bg-canvas` rather than `bg-surface`, because that is what the root primitive
82
+ * paints and therefore what is behind any band excerpted out of the page; a band
83
+ * that paints a surface of its own paints it over this, exactly as it does in
84
+ * place. `color` alongside it because a frame setting only the ground leaves
85
+ * anything inheriting its colour reading the *host's* ink on the tree's paper —
86
+ * the tree's own primitives read `--loom-fg-default` and are unaffected, and
87
+ * everything the host puts in that frame is not.
88
+ */
89
+ export type ThemeGround = {
90
+ readonly backgroundColor: string;
91
+ readonly color: string;
92
+ /**
93
+ * Absent — rather than guessed — when either end of the palette's body-copy
94
+ * pair is a colour `channelsOf` declines to read, in which case whatever
95
+ * `color-scheme` the host's own stylesheet sets stands. Every registered
96
+ * palette declares both as hex and resolves.
97
+ */
98
+ readonly colorScheme?: PaletteScheme;
99
+ };
100
+ /**
101
+ * A resolved theme as the three declarations a host's own frame applies.
102
+ *
103
+ * Takes a `ResolvedTheme` and not a `ThemeResolution`, which is the same bargain
104
+ * `themeStyle` makes: there is no fallback theme, so *the tree names no theme* is
105
+ * a case the host has to answer for its own chrome and not one the runtime can
106
+ * answer by handing back a ground. An unthemed excerpt inherits the same nothing
107
+ * an unthemed page does.
108
+ *
109
+ * `undefined` is the other case and a narrower one — a palette whose pair cannot
110
+ * be read. Both ends come from the palette either way, so a frame re-themes with
111
+ * everything else and cannot be legible under one palette and not another.
112
+ */
113
+ export declare const themeGround: (theme: ResolvedTheme) => ThemeGround | undefined;
61
114
  //# sourceMappingURL=theme.d.ts.map
@@ -1,5 +1,6 @@
1
1
  import { THEME_PROP_KEY } from "../reserved-props.js";
2
2
  import { themeVariables } from "../theme/apply.js";
3
+ import { paletteScheme } from "../theme/measure.js";
3
4
  /**
4
5
  * The theme read out of the runtime's own props.
5
6
  *
@@ -48,5 +49,26 @@ export const resolveTheme = (reserved, registry) => {
48
49
  * types-only step, and it happens once here rather than in every primitive that
49
50
  * has to apply it.
50
51
  */
51
- export const themeStyle = (theme) => themeVariables(theme);
52
+ export const themeStyle = (theme, ramp = "fluid") => themeVariables(theme, { ramp });
53
+ /**
54
+ * A resolved theme as the three declarations a host's own frame applies.
55
+ *
56
+ * Takes a `ResolvedTheme` and not a `ThemeResolution`, which is the same bargain
57
+ * `themeStyle` makes: there is no fallback theme, so *the tree names no theme* is
58
+ * a case the host has to answer for its own chrome and not one the runtime can
59
+ * answer by handing back a ground. An unthemed excerpt inherits the same nothing
60
+ * an unthemed page does.
61
+ *
62
+ * `undefined` is the other case and a narrower one — a palette whose pair cannot
63
+ * be read. Both ends come from the palette either way, so a frame re-themes with
64
+ * everything else and cannot be legible under one palette and not another.
65
+ */
66
+ export const themeGround = (theme) => {
67
+ const backgroundColor = theme.palette.slots["bg-canvas"];
68
+ const color = theme.palette.slots["fg-default"];
69
+ if (backgroundColor === undefined || color === undefined)
70
+ return undefined;
71
+ const colorScheme = paletteScheme(theme.palette);
72
+ return { backgroundColor, color, ...(colorScheme === undefined ? {} : { colorScheme }) };
73
+ };
52
74
  //# sourceMappingURL=theme.js.map
@@ -0,0 +1,152 @@
1
+ import type { NodeData } from "../data/resolution.js";
2
+ import type { JsonObject } from "../json.js";
3
+ import type { PrimitiveType } from "../primitive-type.js";
4
+ import { type Result } from "../result.js";
5
+ /**
6
+ * What a primitive could not show of an answer it was given, and how the walk
7
+ * is told.
8
+ *
9
+ * Every other way a binding can be wrong is visible from outside the primitive:
10
+ * an unregistered source is `data-unavailable`, a malformed declaration is
11
+ * `data-misdeclared`, a name nothing reads is `data-unread` (0181). One is not.
12
+ * A source can answer perfectly, under a name the primitive reads, with rows the
13
+ * primitive then declines row by row — because each row has a shape only the
14
+ * primitive knows, and eleven of twelve failing it is the author's problem and
15
+ * nobody else's.
16
+ *
17
+ * `loom.feed` is the case that made this cost something. 0175 says a listing
18
+ * skips the row it cannot read and names it, and the feed does say so — *"Some
19
+ * entries could not be shown."*, drawn on the page, deliberately without a
20
+ * count, because a number there is a plural this library cannot form in every
21
+ * language it may be served in. The count is not useless. It is useful to
22
+ * exactly one person and that person is not the reader: the author whose source
23
+ * started returning a column under a new name wants to know that eleven of
24
+ * twelve rows stopped reading. Every comparable finding in the walk is a
25
+ * diagnostic, and a primitive had no way to raise one.
26
+ *
27
+ * **The primitive returns a reading; the runtime decides whether to report it.**
28
+ * Nothing here hands a component a way to write into the walk's output, and that
29
+ * is the point rather than an omission — see 0206. A component body runs when
30
+ * React renders the element, which is *after* `renderLoomTree` has returned its
31
+ * diagnostics, as many times as React likes and sometimes not at all. A
32
+ * diagnostic pushed from there lands in an array the caller may have read
33
+ * already, twice under `StrictMode`, and never in a medium that renders the
34
+ * element some other way. A declaration the walk *calls* has none of that: once
35
+ * per node, inside the walk, before anybody sees the array.
36
+ */
37
+ /**
38
+ * What a primitive made of one answer: the rows it was given, and the rows it
39
+ * placed.
40
+ *
41
+ * Both numbers rather than the difference, because the sentence the author needs
42
+ * is *eleven of twelve* and a lone `11` cannot say it. Numbers rather than the
43
+ * rows themselves, because a diagnostic is logged and a row is the host's data —
44
+ * the same line `data-unavailable` holds, which names the source and not what it
45
+ * answered.
46
+ *
47
+ * A reading is owed for every answer the primitive read, including the ones it
48
+ * read whole. Whether `shown === given` is worth saying out loud is the walk's
49
+ * call and not the primitive's, the way every other diagnostic in this package
50
+ * is the walk's call.
51
+ */
52
+ export type UnshownReading = {
53
+ /** The binding name the answer arrived under. */
54
+ readonly name: string;
55
+ /** Rows in the answer as the primitive found it. */
56
+ readonly given: number;
57
+ /** Rows the primitive placed on the page. */
58
+ readonly shown: number;
59
+ };
60
+ /**
61
+ * What a primitive declares: its own reading of this node's answers.
62
+ *
63
+ * A function, where every other declaration on a definition is data, and the
64
+ * asymmetry is the honest one. `reads` is a list of *names*, and a name is data
65
+ * — which is why 0184 could give it a `fromProp` form rather than a callback.
66
+ * How many rows survived a schema is not data about a primitive; it is the
67
+ * primitive reading an answer, which is code by nature and is code the primitive
68
+ * already contains, because it had to decide what to skip in order to skip it.
69
+ *
70
+ * It receives exactly what the component receives of the same two things — the
71
+ * node's props as the tree wrote them, and the host's answers — so it can be
72
+ * the same function the component calls, which is the only way the count and the
73
+ * page cannot disagree. It receives nothing it could not already touch: the
74
+ * component is handed both objects too.
75
+ *
76
+ * Called once per node, inside the walk. It must be pure and it must not wait:
77
+ * there is nothing to wait for, every answer having been resolved before the
78
+ * walk began.
79
+ */
80
+ export type UnshownDeclaration = (props: JsonObject, data: NodeData) => readonly UnshownReading[];
81
+ /**
82
+ * Which primitive declares a reading, asked per type.
83
+ *
84
+ * Structural, and detected the way `BindingReader`, `FrameResolver` and
85
+ * `BehaviourResolver` are: a registry built by the SDK satisfies it, and a host
86
+ * resolving from a plain map has registered nothing that could have declared
87
+ * one — so there is nothing here for a host to wire and nothing that can go
88
+ * missing.
89
+ */
90
+ export interface UnshownReader {
91
+ readonly unshownBy: (type: PrimitiveType) => UnshownDeclaration | undefined;
92
+ }
93
+ export declare const isUnshownReader: (value: object) => value is UnshownReader;
94
+ /**
95
+ * Why a declaration's readings could not be believed.
96
+ *
97
+ * Both kinds are faults in the primitive rather than in the tree or the
98
+ * deployment, which is why they are one shape reported to one person: whoever
99
+ * wrote the component. A tree cannot cause either.
100
+ */
101
+ export type UnshownFault = {
102
+ /**
103
+ * The declaration threw. Rendering is total (see `diagnostics.ts`) and a
104
+ * declaration is not a licence to make it otherwise — a page lost to a
105
+ * primitive's *bookkeeping* would be the worst trade in this package.
106
+ */
107
+ readonly kind: "threw";
108
+ readonly detail: string;
109
+ } | {
110
+ /**
111
+ * A reading that cannot describe anything: an unnamed answer, a count that
112
+ * is not a whole number of rows, or more rows shown than given. Refused
113
+ * rather than clamped, because a diagnostic saying *thirteen of twelve*
114
+ * sends the author to look for a defect that is in the primitive telling
115
+ * them about it.
116
+ */
117
+ readonly kind: "impossible";
118
+ readonly detail: string;
119
+ };
120
+ export declare const describeUnshownFault: (fault: UnshownFault) => string;
121
+ /**
122
+ * The readings one declaration makes of this node, or the fault that means there
123
+ * are none to be had.
124
+ *
125
+ * Guarded, because the declaration is another author's code running inside a
126
+ * walk whose whole contract is that it always returns an element. A throw here
127
+ * would take a page down over a count nobody asked to be told, so a throw is
128
+ * caught and becomes the thing it was trying to report.
129
+ *
130
+ * Validated for the same reason, one step further on: a reading that says more
131
+ * rows were shown than arrived is not a small inaccuracy in a diagnostic, it is
132
+ * a diagnostic that sends its reader hunting the wrong defect. The whole batch
133
+ * is refused rather than the bad reading dropped — a declaration that miscounted
134
+ * one answer has not earned belief about the others, and a partial report is
135
+ * indistinguishable from a complete one once it is in a log.
136
+ *
137
+ * A declaration returning something that is not an array at all reaches
138
+ * `impossible` too: the type says otherwise and a host's JavaScript need not
139
+ * agree with it.
140
+ */
141
+ export declare const readUnshown: (declaration: UnshownDeclaration, props: JsonObject, data: NodeData) => Result<readonly UnshownReading[], UnshownFault>;
142
+ /**
143
+ * The readings worth reporting, in the order the walk reports them.
144
+ *
145
+ * An answer the primitive read whole is not a diagnostic — it is the ordinary
146
+ * case, and a walk that reported it would put one line per bound region into
147
+ * every log on every page. Name-sorted for the reason `unreadBindings` sorts:
148
+ * the caller emits one diagnostic per reading, and a list whose order follows a
149
+ * declaration's own array order is one a test can only assert loosely.
150
+ */
151
+ export declare const unshownRows: (readings: readonly UnshownReading[]) => readonly UnshownReading[];
152
+ //# sourceMappingURL=unshown.d.ts.map
@@ -0,0 +1,80 @@
1
+ import { err, ok } from "../result.js";
2
+ export const isUnshownReader = (value) => typeof value.unshownBy === "function";
3
+ export const describeUnshownFault = (fault) => fault.kind === "threw"
4
+ ? `the declaration threw — ${fault.detail}`
5
+ : `the declaration returned a reading that cannot describe an answer — ${fault.detail}`;
6
+ const countable = (value) => Number.isSafeInteger(value) && value >= 0;
7
+ const faultIn = (reading, index) => {
8
+ const at = `reading ${index}`;
9
+ if (typeof reading.name !== "string" || reading.name === "") {
10
+ return `${at} names no binding`;
11
+ }
12
+ if (!countable(reading.given)) {
13
+ return `${at} ("${reading.name}") was given ${String(reading.given)} rows`;
14
+ }
15
+ if (!countable(reading.shown)) {
16
+ return `${at} ("${reading.name}") showed ${String(reading.shown)} rows`;
17
+ }
18
+ if (reading.shown > reading.given) {
19
+ return `${at} ("${reading.name}") showed ${reading.shown} of ${reading.given} rows`;
20
+ }
21
+ return undefined;
22
+ };
23
+ /**
24
+ * The readings one declaration makes of this node, or the fault that means there
25
+ * are none to be had.
26
+ *
27
+ * Guarded, because the declaration is another author's code running inside a
28
+ * walk whose whole contract is that it always returns an element. A throw here
29
+ * would take a page down over a count nobody asked to be told, so a throw is
30
+ * caught and becomes the thing it was trying to report.
31
+ *
32
+ * Validated for the same reason, one step further on: a reading that says more
33
+ * rows were shown than arrived is not a small inaccuracy in a diagnostic, it is
34
+ * a diagnostic that sends its reader hunting the wrong defect. The whole batch
35
+ * is refused rather than the bad reading dropped — a declaration that miscounted
36
+ * one answer has not earned belief about the others, and a partial report is
37
+ * indistinguishable from a complete one once it is in a log.
38
+ *
39
+ * A declaration returning something that is not an array at all reaches
40
+ * `impossible` too: the type says otherwise and a host's JavaScript need not
41
+ * agree with it.
42
+ */
43
+ export const readUnshown = (declaration, props, data) => {
44
+ let readings;
45
+ try {
46
+ readings = declaration(props, data);
47
+ }
48
+ catch (thrown) {
49
+ return err({
50
+ kind: "threw",
51
+ detail: thrown instanceof Error ? thrown.message : String(thrown),
52
+ });
53
+ }
54
+ if (!Array.isArray(readings)) {
55
+ return err({ kind: "impossible", detail: "the declaration returned no readings at all" });
56
+ }
57
+ for (const [index, reading] of readings.entries()) {
58
+ if (typeof reading !== "object" || reading === null) {
59
+ return err({ kind: "impossible", detail: `reading ${index} is not a reading` });
60
+ }
61
+ const fault = faultIn(reading, index);
62
+ if (fault !== undefined)
63
+ return err({ kind: "impossible", detail: fault });
64
+ }
65
+ return ok(readings);
66
+ };
67
+ /**
68
+ * The readings worth reporting, in the order the walk reports them.
69
+ *
70
+ * An answer the primitive read whole is not a diagnostic — it is the ordinary
71
+ * case, and a walk that reported it would put one line per bound region into
72
+ * every log on every page. Name-sorted for the reason `unreadBindings` sorts:
73
+ * the caller emits one diagnostic per reading, and a list whose order follows a
74
+ * declaration's own array order is one a test can only assert loosely.
75
+ */
76
+ export const unshownRows = (readings) => readings
77
+ /** `filter` copies, so the sort below never reaches the declaration's own array. */
78
+ .filter((reading) => reading.shown < reading.given)
79
+ .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
80
+ //# sourceMappingURL=unshown.js.map