spell 0.8.7 → 0.8.8

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 (243) hide show
  1. package/README-epics.md +96 -36
  2. package/app/package.json +25 -1
  3. package/dist/cli/publish/PublishedPackage.d.ts +2 -1
  4. package/dist/cli/publish/PublishedPackage.js +6 -3
  5. package/dist/cli/publish/ScratchInstall.d.ts +14 -3
  6. package/dist/cli/publish/ScratchInstall.js +69 -8
  7. package/dist/epic/cli/EpicProgram.js +7 -1
  8. package/dist/epic/cli/epicGroups.js +2 -1
  9. package/dist/epic/command/BaseBranch.d.ts +35 -0
  10. package/dist/epic/command/BaseBranch.js +58 -0
  11. package/dist/epic/command/EpicCheckout.d.ts +1 -1
  12. package/dist/epic/command/EpicCheckout.js +4 -4
  13. package/dist/epic/command/EpicGuide.js +3 -2
  14. package/dist/epic/command/EpicTools.d.ts +5 -0
  15. package/dist/epic/command/EpicTools.js +14 -3
  16. package/dist/epic/command/MainMerge.d.ts +26 -15
  17. package/dist/epic/command/MainMerge.js +60 -16
  18. package/dist/epic/command/RepoInit.d.ts +116 -8
  19. package/dist/epic/command/RepoInit.js +308 -13
  20. package/dist/epic/command/Requests.d.ts +1 -0
  21. package/dist/epic/command/Requests.js +6 -1
  22. package/dist/epic/command/SessionMoves.js +2 -1
  23. package/dist/epic/command/SkillsCheck.js +3 -2
  24. package/dist/epic/command/Stock.js +3 -1
  25. package/dist/epic/command/TurnEnd.d.ts +1 -1
  26. package/dist/epic/command/TurnEnd.js +4 -3
  27. package/dist/epic/command/Worktrees.d.ts +18 -3
  28. package/dist/epic/command/Worktrees.js +38 -7
  29. package/dist/epic/command/command.types.d.ts +3 -0
  30. package/dist/epic/components/__pack/epics.entry.js +43 -43
  31. package/dist/epic/components/__pack/epics.pack.js +36 -12794
  32. package/dist/epic/config/EngineFiles.mjs +60 -0
  33. package/dist/epic/config/EpicConfig.d.ts +12 -2
  34. package/dist/epic/config/EpicConfig.js +9 -1
  35. package/dist/epic/config/GitHub.d.ts +41 -1
  36. package/dist/epic/config/GitHub.js +75 -3
  37. package/dist/epic/config/LayeredSettings.js +3 -2
  38. package/dist/epic/server/EpicServer.d.ts +1 -1
  39. package/dist/epic/server/EpicServer.js +26 -12
  40. package/dist/epic/tool/InboxPoller.mjs +2 -1
  41. package/dist/epic/tool/MigrateCommands.js +6 -8
  42. package/dist/epic/tool/PlanDocFiles.js +3 -2
  43. package/dist/epic/tool/ServedFolders.d.ts +1 -1
  44. package/dist/epic/tool/ServedFolders.js +4 -4
  45. package/dist/epic/tools/PageInboxes.js +3 -3
  46. package/dist/epic/tools/_assets/commands.entry.js +149 -68
  47. package/dist/epic/tools/_assets/commands.js +20 -2073
  48. package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
  49. package/dist/epic/tools/_assets/core-reference.js +20 -2142
  50. package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
  51. package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
  52. package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
  53. package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
  54. package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
  55. package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
  56. package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
  57. package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
  58. package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
  59. package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
  60. package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
  61. package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
  62. package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
  63. package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
  64. package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
  65. package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
  66. package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
  67. package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
  68. package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
  69. package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
  70. package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
  71. package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
  72. package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
  73. package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
  74. package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
  75. package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
  76. package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
  77. package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
  78. package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
  79. package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
  80. package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
  81. package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
  82. package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
  83. package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
  84. package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
  85. package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
  86. package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
  87. package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
  88. package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
  89. package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
  90. package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
  91. package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
  92. package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
  93. package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
  94. package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
  95. package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
  96. package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
  97. package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
  98. package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
  99. package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
  100. package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
  101. package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
  102. package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
  103. package/dist/epic/tools/_assets/goals-live.js +318 -210
  104. package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
  105. package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
  106. package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
  107. package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
  108. package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
  109. package/dist/epic/tools/_assets/spell-comments.js +24 -3716
  110. package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
  111. package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
  112. package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
  113. package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
  114. package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
  115. package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
  116. package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
  117. package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
  118. package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
  119. package/dist/epic/tools/pages.d.ts +5 -6
  120. package/dist/epic/tools/pages.js +7 -6
  121. package/dist/epic/window.mjs +2 -3
  122. package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
  123. package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
  124. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
  125. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
  126. package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
  127. package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
  128. package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
  129. package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
  130. package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
  131. package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
  132. package/dist/ui/components/ui-card/UICards.d.ts +31 -0
  133. package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
  134. package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
  135. package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
  136. package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
  137. package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
  138. package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
  139. package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
  140. package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
  141. package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
  142. package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
  143. package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
  144. package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
  145. package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
  146. package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
  147. package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
  148. package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
  149. package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
  150. package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
  151. package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
  152. package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
  153. package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
  154. package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
  155. package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
  156. package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
  157. package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
  158. package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
  159. package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
  160. package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
  161. package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
  162. package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
  163. package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
  164. package/dist/ui/components/ui-list/UIList.d.ts +2 -0
  165. package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
  166. package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
  167. package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
  168. package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
  169. package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
  170. package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
  171. package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
  172. package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
  173. package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
  174. package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
  175. package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
  176. package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
  177. package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
  178. package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
  179. package/dist/ui/components/ui-parts/UIHeader.d.ts +3 -1
  180. package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
  181. package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
  182. package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
  183. package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
  184. package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
  185. package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
  186. package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
  187. package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
  188. package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
  189. package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
  190. package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
  191. package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
  192. package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
  193. package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
  194. package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
  195. package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
  196. package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
  197. package/dist/ui/components/ui-section/UISections.d.ts +1 -0
  198. package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
  199. package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
  200. package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
  201. package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
  202. package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
  203. package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
  204. package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
  205. package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
  206. package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
  207. package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
  208. package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
  209. package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
  210. package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
  211. package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
  212. package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
  213. package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
  214. package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
  215. package/dist/ui/components/ui-table/UICell.d.ts +1 -0
  216. package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
  217. package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
  218. package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
  219. package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
  220. package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
  221. package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
  222. package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
  223. package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
  224. package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
  225. package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
  226. package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
  227. package/dist/util/spell/constants.js +1 -1
  228. package/epic/.claude-plugin/plugin.json +1 -1
  229. package/epic/.codex-plugin/plugin.json +1 -1
  230. package/epic/hooks/handoff.mjs +4 -3
  231. package/epic/hooks/worktree.mjs +22 -3
  232. package/epic/package.json +41 -2
  233. package/epic/skills/details/SKILL.md +2 -1
  234. package/epic/skills/epic/SKILL.md +7 -1
  235. package/epic/skills/epic/guide.md +4 -0
  236. package/epic/skills/isolate/SKILL.md +35 -0
  237. package/epic/src/AGENTS.md +6 -2
  238. package/epic/templates/durable.html +1 -1
  239. package/epic/vscode/package.json +1 -1
  240. package/epic/vscode/spell-epic.vsix +0 -0
  241. package/package.json +1 -1
  242. package/parser/package.json +1 -1
  243. package/ui/package.json +15 -2
