spell 0.8.7 → 0.8.9

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 (304) hide show
  1. package/README-epics.md +149 -49
  2. package/app/package.json +25 -1
  3. package/app/spaces/@spell/guides/SpellUI/SpellUI.spellml +486 -486
  4. package/app/spaces/@spell/sites/SpellApp/SpellApp.spellml +50 -124
  5. package/dist/app/app/pages/SiteBoardView.css +5 -5
  6. package/dist/app/app/pages/SiteBoardView.js +1 -1
  7. package/dist/app/app/pages/SiteEditorPage.js +6 -3
  8. package/dist/app/app/pages/SiteEdits.js +27 -10
  9. package/dist/app/app/pages/SiteWrites.js +11 -0
  10. package/dist/app/app/runner/spellRuntime.js +1 -0
  11. package/dist/cli/publish/PublishedPackage.d.ts +2 -1
  12. package/dist/cli/publish/PublishedPackage.js +6 -3
  13. package/dist/cli/publish/ScratchInstall.d.ts +14 -3
  14. package/dist/cli/publish/ScratchInstall.js +69 -8
  15. package/dist/epic/cli/EpicProgram.js +20 -5
  16. package/dist/epic/cli/epicGroups.js +7 -1
  17. package/dist/epic/command/BaseBranch.d.ts +35 -0
  18. package/dist/epic/command/BaseBranch.js +58 -0
  19. package/dist/epic/command/EpicCheckout.d.ts +1 -1
  20. package/dist/epic/command/EpicCheckout.js +4 -4
  21. package/dist/epic/command/EpicGuide.js +3 -2
  22. package/dist/epic/command/EpicTools.d.ts +5 -0
  23. package/dist/epic/command/EpicTools.js +14 -3
  24. package/dist/epic/command/MainMerge.d.ts +26 -15
  25. package/dist/epic/command/MainMerge.js +60 -16
  26. package/dist/epic/command/PullRequest.d.ts +45 -0
  27. package/dist/epic/command/PullRequest.js +100 -0
  28. package/dist/epic/command/RepoInit.d.ts +196 -39
  29. package/dist/epic/command/RepoInit.js +481 -60
  30. package/dist/epic/command/Requests.d.ts +1 -0
  31. package/dist/epic/command/Requests.js +7 -1
  32. package/dist/epic/command/SessionMoves.js +2 -1
  33. package/dist/epic/command/SkillsCheck.js +3 -2
  34. package/dist/epic/command/Stock.js +3 -1
  35. package/dist/epic/command/TurnEnd.d.ts +1 -1
  36. package/dist/epic/command/TurnEnd.js +4 -3
  37. package/dist/epic/command/Worktrees.d.ts +20 -3
  38. package/dist/epic/command/Worktrees.js +39 -7
  39. package/dist/epic/command/command.types.d.ts +3 -0
  40. package/dist/epic/components/__pack/epics.entry.js +43 -43
  41. package/dist/epic/components/__pack/epics.pack.js +36 -12794
  42. package/dist/epic/config/CodeHost.d.ts +96 -0
  43. package/dist/epic/config/CodeHost.js +89 -0
  44. package/dist/epic/config/EngineFiles.mjs +60 -0
  45. package/dist/epic/config/EpicConfig.d.ts +20 -3
  46. package/dist/epic/config/EpicConfig.js +25 -1
  47. package/dist/epic/config/EpicRepo.js +1 -1
  48. package/dist/epic/config/GitHub.d.ts +75 -3
  49. package/dist/epic/config/GitHub.js +106 -5
  50. package/dist/epic/config/GitLab.d.ts +138 -0
  51. package/dist/epic/config/GitLab.js +297 -0
  52. package/dist/epic/config/LayeredSettings.js +3 -2
  53. package/dist/epic/server/EpicServer.d.ts +1 -1
  54. package/dist/epic/server/EpicServer.js +26 -12
  55. package/dist/epic/tool/InboxPoller.mjs +2 -1
  56. package/dist/epic/tool/MigrateCommands.js +6 -8
  57. package/dist/epic/tool/PlanCommits.d.ts +7 -4
  58. package/dist/epic/tool/PlanCommits.js +7 -5
  59. package/dist/epic/tool/PlanDocCommands.js +3 -4
  60. package/dist/epic/tool/PlanDocFiles.d.ts +3 -1
  61. package/dist/epic/tool/PlanDocFiles.js +13 -5
  62. package/dist/epic/tool/ServedFolders.d.ts +1 -1
  63. package/dist/epic/tool/ServedFolders.js +4 -4
  64. package/dist/epic/tools/PageInboxes.js +3 -3
  65. package/dist/epic/tools/_assets/commands.entry.js +149 -68
  66. package/dist/epic/tools/_assets/commands.js +20 -2073
  67. package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
  68. package/dist/epic/tools/_assets/core-reference.js +20 -2142
  69. package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
  70. package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
  71. package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
  72. package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
  73. package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
  74. package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
  75. package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
  76. package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
  77. package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
  78. package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
  79. package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
  80. package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
  81. package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
  82. package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
  83. package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
  84. package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
  85. package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
  86. package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
  87. package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
  88. package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
  89. package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
  90. package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
  91. package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
  92. package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
  93. package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
  94. package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
  95. package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
  96. package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
  97. package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
  98. package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
  99. package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
  100. package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
  101. package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
  102. package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
  103. package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
  104. package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
  105. package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
  106. package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
  107. package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
  108. package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
  109. package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
  110. package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
  111. package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
  112. package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
  113. package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
  114. package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
  115. package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
  116. package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
  117. package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
  118. package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
  119. package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
  120. package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
  121. package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
  122. package/dist/epic/tools/_assets/goals-live.js +318 -210
  123. package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
  124. package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
  125. package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
  126. package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
  127. package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
  128. package/dist/epic/tools/_assets/spell-comments.js +24 -3716
  129. package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
  130. package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
  131. package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
  132. package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
  133. package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
  134. package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
  135. package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
  136. package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
  137. package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
  138. package/dist/epic/tools/pages.d.ts +5 -6
  139. package/dist/epic/tools/pages.js +7 -6
  140. package/dist/epic/window.mjs +2 -3
  141. package/dist/parser/core/classes/View.d.ts +20 -0
  142. package/dist/parser/core/classes/View.js +91 -17
  143. package/dist/parser/core/core.declarations.json5 +18 -0
  144. package/dist/parser/core/core.scopes.js +5 -0
  145. package/dist/parser/core/sites.d.ts +10 -0
  146. package/dist/parser/core/sites.js +12 -0
  147. package/dist/parser/parser/tokenizer/Tokenizer.d.ts +9 -1
  148. package/dist/parser/parser/tokenizer/Tokenizer.js +43 -5
  149. package/dist/parser/parser/tokenizer/Tokens.d.ts +4 -0
  150. package/dist/parser/parser/tokenizer/Tokens.js +4 -0
  151. package/dist/parser/parser/tokenizer/tokenizer.types.d.ts +5 -0
  152. package/dist/parser/parser/tokenizer/tokenizer.types.js +2 -0
  153. package/dist/parser/py/core/spell_core/apps.py +2 -0
  154. package/dist/parser/spell/PARSING.md +21 -0
  155. package/dist/parser/spell/SpellParser.d.ts +2 -0
  156. package/dist/parser/spell/SpellParser.js +58 -3
  157. package/dist/parser/spell/SpellxTokenizer.js +2 -1
  158. package/dist/parser/spell/SpellxTwin.d.ts +4 -1
  159. package/dist/parser/spell/SpellxTwin.js +10 -3
  160. package/dist/parser/spell/builtinTypes.js +24 -1
  161. package/dist/parser/spell/ingest/PlaceIngest.js +3 -1
  162. package/dist/parser/spell/languages/Language.d.ts +11 -2
  163. package/dist/parser/spell/languages/en/words.js +3 -2
  164. package/dist/parser/spell/languages/es/words.js +7 -4
  165. package/dist/parser/spell/rules/Statement.js +1 -1
  166. package/dist/parser/spell/rules/classes/DrawSlot.js +6 -1
  167. package/dist/parser/spell/rules/sites/SitePage.d.ts +3 -3
  168. package/dist/parser/spell/rules/sites/SitePage.js +2 -2
  169. package/dist/parser/spell/rules/sites/sites.en.js +1 -1
  170. package/dist/parser/spell/rules/sites/sites.es.js +1 -1
  171. package/dist/parser/spell/rules/sites/sites.shared.d.ts +2 -2
  172. package/dist/parser/spell/spell.types.d.ts +7 -0
  173. package/dist/parser/spell/spellSyntax.es.json +6 -6
  174. package/dist/parser/spell/spellSyntax.json +6 -6
  175. package/dist/parser/spellx/SpellxView.js +2 -1
  176. package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
  177. package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
  178. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
  179. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
  180. package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
  181. package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
  182. package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
  183. package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
  184. package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
  185. package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
  186. package/dist/ui/components/ui-card/UICards.d.ts +31 -0
  187. package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
  188. package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
  189. package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
  190. package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
  191. package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
  192. package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
  193. package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
  194. package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
  195. package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
  196. package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
  197. package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
  198. package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
  199. package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
  200. package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
  201. package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
  202. package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
  203. package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
  204. package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
  205. package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
  206. package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
  207. package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
  208. package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
  209. package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
  210. package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
  211. package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
  212. package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
  213. package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
  214. package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
  215. package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
  216. package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
  217. package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
  218. package/dist/ui/components/ui-list/UIList.d.ts +2 -0
  219. package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
  220. package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
  221. package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
  222. package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
  223. package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
  224. package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
  225. package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
  226. package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
  227. package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
  228. package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
  229. package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
  230. package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
  231. package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
  232. package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
  233. package/dist/ui/components/ui-parts/UIHeader.d.ts +15 -3
  234. package/dist/ui/components/ui-parts/UIHeader.en.d.ts +5 -2
  235. package/dist/ui/components/ui-parts/UIHeader.en.js +6 -3
  236. package/dist/ui/components/ui-parts/UIHeader.js +45 -5
  237. package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
  238. package/dist/ui/components/ui-parts/UIParts.css +18 -0
  239. package/dist/ui/components/ui-parts/UIParts.css.inline.js +1 -1
  240. package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
  241. package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
  242. package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
  243. package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
  244. package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
  245. package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
  246. package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
  247. package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
  248. package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
  249. package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
  250. package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
  251. package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
  252. package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
  253. package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
  254. package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
  255. package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
  256. package/dist/ui/components/ui-section/UISections.d.ts +1 -0
  257. package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
  258. package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
  259. package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
  260. package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
  261. package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
  262. package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
  263. package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
  264. package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
  265. package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
  266. package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
  267. package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
  268. package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
  269. package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
  270. package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
  271. package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
  272. package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
  273. package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
  274. package/dist/ui/components/ui-table/UICell.d.ts +1 -0
  275. package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
  276. package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
  277. package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
  278. package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
  279. package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
  280. package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
  281. package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
  282. package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
  283. package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
  284. package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
  285. package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
  286. package/dist/ui/jsx.d.ts +4 -4
  287. package/dist/ui/vocabulary/defaults.generated.js +1 -1
  288. package/dist/util/spell/constants.js +1 -1
  289. package/epic/.claude-plugin/plugin.json +1 -1
  290. package/epic/.codex-plugin/plugin.json +1 -1
  291. package/epic/hooks/handoff.mjs +4 -3
  292. package/epic/hooks/worktree.mjs +22 -3
  293. package/epic/package.json +41 -2
  294. package/epic/skills/details/SKILL.md +2 -1
  295. package/epic/skills/epic/SKILL.md +7 -1
  296. package/epic/skills/epic/guide.md +3 -0
  297. package/epic/skills/isolate/SKILL.md +53 -20
  298. package/epic/src/AGENTS.md +11 -2
  299. package/epic/templates/durable.html +1 -1
  300. package/epic/vscode/package.json +1 -1
  301. package/epic/vscode/spell-epic.vsix +0 -0
  302. package/package.json +1 -1
  303. package/parser/package.json +1 -1
  304. package/ui/package.json +15 -2
