@jam-overture/loom 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (401) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +743 -0
  3. package/dist/catalogue.d.ts +70 -0
  4. package/dist/catalogue.js +88 -0
  5. package/dist/cli/args.d.ts +17 -0
  6. package/dist/cli/args.js +83 -0
  7. package/dist/cli/filesystem.d.ts +15 -0
  8. package/dist/cli/filesystem.js +31 -0
  9. package/dist/cli/index.d.ts +12 -0
  10. package/dist/cli/index.js +12 -0
  11. package/dist/cli/main.d.ts +3 -0
  12. package/dist/cli/main.js +30 -0
  13. package/dist/cli/namespace.d.ts +40 -0
  14. package/dist/cli/namespace.js +40 -0
  15. package/dist/cli/plan.d.ts +84 -0
  16. package/dist/cli/plan.js +113 -0
  17. package/dist/cli/run.d.ts +17 -0
  18. package/dist/cli/run.js +75 -0
  19. package/dist/cli/templates.d.ts +43 -0
  20. package/dist/cli/templates.js +134 -0
  21. package/dist/closed-set.d.ts +34 -0
  22. package/dist/closed-set.js +34 -0
  23. package/dist/data/adapter.d.ts +123 -0
  24. package/dist/data/adapter.js +91 -0
  25. package/dist/data/binding.d.ts +48 -0
  26. package/dist/data/binding.js +39 -0
  27. package/dist/data/catalogue.d.ts +26 -0
  28. package/dist/data/catalogue.js +6 -0
  29. package/dist/data/index.d.ts +14 -0
  30. package/dist/data/index.js +14 -0
  31. package/dist/data/plan.d.ts +58 -0
  32. package/dist/data/plan.js +0 -0
  33. package/dist/data/resolution.d.ts +91 -0
  34. package/dist/data/resolution.js +96 -0
  35. package/dist/data/resolve.d.ts +46 -0
  36. package/dist/data/resolve.js +37 -0
  37. package/dist/data/source.d.ts +40 -0
  38. package/dist/data/source.js +45 -0
  39. package/dist/deadline.d.ts +57 -0
  40. package/dist/deadline.js +78 -0
  41. package/dist/frame/catalogue.d.ts +24 -0
  42. package/dist/frame/catalogue.js +5 -0
  43. package/dist/frame/index.d.ts +12 -0
  44. package/dist/frame/index.js +12 -0
  45. package/dist/frame/origin.d.ts +87 -0
  46. package/dist/frame/origin.js +114 -0
  47. package/dist/frame/resolution.d.ts +85 -0
  48. package/dist/frame/resolution.js +79 -0
  49. package/dist/grammar.d.ts +26 -0
  50. package/dist/grammar.js +28 -0
  51. package/dist/ids.d.ts +57 -0
  52. package/dist/ids.js +104 -0
  53. package/dist/index.d.ts +26 -0
  54. package/dist/index.js +26 -0
  55. package/dist/interactivity.d.ts +50 -0
  56. package/dist/interactivity.js +22 -0
  57. package/dist/interpretation/anthropic.d.ts +22 -0
  58. package/dist/interpretation/anthropic.js +76 -0
  59. package/dist/interpretation/client.d.ts +83 -0
  60. package/dist/interpretation/client.js +2 -0
  61. package/dist/interpretation/draft.d.ts +234 -0
  62. package/dist/interpretation/draft.js +84 -0
  63. package/dist/interpretation/index.d.ts +15 -0
  64. package/dist/interpretation/index.js +15 -0
  65. package/dist/interpretation/interpreter.d.ts +62 -0
  66. package/dist/interpretation/interpreter.js +151 -0
  67. package/dist/interpretation/materialize.d.ts +42 -0
  68. package/dist/interpretation/materialize.js +107 -0
  69. package/dist/interpretation/prompt.d.ts +229 -0
  70. package/dist/interpretation/prompt.js +285 -0
  71. package/dist/interpretation/render.d.ts +76 -0
  72. package/dist/interpretation/render.js +272 -0
  73. package/dist/interpretation/schema.d.ts +49 -0
  74. package/dist/interpretation/schema.js +131 -0
  75. package/dist/json.d.ts +35 -0
  76. package/dist/json.js +11 -0
  77. package/dist/paging.d.ts +60 -0
  78. package/dist/paging.js +49 -0
  79. package/dist/primitive-type.d.ts +32 -0
  80. package/dist/primitive-type.js +39 -0
  81. package/dist/render/addressing.d.ts +59 -0
  82. package/dist/render/addressing.js +60 -0
  83. package/dist/render/anchor.d.ts +105 -0
  84. package/dist/render/anchor.js +84 -0
  85. package/dist/render/behaviour-adjust.d.ts +62 -0
  86. package/dist/render/behaviour-adjust.js +78 -0
  87. package/dist/render/behaviour-copy.d.ts +53 -0
  88. package/dist/render/behaviour-copy.js +75 -0
  89. package/dist/render/behaviour-disclose.d.ts +74 -0
  90. package/dist/render/behaviour-disclose.js +77 -0
  91. package/dist/render/behaviour-present.d.ts +123 -0
  92. package/dist/render/behaviour-present.js +173 -0
  93. package/dist/render/behaviour.d.ts +243 -0
  94. package/dist/render/behaviour.js +284 -0
  95. package/dist/render/control.d.ts +81 -0
  96. package/dist/render/control.js +80 -0
  97. package/dist/render/decorative.d.ts +62 -0
  98. package/dist/render/decorative.js +2 -0
  99. package/dist/render/diagnostics.d.ts +260 -0
  100. package/dist/render/diagnostics.js +61 -0
  101. package/dist/render/disclosed.d.ts +37 -0
  102. package/dist/render/disclosed.js +37 -0
  103. package/dist/render/editable.d.ts +34 -0
  104. package/dist/render/editable.js +35 -0
  105. package/dist/render/frame.d.ts +42 -0
  106. package/dist/render/frame.js +31 -0
  107. package/dist/render/index.d.ts +35 -0
  108. package/dist/render/index.js +35 -0
  109. package/dist/render/inline-variables.d.ts +77 -0
  110. package/dist/render/inline-variables.js +220 -0
  111. package/dist/render/presented.d.ts +82 -0
  112. package/dist/render/presented.js +82 -0
  113. package/dist/render/primitive.d.ts +228 -0
  114. package/dist/render/primitive.js +36 -0
  115. package/dist/render/props.d.ts +48 -0
  116. package/dist/render/props.js +2 -0
  117. package/dist/render/reads.d.ts +73 -0
  118. package/dist/render/reads.js +45 -0
  119. package/dist/render/render.d.ts +164 -0
  120. package/dist/render/render.js +571 -0
  121. package/dist/render/request.d.ts +111 -0
  122. package/dist/render/request.js +60 -0
  123. package/dist/render/text.d.ts +91 -0
  124. package/dist/render/text.js +44 -0
  125. package/dist/render/theme.d.ts +61 -0
  126. package/dist/render/theme.js +52 -0
  127. package/dist/reserved-props.d.ts +35 -0
  128. package/dist/reserved-props.js +45 -0
  129. package/dist/result.d.ts +27 -0
  130. package/dist/result.js +30 -0
  131. package/dist/role.d.ts +71 -0
  132. package/dist/role.js +22 -0
  133. package/dist/runtime/analysis.d.ts +149 -0
  134. package/dist/runtime/analysis.js +187 -0
  135. package/dist/runtime/assessment.d.ts +35 -0
  136. package/dist/runtime/assessment.js +13 -0
  137. package/dist/runtime/disposition.d.ts +102 -0
  138. package/dist/runtime/disposition.js +59 -0
  139. package/dist/runtime/events.d.ts +187 -0
  140. package/dist/runtime/events.js +7 -0
  141. package/dist/runtime/gate.d.ts +43 -0
  142. package/dist/runtime/gate.js +169 -0
  143. package/dist/runtime/index.d.ts +27 -0
  144. package/dist/runtime/index.js +27 -0
  145. package/dist/runtime/intent.d.ts +60 -0
  146. package/dist/runtime/intent.js +36 -0
  147. package/dist/runtime/interpreter.d.ts +117 -0
  148. package/dist/runtime/interpreter.js +46 -0
  149. package/dist/runtime/inverse-interpreter.d.ts +90 -0
  150. package/dist/runtime/inverse-interpreter.js +56 -0
  151. package/dist/runtime/inverse.d.ts +87 -0
  152. package/dist/runtime/inverse.js +48 -0
  153. package/dist/runtime/narration.d.ts +24 -0
  154. package/dist/runtime/narration.js +36 -0
  155. package/dist/runtime/nesting.d.ts +31 -0
  156. package/dist/runtime/nesting.js +46 -0
  157. package/dist/runtime/pipeline.d.ts +124 -0
  158. package/dist/runtime/pipeline.js +178 -0
  159. package/dist/runtime/policy-fingerprint.d.ts +29 -0
  160. package/dist/runtime/policy-fingerprint.js +119 -0
  161. package/dist/runtime/policy-source.d.ts +42 -0
  162. package/dist/runtime/policy-source.js +8 -0
  163. package/dist/runtime/policy.d.ts +156 -0
  164. package/dist/runtime/policy.js +107 -0
  165. package/dist/runtime/proposal.d.ts +423 -0
  166. package/dist/runtime/proposal.js +109 -0
  167. package/dist/runtime/redirection.d.ts +53 -0
  168. package/dist/runtime/redirection.js +38 -0
  169. package/dist/runtime/repointing.d.ts +71 -0
  170. package/dist/runtime/repointing.js +0 -0
  171. package/dist/runtime/reversibility.d.ts +36 -0
  172. package/dist/runtime/reversibility.js +39 -0
  173. package/dist/runtime/stake-level.d.ts +33 -0
  174. package/dist/runtime/stake-level.js +58 -0
  175. package/dist/runtime/stakes.d.ts +47 -0
  176. package/dist/runtime/stakes.js +305 -0
  177. package/dist/runtime/vocabulary.d.ts +122 -0
  178. package/dist/runtime/vocabulary.js +87 -0
  179. package/dist/sdk/audit.d.ts +195 -0
  180. package/dist/sdk/audit.js +128 -0
  181. package/dist/sdk/catalogue.d.ts +37 -0
  182. package/dist/sdk/catalogue.js +16 -0
  183. package/dist/sdk/conformance.d.ts +342 -0
  184. package/dist/sdk/conformance.js +494 -0
  185. package/dist/sdk/copy.d.ts +105 -0
  186. package/dist/sdk/copy.js +90 -0
  187. package/dist/sdk/definition.d.ts +242 -0
  188. package/dist/sdk/definition.js +64 -0
  189. package/dist/sdk/index.d.ts +19 -0
  190. package/dist/sdk/index.js +19 -0
  191. package/dist/sdk/interactivity.d.ts +29 -0
  192. package/dist/sdk/interactivity.js +34 -0
  193. package/dist/sdk/pairings.d.ts +124 -0
  194. package/dist/sdk/pairings.js +81 -0
  195. package/dist/sdk/registry.d.ts +162 -0
  196. package/dist/sdk/registry.js +329 -0
  197. package/dist/sdk/selection.d.ts +46 -0
  198. package/dist/sdk/selection.js +24 -0
  199. package/dist/sdk/text.d.ts +100 -0
  200. package/dist/sdk/text.js +105 -0
  201. package/dist/sdk/vocabulary.d.ts +39 -0
  202. package/dist/sdk/vocabulary.js +36 -0
  203. package/dist/signals/broadcast.d.ts +134 -0
  204. package/dist/signals/broadcast.js +451 -0
  205. package/dist/signals/collect.d.ts +184 -0
  206. package/dist/signals/collect.js +196 -0
  207. package/dist/signals/deliver.d.ts +64 -0
  208. package/dist/signals/deliver.js +85 -0
  209. package/dist/signals/fold.d.ts +112 -0
  210. package/dist/signals/fold.js +76 -0
  211. package/dist/signals/index.d.ts +31 -0
  212. package/dist/signals/index.js +31 -0
  213. package/dist/signals/ingest.d.ts +51 -0
  214. package/dist/signals/ingest.js +70 -0
  215. package/dist/signals/intake.d.ts +149 -0
  216. package/dist/signals/intake.js +154 -0
  217. package/dist/signals/journal.d.ts +94 -0
  218. package/dist/signals/journal.js +11 -0
  219. package/dist/signals/kinds.d.ts +22 -0
  220. package/dist/signals/kinds.js +22 -0
  221. package/dist/signals/ledger.d.ts +46 -0
  222. package/dist/signals/ledger.js +81 -0
  223. package/dist/signals/memory.d.ts +17 -0
  224. package/dist/signals/memory.js +99 -0
  225. package/dist/signals/migrate.d.ts +27 -0
  226. package/dist/signals/migrate.js +78 -0
  227. package/dist/signals/postgres.d.ts +7 -0
  228. package/dist/signals/postgres.js +295 -0
  229. package/dist/signals/rollup.d.ts +142 -0
  230. package/dist/signals/rollup.js +0 -0
  231. package/dist/signals/schema.d.ts +534 -0
  232. package/dist/signals/schema.js +92 -0
  233. package/dist/signals/signal.d.ts +381 -0
  234. package/dist/signals/signal.js +150 -0
  235. package/dist/signals/tally.d.ts +70 -0
  236. package/dist/signals/tally.js +2 -0
  237. package/dist/signals/view.d.ts +51 -0
  238. package/dist/signals/view.js +54 -0
  239. package/dist/store/attribution.d.ts +125 -0
  240. package/dist/store/attribution.js +116 -0
  241. package/dist/store/database.d.ts +14 -0
  242. package/dist/store/database.js +2 -0
  243. package/dist/store/driver.d.ts +29 -0
  244. package/dist/store/driver.js +39 -0
  245. package/dist/store/errors.d.ts +56 -0
  246. package/dist/store/errors.js +37 -0
  247. package/dist/store/index.d.ts +16 -0
  248. package/dist/store/index.js +16 -0
  249. package/dist/store/memory.d.ts +3 -0
  250. package/dist/store/memory.js +115 -0
  251. package/dist/store/migrate.d.ts +54 -0
  252. package/dist/store/migrate.js +122 -0
  253. package/dist/store/postgres-holds.d.ts +4 -0
  254. package/dist/store/postgres-holds.js +192 -0
  255. package/dist/store/postgres.d.ts +8 -0
  256. package/dist/store/postgres.js +262 -0
  257. package/dist/store/replay.d.ts +94 -0
  258. package/dist/store/replay.js +82 -0
  259. package/dist/store/revert.d.ts +116 -0
  260. package/dist/store/revert.js +243 -0
  261. package/dist/store/schema.d.ts +371 -0
  262. package/dist/store/schema.js +78 -0
  263. package/dist/store/source.d.ts +23 -0
  264. package/dist/store/source.js +37 -0
  265. package/dist/store/store.d.ts +231 -0
  266. package/dist/store/store.js +52 -0
  267. package/dist/store/undone.d.ts +18 -0
  268. package/dist/store/undone.js +89 -0
  269. package/dist/submit/catalogue.d.ts +20 -0
  270. package/dist/submit/catalogue.js +5 -0
  271. package/dist/submit/declaration.d.ts +39 -0
  272. package/dist/submit/declaration.js +30 -0
  273. package/dist/submit/endpoint.d.ts +131 -0
  274. package/dist/submit/endpoint.js +160 -0
  275. package/dist/submit/index.d.ts +13 -0
  276. package/dist/submit/index.js +13 -0
  277. package/dist/submit/plan.d.ts +49 -0
  278. package/dist/submit/plan.js +47 -0
  279. package/dist/submit/resolution.d.ts +61 -0
  280. package/dist/submit/resolution.js +64 -0
  281. package/dist/submit/resolve.d.ts +45 -0
  282. package/dist/submit/resolve.js +36 -0
  283. package/dist/telemetry/calibration.d.ts +132 -0
  284. package/dist/telemetry/calibration.js +151 -0
  285. package/dist/telemetry/episode.d.ts +140 -0
  286. package/dist/telemetry/episode.js +272 -0
  287. package/dist/telemetry/event.d.ts +2310 -0
  288. package/dist/telemetry/event.js +405 -0
  289. package/dist/telemetry/index.d.ts +15 -0
  290. package/dist/telemetry/index.js +15 -0
  291. package/dist/telemetry/journal.d.ts +116 -0
  292. package/dist/telemetry/journal.js +11 -0
  293. package/dist/telemetry/memory.d.ts +24 -0
  294. package/dist/telemetry/memory.js +75 -0
  295. package/dist/telemetry/migrate.d.ts +26 -0
  296. package/dist/telemetry/migrate.js +40 -0
  297. package/dist/telemetry/postgres.d.ts +6 -0
  298. package/dist/telemetry/postgres.js +139 -0
  299. package/dist/telemetry/retention.d.ts +131 -0
  300. package/dist/telemetry/retention.js +217 -0
  301. package/dist/telemetry/schema.d.ts +113 -0
  302. package/dist/telemetry/schema.js +33 -0
  303. package/dist/telemetry/sink.d.ts +42 -0
  304. package/dist/telemetry/sink.js +61 -0
  305. package/dist/testing/contracts.d.ts +34 -0
  306. package/dist/testing/contracts.js +34 -0
  307. package/dist/testing/definitions.d.ts +15 -0
  308. package/dist/testing/definitions.js +48 -0
  309. package/dist/testing/doubles.d.ts +94 -0
  310. package/dist/testing/doubles.js +141 -0
  311. package/dist/testing/episode-harness.d.ts +49 -0
  312. package/dist/testing/episode-harness.js +65 -0
  313. package/dist/testing/filesystem.d.ts +17 -0
  314. package/dist/testing/filesystem.js +17 -0
  315. package/dist/testing/fixtures.d.ts +57 -0
  316. package/dist/testing/fixtures.js +84 -0
  317. package/dist/testing/hold-contract.d.ts +19 -0
  318. package/dist/testing/hold-contract.js +374 -0
  319. package/dist/testing/index.d.ts +41 -0
  320. package/dist/testing/index.js +41 -0
  321. package/dist/testing/journal-contract.d.ts +17 -0
  322. package/dist/testing/journal-contract.js +353 -0
  323. package/dist/testing/model-replies.d.ts +34 -0
  324. package/dist/testing/model-replies.js +101 -0
  325. package/dist/testing/primitives.d.ts +7 -0
  326. package/dist/testing/primitives.js +29 -0
  327. package/dist/testing/reader-signal-contract.d.ts +38 -0
  328. package/dist/testing/reader-signal-contract.js +318 -0
  329. package/dist/testing/row-security.d.ts +17 -0
  330. package/dist/testing/row-security.js +21 -0
  331. package/dist/testing/store-contract.d.ts +25 -0
  332. package/dist/testing/store-contract.js +500 -0
  333. package/dist/theme/apply.d.ts +17 -0
  334. package/dist/theme/apply.js +60 -0
  335. package/dist/theme/contrast.d.ts +197 -0
  336. package/dist/theme/contrast.js +259 -0
  337. package/dist/theme/derive.d.ts +77 -0
  338. package/dist/theme/derive.js +167 -0
  339. package/dist/theme/faces.d.ts +73 -0
  340. package/dist/theme/faces.js +119 -0
  341. package/dist/theme/font-packs.d.ts +25 -0
  342. package/dist/theme/font-packs.js +257 -0
  343. package/dist/theme/index.d.ts +20 -0
  344. package/dist/theme/index.js +20 -0
  345. package/dist/theme/lab.d.ts +30 -0
  346. package/dist/theme/lab.js +46 -0
  347. package/dist/theme/library.d.ts +114 -0
  348. package/dist/theme/library.js +300 -0
  349. package/dist/theme/measure.d.ts +144 -0
  350. package/dist/theme/measure.js +145 -0
  351. package/dist/theme/palettes.d.ts +64 -0
  352. package/dist/theme/palettes.js +497 -0
  353. package/dist/theme/registry.d.ts +59 -0
  354. package/dist/theme/registry.js +60 -0
  355. package/dist/theme/separation.d.ts +177 -0
  356. package/dist/theme/separation.js +203 -0
  357. package/dist/theme/style-presets.d.ts +60 -0
  358. package/dist/theme/style-presets.js +124 -0
  359. package/dist/theme/theme.d.ts +253 -0
  360. package/dist/theme/theme.js +171 -0
  361. package/dist/tree/apply.d.ts +16 -0
  362. package/dist/tree/apply.js +104 -0
  363. package/dist/tree/builders.d.ts +19 -0
  364. package/dist/tree/builders.js +20 -0
  365. package/dist/tree/compare.d.ts +68 -0
  366. package/dist/tree/compare.js +75 -0
  367. package/dist/tree/configuration.d.ts +25 -0
  368. package/dist/tree/configuration.js +108 -0
  369. package/dist/tree/delta.d.ts +288 -0
  370. package/dist/tree/delta.js +88 -0
  371. package/dist/tree/errors.d.ts +69 -0
  372. package/dist/tree/errors.js +34 -0
  373. package/dist/tree/identity.d.ts +117 -0
  374. package/dist/tree/identity.js +145 -0
  375. package/dist/tree/index.d.ts +21 -0
  376. package/dist/tree/index.js +21 -0
  377. package/dist/tree/inverse.d.ts +24 -0
  378. package/dist/tree/inverse.js +112 -0
  379. package/dist/tree/mutation.d.ts +18 -0
  380. package/dist/tree/mutation.js +49 -0
  381. package/dist/tree/naming.d.ts +4 -0
  382. package/dist/tree/naming.js +35 -0
  383. package/dist/tree/navigation.d.ts +38 -0
  384. package/dist/tree/navigation.js +83 -0
  385. package/dist/tree/node.d.ts +103 -0
  386. package/dist/tree/node.js +46 -0
  387. package/dist/tree/outline.d.ts +28 -0
  388. package/dist/tree/outline.js +10 -0
  389. package/dist/tree/tree.d.ts +83 -0
  390. package/dist/tree/tree.js +62 -0
  391. package/dist/write/commit.d.ts +124 -0
  392. package/dist/write/commit.js +234 -0
  393. package/dist/write/held.d.ts +674 -0
  394. package/dist/write/held.js +185 -0
  395. package/dist/write/index.d.ts +11 -0
  396. package/dist/write/index.js +11 -0
  397. package/dist/write/liveness.d.ts +132 -0
  398. package/dist/write/liveness.js +91 -0
  399. package/dist/write/revert.d.ts +79 -0
  400. package/dist/write/revert.js +134 -0
  401. package/package.json +160 -0