@@ -1,222 +1,345 @@
1
- var __defProp = Object.defineProperty;
2
- var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
-
4
- // src/tools/_assets/spell-comments.entry.js
5
- import { nextFrame } from "spell/util/dom";
6
- import { clamp } from "spell/util/number";
7
- import { wireComments } from "./spell-doc-comments.js";
8
- import { el } from "./spell-doc-helpers.js";
9
- import { markCurrent, titledItems, toolbarMenu, wireJumpKey } from "./spell-doc-toolbar.js";
10
- var PAGE_MAIN = "main#main";
11
- var PAGE_EVENT = "spell-site:navigated";
12
- var MOUNTED_CLASS = "site-mounted";
13
- var READY_MS = 1e4;
14
- var PAGE_BAR_CLASS = "site-sticky-bar";
15
- var SECTIONS_TOP = "--site-sections-top";
16
- var LANDING_MS = 350;
17
- var READING_LINE = 0.2;
18
- var GLIDE_QUIET_MS = 200;
19
- var GLIDE_MAX_MS = 2e3;
20
- var SHEETS = ["spell-comments.css", "spell-toolbar.css"].map(
1
+ /**
2
+ * Entry of `spell-comments.js`: the docs pages' TOOLBAR and COMMENTS, for the pages that load Spell UI's site bundle
3
+ * instead of the docs bundle (epic `epic-engine` P2, T3; the toolbar since T11).
4
+ * - Epic UI's pages (`src/docs/`, served at `/components/epics/`), and App UI's and Brand's (spell-app's
5
+ * `packages/<set>/docs/`, at `/components/app/`, `/components/brand/`): each loads it in its `<head>`, after the
6
+ * site's (their layouts load the epics pack, whose elements draw the threads and the pane):
7
+ *
8
+ * <script defer src="/_epic/assets/spell-comments.js"></script>
9
+ *
10
+ * - Built by `node src/tools/bundle-spell-ui.js` beside `spell-ui.js` (`--comments`: only this one, which needs no
11
+ * UI build); edit THIS, never the bundle.
12
+ * - NO Spell UI in it, so a page never has two (epic `epic-engine` I18: two copies handle every event twice): the
13
+ * toolbar and the comments make `<ui-*>` markup, and the page's own Spell UI draws it; a toast goes through the
14
+ * page's `window.SpellUI` (the sets' build of the site sets it). A plain IIFE, no global of its own:
15
+ * `window.SpellUI` stays the page's. The build checks it (`checkNoSpellUI()`).
16
+ * - Its look: `spell-comments.css` and `spell-toolbar.css`, beside this script, linked as it runs (the docs pages have
17
+ * them through `spell-doc.css`). The site has no `spell-doc.css`, so the sheets name the tokens they read for
18
+ * `.site-main` too.
19
+ * - THE TOOLBAR (`wireToolbar()`; Owen, 2026-10-20: "Epic UI pages should have a toolbar"): a guide's, built by the
20
+ * same code (`spell-doc-toolbar.js`): a sticky band at the top of the page's article, under the site's masthead,
21
+ * one button per top-level section, the comments' bullhorn at its right, the section being read marked
22
+ * - a `<ui-sticky class="site-sticky-bar">`: the site's own page bar (`SiteSections`' `PAGE_BAR`), so the site
23
+ * sticks the section titles below it and lands links below both
24
+ * - the site's "On this page" column stays (1200px and wider): it lists every section, nested ones too, and holds
25
+ * the site's header and look controls; the toolbar is the page's top level and its comments (epic `epic-engine`
26
+ * T11, J)
27
+ * - CMD / CTRL + K (`wireJumpKey()`, the docs pages' own): a comment's id, or any id on the page; anything else
28
+ * typed goes to the site's search, which Cmd / Ctrl + K opened before (`searchSite()`; `/` still opens it
29
+ * straight away). Only on a page that takes comments: elsewhere the key stays the search's.
30
+ * - WHEN: once the site has put the page in its layout (`html.site-mounted`) and `<ui-root>` is defined; then again
31
+ * for each page the site's router swaps in (its `spell-site:navigated` event): the last page's taken down first
32
+ * (`wire()`'s `signal`), what's typed there and not saved yet sent.
33
+ * - The comments only on a page the page server serves (`window.SPELL_SERVER`), that takes comments:
34
+ * `wireComments()` asks.
35
+ * - Not on a docs page or an epic page: their runtime wires the toolbar and the comments (`spell-doc-runtime.js`).
36
+ */
37
+
38
+ import { nextFrame } from "spell/util/dom"
39
+ import { clamp } from "spell/util/number"
40
+ import { wireComments } from "./spell-doc-comments.js"
41
+ import { el } from "./spell-doc-helpers.js"
42
+ import { markCurrent, titledItems, toolbarMenu, wireJumpKey } from "./spell-doc-toolbar.js"
43
+
44
+ /** The page's own content box, as the site names it (`PAGE_MAIN`, `packages/ui/site/_src/site.types.ts`). */
45
+ const PAGE_MAIN = "main#main"
46
+
47
+ /** What the site's router dispatches on `document` once it swapped another page in (`SiteRouter`'s `PAGE_EVENT`). */
48
+ const PAGE_EVENT = "spell-site:navigated"
49
+
50
+ /** The class the site puts on `<html>` once its layout is in (`SiteShell`'s `MOUNTED_CLASS`). */
51
+ const MOUNTED_CLASS = "site-mounted"
52
+
53
+ /** How long to wait for the site's layout and `<ui-root>`, ms: a page that never mounts gets its comments anyway. */
54
+ const READY_MS = 10_000
55
+
56
+ /** The site's page bar (`SiteSections`' `PAGE_BAR`): it sticks below the site's top, the section titles below it. */
57
+ const PAGE_BAR_CLASS = "site-sticky-bar"
58
+
59
+ /** The line the site's section titles stick at, px, on `main` (`SiteSections`' `--site-sections-top`). */
60
+ const SECTIONS_TOP = "--site-sections-top"
61
+
62
+ /** How long a jump's landing takes the site (`SiteSections`, through Spell UI's `HashLanding`: the root ready, the unfold, a few frames), ms. */
63
+ const LANDING_MS = 350
64
+
65
+ /** Where a section becomes the current one, as a share of the window's height: Spell UI's toc's `READING_LINE`. */
66
+ const READING_LINE = 0.2
67
+
68
+ /** A toolbar click's section stays marked until the page has scrolled to it and been still this long, ms. */
69
+ const GLIDE_QUIET_MS = 200
70
+
71
+ /** ... and no longer than this after the click, ms, whatever the scroll does. */
72
+ const GLIDE_MAX_MS = 2000
73
+
74
+ /** The sheets: beside this script, wherever it's served from. */
75
+ const SHEETS = ["spell-comments.css", "spell-toolbar.css"].map(
21
76
  (name) => new URL(name, document.currentScript?.src ?? location.href).href
22
- );
23
- var wiring = null;
24
- linkSheets();
25
- if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", () => void wire(), { once: true });
26
- else void wire();
27
- document.addEventListener(PAGE_EVENT, () => void wire());
28
- wireJumpKey(go, canGo, { search: searchSite, host: /* @__PURE__ */ __name(() => document.querySelector("ui-root.site"), "host"), first: true });
77
+ )
78
+
79
+ /** The current page's wiring: aborted when the router swaps the next page in. */
80
+ let wiring = null
81
+
82
+ linkSheets()
83
+ if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", () => void wire(), { once: true })
84
+ else void wire()
85
+ document.addEventListener(PAGE_EVENT, () => void wire())
86
+ wireJumpKey(go, canGo, { search: searchSite, host: () => document.querySelector("ui-root.site"), first: true })
87
+
88
+ /** Wire the toolbar and comments of the page shown, once the site is ready; the last page's taken down first. */
29
89
  async function wire() {
30
- wiring?.abort();
31
- const controller = wiring = new AbortController();
32
- const { signal } = controller;
33
- await siteReady();
34
- const main = document.querySelector(PAGE_MAIN);
35
- if (!main || signal.aborted) return;
36
- wireToolbar(main, { signal });
37
- await wireComments(main, { signal, go });
90
+ wiring?.abort()
91
+ const controller = (wiring = new AbortController())
92
+ const { signal } = controller
93
+ await siteReady()
94
+ const main = document.querySelector(PAGE_MAIN)
95
+ if (!main || signal.aborted) return
96
+ wireToolbar(main, { signal })
97
+ await wireComments(main, { signal, go })
38
98
  }