@@ -1,159 +1,276 @@
1
- var __defProp = Object.defineProperty;
2
- var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
1
+ /*
2
+ * THE TOOLBAR, every page's navigation, and its jump key (Cmd / Ctrl + K): ONE code for both kinds of page (epic
3
+ * `epic-engine` T11; Owen, 2026-10-20: "Epic UI pages should have a toolbar").
4
+ * - Its own module, as the comments are (`spell-doc-comments.js`, P2), so two scripts carry it:
5
+ * - the docs bundle, `spell-ui.js`, through the page runtime (`spell-doc-runtime.js`): a guide's and an epic page's
6
+ * toolbar, placed and followed there (`buildPageToolbar()`, `buildToolbar()`, `followScroll()`)
7
+ * - `spell-comments.js` (`spell-comments.entry.js`), on Epic UI's pages: a band under the site's masthead, one
8
+ * button per top-level section, the comments' bullhorn at its right (`wireSiteToolbar()` there)
9
+ * - Plain DOM, no Spell UI imports: it makes `<ui-menu>` / `<ui-item>` / `<ui-label>` / `<ui-modal>` markup and lets
10
+ * the page's Spell UI draw it (the comments' rule: one Spell UI on a page, epic `epic-engine` I18)
11
+ * - Its look: `spell-toolbar.css`, beside it (`@import`ed by `spell-doc.css`; linked by `spell-comments.js`).
12
+ */
3
13
 