@@ -0,0 +1,494 @@
1
+ import { isValidElement } from "react";
2
+ import { NO_DATA } from "../data/resolution.js";
3
+ import { NO_FRAMES } from "../frame/resolution.js";
4
+ import { frameOriginSchema } from "../frame/origin.js";
5
+ import { nodeIdSchema } from "../ids.js";
6
+ import { primitiveTypeSchema } from "../primitive-type.js";
7
+ import { LOOM_NODE_ATTRIBUTE, LOOM_TYPE_ATTRIBUTE } from "../render/editable.js";
8
+ import { NO_BEHAVIOURS } from "../render/behaviour.js";
9
+ import { asCallablePrimitive, NO_SLOTS, } from "../render/primitive.js";
10
+ import { NO_TEXT } from "../render/text.js";
11
+ import { err, ok } from "../result.js";
12
+ import { paletteSlotSchema } from "../theme/theme.js";
13
+ const notCallable = (reason) => ({
14
+ outcome: "not-probeable",
15
+ cause: "not-callable",
16
+ reason,
17
+ failures: [],
18
+ });
19
+ /**
20
+ * Named rather than counted. Whoever reads this has to reproduce it, and
21
+ * `{"type":"select"}` is the whole reproduction.
22
+ */
23
+ export const describeProbeFailures = (failures) => failures
24
+ .map((failure) => {
25
+ const answering = failure.answered && failure.answered.length > 0
26
+ ? ` answering ${failure.answered.join(", ")}`
27
+ : "";
28
+ return `${JSON.stringify(failure.props)}${answering} (${failure.reason})`;
29
+ })
30
+ .join(", ");
31
+ const threwThroughout = (failures) => ({
32
+ outcome: "not-probeable",
33
+ cause: "threw",
34
+ reason: failures.length === 0
35
+ ? "no configuration answered"
36
+ : `threw under every configuration probed: ${describeProbeFailures(failures)}`,
37
+ failures,
38
+ });
39
+ const PROBE_NODE_ID = nodeIdSchema.parse("n_probe");
40
+ const PROBE_TYPE = primitiveTypeSchema.parse("loom.probe");
41
+ const PROBE_CHILDREN = "loom-probe-children";
42
+ /**
43
+ * A probe has no tree, so there is nothing for `loom.decorative()` to render
44
+ * again; it answers with a marker instead.
45
+ *
46
+ * A *distinct* marker, deliberately. A primitive that placed only the
47
+ * decorative copy would render its whole content unaddressable, and if the copy
48
+ * answered with `PROBE_CHILDREN` the placement probe would call that primitive
49
+ * one that renders its children.
50
+ */
51
+ const PROBE_DECORATIVE = () => "loom-probe-decorative";
52
+ /**
53
+ * A probe is handed the primitive's own declared strings rather than an empty
54
+ * map. A component that reads `loom.text.excluded` and formats it would throw on
55
+ * `undefined` and read as `not-probeable` — a false negative produced entirely
56
+ * by the probe, for a primitive that is correct.
57
+ */
58
+ const probeProps = (editable, text, configuration, frames = NO_FRAMES) => ({
59
+ loom: {
60
+ nodeId: PROBE_NODE_ID,
61
+ type: PROBE_TYPE,
62
+ editable,
63
+ slots: NO_SLOTS,
64
+ data: configuration.data,
65
+ frames,
66
+ text,
67
+ behaviours: NO_BEHAVIOURS,
68
+ decorative: PROBE_DECORATIVE,
69
+ },
70
+ props: configuration.props,
71
+ children: PROBE_CHILDREN,
72
+ });
73
+ /** Props with nothing answered beside them, which is most configurations (0185). */
74
+ export const unasked = (props) => ({ props, data: NO_DATA });
75
+ const namesIn = (data) => {
76
+ const names = [];
77
+ for (const name in data)
78
+ names.push(name);
79
+ return names.sort();
80
+ };
81
+ /**
82
+ * The prop configurations a primitive is probed under (0075).
83
+ *
84
+ * The default configuration first, then each closed choice's values one at a
85
+ * time with everything else left alone. The **sum** of the choices rather than
86
+ * their product: a schema with six enums of eight members is forty-eight
87
+ * renders this way and two hundred and sixty thousand the other, and the cost
88
+ * of the cheap answer is that a primitive which places children only under two
89
+ * particular values together is not found. Nothing in the library is shaped
90
+ * that way, and a primitive that were would be one nobody can read.
91
+ */
92
+ export const probeConfigurations = (choices) => [
93
+ {},
94
+ ...choices.flatMap(({ name, options }) => options.map((option) => ({ [name]: option }))),
95
+ ];
96
+ /**
97
+ * The states a primitive is probed in: what its schema closes over, then what
98
+ * its registrant declared it can be answered with (0185).
99
+ *
100
+ * Two functions rather than one, and the split is the argument. What a schema
101
+ * closes over is **derived** — `probeConfigurations` reads it off the
102
+ * registration and cannot be wrong about it. What a bound primitive can be
103
+ * answered with is **supplied**, because nothing here knows it. Folding the
104
+ * second into the first would put a caller's declaration and a machine's
105
+ * enumeration behind one name, and the day they disagree is the day nobody can
106
+ * tell which half was wrong.
107
+ *
108
+ * The answers are summed in rather than crossed with every prop value, for the
109
+ * reason 0075 sums the choices, and it costs less here: what a bound primitive
110
+ * draws turns on the *answer*, and the state a caller has to reach to find an
111
+ * unplaced region is the answer under the props that name it — which is why an
112
+ * answer carries its own optional props.
113
+ */
114
+ export const probeStates = (configurations, answers = []) => [
115
+ ...configurations.map(unasked),
116
+ ...answers.map((answer) => ({ props: answer.props ?? {}, data: answer.data })),
117
+ ];
118
+ const DEFAULT_CONFIGURATIONS = [unasked({})];
119
+ /**
120
+ * A probe has no allowlist, so a declared framable prop is answered `allowed`
121
+ * against an origin that does not exist.
122
+ *
123
+ * `allowed` rather than `refused`, deliberately, and it is the same choice
124
+ * `PROBE_DECORATIVE` makes for the opposite reason. A primitive that declares a
125
+ * frame renders a refusal when it is told no — that is the whole point of the
126
+ * seam — and a probe that always said no would be probing every embed's error
127
+ * state and calling it the primitive. The URL is a marker origin nobody can
128
+ * register, so one that escapes into real markup is recognisable on sight
129
+ * rather than being a plausible-looking video that silently never loads.
130
+ */
131
+ const PROBE_FRAME_ORIGIN = frameOriginSchema.parse("https://probe.loom.invalid");
132
+ const probeFrames = (declared) => {
133
+ if (declared.length === 0)
134
+ return NO_FRAMES;
135
+ const frames = Object.create(null);
136
+ for (const prop of declared) {
137
+ frames[prop] = {
138
+ status: "allowed",
139
+ url: `${PROBE_FRAME_ORIGIN}/${prop}`,
140
+ origin: PROBE_FRAME_ORIGIN,
141
+ sameOrigin: false,
142
+ };
143
+ }
144
+ return Object.freeze(frames);
145
+ };
146
+ /** The marker handed to a declared slot, unique per name so a miss names itself. */
147
+ const slotMarker = (name) => `loom-probe-slot:${name}`;
148
+ /** The same, for a declared behaviour's control. */
149
+ const behaviourMarker = (name) => `loom-probe-behaviour:${name}`;
150
+ /** Whether this element, or anything it returned, carries the probe's decoration. */
151
+ const carriesDecoration = (node, editable) => {
152
+ if (Array.isArray(node))
153
+ return node.some((child) => carriesDecoration(child, editable));
154
+ if (!isValidElement(node))
155
+ return false;
156
+ const props = node.props;
157
+ for (const [key, value] of Object.entries(props)) {
158
+ if (key === LOOM_NODE_ATTRIBUTE && value === PROBE_NODE_ID)
159
+ return true;
160
+ /**
161
+ * A primitive that hands `loom` or `loom.editable` to another component is
162
+ * decorating too — it has delegated its root, and the attributes will reach
163
+ * the DOM through whatever it delegated to. Identity is the test, since a
164
+ * rebuilt object cannot be told apart from an unrelated one.
165
+ */
166
+ if (value === editable)
167
+ return true;
168
+ if (typeof value === "object" && value !== null && "editable" in value && value.editable === editable) {
169
+ return true;
170
+ }
171
+ }
172
+ return carriesDecoration(props["children"], editable);
173
+ };
174
+ const asProbeable = asCallablePrimitive;
175
+ /** Calls a probeable component, turning whatever it throws into a reason. */
176
+ const call = (probeable, props) => {
177
+ try {
178
+ return ok(probeable(props));
179
+ }
180
+ catch (thrown) {
181
+ return err(thrown instanceof Error ? thrown.message : String(thrown));
182
+ }
183
+ };
184
+ const failureOf = (configuration, reason) => {
185
+ const answered = namesIn(configuration.data);
186
+ return answered.length === 0
187
+ ? { props: configuration.props, reason }
188
+ : { props: configuration.props, reason, answered };
189
+ };
190
+ const failuresIn = (attempts) => attempts.flatMap((attempt) => attempt.result.ok ? [] : [failureOf(attempt.configuration, attempt.result.error)]);
191
+ /**
192
+ * Decoration is a promise that holds however the primitive is configured, so
193
+ * one configuration that fails to decorate makes the answer `not-decorated`
194
+ * even if the rest pass. A configuration that throws answers nothing either
195
+ * way and is skipped; when none of them answer, every failure is carried on the
196
+ * verdict, so the reason the probe declined is a value rather than the prose of
197
+ * whichever configuration happened to be first.
198
+ */
199
+ export const probeEditableDecoration = (primitive, text = NO_TEXT, configurations = DEFAULT_CONFIGURATIONS, declaredFrames = []) => {
200
+ const probeable = asProbeable(primitive);
201
+ if (!probeable.ok)
202
+ return notCallable(probeable.error);
203
+ const editable = {
204
+ [LOOM_NODE_ATTRIBUTE]: PROBE_NODE_ID,
205
+ [LOOM_TYPE_ATTRIBUTE]: PROBE_TYPE,
206
+ };
207
+ const attempts = configurations.map((configuration) => ({
208
+ configuration,
209
+ result: call(probeable.value, probeProps(editable, text, configuration, probeFrames(declaredFrames))),
210
+ }));
211
+ const answered = attempts.flatMap((attempt) => (attempt.result.ok ? [attempt.result.value] : []));
212
+ if (answered.length === 0)
213
+ return threwThroughout(failuresIn(attempts));
214
+ return answered.every((node) => carriesDecoration(node, editable))
215
+ ? { outcome: "decorates" }
216
+ : { outcome: "not-decorated" };
217
+ };
218
+ /**
219
+ * Whether the marker string appears anywhere in what the component returned.
220
+ *
221
+ * Every prop is searched, not only `children`: a primitive that hands a region
222
+ * to another component as `header={loom.slots.header}` has placed it, and the
223
+ * probe should not call that a drop because the content left through a prop it
224
+ * did not expect.
225
+ */
226
+ const containsMarker = (node, marker) => {
227
+ if (node === marker)
228
+ return true;
229
+ if (Array.isArray(node))
230
+ return node.some((child) => containsMarker(child, marker));
231
+ if (!isValidElement(node))
232
+ return false;
233
+ return Object.values(node.props).some((value) => containsMarker(value, marker));
234
+ };
235
+ export const probePlacement = (primitive, declaredSlots, text = NO_TEXT, configurations = DEFAULT_CONFIGURATIONS, declaredBehaviours = [], declaredFrames = []) => {
236
+ const probeable = asProbeable(primitive);
237
+ if (!probeable.ok)
238
+ return notCallable(probeable.error);
239
+ const slots = Object.create(null);
240
+ for (const name of declaredSlots)
241
+ slots[name] = slotMarker(name);
242
+ const behaviours = Object.create(null);
243
+ for (const name of declaredBehaviours)
244
+ behaviours[name] = behaviourMarker(name);
245
+ const attempts = configurations.map((configuration) => ({
246
+ configuration,
247
+ result: call(probeable.value, {
248
+ loom: {
249
+ nodeId: PROBE_NODE_ID,
250
+ type: PROBE_TYPE,
251
+ slots,
252
+ data: configuration.data,
253
+ frames: probeFrames(declaredFrames),
254
+ text,
255
+ behaviours: behaviours,
256
+ decorative: PROBE_DECORATIVE,
257
+ },
258
+ props: configuration.props,
259
+ children: PROBE_CHILDREN,
260
+ }),
261
+ }));
262
+ const answered = attempts.flatMap((attempt) => (attempt.result.ok ? [attempt] : []));
263
+ if (answered.length === 0)
264
+ return threwThroughout(failuresIn(attempts));
265
+ const placed = (marker) => answered.some((attempt) => attempt.result.ok && containsMarker(attempt.result.value, marker));
266
+ return {
267
+ outcome: "probed",
268
+ unplacedSlots: declaredSlots.filter((name) => !placed(slotMarker(name))),
269
+ unplacedBehaviours: declaredBehaviours.filter((name) => !placed(behaviourMarker(name))),
270
+ rendersChildren: placed(PROBE_CHILDREN),
271
+ probed: answered.map((attempt) => attempt.configuration),
272
+ threw: failuresIn(attempts),
273
+ };
274
+ };
275
+ /**
276
+ * Absolute rather than root-relative, and on a hostname that cannot resolve.
277
+ * `endpoint.ts` accepts both shapes, so either would be a legal target; this one
278
+ * is additionally impossible to confuse with a path a primitive computed for
279
+ * itself, which is what makes finding it in the output evidence rather than
280
+ * coincidence.
281
+ */
282
+ const PROBE_SUBMIT_ACTION = "https://probe.invalid/loom-probe-submit";
283
+ const PROBE_SUBMISSION = {
284
+ status: "ready",
285
+ target: { action: PROBE_SUBMIT_ACTION, method: "post", fields: [] },
286
+ };
287
+ /**
288
+ * `some` rather than `every`, matching `probePlacement`. The question is
289
+ * whether this primitive posts at all, and a primitive that renders a form
290
+ * under one layout and a summary under another is answering honestly in both.
291
+ */
292
+ export const probeSubmissionPlacement = (primitive, text = NO_TEXT, configurations = DEFAULT_CONFIGURATIONS, declaredFrames = []) => {
293
+ const probeable = asProbeable(primitive);
294
+ if (!probeable.ok)
295
+ return notCallable(probeable.error);
296
+ const attempts = configurations.map((configuration) => ({
297
+ configuration,
298
+ result: call(probeable.value, {
299
+ loom: {
300
+ nodeId: PROBE_NODE_ID,
301
+ type: PROBE_TYPE,
302
+ slots: NO_SLOTS,
303
+ data: configuration.data,
304
+ frames: probeFrames(declaredFrames),
305
+ text,
306
+ behaviours: NO_BEHAVIOURS,
307
+ submit: PROBE_SUBMISSION,
308
+ decorative: PROBE_DECORATIVE,
309
+ },
310
+ props: configuration.props,
311
+ children: PROBE_CHILDREN,
312
+ }),
313
+ }));
314
+ const answered = attempts.flatMap((attempt) => (attempt.result.ok ? [attempt.result.value] : []));
315
+ if (answered.length === 0)
316
+ return threwThroughout(failuresIn(attempts));
317
+ return answered.some((node) => containsMarker(node, PROBE_SUBMIT_ACTION))
318
+ ? { outcome: "places" }
319
+ : { outcome: "not-placed" };
320
+ };
321
+ /** `colour()` emits `var(--loom-<slot>)` and nothing else does. */
322
+ const SLOT_VARIABLE = /^var\(--loom-([a-z-]+)\)$/;
323
+ const slotOf = (value) => {
324
+ if (typeof value !== "string")
325
+ return undefined;
326
+ const named = SLOT_VARIABLE.exec(value)?.[1];
327
+ const parsed = named === undefined ? undefined : paletteSlotSchema.safeParse(named);
328
+ return parsed?.success === true ? parsed.data : undefined;
329
+ };
330
+ const groundOf = (style) => slotOf(style["background"]) ?? slotOf(style["backgroundColor"]);
331
+ const NOTHING_IN_EFFECT = { ground: undefined, ink: undefined };
332
+ const styleOf = (node) => {
333
+ const style = node.props["style"];
334
+ return typeof style === "object" && style !== null ? style : undefined;
335
+ };
336
+ /**
337
+ * React hands children as arbitrarily nested arrays; a stack is over one list of
338
+ * them. `null`, `undefined` and a boolean render nothing at all, and an element
339
+ * whose children are only those is as empty as one with none — which is the
340
+ * difference between a panel and a painted dot, so they are dropped here rather
341
+ * than counted.
342
+ */
343
+ const flatten = (node) => Array.isArray(node)
344
+ ? node.flatMap(flatten)
345
+ : node === null || node === undefined || typeof node === "boolean" || node === ""
346
+ ? []
347
+ : [node];
348
+ const gridAreaOf = (style) => {
349
+ const area = style?.["gridArea"];
350
+ return typeof area === "string" ? area : undefined;
351
+ };
352
+ /**
353
+ * `z-index: auto` and `z-index: 0` paint in the same order as each other, and
354
+ * source order breaks the tie in both cases — which is what the fallback to the
355
+ * element's position in the list is.
356
+ *
357
+ * React takes the property as a number or as a string, and `"2"` is the same
358
+ * layer as `2`; anything else is `auto` by another name.
359
+ */
360
+ const depthOf = (style) => {
361
+ const depth = style?.["zIndex"];
362
+ if (typeof depth === "number")
363
+ return depth;
364
+ if (typeof depth !== "string")
365
+ return 0;
366
+ const parsed = Number(depth.trim());
367
+ return Number.isFinite(parsed) ? parsed : 0;
368
+ };
369
+ /**
370
+ * For each sibling that shares a grid cell with another, the ground painted by
371
+ * the nearest one stacked beneath it.
372
+ *
373
+ * *Nearest* rather than *any*: a scrim over a photograph over a card is three
374
+ * layers, and what the words on top actually sit on is the scrim. Taking the
375
+ * bottom of the stack would name a ground the reader never sees through.
376
+ */
377
+ const stackedGrounds = (siblings) => {
378
+ const members = siblings.flatMap((node, order) => {
379
+ if (!isValidElement(node))
380
+ return [];
381
+ const style = styleOf(node);
382
+ const area = gridAreaOf(style);
383
+ return area === undefined
384
+ ? []
385
+ : [{ node: node, area, order, depth: depthOf(style), ground: style === undefined ? undefined : groundOf(style) }];
386
+ });
387
+ const under = new Map();
388
+ for (const cell of new Set(members.map((member) => member.area))) {
389
+ const stack = members
390
+ .filter((member) => member.area === cell)
391
+ .sort((a, b) => a.depth - b.depth || a.order - b.order);
392
+ for (const [index, member] of stack.entries()) {
393
+ for (let below = index - 1; below >= 0; below -= 1) {
394
+ const ground = stack[below]?.ground;
395
+ if (ground !== undefined) {
396
+ under.set(member.node, ground);
397
+ break;
398
+ }
399
+ }
400
+ }
401
+ }
402
+ return under;
403
+ };
404
+ const collectPaint = (node, effective, stacked, markers, into) => {
405
+ if (typeof node === "string") {
406
+ if (markers.has(node) && effective.ground !== undefined)
407
+ into.childGrounds.push(effective.ground);
408
+ return;
409
+ }
410
+ if (!isValidElement(node))
411
+ return;
412
+ const own = styleOf(node);
413
+ const painted = own === undefined ? undefined : groundOf(own);
414
+ const declared = own === undefined ? undefined : slotOf(own["color"]);
415
+ const ground = painted ?? stacked ?? effective.ground;
416
+ const ink = declared ?? effective.ink;
417
+ const children = flatten(node.props["children"]);
418
+ /**
419
+ * Either half arriving under the other makes the pair, which is why an ink
420
+ * declared here and a ground introduced here are both triggers. An element
421
+ * that changes neither repeats its parent's pairing and is not recorded
422
+ * again.
423
+ *
424
+ * **A ground only answers for an inherited ink if something can be written on
425
+ * it.** `loom.frame` draws its camera notch as an empty `span` filled with
426
+ * `fg-default`, and `loom.message` its typing dots with `fg-muted`: an ink
427
+ * slot used as a shape, inside a card that set `fg-default` above it. Counting
428
+ * those gave `fg-muted on fg-muted` — 1.00:1 in every palette ever written,
429
+ * for a pair no reader will ever meet, which is precisely the row
430
+ * `PALETTE_TEXT_PAIRINGS` refuses to carry. An element with no children is a
431
+ * shape and not a surface. An ink *declared* here is recorded either way,
432
+ * because that is the claim the component itself made.
433
+ */
434
+ const surface = declared !== undefined || children.length > 0;
435
+ if (ink !== undefined && ground !== undefined && surface && (declared !== undefined || ground !== effective.ground)) {
436
+ into.painted.push({ foreground: ink, background: ground });
437
+ }
438
+ if (declared !== undefined && ground === undefined)
439
+ into.floating.push(declared);
440
+ collectChildren(children, { ground, ink }, markers, into);
441
+ };
442
+ const collectChildren = (siblings, effective, markers, into) => {
443
+ const under = stackedGrounds(siblings);
444
+ for (const child of siblings)
445
+ collectPaint(child, effective, under.get(child), markers, into);
446
+ };
447
+ const uniqueSlots = (slots) => [...new Set(slots)].sort();
448
+ const uniquePairings = (pairings) => [...new Map(pairings.map((pairing) => [`${pairing.foreground}|${pairing.background}`, pairing])).values()].sort((a, b) => `${a.foreground}|${a.background}`.localeCompare(`${b.foreground}|${b.background}`));
449
+ /**
450
+ * The union across every configuration, rather than the intersection the
451
+ * decoration probe takes. Decoration is a promise that has to hold however the
452
+ * primitive is configured; a colour pairing is a fact about one configuration,
453
+ * and a `loom.section` that paints `accent-subtle` only under `tone: "accent"`
454
+ * renders that pairing on a real page whatever the other tones do.
455
+ */
456
+ export const probeColourPairings = (primitive, declaredSlots = [], text = NO_TEXT, configurations = DEFAULT_CONFIGURATIONS, declaredFrames = []) => {
457
+ const probeable = asProbeable(primitive);
458
+ if (!probeable.ok)
459
+ return notCallable(probeable.error);
460
+ const slots = Object.create(null);
461
+ for (const name of declaredSlots)
462
+ slots[name] = slotMarker(name);
463
+ const markers = new Set([PROBE_CHILDREN, ...declaredSlots.map(slotMarker)]);
464
+ const attempts = configurations.map((configuration) => ({
465
+ configuration,
466
+ result: call(probeable.value, {
467
+ loom: {
468
+ nodeId: PROBE_NODE_ID,
469
+ type: PROBE_TYPE,
470
+ slots,
471
+ data: configuration.data,
472
+ frames: probeFrames(declaredFrames),
473
+ text,
474
+ behaviours: NO_BEHAVIOURS,
475
+ decorative: PROBE_DECORATIVE,
476
+ },
477
+ props: configuration.props,
478
+ children: PROBE_CHILDREN,
479
+ }),
480
+ }));
481
+ const answered = attempts.flatMap((attempt) => (attempt.result.ok ? [attempt.result.value] : []));
482
+ if (answered.length === 0)
483
+ return threwThroughout(failuresIn(attempts));
484
+ const into = { painted: [], floating: [], childGrounds: [] };
485
+ for (const node of answered)
486
+ collectChildren(flatten(node), NOTHING_IN_EFFECT, markers, into);
487
+ return {
488
+ outcome: "probed",
489
+ painted: uniquePairings(into.painted),
490
+ floating: uniqueSlots(into.floating),
491
+ childGrounds: uniqueSlots(into.childGrounds),
492
+ };
493
+ };
494
+ //# sourceMappingURL=conformance.js.map
@@ -0,0 +1,105 @@
1
+ import type { NodeId } from "../ids.js";
2
+ import type { PrimitiveType } from "../primitive-type.js";
3
+ import type { LoomNode } from "../tree/node.js";
4
+ /**
5
+ * The words a node shows.
6
+ *
7
+ * `textOf` (`tree/navigation.ts`) answers this for text children and stops
8
+ * there, and text children are not where most copy lives.
9
+ * [0052](../../decisions/0052-a-repeated-item-is-a-node-and-a-fixed-field-is-a-prop.md)
10
+ * settled that a fixed field stays a prop and only repeated content earns a
11
+ * node, so `loom.stat` holds its figure, its label and its caption as props and
12
+ * `loom.quote` holds the quote, the author and the role as props. A reading
13
+ * that walks text children reports a proposal to delete three headline numbers
14
+ * as taking away *no words at all*.
15
+ *
16
+ * Which props are copy is knowable by exactly one party. `loom.stat`'s `value`,
17
+ * `label` and `caption` are words a reader reads; `loom.hero`'s `backdrop`,
18
+ * `align` and `stature` are not, and every one of the six is a string in the
19
+ * same shape of JSON. Nothing outside the component can tell them apart —
20
+ * neither the schema, which types both as strings, nor `description`, which is
21
+ * one line of prose for a model.
22
+ *
23
+ * So the author says, and this reads what they said.
24
+ */
25
+ /**
26
+ * A type's declared copy props, or `undefined` where it has not said.
27
+ *
28
+ * The two are different answers and the gap between them is the point: a
29
+ * registry built by this SDK satisfies this, and so does a two-line double.
30
+ */
31
+ export type CopyDeclarations = {
32
+ readonly copyFor: (type: PrimitiveType) => readonly string[] | undefined;
33
+ };
34
+ /**
35
+ * A node whose words this reading could not see, and the props it could not
36
+ * classify.
37
+ *
38
+ * Only a type that declared *nothing* appears here. A type that declared
39
+ * `copy: []` said it shows no words and is believed; a type that declared
40
+ * `copy: ["value"]` and also holds `align` said `align` is not copy and is
41
+ * believed about that too. Absence is the only ambiguity, and it is the one
42
+ * reported — the same bargain `RegistryPairings.unprobedProps` makes, and for
43
+ * the same reason: *I cannot tell you* is not *there are none*, and a reading
44
+ * that quietly rounded one to the other would be wrong in the direction nobody
45
+ * checks.
46
+ */
47
+ export type UnreadCopy = {
48
+ readonly nodeId: NodeId;
49
+ readonly type: PrimitiveType;
50
+ /**
51
+ * Its string-valued props, in the order the node carries them.
52
+ *
53
+ * String-valued, and that is a decision rather than an accident (0169). Where
54
+ * nothing has been declared, a value that is not a string is not a candidate
55
+ * word at all: a `loom.divider` holding `weight: 2` would otherwise be
56
+ * reported as a part whose words a reader might lose, and every layout
57
+ * primitive in the library would join it. The opposite call is made on the
58
+ * declared side, and a declaration is the whole of the difference.
59
+ */
60
+ readonly props: readonly string[];
61
+ };
62
+ /**
63
+ * A prop a type declared as copy, holding something this reading will not turn
64
+ * into a word.
65
+ *
66
+ * `loom.stat` renders `3400` as *3,400*, and the component owns that
67
+ * formatting — so the reading declines to guess it, which is right and used to
68
+ * be the end of the matter. It was also silent: the figure left `words` and
69
+ * arrived nowhere else, on the one seam whose return type exists so that a
70
+ * missing word is never mistaken for an absent one.
71
+ *
72
+ * This is the other half of `unread`, and the two say different things. `unread`
73
+ * is *nobody has told me whether these are words*. This is *somebody told me
74
+ * these are words, and what is in them is not one*. A caller that has neither
75
+ * has read everything the node says.
76
+ */
77
+ export type UnspokenCopy = {
78
+ readonly nodeId: NodeId;
79
+ readonly type: PrimitiveType;
80
+ /** The declared copy props holding a non-string value, in declaration order. */
81
+ readonly props: readonly string[];
82
+ };
83
+ export type NodeCopy = {
84
+ /**
85
+ * In reading order: each element's own declared copy before its children's,
86
+ * because a stat's label is above the things under it and a card's title is
87
+ * above its body. Blank and whitespace-only values are left out — a caller
88
+ * composing a sentence wants words, and an empty string is not one.
89
+ */
90
+ readonly words: readonly string[];
91
+ /** What this reading could not see. Empty when every type under it declared. */
92
+ readonly unread: readonly UnreadCopy[];
93
+ /** What it was told to read and could not. Empty when every declared copy prop held a string. */
94
+ readonly unspoken: readonly UnspokenCopy[];
95
+ };
96
+ /**
97
+ * Reads a node and everything under it.
98
+ *
99
+ * Pure, and a function of the tree rather than of a render: it never calls a
100
+ * component and never touches the DOM, so it answers the same for a node on a
101
+ * server, in a test, and inside a proposal nobody has approved yet — which is
102
+ * where the callers that filed for it are asking from.
103
+ */
104
+ export declare const copyIn: (node: LoomNode, declarations: CopyDeclarations) => NodeCopy;
105
+ //# sourceMappingURL=copy.d.ts.map
@@ -0,0 +1,90 @@
1
+ const NO_WORDS = Object.freeze({
2
+ words: Object.freeze([]),
3
+ unread: Object.freeze([]),
4
+ unspoken: Object.freeze([]),
5
+ });
6
+ const isWord = (value) => typeof value === "string" && value.trim() !== "";
7
+ /**
8
+ * What a type's declaration is worth on one node: the words it found, and the
9
+ * props it was sent to and came back from empty-handed.
10
+ *
11
+ * A value that is not a string is still not coerced. `loom.stat` renders `3400`
12
+ * as *3,400*, the component owns that separator and the runtime does not, so
13
+ * `String(value)` would put a figure on a reviewer's screen that the page does
14
+ * not show. A missing word is a gap; a wrong one is a lie. What changed is that
15
+ * the gap is now handed back rather than dropped.
16
+ *
17
+ * Three cases and only one of them is unspoken:
18
+ *
19
+ * - **Not set.** Nothing to report — a `caption` nobody wrote is not a word
20
+ * this reading lost. Own keys only, so a type that declares a prop named after
21
+ * something on `Object.prototype` reports nothing rather than the prototype's.
22
+ * - **A string, blank or whitespace-only.** Also nothing: the page really does
23
+ * show nothing there, so the absence is the truth rather than a gap in it.
24
+ * - **Set, and not a string.** A word is owed and cannot be given, which is the
25
+ * case this reports.
26
+ */
27
+ const readDeclared = (props, declared) => {
28
+ const words = [];
29
+ const unspoken = [];
30
+ for (const name of declared) {
31
+ if (!Object.hasOwn(props, name))
32
+ continue;
33
+ const value = props[name];
34
+ if (value === undefined)
35
+ continue;
36
+ if (typeof value === "string") {
37
+ if (isWord(value))
38
+ words.push(value);
39
+ continue;
40
+ }
41
+ unspoken.push(name);
42
+ }
43
+ return { words, unspoken };
44
+ };
45
+ const stringProps = (props) => Object.keys(props).filter((name) => isWord(props[name]));
46
+ /**
47
+ * Reads a node and everything under it.
48
+ *
49
+ * Pure, and a function of the tree rather than of a render: it never calls a
50
+ * component and never touches the DOM, so it answers the same for a node on a
51
+ * server, in a test, and inside a proposal nobody has approved yet — which is
52
+ * where the callers that filed for it are asking from.
53
+ */
54
+ export const copyIn = (node, declarations) => {
55
+ const words = [];
56
+ const unread = [];
57
+ const unspoken = [];
58
+ const read = (current) => {
59
+ if (current.kind === "text") {
60
+ if (isWord(current.value))
61
+ words.push(current.value);
62
+ return;
63
+ }
64
+ if (current.kind === "element") {
65
+ const declared = declarations.copyFor(current.type);
66
+ if (declared === undefined) {
67
+ const props = stringProps(current.props);
68
+ if (props.length > 0)
69
+ unread.push({ nodeId: current.id, type: current.type, props });
70
+ }
71
+ else {
72
+ const read = readDeclared(current.props, declared);
73
+ words.push(...read.words);
74
+ if (read.unspoken.length > 0)
75
+ unspoken.push({ nodeId: current.id, type: current.type, props: read.unspoken });
76
+ }
77
+ }
78
+ for (const child of current.children)
79
+ read(child);
80
+ };
81
+ read(node);
82
+ return words.length === 0 && unread.length === 0 && unspoken.length === 0
83
+ ? NO_WORDS
84
+ : {
85
+ words: Object.freeze(words),
86
+ unread: Object.freeze(unread),
87
+ unspoken: Object.freeze(unspoken),
88
+ };
89
+ };
90
+ //# sourceMappingURL=copy.js.map