39
- __name(wire, "wire");
99
+
100
+ /**
101
+ * The page's TOOLBAR (see the header): a `<ui-sticky class="site-sticky-bar">` first in the page's article, holding
102
+ * the toolbar's menu (`toolbarMenu()`, titled), a button per top-level `<ui-section>` (`titledItems()`: its number and
103
+ * its title, `1` `Example`); none without sections.
104
+ * - a page in TABS (a components page's Examples, Usage, API, Theming: Brand's element pages): the SHOWN pane's
105
+ * sections, its bar first in that pane; drawn again for the next pane as the tabs switch (`ui-opened`), the
106
+ * comments' bullhorn kept (`toolbarMenu()` keeps what was added to the row); a pane without sections, none
107
+ * - before: one bar in the first pane, a button for every pane's sections, the hidden ones' too
108
+ * - the section being read marked (`markCurrent()`): the last whose top has reached the line the site sticks titles
109
+ * at (`--site-sections-top`, which counts the bar)
110
+ * - a click lands as the site lands any `#id` link (`SiteSections`: unfolded, below the stuck titles)
111
+ * - the site measured again once it's drawn (a `resize`): its titles stick below the bar, its links land below it
112
+ * - SIDE EFFECT: the bar in `main` (`data-spell-added`: the comments step around it); a scroll, a resize and a
113
+ * `ui-opened` listener, until `signal`
114
+ */
40
115
  function wireToolbar(main, { signal }) {
41
- const sections = topSections(main);
42
- const tabs = sections[0]?.parentElement?.closest("ui-tab")?.closest("ui-tabs");
43
- if (!tabs) return drawToolbar(sections, { signal });
44
- let pane = null;
45
- const drawPane = /* @__PURE__ */ __name(() => {
46
- pane?.abort();
47
- pane = new AbortController();
48
- signal.addEventListener("abort", () => pane.abort(), { once: true, signal: pane.signal });
49
- const shown = [...tabs.querySelectorAll(":scope > ui-tab")].find(isShownPane);
116
+ const sections = topSections(main)
117
+ const tabs = sections[0]?.parentElement?.closest("ui-tab")?.closest("ui-tabs")
118
+ if (!tabs) return drawToolbar(sections, { signal })
119
+ // the toolbar drawn for the pane shown now: aborted for the next
120
+ let pane = null
121
+ const drawPane = () => {
122
+ pane?.abort()
123
+ pane = new AbortController()
124
+ signal.addEventListener("abort", () => pane.abort(), { once: true, signal: pane.signal })
125
+ const shown = [...tabs.querySelectorAll(":scope > ui-tab")].find(isShownPane)
50
126
  drawToolbar(
51
127
  sections.filter((section) => section.parentElement.closest("ui-tab") === shown),
52
128
  { signal: pane.signal }
53
- );
54
- }, "drawPane");
129
+ )
130
+ }
55
131
  tabs.addEventListener(
56
132
  "ui-opened",
57
133
  (event) => event.target.parentElement === tabs && requestAnimationFrame(drawPane),
58
134
  {
59
135
  signal
60
136
  }
61
- );
62
- drawPane();
137
+ )
138
+ drawPane()
63
139
  }