4
- // src/tools/_assets/spell-doc-toolbar.js
5
- import { nextFrame } from "spell/util/dom";
6
- import { clamp } from "spell/util/number";
7
- import { withoutAccents } from "spell/util/string";
8
- import { commentsOnPage, firstWords } from "./spell-doc-comments.js";
9
- import { FIELDS, el, titleInside } from "./spell-doc-helpers.js";
10
- import { ThreadFacts } from "../../comments/index.js";
11
- function titledItems(groups, badgesOf) {
12
- const titles = groups.map(({ label }) => ITEM_ID.test(label) ? label : shortLabel(label));
13
- const letters = accessLetters(titles);
14
+ import { nextFrame } from "spell/util/dom"
15
+ import { clamp } from "spell/util/number"
16
+ import { withoutAccents } from "spell/util/string"
17
+ import { commentsOnPage, firstWords } from "./spell-doc-comments.js"
18
+ import { FIELDS, el, titleInside } from "./spell-doc-helpers.js"
19
+ import { ThreadFacts } from "spell/epic/comments"
20
+
21
+ ////////////////
22
+ // ## The toolbar
23
+ ////////////////
24
+
25
+ /**
26
+ * A TITLED toolbar's items (a guide's, a details page's, Epic UI's): one per top-level section, its mark and title.
27
+ * - `groups`: `{ element, id, label, glyph }` each, the outline's top-level entries
28
+ * - `badgesOf(element)`: its badges (`[kind, number, words]`, `toolbarItem()`); none: `[]`
29
+ * - the mark: an item's number for an item (`Q3 · When?` shows 3, coloured by the section's `data-state`: a
30
+ * details page's questions, `<epic-ask>`); else its `<ui-icon>`; else its number (`2.`); else its access letter,
31
+ * shown only while the titles are hidden (the menu's `:state(icons-only)`)
32
+ * - the title without its number (`2. Markup` is `Markup`), unless it's an item's
33
+ * - its ACCESS LETTER: unique on the toolbar (`accessLetters()`), drawn IN its title (bold, the text's colour);
34
+ * pressing it jumps there as a click does (`wireAccessLetters()`)
35
+ */
36
+ export function titledItems(groups, badgesOf) {
37
+ const titles = groups.map(({ label }) => (ITEM_ID.test(label) ? label : shortLabel(label)))
38
+ const letters = accessLetters(titles)
14
39
  return groups.map(({ element, id, label, glyph }, index) => {
15
- const itemNumber = label.match(ITEM_ID)?.[1];
16
- const number = label.match(/^\d+/)?.[0];
40
+ // an item id first in the label (`Q3 · When?`) says more than any icon: every question's would be the same
41
+ const itemNumber = label.match(ITEM_ID)?.[1]
42
+ const number = label.match(/^\d+/)?.[0]
17
43
  return toolbarItem({
18
44
  id,
19
45
  tip: label,
20
- glyph: itemNumber ? void 0 : glyph,
21
- mark: itemNumber ? el("b", { slot: "icon", class: "spell-toolbar-number" }, itemNumber) : glyph ? void 0 : number ? el("b", { slot: "icon" }, number) : el(
22
- "b",
23
- { slot: "icon", class: "spell-toolbar-letter" },
24
- (letters[index] ?? label.charAt(0)).toUpperCase()
25
- ),
46
+ glyph: itemNumber ? undefined : glyph,
47
+ mark: itemNumber
48
+ ? el("b", { slot: "icon", class: "spell-toolbar-number" }, itemNumber)
49
+ : glyph
50
+ ? undefined
51
+ : number
52
+ ? el("b", { slot: "icon" }, number)
53
+ : el(
54
+ "b",
55
+ { slot: "icon", class: "spell-toolbar-letter" },
56
+ (letters[index] ?? label.charAt(0)).toUpperCase()
57
+ ),
26
58
  title: titles[index],
27
59
  letter: letters[index],
28
60
  state: element.dataset.state,
29
61
  badges: badgesOf(element)
30
- });
31
- });
62
+ })
63
+ })
32
64
  }
33
- __name(titledItems, "titledItems");
34
- var ITEM_ID = /^[A-Z](\d+)\b/;
35
- function accessLetters(titles) {
36
- const taken = /* @__PURE__ */ new Set();
65
+
66
+ /** An item's id first in a section's label: `Q3 · When?`. */
67
+ const ITEM_ID = /^[A-Z](\d+)\b/
68
+
69
+ /**
70
+ * Each title's ACCESS LETTER, unique among them, lower case; `undefined` for a title with no free letter.
71
+ * - its title's first letter, else the next letter IN its title not taken yet:
72
+ * `Types` t, `Groups` g, `Content` c, `States` s, `Variations` v, `Group Variations` r
73
+ * - first come, first served, in toolbar order; letters only (a-z, accents folded: `withoutAccents()`), never a
74
+ * digit or a space
75
+ * - pure: no DOM
76
+ */
77
+ export function accessLetters(titles) {
78
+ const taken = new Set()
37
79
  return titles.map((title) => {
38
- const letters = withoutAccents(title).toLowerCase().replace(/[^a-z]/g, "");
39
- const letter = letters.split("").find((candidate) => !taken.has(candidate));
40
- if (letter) taken.add(letter);
41
- return letter;
42
- });
80
+ const letters = withoutAccents(title)
81
+ .toLowerCase()
82
+ .replace(/[^a-z]/g, "")
83
+ // a-z alone by now: a letter a character
84
+ const letter = letters.split("").find((candidate) => !taken.has(candidate))
85
+ if (letter) taken.add(letter)
86
+ return letter
87
+ })
43
88
  }
44
- __name(accessLetters, "accessLetters");
89
+
90
+ /**
91
+ * A title with its access letter marked: the first occurrence of `letter` in it, any case, as a
92
+ * `<u class="spell-toolbar-key">`; the plain title when `letter` is missing or not in it.
93
+ */
45
94
  function titleWithKey(title, letter) {
46
- const at = letter ? [...title.normalize("NFD")].findIndex((char) => char.toLowerCase() === letter) : -1;
47
- if (at < 0) return [title];
48
- const chars = [...title.normalize("NFD")];
49
- return [chars.slice(0, at).join(""), el("u", { class: "spell-toolbar-key" }, chars[at]), chars.slice(at + 1).join("")];
95
+ const at = letter ? [...title.normalize("NFD")].findIndex((char) => char.toLowerCase() === letter) : -1
96
+ if (at < 0) return [title]
97
+ const chars = [...title.normalize("NFD")]
98
+ return [chars.slice(0, at).join(""), el("u", { class: "spell-toolbar-key" }, chars[at]), chars.slice(at + 1).join("")]
50
99
  }
51
- __name(titleWithKey, "titleWithKey");
52
- function toolbarMenu(items, { titled, segmented = false }) {
53
- const kept = removeToolbar();
54
- const tag = customElements.get("ui-toolbar") ? "ui-toolbar" : "ui-menu";
100
+
101
+ /**
102
+ * THE TOOLBAR, every page's (epic `epic-engine` P3: Owen, 2026-10-19, "Why are we not using <ui-xxxx> or <epic-xxx>
103
+ * components for these pages?"): Spell UI's menu, `<ui-menu class="spell-toolbar" appearance="secondary">`, a `<nav>` landmark of
104
+ * `<ui-item>` links (`toolbarItem()`), its look `spell-toolbar.css`'s, through the menu's tokens.
105
+ * - the current item `selected` (scroll-follow), which the menu draws, and says (`aria-current`)
106
+ * - `titled`: a guide's (and Epic UI's), each item its mark and its title (`spell-toolbar-titled`); else an epic
107
+ * page's, marks only, every item the same width
108
+ * - its titles fit the row: `<ui-toolbar shrinkable>`, Spell UI's own fitting (epic `ui-gaps` P13): the longest
109
+ * end in `...` first; once one would be cut under 50px, the marks only, each title its tooltip; narrower still,
110
+ * one `...` button whose menu holds every section (Owen, 2026-10-10: "remove the titles entirely if they each
111
+ * only get less than 50px")
112
+ * - except a `segmented` one: it scrolls, every title whole, its `‹` / `›` showing what's past either end
113
+ * - an epic page's: it scrolls too, its `‹` / `›` showing what's past either end
114
+ * - after the items, what a page or the comments add to the row: the toolbar's bullhorn (`PageComments`), the spell
115
+ * syntax guide's Expand all and Collapse all; the items scroll sideways under them (`spell-toolbar.css`)
116
+ * - `segmented`: the toolbar under a page's tabs (Spell UI's components pages) is a SEGMENTED menu, as the tabs are:
117
+ * the same pills, and the same sliding key as the section being read changes
118
+ * - the current item scrolled into view, on a row scrolled sideways (`scrollIntoRow()`)
119
+ * - SIDE EFFECT: removes the toolbar built before (`removeToolbar()`), keeping what was added to its row
120
+ */
121
+ export function toolbarMenu(items, { titled, segmented = false }) {
122
+ const kept = removeToolbar()
123
+ // Spell UI's `<ui-toolbar>` where the page has it: `‹` / `›` buttons while its items overflow (an epic page's
124
+ // marks on a phone too, epic `epic-engine` I138: the 6th was cut, nothing saying more was past it)
125
+ const tag = customElements.get("ui-toolbar") ? "ui-toolbar" : "ui-menu"
55
126
  const toolbar = el(tag, {
56
- class: ["spell-toolbar", titled && "spell-toolbar-titled", segmented && "spell-toolbar-segmented"].filter(Boolean).join(" "),
57
- ...segmented ? { appearance: "segmented" } : { appearance: "secondary" },
127
+ class: ["spell-toolbar", titled && "spell-toolbar-titled", segmented && "spell-toolbar-segmented"]
128
+ .filter(Boolean)
129
+ .join(" "),
130
+ ...(segmented ? { appearance: "segmented" } : { appearance: "secondary" }),
58
131
  shrinkable: titled && !segmented,
59
132
  "scroll-first": titled && !segmented,
60
133
  "aria-label": "Sections",
61
134
  "data-spell-added": true
62
- });
63
- toolbar.append(...items, ...kept);
135
+ })
136
+ toolbar.append(...items, ...kept)
64
137
  if (titled) {
65
- wireAccessLetters();
66
- wireKeyTips(toolbar);
138
+ wireAccessLetters()
139
+ wireKeyTips(toolbar)
67
140
  }
68
141
  new MutationObserver((changes) => {
69
- for (const { target } of changes) if (target.hasAttribute("selected")) scrollIntoRow(target);
70
- }).observe(toolbar, { attributeFilter: ["selected"], subtree: true });
71
- return toolbar;
142
+ for (const { target } of changes) if (target.hasAttribute("selected")) scrollIntoRow(target)
143
+ }).observe(toolbar, { attributeFilter: ["selected"], subtree: true })
144
+ return toolbar
72
145
  }
73
- __name(toolbarMenu, "toolbarMenu");
74
- function toolbarTools(toolbar) {
75
- if (!toolbar?.classList.contains("spell-toolbar-titled")) return void 0;
76
- let tools = toolbar.querySelector(":scope > .spell-toolbar-tools");
146
+
147
+ /**
148
+ * A titled toolbar's own small toolbar, made on first use: a separate box in its `right` slot, beside the sections,
149
+ * never scrolling with them, so a badge on it isn't cut off: the page's Expand / Collapse, the comments' bullhorn.
150
+ * - Owen, 2026-11-01: "single expand/collapse button and bullhorn, in a separate toolbar"
151
+ * - kept when the toolbar is built anew (`removeToolbar()`)
152
+ * - `undefined` for a toolbar with no titles (an epic page's, whose tools are `<epic-page>`'s)
153
+ */
154
+ export function toolbarTools(toolbar) {
155
+ if (!toolbar?.classList.contains("spell-toolbar-titled")) return undefined
156
+ let tools = toolbar.querySelector(":scope > .spell-toolbar-tools")
77
157
  if (!tools) {
78
- tools = el("span", { class: "spell-toolbar-tools", slot: "right" });
79
- toolbar.append(tools);
158
+ tools = el("span", { class: "spell-toolbar-tools", slot: "right" })
159
+ toolbar.append(tools)
80
160
  }
81
- return tools;
161
+ return tools
82
162
  }
83
- __name(toolbarTools, "toolbarTools");
163
+
164
+ /**
165
+ * A titled toolbar's ACCESS LETTERS: a letter pressed on its own jumps to the item whose `data-key` it is,
166
+ * as clicking it does (the link inside the item is clicked).
167
+ * - once per page: it finds the toolbar showing at the time, so a toolbar built again needs nothing
168
+ * - left alone: any modifier (Cmd / Ctrl + K is the jump dialog), a key held down, typing (a field, an editable box),
169
+ * an open dialog, a focused control that takes keys of its own (a menu, a dropdown, a live example), `/` (the site's
170
+ * search) and every key that isn't a letter
171
+ */
84
172
  function wireAccessLetters() {
85
- if (accessLettersWired) return;
86
- accessLettersWired = true;
173
+ if (accessLettersWired) return
174
+ accessLettersWired = true
87
175
  document.addEventListener("keydown", (event) => {
88
176
  if (event.metaKey || event.ctrlKey || event.altKey || event.repeat || event.isComposing || event.defaultPrevented)
89
- return;
90
- if (!/^[a-z]$/i.test(event.key) || typingIn(event)) return;
91
- if (document.querySelector("dialog[open], ui-modal:not([hidden])")) return;
92
- const toolbar = document.querySelector(".spell-toolbar-titled");
93
- const focused = document.activeElement;
94
- if (!toolbar || focused && focused !== document.body && !toolbar.contains(focused) && takesKeys(focused)) return;
95
- const item = toolbar.querySelector(`:scope > [data-key="${event.key.toLowerCase()}"]`);
96
- const link = item?.shadowRoot?.querySelector('[part~="item"]');
97
- if (!link) return;
98
- event.preventDefault();
99
- link.click();
100
- });
177
+ return
178
+ if (!/^[a-z]$/i.test(event.key) || typingIn(event)) return
179
+ if (document.querySelector("dialog[open], ui-modal:not([hidden])")) return
180
+ const toolbar = document.querySelector(".spell-toolbar-titled")
181
+ const focused = document.activeElement
182
+ if (!toolbar || (focused && focused !== document.body && !toolbar.contains(focused) && takesKeys(focused))) return
183
+ const item = toolbar.querySelector(`:scope > [data-key="${event.key.toLowerCase()}"]`)
184
+ const link = item?.shadowRoot?.querySelector('[part~="item"]')
185
+ if (!link) return
186
+ event.preventDefault()
187
+ link.click()
188
+ })
101
189
  }