64
- __name(wireToolbar, "wireToolbar");
140
+
141
+ /**
142
+ * Draw the toolbar over `sections`, first in their parent (the page's article, or a tab's pane); none, none.
143
+ * - `signal`: takes it down again (the bar, its listeners); what the comments added to its row is kept for the next
144
+ * (`toolbarMenu()`)
145
+ */
65
146
  function drawToolbar(sections, { signal }) {
66
- if (!sections.length) return;
147
+ if (!sections.length) return
67
148
  const groups = sections.map((element) => ({
68
149
  element,
69
150
  id: element.id,
70
151
  label: sectionLabel(element),
71
- glyph: element.querySelector(':scope > ui-icon[slot="icon"]')?.getAttribute("name") ?? element.getAttribute("icon") ?? void 0
72
- }));
152
+ glyph:
153
+ element.querySelector(':scope > ui-icon[slot="icon"]')?.getAttribute("name") ??
154
+ element.getAttribute("icon") ??
155
+ undefined
156
+ }))
73
157
  const toolbar = toolbarMenu(
74
158
  titledItems(groups, () => []),
75
159
  // under a page's tabs: pills as the tabs are
76
160
  { titled: true, segmented: !!sections[0].closest("ui-tabs") }
77
- );
78
- for (const old of document.querySelectorAll(`.${PAGE_BAR_CLASS}.spell-site-toolbar`)) old.remove();
79
- const bar = el("ui-sticky", { class: `${PAGE_BAR_CLASS} spell-site-toolbar`, "data-spell-added": true }, toolbar);
80
- const article = sections[0].parentElement;
81
- article.prepend(bar);
82
- toolbar.addEventListener("click", glideTo, { signal });
83
- const remeasure = /* @__PURE__ */ __name(() => !signal.aborted && dispatchEvent(new Event("resize")), "remeasure");
84
- void Promise.all(["ui-sticky", "ui-menu", "ui-item"].map((tag) => customElements.whenDefined(tag))).then(() => nextFrame(2)).then(remeasure);
85
- let scheduled = false;
86
- let held = void 0;
87
- let quiet = 0;
88
- let heldSince = 0;
89
- const release = /* @__PURE__ */ __name(() => {
90
- held = void 0;
91
- follow();
92
- }, "release");
93
- const holdQuiet = /* @__PURE__ */ __name(() => {
94
- clearTimeout(quiet);
95
- quiet = setTimeout(release, clamp(heldSince + GLIDE_MAX_MS - Date.now(), 0, GLIDE_QUIET_MS));
96
- }, "holdQuiet");
161
+ )
162
+ for (const old of document.querySelectorAll(`.${PAGE_BAR_CLASS}.spell-site-toolbar`)) old.remove()
163
+ const bar = el("ui-sticky", { class: `${PAGE_BAR_CLASS} spell-site-toolbar`, "data-spell-added": true }, toolbar)
164
+ const article = sections[0].parentElement
165
+ article.prepend(bar)
166
+ toolbar.addEventListener("click", glideTo, { signal })
167
+ // the site re-measures its sticky lines on a resize: now the bar is in, and once it has drawn
168
+ const remeasure = () => !signal.aborted && dispatchEvent(new Event("resize"))
169
+ void Promise.all(["ui-sticky", "ui-menu", "ui-item"].map((tag) => customElements.whenDefined(tag)))
170
+ .then(() => nextFrame(2))
171
+ .then(remeasure)
172
+ let scheduled = false
173
+ // a clicked item is the current one at once, and stays so while the page glides to its section,
174
+ // until the scroll has been still for `GLIDE_QUIET_MS` (`GLIDE_MAX_MS` at most):
175
+ // following the scroll meanwhile flipped the mark through every section passed
176
+ let held = undefined
177
+ let quiet = 0
178
+ let heldSince = 0
179
+ const release = () => {
180
+ held = undefined
181
+ follow()
182
+ }
183
+ const holdQuiet = () => {
184
+ clearTimeout(quiet)
185
+ quiet = setTimeout(release, clamp(heldSince + GLIDE_MAX_MS - Date.now(), 0, GLIDE_QUIET_MS))
186
+ }
97
187
  toolbar.addEventListener(
98
188
  "click",
99
189
  (event) => {
100
- const item = event.composedPath().find((node) => node.localName === "ui-item" && node.hasAttribute("data-rail"));
101
- if (!item) return;
102
- held = item.dataset.rail;
103
- heldSince = Date.now();
104
- markCurrent(toolbar, held);
105
- holdQuiet();
190
+ const item = event.composedPath().find((node) => node.localName === "ui-item" && node.hasAttribute("data-rail"))
191
+ if (!item) return
192
+ held = item.dataset.rail
193
+ heldSince = Date.now()
194
+ markCurrent(toolbar, held)
195
+ holdQuiet()
106
196
  },
107
197
  { signal }
108
- );
109
- const follow = /* @__PURE__ */ __name(() => {
110
- if (held !== void 0) return holdQuiet();
111
- if (scheduled) return;
112
- scheduled = true;
198
+ )
199
+ const follow = () => {
200
+ if (held !== undefined) return holdQuiet()
201
+ if (scheduled) return
202
+ scheduled = true
113
203
  requestAnimationFrame(() => {
114
- scheduled = false;
204
+ scheduled = false
115
205
  if (!signal.aborted)
116
- markCurrent(toolbar, currentSection(document.querySelector(PAGE_MAIN), sections)?.id ?? sections[0].id);
117
- });
118
- }, "follow");
119
- signal.addEventListener("abort", () => clearTimeout(quiet), { once: true });
120
- addEventListener("scroll", follow, { passive: true, signal });
121
- addEventListener("resize", follow, { passive: true, signal });
122
- follow();
206
+ markCurrent(toolbar, currentSection(document.querySelector(PAGE_MAIN), sections)?.id ?? sections[0].id)
207
+ })
208
+ }
209
+ signal.addEventListener("abort", () => clearTimeout(quiet), { once: true })
210
+ addEventListener("scroll", follow, { passive: true, signal })
211
+ addEventListener("resize", follow, { passive: true, signal })
212
+ follow()
123
213
  }