102
- __name(wireAccessLetters, "wireAccessLetters");
103
- var accessLettersWired = false;
190
+
191
+ /** Whether the page listens for access letters yet (`wireAccessLetters()`): once per page. */
192
+ let accessLettersWired = false
193
+
194
+ /**
195
+ * A titled toolbar's KEY TIPS: under the pointer or the keyboard's focus, an item with an access letter shows
196
+ * "Type T to jump to this section", the letter as a key cap.
197
+ * - ONE tip per page (`.spell-toolbar-tip`), a `popover` in the top layer: the toolbar's row scrolls sideways, which
198
+ * would clip a tip inside it
199
+ * - placed under the item, centred on it, kept inside the window; gone at once as the pointer leaves, focus moves on,
200
+ * the page scrolls or the item is clicked
201
+ * - under the pointer only after a second of resting on the item (`TIP_DELAY_MS`);
202
+ * the keyboard's focus shows it at once
203
+ * - the item's accessible name says the same (`aria-keyshortcuts`): the tip is for the eye only (`aria-hidden`)
204
+ */
104
205
  function wireKeyTips(toolbar) {
105
- const tip = keyTip();
106
- let waiting;
107
- const show = /* @__PURE__ */ __name((event) => {
108
- const item = event.target.closest?.("ui-item[data-key]");
109
- if (!item || !toolbar.contains(item)) return;
110
- clearTimeout(waiting);
111
- if (event.type === "pointerover") waiting = setTimeout(() => showUnder(item), TIP_DELAY_MS);
112
- else showUnder(item);
113
- }, "show");
114
- const showUnder = /* @__PURE__ */ __name((item) => {
115
- const box = item.shadowRoot?.querySelector('[part~="item"]')?.getBoundingClientRect() ?? item.getBoundingClientRect();
116
- tip.querySelector("kbd").textContent = item.dataset.key.toUpperCase();
117
- if (!tip.matches(":popover-open")) tip.showPopover();
118
- const width = tip.offsetWidth;
119
- tip.style.left = `${clamp(box.left + box.width / 2 - width / 2, 8, innerWidth - width - 8)}px`;
120
- tip.style.top = `${box.bottom + 6}px`;
121
- }, "showUnder");
122
- const hide = /* @__PURE__ */ __name(() => {
123
- clearTimeout(waiting);
124
- if (tip.matches(":popover-open")) tip.hidePopover();
125
- }, "hide");
126
- toolbar.addEventListener("pointerover", show);
127
- toolbar.addEventListener("focusin", show);
128
- toolbar.addEventListener("pointerleave", hide);
129
- toolbar.addEventListener("focusout", hide);
130
- toolbar.addEventListener("click", hide);
206
+ const tip = keyTip()
207
+ let waiting
208
+ const show = (event) => {
209
+ const item = event.target.closest?.("ui-item[data-key]")
210
+ if (!item || !toolbar.contains(item)) return
211
+ clearTimeout(waiting)
212
+ if (event.type === "pointerover") waiting = setTimeout(() => showUnder(item), TIP_DELAY_MS)
213
+ else showUnder(item)
214
+ }
215
+ const showUnder = (item) => {
216
+ const box =
217
+ item.shadowRoot?.querySelector('[part~="item"]')?.getBoundingClientRect() ?? item.getBoundingClientRect()
218
+ tip.querySelector("kbd").textContent = item.dataset.key.toUpperCase()
219
+ if (!tip.matches(":popover-open")) tip.showPopover()
220
+ const width = tip.offsetWidth
221
+ tip.style.left = `${clamp(box.left + box.width / 2 - width / 2, 8, innerWidth - width - 8)}px`
222
+ tip.style.top = `${box.bottom + 6}px`
223
+ }
224
+ const hide = () => {
225
+ clearTimeout(waiting)
226
+ if (tip.matches(":popover-open")) tip.hidePopover()
227
+ }
228
+ toolbar.addEventListener("pointerover", show)
229
+ toolbar.addEventListener("focusin", show)
230
+ toolbar.addEventListener("pointerleave", hide)
231
+ toolbar.addEventListener("focusout", hide)
232
+ toolbar.addEventListener("click", hide)
131
233
  }
132
- __name(wireKeyTips, "wireKeyTips");
133
- var TIP_DELAY_MS = 1e3;
234
+
235
+ /** How long the pointer rests on an item before its key tip shows (`wireKeyTips()`). */
236
+ const TIP_DELAY_MS = 1000
237
+
238
+ /** The page's one key tip (`wireKeyTips()`), made the first time a toolbar asks. */
134
239
  function keyTip() {
135
- const found = document.querySelector("body > .spell-toolbar-tip");
136
- if (found) return found;
240
+ const found = document.querySelector("body > .spell-toolbar-tip")
241
+ if (found) return found
137
242
  const tip = el(
138
243
  "div",
139
244
  { class: "spell-toolbar-tip", popover: "manual", "aria-hidden": "true", "data-spell-added": true },
140
245
  "Type ",
141
246
  el("kbd"),
142
247
  " to jump to this section"
143
- );
144
- document.body.append(tip);
145
- addEventListener("scroll", () => tip.matches(":popover-open") && tip.hidePopover(), { passive: true });
146
- return tip;
248
+ )
249
+ document.body.append(tip)
250
+ addEventListener("scroll", () => tip.matches(":popover-open") && tip.hidePopover(), { passive: true })
251
+ return tip
147
252
  }