124
- __name(drawToolbar, "drawToolbar");
214
+
215
+ /** Is `<ui-tab>` `tab` the pane its `<ui-tabs>` shows (its `:state(selected)`)? No `:state()`: unless hidden. */
125
216
  function isShownPane(tab) {
126
217
  try {
127
- return tab.matches(":state(selected)");
218
+ return tab.matches(":state(selected)")
128
219
  } catch {
129
- return !tab.hidden;
220
+ return !tab.hidden
130
221
  }
131
222
  }
132
- __name(isShownPane, "isShownPane");
223
+
224
+ /** The page's top-level `<ui-section>`s: its article's own, else every one not inside another (or an example). */
133
225
  function topSections(main) {
134
- const article = main.querySelector(".site-article");
135
- const own = article ? [...article.querySelectorAll(":scope > ui-section[id]")] : [];
136
- if (own.length) return own;
226
+ const article = main.querySelector(".site-article")
227
+ const own = article ? [...article.querySelectorAll(":scope > ui-section[id]")] : []
228
+ if (own.length) return own
137
229
  return [...main.querySelectorAll("ui-section[id]")].filter(
138
230
  (section) => !section.parentElement?.closest("ui-section, ui-example, template")
139
- );
231
+ )
140
232
  }
141
- __name(topSections, "topSections");
233
+
234
+ /** A `<ui-section>`'s label: its `label`, else the text of its `slot="label"` child. */
142
235
  function sectionLabel(section) {
143
- const label = section.getAttribute("label")?.trim();
144
- if (label) return label;
145
- const slotted = section.querySelector(':scope > [slot="label"]');
146
- return slotted?.textContent.replace(/\s+/g, " ").trim() ?? section.id;
236
+ const label = section.getAttribute("label")?.trim()
237
+ if (label) return label
238
+ const slotted = section.querySelector(':scope > [slot="label"]')
239
+ return slotted?.textContent.replace(/\s+/g, " ").trim() ?? section.id
147
240
  }