148
- __name(keyTip, "keyTip");
253
+
254
+ /** A focused element that takes letters itself: a control with a role or a custom element of its own. */
149
255
  function takesKeys(element) {
150
256
  return element.matches(
151
- '[role="menu"], [role="menubar"], [role="listbox"], [role="combobox"], [role="grid"], [role="tree"], [role="slider"], [role="tablist"], ui-dropdown, ui-select, ui-search, ui-calendar, ui-menu, ui-tabs, ui-example *, ui-example'
152
- );
257
+ '[role="menu"], [role="menubar"], [role="listbox"], [role="combobox"], [role="grid"], [role="tree"], ' +
258
+ '[role="slider"], [role="tablist"], ui-dropdown, ui-select, ui-search, ui-calendar, ui-menu, ui-tabs, ' +
259
+ "ui-example *, ui-example"
260
+ )
153
261
  }
154
- __name(takesKeys, "takesKeys");
155
- function toolbarItem({ id, tip, glyph, mark, title, letter, state, badges }) {
156
- const said = [tip, ...badges.map(([, , words]) => words)].join(" · ");
262
+
263
+ /**
264
+ * One toolbar item: a `<ui-item>` link to section `id` (`data-rail`), its mark (`glyph`, the menu's icon box; else
265
+ * `mark`, a `slot="icon"` element), its `title` when the toolbar is titled (a plain `<span>` in the item: a
266
+ * shrinkable menu's item draws it in its title box, and cuts it there), its `badges` (`[kind, number, words]`: `<ui-label slot="badge">`s, over
267
+ * the mark's top right on an epic page), `state` (`data-state`, a details page's question's colour).
268
+ * - its tooltip `tip` on the link inside, where the pointer lands (`titleInside()`): its mark, title and badges let
269
+ * the pointer through (`spell-toolbar.css`), so it shows in VS Code too; the badges say theirs in it, and to a
270
+ * screen reader
271
+ */
272
+ export function toolbarItem({ id, tip, glyph, mark, title, letter, state, badges }) {
273
+ const said = [tip, ...badges.map(([, , words]) => words)].join(" · ")
157
274
  const item = el(
158
275
  "ui-item",
159
276
  {
@@ -172,79 +289,123 @@ function toolbarItem({ id, tip, glyph, mark, title, letter, state, badges }) {
172
289
  mark,
173
290
  // one box for the title and its access letter: loose, the item's flex row would part them ("T ypes")
174
291
  title && el("span", {}, ...titleWithKey(title, letter)),
175
- ...badges.map(
176
- ([kind, number]) => el(
292
+ ...badges.map(([kind, number]) =>
293
+ el(
177
294
  "ui-label",
178
295
  { class: `spell-toolbar-count ${kind}`, slot: "badge", appearance: "circular", size: "mini" },
179
296
  String(number)
180
297
  )
181
298
  )
182
- );
183
- titleInside(item, "item");
184
- return item;
299
+ )
300
+ titleInside(item, "item")
301
+ return item
185
302
  }
186
- __name(toolbarItem, "toolbarItem");
187
- function removeToolbar() {
188
- const kept = [];
303
+
304
+ /**
305
+ * Take the page's toolbar away (and a hand-written `.spell-toc-open`: pages before 2026-10-01 had a "Contents"
306
+ * button); returns what pages and the comments had added to its row, for the toolbar built next.
307
+ */
308
+ export function removeToolbar() {
309
+ const kept = []
189
310
  for (const old of document.querySelectorAll(".spell-toc-open, .spell-toolbar")) {
190
- kept.push(...[...old.children].filter((child) => !child.hasAttribute("data-rail")));
191
- old.remove();
311
+ kept.push(...[...old.children].filter((child) => !child.hasAttribute("data-rail")))
312
+ old.remove()
192
313
  }
193
- return kept;
314
+ return kept
194
315
  }
195
- __name(removeToolbar, "removeToolbar");
196
- function markCurrent(toolbar, id) {
316
+
317
+ /** Mark item `id` of `toolbar` as the section being read (`selected`), and no other; `""`: none. */
318
+ export function markCurrent(toolbar, id) {
197
319
  for (const item of toolbar?.querySelectorAll("[data-rail]") ?? [])
198
- item.toggleAttribute("selected", item.dataset.rail === id);
320
+ item.toggleAttribute("selected", item.dataset.rail === id)
199
321
  }
200
- __name(markCurrent, "markCurrent");
201
- function shortLabel(label) {
202
- return label.replace(/^\d+(?:\.\d+)*\.?\s+/, "");
322
+
323
+ /** A block's label without its number: `3. Questions` is `Questions`. */
324
+ export function shortLabel(label) {
325
+ return label.replace(/^\d+(?:\.\d+)*\.?\s+/, "")
203
326
  }
204
- __name(shortLabel, "shortLabel");
327
+
328
+ /** The toolbar's row: the menu's `<nav>`, in its shadow root; `undefined` before it has drawn. */
205
329
  function toolbarRow(toolbar) {
206
- return toolbar.shadowRoot?.querySelector('[part~="menu"]') ?? void 0;
330
+ return toolbar.shadowRoot?.querySelector('[part~="menu"]') ?? undefined
207
331
  }
208
- __name(toolbarRow, "toolbarRow");
332
+
333
+ /** The box `element` draws: a `<ui-item>`'s item, in its shadow root (the host is `display: contents`). */
209
334
  function boxOf(element) {
210
- const box = element.shadowRoot?.querySelector('[part~="item"]') ?? element;
211
- return box.getBoundingClientRect();
335
+ const box = element.shadowRoot?.querySelector('[part~="item"]') ?? element
336
+ return box.getBoundingClientRect()
212
337
  }
213
- __name(boxOf, "boxOf");
338
+
339
+ /** Scroll `item`'s row sideways (never the page) until it shows whole, centred if it has to move. */
214
340
  function scrollIntoRow(item) {
215
- const row = toolbarRow(item.parentElement);
216
- if (!row || row.scrollWidth <= row.clientWidth) return;
217
- const box = boxOf(item);
218
- const start = box.left - row.getBoundingClientRect().left + row.scrollLeft;
219
- if (start >= row.scrollLeft && start + box.width <= row.scrollLeft + row.clientWidth) return;
220
- row.scrollTo({ left: start - (row.clientWidth - box.width) / 2, behavior: "smooth" });
341
+ const row = toolbarRow(item.parentElement)
342
+ if (!row || row.scrollWidth <= row.clientWidth) return
343
+ const box = boxOf(item)
344
+ const start = box.left - row.getBoundingClientRect().left + row.scrollLeft
345
+ if (start >= row.scrollLeft && start + box.width <= row.scrollLeft + row.clientWidth) return
346
+ row.scrollTo({ left: start - (row.clientWidth - box.width) / 2, behavior: "smooth" })
221
347
  }
222
- __name(scrollIntoRow, "scrollIntoRow");
223
- var ID_LIKE = /^#?[a-z]{1,2}\d+$/i;
224
- function wireJumpKey(go, canGo, { search, host, first = false } = {}) {
225
- const onKey = /* @__PURE__ */ __name((event) => {
226
- if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey || event.defaultPrevented) return;
227
- const epicPage = document.body.classList.contains("plan-doc");
228
- if (event.key.toLowerCase() !== "k" || event.isComposing || !(epicPage || commentsOnPage())) return;
229
- if (document.querySelector("dialog[open], ui-modal:not([hidden])") || typingIn(event)) return;
230
- event.preventDefault();
231
- event.stopPropagation();
232
- openJumpPrompt(go, canGo, { search, host: typeof host === "function" ? host() : host });
233
- }, "onKey");
234
- if (first) addEventListener("keydown", onKey, { capture: true });
235
- else document.addEventListener("keydown", onKey);
348
+
349
+ ////////////////
350
+ // ## Jump to an id (Cmd / Ctrl + K)
351
+ ////////////////
352
+
353
+ /** What a typed id looks like (`C3`, `j7`, `cm3`, `#p2`): on Epic UI's pages, anything else is words to search. */
354
+ const ID_LIKE = /^#?[a-z]{1,2}\d+$/i
355
+
356
+ /**
357
+ * Cmd-K (Ctrl-K) on an epic page asks which item to jump to (Owen, 2026-10-10: "add command-k which brings up
358
+ * ui-prompt asking what number I want to jump to (e.g. J7)"), and lands there exactly as a link to `#j7` does
359
+ * (`go()`: what hides it unfolds, an item opens, it lands below the stuck titles).
360
+ * - any id on the page, case and a `#` aside: `J7`, `q3`, `P2`, `o1`, `#decisions`
361
+ * - a COMMENT's (epic `epic-workflow` P23; Owen, 2026-10-10: "⌘K taking comment ids"): `C3` (`c3`, the old `cm3`;
362
+ * `M3` is a manual test's since epic `epic-engine` P44)
363
+ * lands on its thread, opened, below the stuck titles (`PageComments.landOn()`); under the box, the threads
364
+ * waiting on Owen (Claude spoke last), each a line "C3 · his first words" that lands there
365
+ * - an epic page, and every page that takes comments (a guide, Epic UI's pages: comment ids, and any other id on it)
366
+ * - an id that isn't there: the dialog says so and stays open, the text selected for typing over
367
+ * - never while typing in a field (a note box, the new item form), nor with a dialog already open
368
+ * - the dialog is a `<ui-modal>` built as `UI.modals.prompt()` builds its own (`ModalDialogs`):
369
+ * no `<ui-prompt>` element exists, and `prompt()` closes on any answer, so it couldn't stay open on a miss;
370
+ * here its cancelable `ui-approving` is cancelled instead
371
+ * - K is free: the live client takes only Cmd / Ctrl + A C X V Z in VS Code's view (`liveClient.ts` `editKey()`)
372
+ * - options, for Epic UI's pages (`spell-comments.entry.js`), whose site has its own Cmd / Ctrl + K, its search:
373
+ * - `search(words)`: what's typed that isn't an id (`ID_LIKE`) goes to it, the site's search (epic `epic-engine`
374
+ * T11, J: one key for both, as on a guide; `/` still opens the search straight away)
375
+ * - `host`: where the dialog goes, a `<ui-root>` that loads its elements (the site's, which loads what's added to
376
+ * it); default `<body>`
377
+ * - `first`: listen before the page's own handlers (window, capture), so the site's search doesn't take the key too
378
+ */
379
+ export function wireJumpKey(go, canGo, { search, host, first = false } = {}) {
380
+ const onKey = (event) => {
381
+ if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey || event.defaultPrevented) return
382
+ const epicPage = document.body.classList.contains("plan-doc")
383
+ if (event.key.toLowerCase() !== "k" || event.isComposing || !(epicPage || commentsOnPage())) return
384
+ if (document.querySelector("dialog[open], ui-modal:not([hidden])") || typingIn(event)) return
385
+ event.preventDefault()
386
+ event.stopPropagation()
387
+ openJumpPrompt(go, canGo, { search, host: typeof host === "function" ? host() : host })
388
+ }
389
+ if (first) addEventListener("keydown", onKey, { capture: true })
390
+ else document.addEventListener("keydown", onKey)
236
391
  }
237
- __name(wireJumpKey, "wireJumpKey");
392
+
393
+ /**
394
+ * The jump dialog: an id typed, Go lands there; Cancel or Escape just closes it.
395
+ * - a comment's id (`C3`) lands on its thread, opened; the threads waiting on the person are listed under the box
396
+ * (`jumpWaitingList()`)
397
+ * - `search`, `host`: as `wireJumpKey()` takes them
398
+ */
238
399
  function openJumpPrompt(go, canGo, { search, host } = {}) {
239
- const epicPage = document.body.classList.contains("plan-doc");
240
- const header = epicPage ? "Jump to which item?" : search ? "Jump to a comment, or search" : "Jump to which comment?";
241
- const input = el("input", { type: "text", autofocus: true, autocomplete: "off", spellcheck: "false" });
242
- const miss = el("p", { class: "spell-jump-miss", role: "alert", hidden: true });
243
- const approve = el("ui-button", { class: "approve", color: "primary" }, "Go");
400
+ const epicPage = document.body.classList.contains("plan-doc")
401
+ const header = epicPage ? "Jump to which item?" : search ? "Jump to a comment, or search" : "Jump to which comment?"
402
+ const input = el("input", { type: "text", autofocus: true, autocomplete: "off", spellcheck: "false" })
403
+ const miss = el("p", { class: "spell-jump-miss", role: "alert", hidden: true })
404
+ const approve = el("ui-button", { class: "approve", color: "primary" }, "Go")
244
405
  const waiting = jumpWaitingList((id) => {
245
- input.value = id;
246
- approve.click();
247
- });
406
+ input.value = id
407
+ approve.click()
408
+ })
248
409
  const modal = el(
249
410
  "ui-modal",
250
411
  { size: "tiny", closedby: "closerequest", heading: header, "data-spell-added": true },
@@ -254,81 +415,98 @@ function openJumpPrompt(go, canGo, { search, host } = {}) {
254
415
  el(
255
416
  "label",
256
417
  { class: "ui-native spell-jump" },
257
- epicPage ? "Its id: J7, q3, P2, C3 ..." : search ? "A comment's id (C3), any id on the page, or words to search the site" : "Its id: C3, or any id on the page",
418
+ epicPage
419
+ ? "Its id: J7, q3, P2, C3 ..."
420
+ : search
421
+ ? "A comment's id (C3), any id on the page, or words to search the site"
422
+ : "Its id: C3, or any id on the page",
258
423
  input
259
424
  ),
260
425
  miss,
261
426
  waiting
262
427
  ),
263
428
  el("ui-actions", {}, el("ui-button", { class: "cancel" }, "Cancel"), approve)
264
- );
265
- let target = "";
266
- let thread = "";
267
- let words = "";
429
+ )
430
+ let target = ""
431
+ let thread = ""
432
+ let words = ""
268
433
  input.addEventListener("keydown", (event) => {
269
- if (event.key !== "Enter") return;
270
- event.preventDefault();
271
- approve.click();
272
- });
273
- input.addEventListener("input", () => miss.hidden = true);
434
+ if (event.key !== "Enter") return
435
+ // its default would press what has the focus by then: a comment's thread takes it to its fold, which folds it
436
+ event.preventDefault()
437
+ approve.click()
438
+ })
439
+ input.addEventListener("input", () => (miss.hidden = true))
274
440
  modal.addEventListener("ui-approving", (event) => {
275
- const typed = input.value.trim();
276
- const id = typed.replace(/^#/, "").toLowerCase();
277
- const comment = commentsOnPage()?.find(id);
441
+ const typed = input.value.trim()
442
+ const id = typed.replace(/^#/, "").toLowerCase()
443
+ const comment = commentsOnPage()?.find(id)
278
444
  if (comment) {
279
- thread = comment.id;
280
- return;
445
+ thread = comment.id
446
+ return
281
447
  }
282
448
  if (id && canGo(id)) {
283
- target = id;
284
- return;
449
+ target = id
450
+ return
285
451
  }
286
452
  if (search && typed && !ID_LIKE.test(typed)) {
287
- words = typed;
288
- return;
453
+ words = typed
454
+ return
289
455
  }
290
- event.preventDefault();
291
- miss.textContent = id ? `No ${typed} on this page.` : "Type an id first.";
292
- miss.hidden = false;
293
- input.select();
294
- });
456
+ // stays open: says what it couldn't find
457
+ event.preventDefault()
458
+ miss.textContent = id ? `No ${typed} on this page.` : "Type an id first."
459
+ miss.hidden = false
460
+ input.select()
461
+ })
295
462
  modal.addEventListener(
296
463
  "ui-closed",
297
464
  () => {
298
- modal.remove();
299
- if (thread) void commentsOnPage()?.landOn(thread);
300
- else if (target) go(target);
301
- else if (words) void search(words);
465
+ modal.remove()
466
+ if (thread) void commentsOnPage()?.landOn(thread)
467
+ else if (target) go(target)
468
+ else if (words) void search(words)
302
469
  },
303
470
  { once: true }
304
- );
305
- (host ?? document.body).append(modal);
306
- modal.visible = true;
307
- void customElements.whenDefined("ui-modal").then(() => {
308
- modal.visible = true;
309
- return nextFrame(2);
310
- }).then(() => input.focus());
471
+ )
472
+ ;(host ?? document.body).append(modal)
473
+ modal.visible = true
474
+ // the input once the dialog has drawn: `autofocus` alone loses to the dialog's own focus on some opens; an element
475
+ // the page's root loads (Epic UI's) draws a frame or two later
476
+ void customElements
477
+ .whenDefined("ui-modal")
478
+ .then(() => {
479
+ modal.visible = true
480
+ return nextFrame(2)
481
+ })
482
+ .then(() => input.focus())
311
483
  }
312
- __name(openJumpPrompt, "openJumpPrompt");
484
+
485
+ /**
486
+ * The jump dialog's list of the threads waiting on the person (Claude spoke last; `PageComments.waitingOnPerson`), in page
487
+ * order: a line each, "C3 · his first words", that `pick(label)` takes; `undefined` when none wait, or the page takes
488
+ * no comments.
489
+ * - Spell UI's menu (epic `epic-engine` P3): a `<ui-menu direction="vertical" appearance="secondary link">`, its title a header item, each line
490
+ * a `<ui-item>` button, so it takes the focus, and Enter
491
+ */
313
492
  function jumpWaitingList(pick) {
314
- const waiting = commentsOnPage()?.waitingInPageOrder() ?? [];
315
- if (!waiting.length) return void 0;
316
- const title = waiting.length === 1 ? "Waiting on you:" : `${waiting.length} waiting on you:`;
493
+ const waiting = commentsOnPage()?.waitingInPageOrder() ?? []
494
+ if (!waiting.length) return undefined
495
+ const title = waiting.length === 1 ? "Waiting on you:" : `${waiting.length} waiting on you:`
317
496
  const lines = waiting.map((comment) => {
318
- const label = ThreadFacts.label(comment.id);
319
- const tip = `${ThreadFacts.aboutTip({ id: comment.id, place: comment })}
320
- (Jump there)`;
497
+ const label = ThreadFacts.label(comment.id)
498
+ const tip = `${ThreadFacts.aboutTip({ id: comment.id, place: comment })}\n(Jump there)`
321
499
  const line = el(
322
500
  "ui-item",
323
501
  { class: "spell-jump-thread", title: tip },
324
502
  el("b", {}, label),
325
503
  " · ",
326
504
  el("span", {}, firstWords(comment.text))
327
- );
328
- line.addEventListener("click", () => pick(label));
329
- titleInside(line, "item");
330
- return line;
331
- });
505
+ )
506
+ line.addEventListener("click", () => pick(label))
507
+ titleInside(line, "item")
508
+ return line
509
+ })
332
510
  return el(
333
511
  "ui-menu",
334
512
  {
@@ -340,21 +518,12 @@ function jumpWaitingList(pick) {
340
518
  },
341
519
  el("ui-item", { class: "spell-jump-waiting-title", kind: "header" }, title),
342
520
  ...lines
343
- );
521
+ )
344
522
  }
345
- __name(jumpWaitingList, "jumpWaitingList");
523
+
524
+ /** Is `event`'s key typed into a field (an input, a textarea, a select, editable text)? */
346
525
  function typingIn(event) {
347
- return event.composedPath().some((node) => node instanceof Element && (node.isContentEditable || node.matches(`${FIELDS}, textarea, input`)));
526
+ return event
527
+ .composedPath()
528
+ .some((node) => node instanceof Element && (node.isContentEditable || node.matches(`${FIELDS}, textarea, input`)))
348
529
  }
349
- __name(typingIn, "typingIn");
350
- export {
351
- accessLetters,
352
- markCurrent,
353
- removeToolbar,
354
- shortLabel,
355
- titledItems,
356
- toolbarItem,
357
- toolbarMenu,
358
- toolbarTools,
359
- wireJumpKey
360
- };