148
- __name(sectionLabel, "sectionLabel");
241
+
242
+ /**
243
+ * The last of `sections` whose top has reached the reading line; none above the first.
244
+ * - Its own copy of Spell UI's rule (`TocIndex.current()`), on purpose: this script bundles no Spell UI
245
+ * (`checkNoSpellUI()`), and the site's bundle doesn't offer it to the page
246
+ * - the line: the "On this page" list's, never above the line the site sticks its titles at
247
+ * - at the page's end, the last one showing on screen:
248
+ * a short last section can't scroll up to the line, so a click on it would leave the one above marked
249
+ */
149
250
  function currentSection(main, sections) {
150
- const padding = parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) || 0;
151
- const stuck = (parseFloat(main.style.getPropertyValue(SECTIONS_TOP)) || 0) + 4;
152
- const line = Math.max(stuck, padding + innerHeight * READING_LINE);
153
- const atEnd = scrollY + innerHeight >= document.documentElement.scrollHeight - 2;
154
- let current;
251
+ // the "On this page" list's reading line (Spell UI's `TocIndex.current()`: the page's scroll padding and a fifth
252
+ // of the window), so the toolbar and that list mark the same section
253
+ const padding = parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) || 0
254
+ const stuck = (parseFloat(main.style.getPropertyValue(SECTIONS_TOP)) || 0) + 4
255
+ const line = Math.max(stuck, padding + innerHeight * READING_LINE)
256
+ const atEnd = scrollY + innerHeight >= document.documentElement.scrollHeight - 2
257
+ let current
155
258
  for (const section of sections) {
156
- const box = section.getBoundingClientRect();
157
- if (!box.height && !box.width) continue;
158
- if (box.top > (atEnd ? innerHeight - 1 : line)) break;
159
- current = section;
259
+ const box = section.getBoundingClientRect()
260
+ if (!box.height && !box.width) continue
261
+ if (box.top > (atEnd ? innerHeight - 1 : line)) break
262
+ current = section
160
263
  }
161
- return current;
264
+ return current
162
265
  }
163
- __name(currentSection, "currentSection");
266
+
267
+ /**
268
+ * A click on a section's button GLIDES there, rather than the whole page jumping.
269
+ * - the browser's own jump to `#id` is stopped, and the address set without a scroll
270
+ * - then a `hashchange` tells the site to land there (`SiteSections`: a smooth scroll, the stuck bars put)
271
+ * - a click with a modifier (a new tab, a new window) is left to the browser
272
+ */
164
273
  function glideTo(event) {
165
- if (event.defaultPrevented || event.button !== 0) return;
166
- if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
167
- const item = event.composedPath().find((node) => node.localName === "ui-item" && node.hasAttribute("data-rail"));
168
- const hash = item?.getAttribute("href");
169
- if (!hash?.startsWith("#")) return;
170
- event.preventDefault();
171
- const oldURL = location.href;
172
- history.pushState(history.state, "", hash);
173
- dispatchEvent(new HashChangeEvent("hashchange", { oldURL, newURL: location.href }));
274
+ if (event.defaultPrevented || event.button !== 0) return
275
+ if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
276
+ const item = event.composedPath().find((node) => node.localName === "ui-item" && node.hasAttribute("data-rail"))
277
+ const hash = item?.getAttribute("href")
278
+ if (!hash?.startsWith("#")) return
279
+ event.preventDefault()
280
+ const oldURL = location.href
281
+ history.pushState(history.state, "", hash)
282
+ dispatchEvent(new HashChangeEvent("hashchange", { oldURL, newURL: location.href }))
174
283
  }
175
- __name(glideTo, "glideTo");
284
+
285
+ /**
286
+ * Land on `id` in the page shown, as a link to it does: the site's own landing (`SiteSections`, on `hashchange`:
287
+ * what hides it unfolds, it lands below the stuck titles); resolves once it has.
288
+ * - the address cleared first, so the same `#id` again still lands
289
+ */
176
290
  async function go(id) {
177
291
  if (decodeURIComponent(location.hash.slice(1)) === id)
178
- history.replaceState(history.state, "", `${location.pathname}${location.search}`);
179
- location.hash = id;
180
- await new Promise((resolve) => setTimeout(resolve, LANDING_MS));
292
+ history.replaceState(history.state, "", `${location.pathname}${location.search}`)
293
+ location.hash = id
294
+ await new Promise((resolve) => setTimeout(resolve, LANDING_MS))
181
295
  }
182
- __name(go, "go");
296
+
297
+ /** Is there an element `id` in the page shown? */
183
298
  function canGo(id) {
184
- const element = document.getElementById(id);
185
- return !!element && !!document.querySelector(PAGE_MAIN)?.contains(element);
299
+ const element = document.getElementById(id)
300
+ return !!element && !!document.querySelector(PAGE_MAIN)?.contains(element)
186
301
  }
187
- __name(canGo, "canGo");
302
+
303
+ /**
304
+ * Search the site for `words`: its search field (`<ui-docs-search>`, in the side column's nav, or the narrow
305
+ * screens' flyout), summoned as Cmd / Ctrl + K summoned it before, the words typed in.
306
+ * - the visible field, else one in a drawer (the flyout: `summon()` opens it), as the site's own key picks
307
+ */
188
308
  async function searchSite(words) {
189
- const fields = [...document.querySelectorAll("ui-docs-nav")].map((nav) => nav.shadowRoot?.querySelector("ui-docs-search") ?? nav.querySelector("ui-docs-search")).filter(Boolean);
190
- const field = fields.find((each) => each.checkVisibility()) ?? fields[0];
191
- if (!field?.summon) return;
192
- await field.summon();
193
- const input = field.shadowRoot?.querySelector('input[part~="input"]') ?? field.shadowRoot?.querySelector("input");
194
- if (!input) return;
195
- input.value = words;
196
- input.dispatchEvent(new InputEvent("input", { bubbles: true, composed: true, inputType: "insertText", data: words }));
309
+ const fields = [...document.querySelectorAll("ui-docs-nav")]
310
+ .map((nav) => nav.shadowRoot?.querySelector("ui-docs-search") ?? nav.querySelector("ui-docs-search"))
311
+ .filter(Boolean)
312
+ const field = fields.find((each) => each.checkVisibility()) ?? fields[0]
313
+ if (!field?.summon) return
314
+ await field.summon()
315
+ const input = field.shadowRoot?.querySelector('input[part~="input"]') ?? field.shadowRoot?.querySelector("input")
316
+ if (!input) return
317
+ input.value = words
318
+ input.dispatchEvent(new InputEvent("input", { bubbles: true, composed: true, inputType: "insertText", data: words }))
197
319
  }
198
- __name(searchSite, "searchSite");
320
+
321
+ /** Resolves once the site's layout is in and `<ui-root>` defined, or after `READY_MS`. NEVER rejects. */
199
322
  function siteReady() {
200
323
  const mounted = new Promise((resolve) => {
201
- if (document.documentElement.classList.contains(MOUNTED_CLASS)) return resolve();
324
+ if (document.documentElement.classList.contains(MOUNTED_CLASS)) return resolve()
202
325
  const watch = new MutationObserver(() => {
203
- if (!document.documentElement.classList.contains(MOUNTED_CLASS)) return;
204
- watch.disconnect();
205
- resolve();
206
- });
207
- watch.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
208
- });
209
- const ready = mounted.then(() => customElements.whenDefined("ui-root"));
210
- return Promise.race([ready, new Promise((resolve) => setTimeout(resolve, READY_MS))]);
326
+ if (!document.documentElement.classList.contains(MOUNTED_CLASS)) return
327
+ watch.disconnect()
328
+ resolve()
329
+ })
330
+ watch.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] })
331
+ })
332
+ const ready = mounted.then(() => customElements.whenDefined("ui-root"))
333
+ return Promise.race([ready, new Promise((resolve) => setTimeout(resolve, READY_MS))])
211
334
  }
212
- __name(siteReady, "siteReady");
335
+
336
+ /** Link the sheets into the page's `<head>`, once each. */
213
337
  function linkSheets() {
214
338
  for (const sheet of SHEETS) {
215
- if (document.querySelector(`link[rel="stylesheet"][href="${CSS.escape(sheet)}"]`)) continue;
216
- const link = document.createElement("link");
217
- link.rel = "stylesheet";
218
- link.href = sheet;
219
- document.head.append(link);
339
+ if (document.querySelector(`link[rel="stylesheet"][href="${CSS.escape(sheet)}"]`)) continue
340
+ const link = document.createElement("link")
341
+ link.rel = "stylesheet"
342
+ link.href = sheet
343
+ document.head.append(link)
220
344
  }
221
345
  }
222
- __name(linkSheets, "linkSheets");