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.
- package/README-epics.md +96 -36
- package/app/package.json +25 -1
- package/dist/cli/publish/PublishedPackage.d.ts +2 -1
- package/dist/cli/publish/PublishedPackage.js +6 -3
- package/dist/cli/publish/ScratchInstall.d.ts +14 -3
- package/dist/cli/publish/ScratchInstall.js +69 -8
- package/dist/epic/cli/EpicProgram.js +7 -1
- package/dist/epic/cli/epicGroups.js +2 -1
- package/dist/epic/command/BaseBranch.d.ts +35 -0
- package/dist/epic/command/BaseBranch.js +58 -0
- package/dist/epic/command/EpicCheckout.d.ts +1 -1
- package/dist/epic/command/EpicCheckout.js +4 -4
- package/dist/epic/command/EpicGuide.js +3 -2
- package/dist/epic/command/EpicTools.d.ts +5 -0
- package/dist/epic/command/EpicTools.js +14 -3
- package/dist/epic/command/MainMerge.d.ts +26 -15
- package/dist/epic/command/MainMerge.js +60 -16
- package/dist/epic/command/RepoInit.d.ts +116 -8
- package/dist/epic/command/RepoInit.js +308 -13
- package/dist/epic/command/Requests.d.ts +1 -0
- package/dist/epic/command/Requests.js +6 -1
- package/dist/epic/command/SessionMoves.js +2 -1
- package/dist/epic/command/SkillsCheck.js +3 -2
- package/dist/epic/command/Stock.js +3 -1
- package/dist/epic/command/TurnEnd.d.ts +1 -1
- package/dist/epic/command/TurnEnd.js +4 -3
- package/dist/epic/command/Worktrees.d.ts +18 -3
- package/dist/epic/command/Worktrees.js +38 -7
- package/dist/epic/command/command.types.d.ts +3 -0
- package/dist/epic/components/__pack/epics.entry.js +43 -43
- package/dist/epic/components/__pack/epics.pack.js +36 -12794
- package/dist/epic/config/EngineFiles.mjs +60 -0
- package/dist/epic/config/EpicConfig.d.ts +12 -2
- package/dist/epic/config/EpicConfig.js +9 -1
- package/dist/epic/config/GitHub.d.ts +41 -1
- package/dist/epic/config/GitHub.js +75 -3
- package/dist/epic/config/LayeredSettings.js +3 -2
- package/dist/epic/server/EpicServer.d.ts +1 -1
- package/dist/epic/server/EpicServer.js +26 -12
- package/dist/epic/tool/InboxPoller.mjs +2 -1
- package/dist/epic/tool/MigrateCommands.js +6 -8
- package/dist/epic/tool/PlanDocFiles.js +3 -2
- package/dist/epic/tool/ServedFolders.d.ts +1 -1
- package/dist/epic/tool/ServedFolders.js +4 -4
- package/dist/epic/tools/PageInboxes.js +3 -3
- package/dist/epic/tools/_assets/commands.entry.js +149 -68
- package/dist/epic/tools/_assets/commands.js +20 -2073
- package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
- package/dist/epic/tools/_assets/core-reference.js +20 -2142
- package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
- package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
- package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
- package/dist/epic/tools/_assets/goals-live.js +318 -210
- package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
- package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
- package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
- package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
- package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
- package/dist/epic/tools/_assets/spell-comments.js +24 -3716
- package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
- package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
- package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
- package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
- package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
- package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
- package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
- package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
- package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
- package/dist/epic/tools/pages.d.ts +5 -6
- package/dist/epic/tools/pages.js +7 -6
- package/dist/epic/window.mjs +2 -3
- package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
- package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
- package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
- package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
- package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
- package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
- package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
- package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
- package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
- package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
- package/dist/ui/components/ui-card/UICards.d.ts +31 -0
- package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
- package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
- package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
- package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
- package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
- package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
- package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
- package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
- package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
- package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
- package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
- package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
- package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
- package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
- package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
- package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
- package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
- package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
- package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
- package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
- package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
- package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
- package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
- package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
- package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
- package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
- package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
- package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
- package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
- package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
- package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
- package/dist/ui/components/ui-list/UIList.d.ts +2 -0
- package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
- package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
- package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
- package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
- package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
- package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIHeader.d.ts +3 -1
- package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
- package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
- package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
- package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
- package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
- package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
- package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
- package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
- package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
- package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
- package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
- package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
- package/dist/ui/components/ui-section/UISections.d.ts +1 -0
- package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
- package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
- package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
- package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
- package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
- package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
- package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
- package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
- package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
- package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
- package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
- package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
- package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
- package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
- package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
- package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
- package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
- package/dist/ui/components/ui-table/UICell.d.ts +1 -0
- package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
- package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
- package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
- package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
- package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
- package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
- package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
- package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
- package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
- package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
- package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
- package/dist/util/spell/constants.js +1 -1
- package/epic/.claude-plugin/plugin.json +1 -1
- package/epic/.codex-plugin/plugin.json +1 -1
- package/epic/hooks/handoff.mjs +4 -3
- package/epic/hooks/worktree.mjs +22 -3
- package/epic/package.json +41 -2
- package/epic/skills/details/SKILL.md +2 -1
- package/epic/skills/epic/SKILL.md +7 -1
- package/epic/skills/epic/guide.md +4 -0
- package/epic/skills/isolate/SKILL.md +35 -0
- package/epic/src/AGENTS.md +6 -2
- package/epic/templates/durable.html +1 -1
- package/epic/vscode/package.json +1 -1
- package/epic/vscode/spell-epic.vsix +0 -0
- package/package.json +1 -1
- package/parser/package.json +1 -1
- package/ui/package.json +15 -2
|
@@ -1,13 +1,89 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
1
|
+
/*
|
|
2
|
+
* Page behaviour for the `.html` docs.
|
|
3
|
+
* Bundled into `spell-ui.js` (a classic IIFE, beside spell-ui) by `scripts/bundle-spell-ui.js`;
|
|
4
|
+
* side effects only. The page's markup is hand-authored; this only DRIVES it.
|
|
5
|
+
* - Two page markups, read into ONE outline (`outlineOf()`) that everything below works from:
|
|
6
|
+
* - SECTIONS (every page but the saga pages):
|
|
7
|
+
* `<ui-section id label sticky collapsible dividing>` in `main`, nested for sub-sections,
|
|
8
|
+
* `open="false"` to start folded.
|
|
9
|
+
* - the element draws the title, the fold button, the rule and the stack of stuck titles
|
|
10
|
+
* - this runtime sets the top-level `offset`s, remembers folds, writes counts
|
|
11
|
+
* - an EPIC PAGE is `<epic-page>` markup (the `epics` pack, `spell-epic`):
|
|
12
|
+
* its folding blocks (`<epic-overview>`, `<epic-section>`, `<epic-phase>`, `EPIC_FOLDS`) are its sections.
|
|
13
|
+
* They draw and stick themselves, count their items, filter them,
|
|
14
|
+
* and draw the page header, the review line, the commits and every review control;
|
|
15
|
+
* this runtime only lists them (each host's `contentsEntry`, with label, icon and count),
|
|
16
|
+
* remembers their folds, and lands links inside them
|
|
17
|
+
* - HEADINGS (the saga pages): `section.s2|s3` > `<ui-sticky class="spell-h2|spell-h3">` > `<h2|h3 id>`;
|
|
18
|
+
* this runtime adds the fold chevrons and every sticky's `offset`
|
|
19
|
+
* - the TOOLBAR, the page's one navigation (epic `airplane` P8; the floating right-edge rail before):
|
|
20
|
+
* a row of the top-level sections' buttons, the last row of the sticky page header (`buildPageToolbar()`)
|
|
21
|
+
* - mark and title, the titles shrinking, then gone on a narrow window
|
|
22
|
+
* - No contents list: Owen, 2026-10-08
|
|
23
|
+
* - an EPIC PAGE's (`buildToolbar()`): its blocks' icons only, with badges of the items waiting on the person,
|
|
24
|
+
* in `<epic-page>`'s header; and Cmd / Ctrl + K asks for an item to jump to (`wireJumpKey()`)
|
|
25
|
+
* - at its right, on any page that takes comments, a bullhorn counting the threads waiting on the person,
|
|
26
|
+
* landing on the next at each click (`PageComments.drawWaiting()`); Cmd / Ctrl + K takes a comment's id too (`C3`)
|
|
27
|
+
* - sticky headers: the page header (`ui-sticky.spell-h1`) sticks at the top, each top-level title below it,
|
|
28
|
+
* nested ones below their parents' (re-measured on resize);
|
|
29
|
+
* CSS variables on the sections let anchors land below them all
|
|
30
|
+
* - everything that sticks or lands at the top starts BELOW the fixed site header (`<spell-site-header>`,
|
|
31
|
+
* `siteHeaderHeight()`): the page header and its toolbar, the titles
|
|
32
|
+
* - folding: every section folds from a chevron on its title; folds are remembered per page, and `open="false"`
|
|
33
|
+
* (`data-fold="closed"` on HEADINGS pages) starts one folded
|
|
34
|
+
* - counts: a top-level section holding `[data-status]` items (the Epics index's epic cards, the saga pages' items)
|
|
35
|
+
* shows open / all on its title;
|
|
36
|
+
* the toolbar shows, with a red badge, how many NEED OWEN (none: no badge; `countItems()`);
|
|
37
|
+
* an epic card section also gets state chips with counts, filtering its items (`wireItemFilters()`)
|
|
38
|
+
* - scroll-follow: the toolbar's button of the section being read is highlighted, and the address follows it
|
|
39
|
+
* - links to any id in `main` (a section, a heading, a plan item) land below the stuck titles,
|
|
40
|
+
* unfolding what hides it; a `#hash` in another case than the page's id (`#T1` for `t1`) lands too
|
|
41
|
+
* - SHORT ADDRESSES (`wireAddresses()`, epic `epic-workflow` P15):
|
|
42
|
+
* a link to `SAGA:/<saga>[/<epic>][#<id>]` becomes the saga or epic page and its `#id`, so both kinds of link work
|
|
43
|
+
* - the CHEATSHEET card filters
|
|
44
|
+
* - highlight.js, when the page loaded it
|
|
45
|
+
* - COMMENTS (`wireComments()`), served by the page server:
|
|
46
|
+
* - a bullhorn beside every major block (and in the page header), and ⌘ I or a floating bullhorn on selected text,
|
|
47
|
+
* which open a comment box under the block
|
|
48
|
+
* - the comments wait in an inbox file (a docs page's own, an epic page's review inbox), drawn under their blocks
|
|
49
|
+
* - their own module, `spell-doc-comments.js` (epic `epic-engine` P2), which Epic UI's pages load alone too
|
|
50
|
+
* - PAGE NOTES (`wireNotes()`), written into docs pages before them: each `<spell-note>` a folded card
|
|
51
|
+
* - SCREENSHOTS open full size (`wireImageZoom()`, epic `epic-engine` I129): a click on a content image (one shown
|
|
52
|
+
* smaller than its size, in a `<figure>`, or in a link to an image) shows it over the page, in Spell UI's
|
|
53
|
+
* `<ui-zoom>` (epic `ui-gaps` P14), never following its link; the rule is `ImageZoom`'s
|
|
54
|
+
* - the EPICS PAGE's sort buttons, `<epic-sort>`, in its header (`wireEpicSort()`):
|
|
55
|
+
* its list, its cards' stars and saga chips are the epics pack's elements (`<epic-list>`, `<epic-card>`),
|
|
56
|
+
* which do their own
|
|
57
|
+
* LANDING -- where a jump puts its target, ONE model for every kind of jump:
|
|
58
|
+
* - the line: just below the lowest title that will be stuck over the target: site header + `--spell-top` (page
|
|
59
|
+
* header, filter bar) + the stack of the target's sections' titles
|
|
60
|
+
* - CSS `scroll-margin-top` holds that line MINUS the site header (`spell-doc.css`); the site header is added by
|
|
61
|
+
* whoever does the scrolling, once:
|
|
62
|
+
* - our jumps (link clicks, a `#hash` load, `hashchange` / `popstate`, so also `location.hash = id`):
|
|
63
|
+
* `scrollTo()` with a computed top, which `scroll-padding` never touches: `offsetFor()` adds the site header
|
|
64
|
+
* - the browser's own (a `#hash` before this runs, `scrollIntoView()`, focus):
|
|
65
|
+
* `:root`'s `scroll-padding-top`, the site header's height (`<spell-site-header>` installs it)
|
|
66
|
+
* - paging (Page Down / Up, Space): ours (`wirePaging()`), measured at the destination:
|
|
67
|
+
* the old bottom lands just below the titles stuck THERE
|
|
68
|
+
* - the browser's own paging (where ours stands aside) goes by `scroll-padding-top`:
|
|
69
|
+
* while titles are stuck, `<ui-section>` / `<ui-sticky>` (`StickyWatch`) write the lowest stuck edge
|
|
70
|
+
* as an INLINE `scroll-padding-top` on `<html>`, overriding `:root`'s; removed once none is stuck
|
|
71
|
+
* - it includes the site header: titles stick below it
|
|
72
|
+
* - that's where it STARTS, so a title that sticks on the way can cover the old bottom
|
|
73
|
+
* - NOTE: a browser jump made WHILE titles are stuck adds that inline padding to the margin, landing one stack lower:
|
|
74
|
+
* every such jump that changes the hash (`hashchange`) lands again through ours;
|
|
75
|
+
* `scrollIntoView()` from code doesn't --
|
|
76
|
+
* call `jump`'s path (a click on a `#id` link, or set `location.hash`) instead
|
|
77
|
+
* NOTE: panels open and close through the accordion's `open` PROPERTY (panel indexes as text):
|
|
78
|
+
* that's `<ui-accordion>`'s controlled state, and writing it announces nothing (`ui-opening` / `ui-closing` mean the person).
|
|
79
|
+
*/
|
|
80
|
+
|
|
81
|
+
import { nextFrame } from "spell/util/dom"
|
|
82
|
+
import { clamp } from "spell/util/number"
|
|
83
|
+
import { PrefStore } from "spell/util/persist/PrefStore"
|
|
84
|
+
import { slug } from "spell/util/string"
|
|
85
|
+
import { PagePatch } from "spell/server/site"
|
|
86
|
+
import { wireComments } from "./spell-doc-comments.js"
|
|
11
87
|
import {
|
|
12
88
|
FIELDS,
|
|
13
89
|
addBlockAction,
|
|
@@ -23,7 +99,7 @@ import {
|
|
|
23
99
|
restoreEpicFolds,
|
|
24
100
|
titleInside,
|
|
25
101
|
writeJSON
|
|
26
|
-
} from "./spell-doc-helpers.js"
|
|
102
|
+
} from "./spell-doc-helpers.js"
|
|
27
103
|
import {
|
|
28
104
|
removeToolbar,
|
|
29
105
|
shortLabel,
|
|
@@ -32,16 +108,21 @@ import {
|
|
|
32
108
|
toolbarMenu,
|
|
33
109
|
toolbarTools,
|
|
34
110
|
wireJumpKey
|
|
35
|
-
} from "./spell-doc-toolbar.js"
|
|
36
|
-
import { readingTime } from "
|
|
37
|
-
import { EpicAddress, PageTargets } from "
|
|
38
|
-
import { PageStages } from "
|
|
39
|
-
import { ServerLink } from "
|
|
40
|
-
|
|
41
|
-
import {
|
|
42
|
-
import {
|
|
43
|
-
|
|
44
|
-
|
|
111
|
+
} from "./spell-doc-toolbar.js"
|
|
112
|
+
import { readingTime } from "spell/epic/tools/ReadingTime.js"
|
|
113
|
+
import { EpicAddress, PageTargets } from "spell/epic/links"
|
|
114
|
+
import { PageStages } from "spell/epic/phases"
|
|
115
|
+
import { ServerLink } from "spell/epic/review"
|
|
116
|
+
// plain DOM, no Solid: the element it opens, `<ui-zoom>`, is Spell UI's, which this bundle loads like any other
|
|
117
|
+
import { ImageZoom } from "spell/ui/components/ui-zoom/ImageZoom"
|
|
118
|
+
import { ComponentPacks } from "spell/ui/components/ui-components"
|
|
119
|
+
// the doc-only families' plain-DOM leaves, bundled from source (`bundle-spell-ui.js`): Spell UI's docs land links and
|
|
120
|
+
// follow the scroll the same way (epic `coherence` P11)
|
|
121
|
+
import { HashLanding } from "spell/ui/components/ui-toc/HashLanding"
|
|
122
|
+
import { TocIndex } from "spell/ui/components/ui-toc/TocIndex"
|
|
123
|
+
|
|
124
|
+
/** Custom elements this runtime drives: wait for their definitions before wiring. */
|
|
125
|
+
const TAGS = [
|
|
45
126
|
"ui-accordion",
|
|
46
127
|
"ui-title",
|
|
47
128
|
"ui-content",
|
|
@@ -56,806 +137,1362 @@ var TAGS = [
|
|
|
56
137
|
"ui-section",
|
|
57
138
|
// installs `--spell-site-header-height`, which every sticky line starts from
|
|
58
139
|
"spell-site-header"
|
|
59
|
-
]
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
140
|
+
]
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Frames a `<ui-section>` takes to draw what opening it (`open`) revealed: the write lands on a microtask, the
|
|
144
|
+
* render on the next frame. A jump lands only then: before, the target is laid out in a box of no height.
|
|
145
|
+
*/
|
|
146
|
+
const UNFOLD_FRAMES = 2
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* When a jump on a `<ui-section>` page lands once more, unless the reader scrolled since:
|
|
150
|
+
* a fold the BROWSER opened (a `#hash` load reveals `hidden="until-found"` content itself) grows with its transition
|
|
151
|
+
* (`--ui-section-duration`, 300ms) and moves the target a few pixels after the first landing.
|
|
152
|
+
*/
|
|
153
|
+
const SETTLE_MS = 450
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* The events a fold sends as the reader opens or closes it, and a source host as its body arrives:
|
|
157
|
+
* - a `<ui-section>`'s (`ui-opening`, `ui-closing`; its old names went in epic `repo-split` P14)
|
|
158
|
+
* - an `<epic-*>` block's and a `<ui-accordion>`'s (`ui-opening`, `ui-closing`)
|
|
159
|
+
* - every source host's body: `ui-loaded` (Spell UI's `LoadableBody`, the `<epic-*>` blocks' too)
|
|
160
|
+
*/
|
|
161
|
+
const OPENING = ["ui-opening", "ui-opening"]
|
|
162
|
+
const CLOSING = ["ui-closing", "ui-closing"]
|
|
163
|
+
const LOADED = "ui-loaded"
|
|
164
|
+
|
|
165
|
+
/** How long a closing fold's header is held in place (`holdWhileFolding()`): its transition (300ms) and a margin. */
|
|
166
|
+
const FOLD_HOLD_MS = 600
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* How long a live reload holds the page at its saved scroll (`holdScroll()`), ms: while the folds it put back draw,
|
|
170
|
+
* and their parts load.
|
|
171
|
+
*/
|
|
172
|
+
const RESTORE_HOLD_MS = 1500
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* How long a part's body swapped in may hold the old one on screen, in ms (`reloadBody()`'s cross-fade): the page
|
|
176
|
+
* shows the old frame meanwhile, and takes no clicks
|
|
177
|
+
*/
|
|
178
|
+
const BODY_WAIT_MS = 1000
|
|
179
|
+
|
|
180
|
+
/** What the reader does that stops the page landing by itself: he's moving it. */
|
|
181
|
+
const READER_INPUT = ["wheel", "touchstart", "keydown", "pointerdown"]
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* An epic page's folding blocks (`spell-epic`): its sections, in the outline, the folds and the landing.
|
|
185
|
+
* Each host has `open` (page state) and `contentsEntry` (`EpicFoldHost`).
|
|
186
|
+
*/
|
|
187
|
+
const EPIC_FOLDS = "epic-overview, epic-section, epic-phase"
|
|
188
|
+
|
|
189
|
+
/** What a link into an epic page opens on its way: the folding blocks, and the items (which fold too). */
|
|
190
|
+
const EPIC_OPENERS = `${EPIC_FOLDS}, epic-item`
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* The fields that fold inside an epic page's blocks (`<epic-field>`, epic `epic-engine` I167): `reveal()` opens one a
|
|
194
|
+
* link or a comment lands in, through its own `reveal()`.
|
|
195
|
+
*/
|
|
196
|
+
const FIELDS_THAT_FOLD = "epic-field"
|
|
197
|
+
|
|
198
|
+
/** Every element the outline takes for a section: `<ui-section>`s and an epic page's folding blocks. */
|
|
199
|
+
const SECTIONS = `ui-section, ${EPIC_FOLDS}`
|
|
200
|
+
/** What folds, for `holdWhileFolding()`: the sections and epic blocks, and accordions (asides, code) */
|
|
201
|
+
const FOLDING = `${SECTIONS}, ui-accordion`
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* How long `start()` waits for an epic page's elements (the `epics` pack, loaded by `<ui-root>`) to define and draw,
|
|
205
|
+
* before listing the page without them: a pack that never loads must not hold up the rest.
|
|
206
|
+
*/
|
|
207
|
+
const EPIC_WAIT_MS = 5000
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* The `epics` pack's script at the engine's route (`EpicServer`'s `/_epic/pack/`), as epic pages name it:
|
|
211
|
+
* what `loadEpicsPack()` loads on a page that names none.
|
|
212
|
+
*/
|
|
213
|
+
const EPICS_PACK = "/_epic/pack/epics.pack.js"
|
|
214
|
+
|
|
215
|
+
/** The docs head's h1, its title (`oneLineHead()`): an epic page has none, `<epic-page>` draws its own. */
|
|
216
|
+
const PAGE_TITLE = ":scope > ui-sticky.spell-h1 > .spell-page-head > h1"
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Space between the stuck titles and an element a link lands on inside an epic page, px: the page's own lander's
|
|
220
|
+
* (`landingLine()`), the ONE landing on an epic page since epic `coherence` P18.
|
|
221
|
+
*/
|
|
222
|
+
const EPIC_LAND_GAP = 8
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* `localStorage` key prefix of a page's card filter: then its path, or the name its input gives (`data-spell-filter`).
|
|
226
|
+
* - per page: every `file://` page shares one origin, so one key would leak a filter between cheat sheets
|
|
227
|
+
* - a named one was kept under its name alone before epic `prefs-and-undo` P4: moved over once (`wireFilter()`)
|
|
228
|
+
*/
|
|
229
|
+
const FILTER_KEY_PREFIX = "spell-filter:"
|
|
230
|
+
|
|
231
|
+
/** `localStorage` key prefix of a page's folds (`{ [section or heading id]: folded }`), per page like the filter's. */
|
|
232
|
+
const FOLD_KEY_PREFIX = "spell-folds:"
|
|
233
|
+
|
|
234
|
+
/** `sessionStorage` key prefix of the folds a live reload puts back (`{ [id]: open }`, `keepFoldsForReload()`). */
|
|
235
|
+
const KEPT_FOLDS_KEY_PREFIX = "spell-doc:kept-folds:"
|
|
236
|
+
|
|
237
|
+
/**
|
|
238
|
+
* `localStorage` key prefix of a page's item filters (`{ [section id]: [states shown] }`), per page.
|
|
239
|
+
* - `<epic-section>`'s own key too (its `FILTER_KEY`), the same shape
|
|
240
|
+
* - NOTE: not `spell-item-filter:`, Open | All's before P3 of `review-review`: its saved "open" meant "not done"
|
|
241
|
+
*/
|
|
242
|
+
const ITEM_FILTER_KEY_PREFIX = "spell-item-state:"
|
|
243
|
+
|
|
244
|
+
/** How long a page coming up stays still (`quietFor()`): its folds put back and its scroll held (`RESTORE_HOLD_MS`). */
|
|
245
|
+
const QUIET_LOAD_MS = 2500
|
|
246
|
+
|
|
247
|
+
/** How long a live patch keeps the page still (`quietFor()`): its re-wiring, a frame or two, and what settles after. */
|
|
248
|
+
const QUIET_PATCH_MS = 900
|
|
249
|
+
|
|
250
|
+
/** The timer ending the page's quiet (`quietFor()`). */
|
|
251
|
+
let quietTimer = 0
|
|
252
|
+
|
|
253
|
+
/** The listeners of the last `wireFolds()` call: aborted by the next, so a rebuilt page doesn't double them. */
|
|
254
|
+
let foldWiring = null
|
|
255
|
+
|
|
256
|
+
// still, from the first moment: a page coming up draws its folds and marks as they ARE, never animating into them
|
|
257
|
+
quietFor(QUIET_LOAD_MS)
|
|
258
|
+
if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start, { once: true })
|
|
259
|
+
else void start()
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* QUIET (Owen, 2026-10-25: "part of the reason the page continually flashes is that you are running animations when
|
|
263
|
+
* updating / reloading the page ... if page is already loaded, skip the animations"): no motion for `ms` from now,
|
|
264
|
+
* longer if asked again meanwhile.
|
|
265
|
+
* - `<html data-spell-quiet>`: `spell-doc.css` sets every duration token to 0s under it (Spell UI's
|
|
266
|
+
* `--ui-duration-*`, `--ui-section-duration`, the epic elements' `--epic-*-duration`), which reach every shadow root
|
|
267
|
+
* - the page's load (until it has settled: folds put back, the scroll held) and every live patch; a fold the reader
|
|
268
|
+
* clicks after that still animates
|
|
269
|
+
*/
|
|
89
270
|
function quietFor(ms) {
|
|
90
|
-
const root = document.documentElement
|
|
91
|
-
root.dataset.spellQuiet = ""
|
|
92
|
-
clearTimeout(quietTimer)
|
|
93
|
-
quietTimer = setTimeout(() => delete root.dataset.spellQuiet, ms)
|
|
271
|
+
const root = document.documentElement
|
|
272
|
+
root.dataset.spellQuiet = ""
|
|
273
|
+
clearTimeout(quietTimer)
|
|
274
|
+
quietTimer = setTimeout(() => delete root.dataset.spellQuiet, ms)
|
|
94
275
|
}
|
|
95
|
-
|
|
276
|
+
|
|
277
|
+
////////////////
|
|
278
|
+
// ## Start
|
|
279
|
+
////////////////
|
|
280
|
+
|
|
281
|
+
/** Highlight at once (plain DOM); wire the widgets once their elements are defined. */
|
|
96
282
|
async function start() {
|
|
97
|
-
loadEpicsPack()
|
|
98
|
-
nameTab()
|
|
99
|
-
const main = document.querySelector("main.spell-doc-main") ?? document.querySelector("main")
|
|
100
|
-
if (!main) return
|
|
101
|
-
|
|
102
|
-
const
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
283
|
+
loadEpicsPack()
|
|
284
|
+
nameTab()
|
|
285
|
+
const main = document.querySelector("main.spell-doc-main") ?? document.querySelector("main")
|
|
286
|
+
if (!main) return
|
|
287
|
+
// where to land, read before anything scrolls: scroll-follow rewrites the address as the page moves
|
|
288
|
+
const landing = { hash: hashId(), scroll: window.SPELL_SERVER?.takeScroll?.() }
|
|
289
|
+
// a LIVE reload (the page's code changed) comes back as the reader left it: every fold, and the scroll
|
|
290
|
+
const kept = takeKeptFolds(landing.scroll !== undefined)
|
|
291
|
+
keepFoldsForReload(main)
|
|
292
|
+
if (landing.scroll !== undefined) {
|
|
293
|
+
// never the section the address names: `<epic-*>` blocks follow the address's `#hash` by themselves as they
|
|
294
|
+
// first connect, and landed on its top (I23 of `epic-engine`); the address follows the scroll again once landed
|
|
295
|
+
landing.hash = undefined
|
|
296
|
+
if (location.hash) history.replaceState(history.state, "", `${location.pathname}${location.search}`)
|
|
297
|
+
}
|
|
298
|
+
// an old phase address (`#p7`) shows the phase's stable id it landed on (`addressedId()`)
|
|
299
|
+
else if (landing.hash && landing.hash !== TocIndex.decode(location.hash.slice(1)))
|
|
300
|
+
history.replaceState(null, "", `#${landing.hash}`)
|
|
301
|
+
// listening at once: an edit that comes in while this is still wiring waits for `live.ready()`
|
|
302
|
+
const live = wireLiveUpdate(main)
|
|
303
|
+
editMarkdownInPlace([main])
|
|
304
|
+
highlight()
|
|
305
|
+
addCodeCopies(main)
|
|
306
|
+
wireImageZoom()
|
|
307
|
+
// an epic page: its saved folds before its blocks first draw (so nothing animates), then the blocks, which the
|
|
308
|
+
// outline reads (their labels, icons and counts)
|
|
114
309
|
if (main.querySelector("epic-page")) {
|
|
115
310
|
restoreEpicFolds(main.querySelectorAll(kept ? EPIC_OPENERS : EPIC_FOLDS), {
|
|
116
311
|
saved: readJSON(`${FOLD_KEY_PREFIX}${location.pathname}`),
|
|
117
312
|
kept
|
|
118
|
-
})
|
|
119
|
-
await epicsDrawn(main)
|
|
120
|
-
}
|
|
121
|
-
const outline = outlineOf(main)
|
|
122
|
-
oneLineHead(main)
|
|
123
|
-
wireReadingTime(main)
|
|
124
|
-
const counts = countItems(outline)
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
const
|
|
129
|
-
|
|
130
|
-
const
|
|
131
|
-
|
|
132
|
-
const
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
const
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
313
|
+
})
|
|
314
|
+
await epicsDrawn(main)
|
|
315
|
+
}
|
|
316
|
+
const outline = outlineOf(main)
|
|
317
|
+
oneLineHead(main)
|
|
318
|
+
wireReadingTime(main)
|
|
319
|
+
const counts = countItems(outline)
|
|
320
|
+
// the saga pages (HEADINGS) get no filter, but their id chips are coloured by state too
|
|
321
|
+
if (outline.sections) wireItemFilters(main)
|
|
322
|
+
else markItemStates(main)
|
|
323
|
+
const rail = buildNavigation(main, outline, counts)
|
|
324
|
+
// before the sections first draw, so a saved fold doesn't animate shut
|
|
325
|
+
const folds = wireFolds(main, outline, kept)
|
|
326
|
+
addFoldAll(main, folds)
|
|
327
|
+
const used = TAGS.filter((tag) => document.querySelector(tag))
|
|
328
|
+
await Promise.all(used.map((tag) => customElements.whenDefined(tag)))
|
|
329
|
+
const sticky = trackStickyHeights(main, outline)
|
|
330
|
+
const follow = followScroll(main, outline, rail)
|
|
331
|
+
// before the anchors: a short address into this page becomes a `#id` link they take
|
|
332
|
+
wireAddresses()
|
|
333
|
+
const { jump, go, canGo } = wireAnchors(main, outline, sticky, follow, folds)
|
|
334
|
+
wirePaging(main)
|
|
335
|
+
wireJumpKey(go, canGo)
|
|
336
|
+
wireFilter(main)
|
|
337
|
+
wireTableWidths(main)
|
|
338
|
+
wireTwoColumnTables(main)
|
|
339
|
+
wireTableHeads(main)
|
|
340
|
+
wireStuckTrail(main)
|
|
341
|
+
// UI renders its shadow content a little after the definitions: land once it has
|
|
342
|
+
await nextFrame(2)
|
|
343
|
+
sticky.measure()
|
|
344
|
+
land(landing, jump, follow)
|
|
345
|
+
// a live reload held the new page behind the old one until now: it cross-fades in, landed and themed (I164)
|
|
346
|
+
void Promise.resolve(window.SpellUI?.themed).then(() => window.SPELL_SERVER?.reveal?.())
|
|
347
|
+
live.ready({ main, rail, sticky, follow, entries: railKey(outline, counts) })
|
|
348
|
+
wireNotes(main)
|
|
349
|
+
void wireComments(main, { go, pageFolds: folds })
|
|
350
|
+
stackWrappedSteps(main)
|
|
351
|
+
wireNewEpic(main)
|
|
352
|
+
wireEpicSort(main)
|
|
353
|
+
// the docs index tool rewrites this page after a new epic: its header comes back without the pill and the sort
|
|
153
354
|
addEventListener("spell-doc:updated", () => {
|
|
154
|
-
wireNewEpic(main)
|
|
155
|
-
wireEpicSort(main)
|
|
156
|
-
})
|
|
355
|
+
wireNewEpic(main)
|
|
356
|
+
wireEpicSort(main)
|
|
357
|
+
})
|
|
157
358
|
}
|
|
158
|
-
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* Load the `epics` pack on EVERY page this runtime runs on (epic `epic-engine` P3), so an `<epic-*>` element in it,
|
|
362
|
+
* written or drawn by our tools, upgrades: a guide, a list or details page, the changelog, not only an epic page.
|
|
363
|
+
* - Through `ComponentPacks.load()`, as `<ui-root>` loads a `<ui-components source>`: ONE script per page, keyed by
|
|
364
|
+
* its URL, the pack registered once. So a page that names the pack already (an epic page's root, a saga page's old
|
|
365
|
+
* path) loads it by THAT source, and its root's load and this one are the same.
|
|
366
|
+
* - No `<ui-root>` needed: the pack defines its tags for the whole document. Most guides have none.
|
|
367
|
+
* - Async (a `<script>` added): it never holds up the first paint, or `start()`.
|
|
368
|
+
* An element made before it registers upgrades as it does; wait with `customElements.whenDefined()`.
|
|
369
|
+
* - A pack that can't load (a page from `file://`): a console warning, and the page goes on without.
|
|
370
|
+
*/
|
|
159
371
|
function loadEpicsPack() {
|
|
160
|
-
const declared = [...document.querySelectorAll("ui-components[source]")]
|
|
161
|
-
|
|
372
|
+
const declared = [...document.querySelectorAll("ui-components[source]")]
|
|
373
|
+
.map((element) => element.getAttribute("source"))
|
|
374
|
+
.find((source) => source && ComponentPacks.nameFor(new URL(source, document.baseURI).href) === "epics")
|
|
375
|
+
ComponentPacks.load(declared ?? EPICS_PACK).catch((error) => console.warn("spell-doc: the epics pack", error))
|
|
162
376
|
}
|
|
163
|
-
|
|
377
|
+
|
|
378
|
+
/**
|
|
379
|
+
* The page's head on ONE line, as an epic page's: `DOCS / SPELL SYNTAX`, the crumbs then the title,
|
|
380
|
+
* in the crumbs' own type, the title twice their size and bold (`spell-doc.css`, "The page's head on one line").
|
|
381
|
+
* - Owen, 2026-10-13: "Make the header changes in the other doc files"
|
|
382
|
+
* - a copy of the page's breadcrumb (`.spell-crumbs`, before the sticky head) goes INTO the h1, before its text;
|
|
383
|
+
* `data-spell-added`, so a live update steps around it
|
|
384
|
+
* - its last section (the page itself) stays, emptied: the title says its words;
|
|
385
|
+
* so the `/` before the title is the breadcrumb's own divider (epic `epic-engine` P3: a `<span>` of ours before)
|
|
386
|
+
* - the breadcrumb itself stays where it was, hidden (`<body class="spell-one-line-head">`):
|
|
387
|
+
* live updates still patch it, and the copy follows when the page reloads
|
|
388
|
+
* - a page with no breadcrumb: the title alone, in the same type
|
|
389
|
+
*/
|
|
164
390
|
function oneLineHead(main) {
|
|
165
|
-
const h1 = main.querySelector(PAGE_TITLE)
|
|
166
|
-
if (!h1) return
|
|
167
|
-
document.body.classList.add("spell-one-line-head")
|
|
168
|
-
const crumbs = main.querySelector(":scope > ui-breadcrumbs.spell-crumbs")
|
|
169
|
-
if (!crumbs || h1.querySelector(":scope > .spell-head-crumbs")) return
|
|
170
|
-
const trail = crumbs.cloneNode(true)
|
|
171
|
-
trail.classList.add("spell-head-crumbs")
|
|
172
|
-
trail.dataset.spellAdded = ""
|
|
173
|
-
trail.removeAttribute("id")
|
|
174
|
-
const page = trail.querySelector(":scope > ui-breadcrumb[selected]")
|
|
391
|
+
const h1 = main.querySelector(PAGE_TITLE)
|
|
392
|
+
if (!h1) return
|
|
393
|
+
document.body.classList.add("spell-one-line-head")
|
|
394
|
+
const crumbs = main.querySelector(":scope > ui-breadcrumbs.spell-crumbs")
|
|
395
|
+
if (!crumbs || h1.querySelector(":scope > .spell-head-crumbs")) return
|
|
396
|
+
const trail = crumbs.cloneNode(true)
|
|
397
|
+
trail.classList.add("spell-head-crumbs")
|
|
398
|
+
trail.dataset.spellAdded = ""
|
|
399
|
+
trail.removeAttribute("id")
|
|
400
|
+
const page = trail.querySelector(":scope > ui-breadcrumb[selected]")
|
|
175
401
|
if (page) {
|
|
176
|
-
page.textContent = ""
|
|
402
|
+
page.textContent = ""
|
|
403
|
+
// the space before it too: the divider sits as the old one did, `spell-doc.css` spacing it
|
|
177
404
|
if (page.previousSibling?.nodeType === Node.TEXT_NODE && !page.previousSibling.textContent.trim())
|
|
178
|
-
page.previousSibling.remove()
|
|
405
|
+
page.previousSibling.remove()
|
|
179
406
|
}
|
|
180
|
-
h1.prepend(trail)
|
|
407
|
+
h1.prepend(trail)
|
|
181
408
|
}
|
|
182
|
-
|
|
409
|
+
|
|
410
|
+
/**
|
|
411
|
+
* The READING TIME chip, right after the page's title (epic `epic-engine` P14, Q5):
|
|
412
|
+
* `SOLID 2 · 48 min read`, a quiet `<ui-label>` (`spell-doc.css`, "The reading time chip").
|
|
413
|
+
* - its tooltip: the exact count, "8,749 words, 2,281 of them code" (`readingTime()`, `ReadingTime.js`)
|
|
414
|
+
* - every page with the docs head: guides, the index pages, details and choice pages
|
|
415
|
+
* - NOT an epic or saga page: `<epic-page>` draws its own head, and its own chip, counting only what's SHOWN
|
|
416
|
+
* (`shownReadingTime()`; J91, Owen: "Count what's shown"): its items' bodies wait in part files until opened
|
|
417
|
+
* - recounted on every `spell-doc:updated`: an edit saved, a section's body loaded
|
|
418
|
+
*/
|
|
183
419
|
function wireReadingTime(main) {
|
|
184
|
-
drawReadingTime(main)
|
|
185
|
-
addEventListener("spell-doc:updated", () => drawReadingTime(main))
|
|
420
|
+
drawReadingTime(main)
|
|
421
|
+
addEventListener("spell-doc:updated", () => drawReadingTime(main))
|
|
186
422
|
}
|
|
187
|
-
|
|
423
|
+
|
|
424
|
+
/**
|
|
425
|
+
* Draw the reading time chip at the end of the page's h1, or update the one there.
|
|
426
|
+
* - `data-spell-added`: a live update steps around it, and `readingTime()` skips it
|
|
427
|
+
*/
|
|
188
428
|
function drawReadingTime(main) {
|
|
189
|
-
const h1 = main.querySelector(PAGE_TITLE)
|
|
190
|
-
if (!h1) return
|
|
191
|
-
const { words, code, minutes } = readingTime(main)
|
|
192
|
-
let chip = h1.querySelector(":scope > ui-label.spell-reading-time")
|
|
429
|
+
const h1 = main.querySelector(PAGE_TITLE)
|
|
430
|
+
if (!h1) return
|
|
431
|
+
const { words, code, minutes } = readingTime(main)
|
|
432
|
+
let chip = h1.querySelector(":scope > ui-label.spell-reading-time")
|
|
193
433
|
if (!chip) {
|
|
194
|
-
chip = el("ui-label", { class: "spell-reading-time", size: "tiny", appearance: "basic", "data-spell-added": true })
|
|
195
|
-
h1.append(chip)
|
|
434
|
+
chip = el("ui-label", { class: "spell-reading-time", size: "tiny", appearance: "basic", "data-spell-added": true })
|
|
435
|
+
h1.append(chip)
|
|
196
436
|
}
|
|
197
|
-
const counted = code
|
|
198
|
-
|
|
199
|
-
|
|
437
|
+
const counted = code
|
|
438
|
+
? `${words.toLocaleString()} words, ${code.toLocaleString()} of them code`
|
|
439
|
+
: `${words.toLocaleString()} words`
|
|
440
|
+
if (chip.textContent !== `${minutes} min read`) chip.textContent = `${minutes} min read`
|
|
441
|
+
if (chip.title !== counted) chip.title = counted
|
|
200
442
|
}
|
|
201
|
-
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* The wide layout, every page's (`spell-doc.css`, "Layout"; epic `epic-engine` P2):
|
|
446
|
+
* every table sits in the reading column, as prose does,
|
|
447
|
+
* with an EXPAND button over its top right corner that runs it the page's full width.
|
|
448
|
+
* - Owen, 2026-10-13: "make tables fit in the column by default, but have an expand button ...
|
|
449
|
+
* Remember that setting per table"
|
|
450
|
+
* - The button is a bare icon in the table's ACTIONS ROW (`addBlockAction()`), right of its bullhorn.
|
|
451
|
+
* - `.spell-table-toggle`, a `<ui-button appearance="basic">` with no edge (`spell-doc.css`)
|
|
452
|
+
* - Owen, 2026-10-19: "The expand button should be to the right of the bullhorn rather than in its own line"
|
|
453
|
+
* - the row is a line of no height, so it takes no room; a click flips it back
|
|
454
|
+
* - Expanded, the row moves with the table: its buttons stay over the table's top right corner.
|
|
455
|
+
* - Expanded: CSS can't know how far in a table starts (a list's indent, an item's inset), so this measures it,
|
|
456
|
+
* moving the table out to the page's gutter with the page's width, less the gutter on both sides.
|
|
457
|
+
* Again whenever its parent changes size (a section or item opening, the window resizing).
|
|
458
|
+
* - Never past a box that CLIPS it (`roomFor()`): an ancestor between it and `main` that hides its overflow (an
|
|
459
|
+
* epic element's reply card, `div.reply`) would cut the widened table off on both sides (epic `epic-engine` r10:
|
|
460
|
+
* "the expand table button made the table unusable"). With less than `MIN_WIDE_GAIN` to gain on its width in the
|
|
461
|
+
* column, the button hides.
|
|
462
|
+
* - Inside a `<ui-table>`, the host is what moves.
|
|
463
|
+
* - Remembered in this browser, per page, by the table's key (`tableKey()`): `spell-table-wide:<path>`.
|
|
464
|
+
* - Tables a part's body or a live update adds later get theirs too (`eachTable()`).
|
|
465
|
+
*/
|
|
202
466
|
function wireTableWidths(main) {
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
const
|
|
206
|
-
const
|
|
467
|
+
// a page in the layout (`spell-doc.css`'s `body.spell-doc-page`), not one that only loads the bundle
|
|
468
|
+
if (!document.body.classList.contains("spell-doc-page")) return
|
|
469
|
+
const storeKey = `spell-table-wide:${location.pathname}`
|
|
470
|
+
const toggles = new Map()
|
|
471
|
+
const narrow = new WeakMap()
|
|
207
472
|
const sizes = new ResizeObserver((entries) => {
|
|
208
|
-
for (const entry of entries) for (const box of tableBoxes(entry.target)) place(box)
|
|
209
|
-
})
|
|
210
|
-
const isWide =
|
|
211
|
-
const place =
|
|
212
|
-
const toggle = toggles.get(box)
|
|
213
|
-
const parent = box.parentElement
|
|
214
|
-
if (!toggle || !parent || !box.isConnected) return
|
|
215
|
-
const row = toggle.closest(BLOCK_ROW)
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
toggle.
|
|
220
|
-
|
|
221
|
-
toggle.
|
|
222
|
-
toggle.
|
|
223
|
-
|
|
473
|
+
for (const entry of entries) for (const box of tableBoxes(entry.target)) place(box)
|
|
474
|
+
})
|
|
475
|
+
const isWide = (box) => !!readJSON(storeKey)[tableKey(box, main)]
|
|
476
|
+
const place = (box) => {
|
|
477
|
+
const toggle = toggles.get(box)
|
|
478
|
+
const parent = box.parentElement
|
|
479
|
+
if (!toggle || !parent || !box.isConnected) return
|
|
480
|
+
const row = toggle.closest(BLOCK_ROW)
|
|
481
|
+
// its width in the column, measured while not widened:
|
|
482
|
+
// the column is often the table's own `max-width`, not its parent's
|
|
483
|
+
if (!box.style.width && box.getClientRects().length) narrow.set(box, box.getBoundingClientRect().width)
|
|
484
|
+
toggle.hidden = roomWidth(box, main) <= (narrow.get(box) ?? 0) + MIN_WIDE_GAIN
|
|
485
|
+
const wide = isWide(box) && !toggle.hidden
|
|
486
|
+
toggle.toggleAttribute("selected", wide)
|
|
487
|
+
toggle.title = wide ? "Back into the column" : "Expand to the page's width"
|
|
488
|
+
toggle.setAttribute("aria-label", toggle.title)
|
|
489
|
+
toggle.setAttribute("icon", wide ? "arrows left right to line" : "arrows left right")
|
|
490
|
+
titleInside(toggle)
|
|
224
491
|
if (!wide) {
|
|
225
|
-
for (const each of [box, row]) each.style.removeProperty("margin-inline-start")
|
|
226
|
-
for (const each of [box, row]) each.style.removeProperty("width")
|
|
227
|
-
box.style.removeProperty("max-width")
|
|
228
|
-
return alignBlockActions(row)
|
|
492
|
+
for (const each of [box, row]) each.style.removeProperty("margin-inline-start")
|
|
493
|
+
for (const each of [box, row]) each.style.removeProperty("width")
|
|
494
|
+
box.style.removeProperty("max-width")
|
|
495
|
+
return alignBlockActions(row)
|
|
229
496
|
}
|
|
230
|
-
if (!parent.getClientRects().length) return
|
|
231
|
-
const room = roomFor(box, main)
|
|
232
|
-
const style = getComputedStyle(parent)
|
|
233
|
-
const contentLeft =
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
box.style.
|
|
237
|
-
box.style.
|
|
238
|
-
|
|
239
|
-
row.style.
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
const
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
toggle
|
|
253
|
-
toggle.
|
|
254
|
-
toggle.setAttribute("
|
|
255
|
-
toggle.
|
|
256
|
-
|
|
257
|
-
|
|
497
|
+
if (!parent.getClientRects().length) return
|
|
498
|
+
const room = roomFor(box, main)
|
|
499
|
+
const style = getComputedStyle(parent)
|
|
500
|
+
const contentLeft =
|
|
501
|
+
parent.getBoundingClientRect().left + parseFloat(style.borderLeftWidth) + parseFloat(style.paddingLeft)
|
|
502
|
+
const start = `${room.left - contentLeft}px`
|
|
503
|
+
box.style.maxWidth = "none"
|
|
504
|
+
box.style.width = `${room.right - room.left}px`
|
|
505
|
+
box.style.marginInlineStart = start
|
|
506
|
+
row.style.width = box.style.width
|
|
507
|
+
row.style.marginInlineStart = start
|
|
508
|
+
alignBlockActions(row)
|
|
509
|
+
}
|
|
510
|
+
const flip = (box) => {
|
|
511
|
+
const saved = readJSON(storeKey)
|
|
512
|
+
const key = tableKey(box, main)
|
|
513
|
+
if (saved[key]) delete saved[key]
|
|
514
|
+
else saved[key] = true
|
|
515
|
+
writeJSON(storeKey, saved)
|
|
516
|
+
place(box)
|
|
517
|
+
}
|
|
518
|
+
const toggleFor = (box) => {
|
|
519
|
+
const toggle = document.createElement("ui-button")
|
|
520
|
+
toggle.className = "spell-table-toggle"
|
|
521
|
+
toggle.setAttribute("appearance", "basic")
|
|
522
|
+
toggle.setAttribute("size", "mini")
|
|
523
|
+
toggle.addEventListener("click", () => flip(box))
|
|
524
|
+
return toggle
|
|
525
|
+
}
|
|
258
526
|
const redrawSoon = eachTable(main, {
|
|
259
527
|
added(box) {
|
|
260
|
-
if (!box.parentElement) return false
|
|
261
|
-
const toggle = toggleFor(box)
|
|
262
|
-
addBlockAction(box, toggle, "expand")
|
|
263
|
-
toggles.set(box, toggle)
|
|
264
|
-
sizes.observe(box.parentElement)
|
|
265
|
-
place(box)
|
|
528
|
+
if (!box.parentElement) return false
|
|
529
|
+
const toggle = toggleFor(box)
|
|
530
|
+
addBlockAction(box, toggle, "expand")
|
|
531
|
+
toggles.set(box, toggle)
|
|
532
|
+
sizes.observe(box.parentElement)
|
|
533
|
+
place(box)
|
|
266
534
|
},
|
|
267
535
|
// a table a live update replaced, or moved away from its actions row: its button goes with it
|
|
268
|
-
keeps:
|
|
536
|
+
keeps: (box) => toggles.get(box)?.closest(BLOCK_ROW)?.nextElementSibling === box,
|
|
269
537
|
gone(box) {
|
|
270
|
-
const toggle = toggles.get(box)
|
|
271
|
-
const row = toggle?.closest(BLOCK_ROW)
|
|
272
|
-
for (const name of ["width", "margin-inline-start"]) row?.style.removeProperty(name)
|
|
273
|
-
if (toggle) dropBlockAction(toggle)
|
|
274
|
-
toggles.delete(box)
|
|
538
|
+
const toggle = toggles.get(box)
|
|
539
|
+
const row = toggle?.closest(BLOCK_ROW)
|
|
540
|
+
for (const name of ["width", "margin-inline-start"]) row?.style.removeProperty(name)
|
|
541
|
+
if (toggle) dropBlockAction(toggle)
|
|
542
|
+
toggles.delete(box)
|
|
275
543
|
},
|
|
276
|
-
redraw:
|
|
277
|
-
})
|
|
278
|
-
addEventListener("resize", () => redrawSoon())
|
|
544
|
+
redraw: () => toggles.forEach((_toggle, box) => place(box))
|
|
545
|
+
})
|
|
546
|
+
addEventListener("resize", () => redrawSoon())
|
|
279
547
|
}
|
|
280
|
-
|
|
548
|
+
|
|
549
|
+
/**
|
|
550
|
+
* A TWO-COLUMN table's first column WRAPS once it would take more than 40% of the table, so the second keeps a
|
|
551
|
+
* readable measure (epic `epic-engine` I145; Owen, 2026-10-26: "table layout sucks").
|
|
552
|
+
* - its first column never wraps otherwise (`spell-doc.css`, "A TWO-COLUMN table")
|
|
553
|
+
* - at the side bar's width, a long first column held whole squeezed the second to a word per line
|
|
554
|
+
* - CSS can't say "no wider than its words, nor than 40%" for a table's cell, so this measures:
|
|
555
|
+
* - each column's width with nothing wrapped (`data-spell-measuring`, for that moment only), and the room the table
|
|
556
|
+
* has (its box's width, wide or not)
|
|
557
|
+
* - the first column whole still leaves the second a readable measure (its words whole, or 24em): nothing to do
|
|
558
|
+
* - else, a first column wider than 40% of the room wraps (`data-spell-wrap-first`), at the wider of:
|
|
559
|
+
* - 40% of the room
|
|
560
|
+
* - the room less that readable measure (so the first wraps no more than it must)
|
|
561
|
+
* - but never so wide that the second gets less than `TWO_COLUMN_MIN_SECOND` (12em of its type)
|
|
562
|
+
* - the width: `--spell-first-column`, on the table
|
|
563
|
+
* - and only when that takes 2em or more off it (`TWO_COLUMN_LEAST_GAIN`): never a word wrapped for a few px
|
|
564
|
+
* - too narrow even then (a phone): the table scrolls sideways inside its own box, as every table does
|
|
565
|
+
* - again whenever its box changes size (a section or item opening, the side bar or window resizing, the expand
|
|
566
|
+
* button), a frame at a time; tables a part's body or a live update adds later get theirs too (`eachTable()`)
|
|
567
|
+
*/
|
|
281
568
|
function wireTwoColumnTables(main) {
|
|
282
|
-
const sizes = new ResizeObserver((entries) => entries.forEach((entry) => redrawSoon(entry.target)))
|
|
569
|
+
const sizes = new ResizeObserver((entries) => entries.forEach((entry) => redrawSoon(entry.target)))
|
|
283
570
|
const redrawSoon = eachTable(main, {
|
|
284
571
|
// its first notice comes at once: the first fit
|
|
285
|
-
added:
|
|
286
|
-
redraw:
|
|
287
|
-
})
|
|
288
|
-
}
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
572
|
+
added: (box) => sizes.observe(box),
|
|
573
|
+
redraw: (boxes) => boxes.forEach((box) => fitTwoColumns(box))
|
|
574
|
+
})
|
|
575
|
+
}
|
|
576
|
+
|
|
577
|
+
/** How much of a two-column table's room its first column may take before it wraps (`wireTwoColumnTables()`). */
|
|
578
|
+
const TWO_COLUMN_FIRST_SHARE = 0.4
|
|
579
|
+
|
|
580
|
+
/** The least a two-column table's second column keeps before the table scrolls, in ems of its own type. */
|
|
581
|
+
const TWO_COLUMN_MIN_SECOND = 12
|
|
582
|
+
|
|
583
|
+
/** The least a two-column table's first column must give up to wrap at all, in ems of the body's type. */
|
|
584
|
+
const TWO_COLUMN_LEAST_GAIN = 2
|
|
585
|
+
|
|
586
|
+
/**
|
|
587
|
+
* Fit one table's box (`tableBoxes()`) as `wireTwoColumnTables()` says: wrap its first column, or not.
|
|
588
|
+
* - SIDE EFFECT: `data-spell-wrap-first` and `--spell-first-column` on its `<table>`, set or removed
|
|
589
|
+
* - a table that isn't two columns, or isn't shown, is left alone
|
|
590
|
+
*/
|
|
293
591
|
function fitTwoColumns(box) {
|
|
294
|
-
const table = tableOf(box)
|
|
295
|
-
if (!table?.isConnected || !table.getClientRects().length) return
|
|
296
|
-
const rows = [...table.rows]
|
|
297
|
-
const pair = rows.find((row) => row.cells.length === 2 && row.cells[0].colSpan === 1)
|
|
298
|
-
if (!pair || rows.some((row) => row.cells.length > 2)) return
|
|
299
|
-
table
|
|
300
|
-
|
|
301
|
-
const
|
|
302
|
-
const
|
|
303
|
-
|
|
304
|
-
const
|
|
305
|
-
|
|
306
|
-
const
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
592
|
+
const table = tableOf(box)
|
|
593
|
+
if (!table?.isConnected || !table.getClientRects().length) return
|
|
594
|
+
const rows = [...table.rows]
|
|
595
|
+
const pair = rows.find((row) => row.cells.length === 2 && row.cells[0].colSpan === 1)
|
|
596
|
+
if (!pair || rows.some((row) => row.cells.length > 2)) return
|
|
597
|
+
// with nothing wrapped: a `display: block` table is as wide as its room, its cells as wide as their words
|
|
598
|
+
table.setAttribute("data-spell-measuring", "")
|
|
599
|
+
const room = table.clientWidth
|
|
600
|
+
const [first, second] = [...pair.cells].map((cell) => cell.getBoundingClientRect().width)
|
|
601
|
+
// a body cell's type, not the header's small capitals
|
|
602
|
+
const style = getComputedStyle(rows.find((row) => row.cells[1]?.localName === "td")?.cells[1] ?? pair.cells[1])
|
|
603
|
+
table.removeAttribute("data-spell-measuring")
|
|
604
|
+
const minSecond =
|
|
605
|
+
parseFloat(style.fontSize) * TWO_COLUMN_MIN_SECOND +
|
|
606
|
+
parseFloat(style.paddingLeft) +
|
|
607
|
+
parseFloat(style.paddingRight) +
|
|
608
|
+
parseFloat(style.borderLeftWidth) +
|
|
609
|
+
parseFloat(style.borderRightWidth)
|
|
610
|
+
// what the second column needs to read well: its words whole, or twice its least, if less
|
|
611
|
+
const readable = Math.min(second, minSecond * 2)
|
|
612
|
+
const width = Math.max(0, Math.min(Math.max(room * TWO_COLUMN_FIRST_SHARE, room - readable), room - minSecond))
|
|
613
|
+
// and only for a real gain: not to take a word or two off it
|
|
614
|
+
const wraps =
|
|
615
|
+
first > room * TWO_COLUMN_FIRST_SHARE &&
|
|
616
|
+
room - first < readable &&
|
|
617
|
+
first + second > room + 1 &&
|
|
618
|
+
first - width >= parseFloat(style.fontSize) * TWO_COLUMN_LEAST_GAIN
|
|
619
|
+
table.toggleAttribute("data-spell-wrap-first", wraps)
|
|
620
|
+
setStyle(table, "--spell-first-column", wraps ? `${Math.floor(width)}px` : "")
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
/**
|
|
624
|
+
* A table's HEADER ROW sticks (epic `epic-engine` r4; Owen, 2026-10-19: "make the table headers sticky"):
|
|
625
|
+
* while its rows scroll past, it stays just under the stuck titles, the page header's and the sections',
|
|
626
|
+
* until the table ends.
|
|
627
|
+
* - its header: its `<thead>`, else a first row of `<th>`s alone
|
|
628
|
+
* - a PIN, not the row itself: `position: sticky` on a `<thead>` holds only inside its nearest scroll box.
|
|
629
|
+
* - A table wider than its column scrolls sideways in its own box (every `<ui-table>`, a bare table at phone width),
|
|
630
|
+
* which scrolls nothing up or down.
|
|
631
|
+
* - So a COPY of the header (`.spell-table-pin`, `data-spell-added`) sticks instead.
|
|
632
|
+
* - the copy:
|
|
633
|
+
* - a line of no height just before the table (and its actions row), sticking at the line below the titles:
|
|
634
|
+
* the browser holds it there while the page scrolls, as it holds the titles
|
|
635
|
+
* - shown only while the table's own header is under that line,
|
|
636
|
+
* over the table's width as it shows (its box's, wide or not, scrolled sideways or not),
|
|
637
|
+
* its columns as wide as the table's, moved sideways with them
|
|
638
|
+
* - as the table ends, it goes up with the table's last row, cut off at the line: never over a title
|
|
639
|
+
* - the copy draws as the table does: the same classes in the same place (a `<ui-table>` copy for a `<ui-table>`);
|
|
640
|
+
* no pointer, no ids, hidden from readers
|
|
641
|
+
* - the line, below the titles stuck over the table (`tableLine()`)
|
|
642
|
+
* - read only for the tables on screen (an IntersectionObserver), a frame at a time,
|
|
643
|
+
* on any scroll (the page's, or a table's sideways) or resize
|
|
644
|
+
* - tables a part's body or a live update adds later get theirs too (`eachTable()`)
|
|
645
|
+
*/
|
|
312
646
|
function wireTableHeads(main) {
|
|
313
|
-
const pins =
|
|
314
|
-
const onScreen =
|
|
315
|
-
|
|
647
|
+
const pins = new Map()
|
|
648
|
+
const onScreen = new Set()
|
|
649
|
+
// tables whose copy can't stick (a scroll box between them and the page): left alone until the window changes
|
|
650
|
+
let unpinnable = new WeakSet()
|
|
316
651
|
const screen = new IntersectionObserver((entries) => {
|
|
317
652
|
for (const entry of entries) {
|
|
318
|
-
if (entry.isIntersecting) onScreen.add(entry.target)
|
|
319
|
-
else onScreen.delete(entry.target)
|
|
653
|
+
if (entry.isIntersecting) onScreen.add(entry.target)
|
|
654
|
+
else onScreen.delete(entry.target)
|
|
320
655
|
}
|
|
321
|
-
redrawSoon()
|
|
322
|
-
})
|
|
656
|
+
redrawSoon()
|
|
657
|
+
})
|
|
323
658
|
const redrawSoon = eachTable(main, {
|
|
324
659
|
// a table with no header row (yet): looked at again as the page changes
|
|
325
660
|
added(box) {
|
|
326
|
-
if (!headRows(tableOf(box)).length) return false
|
|
327
|
-
screen.observe(box)
|
|
661
|
+
if (!headRows(tableOf(box)).length) return false
|
|
662
|
+
screen.observe(box)
|
|
328
663
|
},
|
|
329
|
-
redraw:
|
|
330
|
-
})
|
|
331
|
-
const update =
|
|
664
|
+
redraw: () => update()
|
|
665
|
+
})
|
|
666
|
+
const update = () => {
|
|
332
667
|
for (const [box, pin] of pins) {
|
|
333
|
-
if (box.isConnected) continue
|
|
334
|
-
pin.remove()
|
|
335
|
-
pins.delete(box)
|
|
336
|
-
onScreen.delete(box)
|
|
668
|
+
if (box.isConnected) continue
|
|
669
|
+
pin.remove()
|
|
670
|
+
pins.delete(box)
|
|
671
|
+
onScreen.delete(box)
|
|
337
672
|
}
|
|
338
|
-
for (const [box, pin] of pins) if (!onScreen.has(box)) pin.hidden = true
|
|
339
|
-
for (const box of onScreen) if (box.isConnected && !unpinnable.has(box)) place(box)
|
|
340
|
-
}
|
|
341
|
-
const place =
|
|
342
|
-
const table = tableOf(box)
|
|
343
|
-
const rows = headRows(table)
|
|
344
|
-
if (!rows.length) return
|
|
345
|
-
const head = rows[0].getBoundingClientRect()
|
|
346
|
-
const height = rows.at(-1).getBoundingClientRect().bottom - head.top
|
|
347
|
-
const line = tableLine(box)
|
|
348
|
-
const end = table.getBoundingClientRect().bottom
|
|
349
|
-
let pin = pins.get(box)
|
|
673
|
+
for (const [box, pin] of pins) if (!onScreen.has(box)) pin.hidden = true
|
|
674
|
+
for (const box of onScreen) if (box.isConnected && !unpinnable.has(box)) place(box)
|
|
675
|
+
}
|
|
676
|
+
const place = (box) => {
|
|
677
|
+
const table = tableOf(box)
|
|
678
|
+
const rows = headRows(table)
|
|
679
|
+
if (!rows.length) return
|
|
680
|
+
const head = rows[0].getBoundingClientRect()
|
|
681
|
+
const height = rows.at(-1).getBoundingClientRect().bottom - head.top
|
|
682
|
+
const line = tableLine(box)
|
|
683
|
+
const end = table.getBoundingClientRect().bottom
|
|
684
|
+
let pin = pins.get(box)
|
|
350
685
|
if (!(head.top < line - 0.5 && end > line + 1)) {
|
|
351
|
-
if (pin) pin.hidden = true
|
|
352
|
-
return
|
|
686
|
+
if (pin) pin.hidden = true
|
|
687
|
+
return
|
|
353
688
|
}
|
|
354
689
|
if (!pin) {
|
|
355
|
-
pin = el("div", { class: "spell-table-pin", "data-spell-added": true, "aria-hidden": "true", inert: true })
|
|
356
|
-
pin.hidden = true
|
|
357
|
-
pins.set(box, pin)
|
|
358
|
-
const row = box.previousElementSibling
|
|
359
|
-
(row?.matches(BLOCK_ROW) ? row : box).before(pin)
|
|
690
|
+
pin = el("div", { class: "spell-table-pin", "data-spell-added": true, "aria-hidden": "true", inert: true })
|
|
691
|
+
pin.hidden = true
|
|
692
|
+
pins.set(box, pin)
|
|
693
|
+
const row = box.previousElementSibling
|
|
694
|
+
;(row?.matches(BLOCK_ROW) ? row : box).before(pin)
|
|
360
695
|
}
|
|
361
|
-
|
|
362
|
-
pin.hidden
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
const
|
|
366
|
-
const
|
|
696
|
+
// shown again: the header as it is now (a live update may have changed it)
|
|
697
|
+
if (pin.hidden) copyHead(pin, box, table, rows)
|
|
698
|
+
pin.hidden = false
|
|
699
|
+
setStyle(pin, "top", `${line}px`)
|
|
700
|
+
const view = pin.firstElementChild
|
|
701
|
+
const area = box.getBoundingClientRect()
|
|
702
|
+
const at = pin.getBoundingClientRect()
|
|
703
|
+
// not held at the line: nothing, rather than a copy out of place
|
|
367
704
|
if (Math.abs(at.top - line) > 1) {
|
|
368
|
-
pin.hidden = true
|
|
369
|
-
unpinnable.add(box)
|
|
370
|
-
return
|
|
705
|
+
pin.hidden = true
|
|
706
|
+
unpinnable.add(box)
|
|
707
|
+
return
|
|
371
708
|
}
|
|
372
|
-
setStyle(view, "left", `${area.left - at.left}px`)
|
|
373
|
-
setStyle(view, "width", `${area.width}px`)
|
|
374
|
-
|
|
375
|
-
const
|
|
376
|
-
widths.
|
|
377
|
-
|
|
378
|
-
const
|
|
379
|
-
const
|
|
380
|
-
|
|
381
|
-
const
|
|
382
|
-
setStyle(copy, "
|
|
383
|
-
const
|
|
384
|
-
setStyle(
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
709
|
+
setStyle(view, "left", `${area.left - at.left}px`)
|
|
710
|
+
setStyle(view, "width", `${area.width}px`)
|
|
711
|
+
// each column as wide as the table's, and the copy moved to where the table's header is (sideways too)
|
|
712
|
+
const copies = [...view.querySelectorAll("tr")].flatMap((each) => [...each.cells])
|
|
713
|
+
const widths = rows.flatMap((each) => [...each.cells]).map((cell) => cell.getBoundingClientRect().width)
|
|
714
|
+
widths.forEach((width, n) => copies[n] && setStyle(copies[n], "width", `${width}px`))
|
|
715
|
+
const copy = view.querySelector("table")
|
|
716
|
+
const first = view.querySelector("tr")
|
|
717
|
+
// the copy as wide as the row, its own edges added (`table-layout: fixed` keeps the columns as set)
|
|
718
|
+
const edges = copy.getBoundingClientRect().width - first.getBoundingClientRect().width
|
|
719
|
+
setStyle(copy, "width", `${head.width + edges}px`)
|
|
720
|
+
const shift = parseFloat(copy.style.translate) || 0
|
|
721
|
+
setStyle(copy, "translate", `${shift + head.left - first.getBoundingClientRect().left}px`)
|
|
722
|
+
// leaving with the table's last row: up, the part above the line cut off
|
|
723
|
+
const up = Math.min(0, end - (line + height))
|
|
724
|
+
setStyle(view, "translate", up ? `0 ${up}px` : "")
|
|
725
|
+
setStyle(view, "clip-path", up ? `inset(${-up}px 0 0 0)` : "")
|
|
726
|
+
}
|
|
727
|
+
// capture: a table's own sideways scroll too, which doesn't bubble
|
|
728
|
+
document.addEventListener("scroll", () => redrawSoon(), { capture: true, passive: true })
|
|
388
729
|
addEventListener("resize", () => {
|
|
389
|
-
unpinnable =
|
|
390
|
-
redrawSoon()
|
|
391
|
-
})
|
|
730
|
+
unpinnable = new WeakSet()
|
|
731
|
+
redrawSoon()
|
|
732
|
+
})
|
|
392
733
|
}
|
|
393
|
-
|
|
734
|
+
|
|
735
|
+
/** Set `element`'s inline style `name` to `value` ("" removes it), unless it's that already. */
|
|
394
736
|
function setStyle(element, name, value) {
|
|
395
|
-
if (element.style.getPropertyValue(name) === value) return
|
|
396
|
-
if (value) element.style.setProperty(name, value)
|
|
397
|
-
else element.style.removeProperty(name)
|
|
737
|
+
if (element.style.getPropertyValue(name) === value) return
|
|
738
|
+
if (value) element.style.setProperty(name, value)
|
|
739
|
+
else element.style.removeProperty(name)
|
|
398
740
|
}
|
|
399
|
-
|
|
741
|
+
|
|
742
|
+
/** The `<table>` of a table's box (`tableBoxes()`): the box itself, or the `<ui-table>`'s own. */
|
|
400
743
|
function tableOf(box) {
|
|
401
|
-
return box.localName === "table" ? box : box.querySelector(":scope > table")
|
|
744
|
+
return box.localName === "table" ? box : box.querySelector(":scope > table")
|
|
402
745
|
}
|
|
403
|
-
|
|
746
|
+
|
|
747
|
+
/** A table's header rows (`wireTableHeads()`): its `<thead>`'s, else its first row when it holds `<th>`s alone. */
|
|
404
748
|
function headRows(table) {
|
|
405
|
-
if (!table) return []
|
|
406
|
-
if (table.tHead?.rows.length) return [...table.tHead.rows]
|
|
407
|
-
const first = table.rows[0]
|
|
408
|
-
return first?.cells.length && [...first.cells].every((cell) => cell.localName === "th") ? [first] : []
|
|
749
|
+
if (!table) return []
|
|
750
|
+
if (table.tHead?.rows.length) return [...table.tHead.rows]
|
|
751
|
+
const first = table.rows[0]
|
|
752
|
+
return first?.cells.length && [...first.cells].every((cell) => cell.localName === "th") ? [first] : []
|
|
409
753
|
}
|
|
410
|
-
|
|
754
|
+
|
|
755
|
+
/**
|
|
756
|
+
* Draw a copy of `table`'s header `rows` into `pin` (`wireTableHeads()`): the table's own tag and classes, in a
|
|
757
|
+
* shallow copy of its `<ui-table>`, so the page's rules draw it as they draw the table; never its ids, the table's
|
|
758
|
+
* inline styles (the expand button's widths) or its body.
|
|
759
|
+
*/
|
|
411
760
|
function copyHead(pin, box, table, rows) {
|
|
412
|
-
const copy = table.cloneNode(false)
|
|
413
|
-
const head = el("thead", {}, ...rows.map((row) => row.cloneNode(true)))
|
|
414
|
-
copy.append(head)
|
|
415
|
-
const host = box === table ?
|
|
416
|
-
host?.append(copy)
|
|
761
|
+
const copy = table.cloneNode(false)
|
|
762
|
+
const head = el("thead", {}, ...rows.map((row) => row.cloneNode(true)))
|
|
763
|
+
copy.append(head)
|
|
764
|
+
const host = box === table ? undefined : box.cloneNode(false)
|
|
765
|
+
host?.append(copy)
|
|
417
766
|
for (const each of [copy, host]) {
|
|
418
|
-
each?.removeAttribute("id")
|
|
419
|
-
each?.removeAttribute("style")
|
|
767
|
+
each?.removeAttribute("id")
|
|
768
|
+
each?.removeAttribute("style")
|
|
420
769
|
}
|
|
421
|
-
for (const each of head.querySelectorAll("[id]")) each.removeAttribute("id")
|
|
422
|
-
pin.replaceChildren(el("div", { class: "spell-table-pin-view" }, host ?? copy))
|
|
770
|
+
for (const each of head.querySelectorAll("[id]")) each.removeAttribute("id")
|
|
771
|
+
pin.replaceChildren(el("div", { class: "spell-table-pin-view" }, host ?? copy))
|
|
423
772
|
}
|
|
424
|
-
|
|
773
|
+
|
|
774
|
+
/**
|
|
775
|
+
* Where a table's header sticks (`wireTableHeads()`), px from the window's top: the bottom of what is stuck over it.
|
|
776
|
+
* - an epic page's: its `--epic-stack` (the page header and bar, the stuck block titles), and the line of the item
|
|
777
|
+
* it's in, which sticks there too
|
|
778
|
+
* - a `<ui-section>` page's: the site header and the TOP-LEVEL section's stack (`--spell-stack`, the page header and
|
|
779
|
+
* its title): a nested section's stuck title joins that one's row (`wireStuckTrail()`), its own room left empty
|
|
780
|
+
* - a headings page's (the saga pages): the page header, then the h2's and h3's above it
|
|
781
|
+
*/
|
|
425
782
|
function tableLine(box) {
|
|
426
|
-
const style = getComputedStyle(box)
|
|
427
|
-
const px =
|
|
783
|
+
const style = getComputedStyle(box)
|
|
784
|
+
const px = (name) => parseFloat(style.getPropertyValue(name)) || 0
|
|
428
785
|
if (box.closest("epic-page")) {
|
|
429
|
-
const line = box.parentElement?.closest("epic-item")?.shadowRoot?.querySelector('[part~="line"]')
|
|
430
|
-
return (px("--epic-stack") || siteHeaderHeight()) + (line?.getBoundingClientRect().height ?? 0)
|
|
786
|
+
const line = box.parentElement?.closest("epic-item")?.shadowRoot?.querySelector('[part~="line"]')
|
|
787
|
+
return (px("--epic-stack") || siteHeaderHeight()) + (line?.getBoundingClientRect().height ?? 0)
|
|
431
788
|
}
|
|
432
|
-
let section = box.closest("ui-section")
|
|
433
|
-
while (section?.parentElement?.closest("ui-section")) section = section.parentElement.closest("ui-section")
|
|
434
|
-
if (section) return siteHeaderHeight() + (parseFloat(section.style.getPropertyValue("--spell-stack")) || 0)
|
|
435
|
-
return siteHeaderHeight() + px("--spell-top") + px("--spell-h2-h") + px("--spell-h3-h")
|
|
789
|
+
let section = box.closest("ui-section")
|
|
790
|
+
while (section?.parentElement?.closest("ui-section")) section = section.parentElement.closest("ui-section")
|
|
791
|
+
if (section) return siteHeaderHeight() + (parseFloat(section.style.getPropertyValue("--spell-stack")) || 0)
|
|
792
|
+
return siteHeaderHeight() + px("--spell-top") + px("--spell-h2-h") + px("--spell-h3-h")
|
|
436
793
|
}
|
|
437
|
-
|
|
794
|
+
|
|
795
|
+
/**
|
|
796
|
+
* Stuck titles on ONE row (Owen, 2026-10-13: "This could collapse to one row when stickified").
|
|
797
|
+
* - while a nested section's title is stuck under its parent's,
|
|
798
|
+
* the top-level stuck title reads `2. Files on disk › 2.1 The repo`
|
|
799
|
+
* - the nested stuck titles under it hide: their room shows the text scrolling under them
|
|
800
|
+
* - the trail is the top-level title's `::part(header)::after`, from `--spell-stuck-trail` on it, with
|
|
801
|
+
* `data-spell-trail`; each hidden one has `data-spell-merged` (`spell-doc.css`, "Stuck titles on one row")
|
|
802
|
+
* - worked out again on every scroll and resize, a frame at a time, and once more as it settles:
|
|
803
|
+
* `:state(stuck)` (`<ui-section sticky>`'s) sends no event
|
|
804
|
+
* - every page's `<ui-section>`s; an epic page draws its own sections, in its elements' shadow roots
|
|
805
|
+
*/
|
|
438
806
|
function wireStuckTrail(main) {
|
|
439
|
-
const marked =
|
|
440
|
-
const isStuck =
|
|
441
|
-
|
|
442
|
-
const
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
807
|
+
const marked = new Set()
|
|
808
|
+
const isStuck = (section) => section.matches("[sticky]") && section.matches(":state(stuck)")
|
|
809
|
+
// the sections directly under `section` (none between), as nesting goes
|
|
810
|
+
const childrenOf = (section) =>
|
|
811
|
+
[...section.querySelectorAll("ui-section")].filter((each) => each.parentElement.closest("ui-section") === section)
|
|
812
|
+
const titleOf = (section) =>
|
|
813
|
+
(section.getAttribute("label") ?? section.querySelector(':scope > [slot="label"]')?.textContent ?? "")
|
|
814
|
+
.replace(/\s+/g, " ")
|
|
815
|
+
.trim()
|
|
816
|
+
const update = () => {
|
|
817
|
+
const merged = new Set()
|
|
818
|
+
const trails = new Map()
|
|
446
819
|
for (const top of main.querySelectorAll("ui-section")) {
|
|
447
|
-
if (top.parentElement.closest("ui-section") || !isStuck(top)) continue
|
|
448
|
-
const trail = []
|
|
449
|
-
for (let at = top; ;
|
|
450
|
-
const child = childrenOf(at).find(isStuck)
|
|
451
|
-
if (!child) break
|
|
452
|
-
trail.push(
|
|
453
|
-
merged.add(child)
|
|
454
|
-
at = child
|
|
820
|
+
if (top.parentElement.closest("ui-section") || !isStuck(top)) continue
|
|
821
|
+
const trail = []
|
|
822
|
+
for (let at = top; ;) {
|
|
823
|
+
const child = childrenOf(at).find(isStuck)
|
|
824
|
+
if (!child) break
|
|
825
|
+
trail.push(titleOf(child))
|
|
826
|
+
merged.add(child)
|
|
827
|
+
at = child
|
|
455
828
|
}
|
|
456
|
-
if (trail.length) trails.set(top, JSON.stringify(` › ${trail.join(" › ")}`))
|
|
829
|
+
if (trail.length) trails.set(top, JSON.stringify(` › ${trail.join(" › ")}`))
|
|
457
830
|
}
|
|
458
831
|
for (const section of marked) {
|
|
459
|
-
if (!merged.has(section)) section.removeAttribute("data-spell-merged")
|
|
832
|
+
if (!merged.has(section)) section.removeAttribute("data-spell-merged")
|
|
460
833
|
if (!trails.has(section)) {
|
|
461
|
-
section.removeAttribute("data-spell-trail")
|
|
462
|
-
section.style.removeProperty("--spell-stuck-trail")
|
|
834
|
+
section.removeAttribute("data-spell-trail")
|
|
835
|
+
section.style.removeProperty("--spell-stuck-trail")
|
|
463
836
|
}
|
|
464
837
|
}
|
|
465
|
-
marked.clear()
|
|
838
|
+
marked.clear()
|
|
466
839
|
for (const section of merged) {
|
|
467
|
-
if (!section.hasAttribute("data-spell-merged")) section.setAttribute("data-spell-merged", "")
|
|
468
|
-
marked.add(section)
|
|
840
|
+
if (!section.hasAttribute("data-spell-merged")) section.setAttribute("data-spell-merged", "")
|
|
841
|
+
marked.add(section)
|
|
469
842
|
}
|
|
470
843
|
for (const [section, trail] of trails) {
|
|
471
844
|
if (section.style.getPropertyValue("--spell-stuck-trail") !== trail)
|
|
472
|
-
section.style.setProperty("--spell-stuck-trail", trail)
|
|
473
|
-
if (!section.hasAttribute("data-spell-trail")) section.setAttribute("data-spell-trail", "")
|
|
474
|
-
marked.add(section)
|
|
845
|
+
section.style.setProperty("--spell-stuck-trail", trail)
|
|
846
|
+
if (!section.hasAttribute("data-spell-trail")) section.setAttribute("data-spell-trail", "")
|
|
847
|
+
marked.add(section)
|
|
475
848
|
}
|
|
476
|
-
}
|
|
477
|
-
let queued = false
|
|
478
|
-
const soon =
|
|
479
|
-
if (queued) return
|
|
480
|
-
queued = true
|
|
849
|
+
}
|
|
850
|
+
let queued = false
|
|
851
|
+
const soon = () => {
|
|
852
|
+
if (queued) return
|
|
853
|
+
queued = true
|
|
481
854
|
requestAnimationFrame(() => {
|
|
482
|
-
queued = false
|
|
483
|
-
update()
|
|
484
|
-
})
|
|
485
|
-
}
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
later
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
855
|
+
queued = false
|
|
856
|
+
update()
|
|
857
|
+
})
|
|
858
|
+
}
|
|
859
|
+
// `:state(stuck)` follows a moment after the scroll (`StickyWatch` hears it from an observer):
|
|
860
|
+
// so again once the scrolling settles, or the last frame would read the titles as they were
|
|
861
|
+
let settle
|
|
862
|
+
const later = () => {
|
|
863
|
+
soon()
|
|
864
|
+
clearTimeout(settle)
|
|
865
|
+
settle = setTimeout(soon, STUCK_SETTLE_MS)
|
|
866
|
+
}
|
|
867
|
+
addEventListener("scroll", later, { passive: true })
|
|
868
|
+
addEventListener("resize", later)
|
|
869
|
+
later()
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
/** How long after the last scroll the stuck titles are read again (`wireStuckTrail()`), ms. */
|
|
873
|
+
const STUCK_SETTLE_MS = 120
|
|
874
|
+
|
|
875
|
+
/**
|
|
876
|
+
* A table's key, for remembering its width: its id, else the nearest id above it and which table it is under that
|
|
877
|
+
* (`p14#table-1`, `memory#table-2`); `page#table-<n>` with no id above it.
|
|
878
|
+
*/
|
|
498
879
|
function tableKey(box, main) {
|
|
499
|
-
if (box.id) return box.id
|
|
500
|
-
const holder = box.parentElement.closest("[id]")
|
|
501
|
-
const root = holder && main.contains(holder) ? holder : main
|
|
502
|
-
return `${root === main ? "page" : root.id}#table-${tableBoxes(root).indexOf(box) + 1}
|
|
880
|
+
if (box.id) return box.id
|
|
881
|
+
const holder = box.parentElement.closest("[id]")
|
|
882
|
+
const root = holder && main.contains(holder) ? holder : main
|
|
883
|
+
return `${root === main ? "page" : root.id}#table-${tableBoxes(root).indexOf(box) + 1}`
|
|
503
884
|
}
|
|
504
|
-
|
|
885
|
+
|
|
886
|
+
/**
|
|
887
|
+
* How far a widened table `box` may run, as window x's `{ left, right }`:
|
|
888
|
+
* `main`'s width less its gutter (`--spell-gutter`) on both sides,
|
|
889
|
+
* cut to every ancestor between them that clips its overflow (`overflow-x` not `visible`), at its inner edges.
|
|
890
|
+
* - up through slots and shadow roots:
|
|
891
|
+
* a table in an `<epic-*>` element's light DOM is laid out in its shadow root's boxes
|
|
892
|
+
*/
|
|
505
893
|
function roomFor(box, main) {
|
|
506
|
-
const page = main.getBoundingClientRect()
|
|
507
|
-
const gutter = parseFloat(getComputedStyle(main).getPropertyValue("--spell-gutter")) || 16
|
|
508
|
-
const room = { left: page.left + gutter, right: page.right - gutter }
|
|
509
|
-
for (let
|
|
510
|
-
if (getComputedStyle(
|
|
511
|
-
const left =
|
|
512
|
-
room.left = Math.max(room.left, left)
|
|
513
|
-
room.right = Math.min(room.right, left +
|
|
514
|
-
}
|
|
515
|
-
return room
|
|
516
|
-
}
|
|
517
|
-
|
|
894
|
+
const page = main.getBoundingClientRect()
|
|
895
|
+
const gutter = parseFloat(getComputedStyle(main).getPropertyValue("--spell-gutter")) || 16
|
|
896
|
+
const room = { left: page.left + gutter, right: page.right - gutter }
|
|
897
|
+
for (let el = layoutParent(box); el && el !== main; el = layoutParent(el)) {
|
|
898
|
+
if (getComputedStyle(el).overflowX === "visible") continue
|
|
899
|
+
const left = el.getBoundingClientRect().left + el.clientLeft
|
|
900
|
+
room.left = Math.max(room.left, left)
|
|
901
|
+
room.right = Math.min(room.right, left + el.clientWidth)
|
|
902
|
+
}
|
|
903
|
+
return room
|
|
904
|
+
}
|
|
905
|
+
|
|
906
|
+
/** How wide `roomFor()` lets `box` run. */
|
|
518
907
|
function roomWidth(box, main) {
|
|
519
|
-
const room = roomFor(box, main)
|
|
520
|
-
return room.right - room.left
|
|
908
|
+
const room = roomFor(box, main)
|
|
909
|
+
return room.right - room.left
|
|
521
910
|
}
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
911
|
+
|
|
912
|
+
/** The least a widened table must gain on its column (px) for the expand button to show. */
|
|
913
|
+
const MIN_WIDE_GAIN = 24
|
|
914
|
+
|
|
915
|
+
/** The box `el` is laid out in: its slot when it's slotted, else its parent, else its shadow root's host. */
|
|
916
|
+
function layoutParent(el) {
|
|
917
|
+
return el.assignedSlot ?? el.parentElement ?? el.getRootNode().host ?? null
|
|
526
918
|
}
|
|
527
|
-
|
|
919
|
+
|
|
920
|
+
/**
|
|
921
|
+
* The tables in `root`, each by its BOX: its `<ui-table>` host, else the bare table. Never a pinned header's copy
|
|
922
|
+
* (`wireTableHeads()`), which isn't the page's.
|
|
923
|
+
*/
|
|
528
924
|
function tableBoxes(root) {
|
|
529
|
-
const tables = [...root.querySelectorAll("table")].filter((table) => !table.closest(".spell-table-pin"))
|
|
530
|
-
return [...new Set(tables.map((table) => table.closest("ui-table") ?? table))]
|
|
531
|
-
}
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
925
|
+
const tables = [...root.querySelectorAll("table")].filter((table) => !table.closest(".spell-table-pin"))
|
|
926
|
+
return [...new Set(tables.map((table) => table.closest("ui-table") ?? table))]
|
|
927
|
+
}
|
|
928
|
+
|
|
929
|
+
/**
|
|
930
|
+
* Watch every TABLE in `main` (each by its box, `tableBoxes()`): the ONE watch the table features run on
|
|
931
|
+
* (`wireTableWidths()`, `wireTwoColumnTables()`, `wireTableHeads()`; epic `coherence` P22).
|
|
932
|
+
* - `added(box)`: each box once, as it's first seen: now, and as a part's body or a live update adds tables
|
|
933
|
+
* - `false`: not taken yet, so it's handed over again at the next change (a table with no header row yet)
|
|
934
|
+
* - `gone(box)`: a box taken that's left the page, or that `keeps(box)` lets go: handed to `added()` again while
|
|
935
|
+
* it's there. Default: every box on the page is kept.
|
|
936
|
+
* - `redraw(boxes)`: once a frame at most, with the boxes asked for since; returns what asks for it,
|
|
937
|
+
* `redrawSoon(box?)`: a box, or none (a resize, a scroll: every box is the caller's to redraw)
|
|
938
|
+
* - SIDE EFFECT: watches `main`'s tree for the page's life
|
|
939
|
+
*/
|
|
940
|
+
function eachTable(main, { added, gone, keeps = () => true, redraw = () => {} }) {
|
|
941
|
+
const taken = new Set()
|
|
942
|
+
let asked = new Set()
|
|
943
|
+
let frame = 0
|
|
944
|
+
look()
|
|
945
|
+
new MutationObserver(() => requestAnimationFrame(look)).observe(main, { childList: true, subtree: true })
|
|
946
|
+
return redrawSoon
|
|
947
|
+
|
|
948
|
+
/** What's gone first, then the boxes not seen yet. */
|
|
541
949
|
function look() {
|
|
542
950
|
for (const box of taken) {
|
|
543
|
-
if (box.isConnected && keeps(box)) continue
|
|
544
|
-
taken.delete(box)
|
|
545
|
-
gone?.(box)
|
|
951
|
+
if (box.isConnected && keeps(box)) continue
|
|
952
|
+
taken.delete(box)
|
|
953
|
+
gone?.(box)
|
|
546
954
|
}
|
|
547
|
-
for (const box of tableBoxes(main)) if (!taken.has(box) && added(box) !== false) taken.add(box)
|
|
955
|
+
for (const box of tableBoxes(main)) if (!taken.has(box) && added(box) !== false) taken.add(box)
|
|
548
956
|
}
|
|
549
|
-
|
|
957
|
+
|
|
958
|
+
/** `redraw()` at the next frame, once however often it's asked, with every box asked for since. */
|
|
550
959
|
function redrawSoon(box) {
|
|
551
|
-
if (box) asked.add(box)
|
|
960
|
+
if (box) asked.add(box)
|
|
552
961
|
frame ||= requestAnimationFrame(() => {
|
|
553
|
-
frame = 0
|
|
554
|
-
const boxes = asked
|
|
555
|
-
asked =
|
|
556
|
-
redraw(boxes)
|
|
557
|
-
})
|
|
962
|
+
frame = 0
|
|
963
|
+
const boxes = asked
|
|
964
|
+
asked = new Set()
|
|
965
|
+
redraw(boxes)
|
|
966
|
+
})
|
|
558
967
|
}
|
|
559
|
-
__name(redrawSoon, "redrawSoon");
|
|
560
968
|
}
|
|
561
|
-
|
|
969
|
+
|
|
970
|
+
/**
|
|
971
|
+
* Land where the page should open, once its sections have drawn and folded:
|
|
972
|
+
* - a live reload's saved scroll position (`SPELL_SERVER.takeScroll()`): exactly there, held while the page settles
|
|
973
|
+
* (`holdScroll()`); its `#hash` was dropped (`start()`)
|
|
974
|
+
* - else the URL's `#hash`:
|
|
975
|
+
* - a section or heading WITHOUT unfolding the target itself: the address follows the section being read
|
|
976
|
+
* (`followScroll()`), so a reload (or VS Code restarting) lands on it, folded or not, as the reader left it
|
|
977
|
+
* - a plan item (`<epic-item>`) OPENS: the address never follows items, so an item's `#q16` is a link someone
|
|
978
|
+
* followed (`epic pages link --hash q16 --show`), and a folded item shows nothing of what it pointed at
|
|
979
|
+
* - else nowhere: the top
|
|
980
|
+
* - then the address starts following the scroll; after a `#hash`, only once the jump has landed:
|
|
981
|
+
* a target in a body not loaded yet (a split epic page's part) lands a moment later, and following before that saw
|
|
982
|
+
* the top of the page, and wrote the hash away (I3 of `windows-and-review`)
|
|
983
|
+
*/
|
|
562
984
|
function land({ hash, scroll }, jump, follow) {
|
|
563
|
-
if (scroll !==
|
|
564
|
-
holdScroll(scroll)
|
|
565
|
-
follow?.update()
|
|
985
|
+
if (scroll !== undefined) {
|
|
986
|
+
holdScroll(scroll)
|
|
987
|
+
follow?.update()
|
|
566
988
|
} else if (hash) {
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
989
|
+
// `HashLanding` lands once more as the page settles, unless the reader has moved meanwhile: the browser's own
|
|
990
|
+
// jump to the `#hash` can come AFTER ours and land the target under the stuck titles (an item has no box of its
|
|
991
|
+
// own: `display: contents`)
|
|
992
|
+
const landed = jump(hash, { unfoldTarget: document.getElementById(hash)?.localName === "epic-item" })
|
|
993
|
+
void landed.then(() => follow?.followAddress())
|
|
994
|
+
return
|
|
995
|
+
} else follow?.update()
|
|
996
|
+
follow?.followAddress()
|
|
572
997
|
}
|
|
573
|
-
|
|
998
|
+
|
|
999
|
+
/**
|
|
1000
|
+
* Keep the page at `top` while it settles after a live reload:
|
|
1001
|
+
* every frame for `RESTORE_HOLD_MS`, until the reader does anything (`READER_INPUT`).
|
|
1002
|
+
* - why: the page grows as it settles (the folds put back draw, their parts load),
|
|
1003
|
+
* and the browser and the elements scroll it meanwhile
|
|
1004
|
+
* - one scroll, and one more after `SETTLE_MS` only when nothing else had moved it, landed short
|
|
1005
|
+
* (I23 of `epic-engine`: 1150 -> 671)
|
|
1006
|
+
* - the page may be too short for `top` at first: it gets there as it grows
|
|
1007
|
+
*/
|
|
574
1008
|
function holdScroll(top) {
|
|
575
|
-
const reader = new AbortController()
|
|
1009
|
+
const reader = new AbortController()
|
|
576
1010
|
for (const type of READER_INPUT)
|
|
577
|
-
addEventListener(type, () => reader.abort(), { once: true, passive: true, signal: reader.signal })
|
|
578
|
-
const until = performance.now() + RESTORE_HOLD_MS
|
|
579
|
-
const hold =
|
|
580
|
-
if (reader.signal.aborted) return
|
|
581
|
-
if (Math.abs(scrollY - top) >= 1) scrollTo({ top, behavior: "instant" })
|
|
582
|
-
if (performance.now() < until) requestAnimationFrame(hold)
|
|
583
|
-
else reader.abort()
|
|
584
|
-
}
|
|
585
|
-
hold()
|
|
586
|
-
}
|
|
587
|
-
|
|
1011
|
+
addEventListener(type, () => reader.abort(), { once: true, passive: true, signal: reader.signal })
|
|
1012
|
+
const until = performance.now() + RESTORE_HOLD_MS
|
|
1013
|
+
const hold = () => {
|
|
1014
|
+
if (reader.signal.aborted) return
|
|
1015
|
+
if (Math.abs(scrollY - top) >= 1) scrollTo({ top, behavior: "instant" })
|
|
1016
|
+
if (performance.now() < until) requestAnimationFrame(hold)
|
|
1017
|
+
else reader.abort()
|
|
1018
|
+
}
|
|
1019
|
+
hold()
|
|
1020
|
+
}
|
|
1021
|
+
|
|
1022
|
+
/**
|
|
1023
|
+
* Resolves once an epic page's elements are defined and have drawn (their hosts' `ready`), so their
|
|
1024
|
+
* `contentsEntry` can be read; after `EPIC_WAIT_MS` at most (a pack that won't load: the page goes on without).
|
|
1025
|
+
*/
|
|
588
1026
|
async function epicsDrawn(main) {
|
|
589
|
-
const tags = ["epic-page", ...EPIC_FOLDS.split(", ")]
|
|
590
|
-
const drawn = Promise.all(tags.map((tag) => customElements.whenDefined(tag))).then(
|
|
591
|
-
|
|
592
|
-
)
|
|
593
|
-
await Promise.race([drawn, new Promise((done) => setTimeout(done, EPIC_WAIT_MS))])
|
|
1027
|
+
const tags = ["epic-page", ...EPIC_FOLDS.split(", ")]
|
|
1028
|
+
const drawn = Promise.all(tags.map((tag) => customElements.whenDefined(tag))).then(() =>
|
|
1029
|
+
Promise.all(Array.from(main.querySelectorAll(EPIC_FOLDS), (host) => host.ready))
|
|
1030
|
+
)
|
|
1031
|
+
await Promise.race([drawn, new Promise((done) => setTimeout(done, EPIC_WAIT_MS))])
|
|
594
1032
|
}
|
|
595
|
-
|
|
1033
|
+
|
|
1034
|
+
/**
|
|
1035
|
+
* An epic page (`epics/<name>/<name>.plan.html`; before 2026-10-04 `<name>.html`) names its tab `<name>`:
|
|
1036
|
+
* every link to it has `target="<name>"` (`doc-links.js`),
|
|
1037
|
+
* so they reuse this tab, as `epic open <name>` does.
|
|
1038
|
+
*/
|
|
596
1039
|
function nameTab() {
|
|
597
|
-
const plan = /\/epics\/([^/]+)\/\1(?:\.plan)?\.html$/.exec(decodeURIComponent(location.pathname))
|
|
598
|
-
if (plan) window.name = plan[1]
|
|
1040
|
+
const plan = /\/epics\/([^/]+)\/\1(?:\.plan)?\.html$/.exec(decodeURIComponent(location.pathname))
|
|
1041
|
+
if (plan) window.name = plan[1]
|
|
599
1042
|
}
|
|
600
|
-
|
|
1043
|
+
|
|
1044
|
+
/** highlight.js colors every `pre code`; without it (offline) the code stays plain monospace. */
|
|
601
1045
|
function highlight() {
|
|
602
1046
|
try {
|
|
603
|
-
globalThis.hljs?.highlightAll()
|
|
1047
|
+
globalThis.hljs?.highlightAll()
|
|
604
1048
|
} catch {
|
|
1049
|
+
// plain monospace is fine
|
|
605
1050
|
}
|
|
606
1051
|
}
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
1052
|
+
|
|
1053
|
+
////////////////
|
|
1054
|
+
// ## Live update
|
|
1055
|
+
////////////////
|
|
1056
|
+
|
|
1057
|
+
/**
|
|
1058
|
+
* Elements the runtime adds INSIDE `main`, so not in the page's source: the patch steps around them.
|
|
1059
|
+
* - NOTE: anything else the runtime (or a page script) adds in `main` should carry `data-spell-added`;
|
|
1060
|
+
* an unknown extra of another tag than its source siblings doesn't shift their addresses either (`PagePatch`)
|
|
1061
|
+
*/
|
|
1062
|
+
const ADDED = ".spell-item-filter, .spell-hidden-note, [data-spell-added]"
|
|
1063
|
+
|
|
1064
|
+
/**
|
|
1065
|
+
* The page state of an `<epic-*>` element (epic `epic-components`, P10): folded or open (items, sections, phases,
|
|
1066
|
+
* the Overview), the page being reviewed (`<epic-page reviewing>`), and an item its section's filter hides
|
|
1067
|
+
* (`data-epic-filtered`, epic `epic-engine` P45); never in the file, so a patch keeps them
|
|
1068
|
+
* (`KEPT_ATTRIBUTES`), and a replaced subtree carries them over (`carryEpicState()`).
|
|
1069
|
+
* - NOTE: their review controls and note boxes are in their shadow roots (P9): a patch never sees them
|
|
1070
|
+
*/
|
|
1071
|
+
const EPIC_PAGE_STATE = ["open", "reviewing", "data-epic-filtered"]
|
|
1072
|
+
|
|
1073
|
+
/**
|
|
1074
|
+
* Attributes the reader's state lives in (folds, counts, the item filter, `EPIC_PAGE_STATE`):
|
|
1075
|
+
* a patch keeps them (`PagePatch`'s `keptAttributes`, beside the shared `open`).
|
|
1076
|
+
*/
|
|
1077
|
+
const KEPT_ATTRIBUTES = ["badge", "data-show", "data-ui-zoom", ...EPIC_PAGE_STATE]
|
|
1078
|
+
|
|
1079
|
+
/**
|
|
1080
|
+
* Elements that manage their children (panels and tabs by index, options): a change inside replaces the whole
|
|
1081
|
+
* element, its open panels carried over (the kit's shared rules, `PagePatch.keepReaderState()`).
|
|
1082
|
+
*/
|
|
1083
|
+
const MANAGERS = "ui-accordion, ui-tabs, ui-select, ui-dropdown"
|
|
1084
|
+
|
|
1085
|
+
/**
|
|
1086
|
+
* A tag of the `epics` pack's elements (`<epic-page>`, `<epic-item>` ...): NEVER replaced by a patch while its tag
|
|
1087
|
+
* stays: each keeps its fold, its loaded part and what's typed in it.
|
|
1088
|
+
* - patched in place like any element, attributes and children, text by text (`PagePatch`);
|
|
1089
|
+
* even a body file changing (`source`) doesn't replace one
|
|
1090
|
+
*/
|
|
1091
|
+
const EPIC_TAG = /^epic-/
|
|
1092
|
+
|
|
1093
|
+
/**
|
|
1094
|
+
* The page patch, the kit's ONE patcher (`PagePatch`, `spell/server/site`; epic `epic-engine` P40), with this
|
|
1095
|
+
* runtime's rules laid over the shared ones:
|
|
1096
|
+
* - `ADDED`: what this runtime adds in `main`, stepped around
|
|
1097
|
+
* - `KEPT_ATTRIBUTES`: the reader's
|
|
1098
|
+
* - `MANAGERS`: replaced whole, their open panels carried over
|
|
1099
|
+
* - a host whose body comes from a file (`<ui-section source>`, an epic page's parts: `isSourceHost()`): only its
|
|
1100
|
+
* slotted children (icon, header) are the page's; the body is the file's (`wireSourceBodies()`)
|
|
1101
|
+
* - its `source` changing: replaced, so it loads the new file (never an `<epic-*>`: `EPIC_TAG`)
|
|
1102
|
+
* - a copy brought in: folded as the reader has it, its `<epic-*>` page state kept (`carryState()`)
|
|
1103
|
+
*/
|
|
1104
|
+
const patcher = new PagePatch({
|
|
614
1105
|
skip: ADDED,
|
|
615
1106
|
keptAttributes: KEPT_ATTRIBUTES,
|
|
616
1107
|
replacedWhole: MANAGERS,
|
|
617
1108
|
slotsOnly: isSourceHost,
|
|
618
|
-
mustReplace:
|
|
1109
|
+
mustReplace: (before, after) =>
|
|
1110
|
+
!EPIC_TAG.test(after.localName) && before.getAttribute("source") !== after.getAttribute("source"),
|
|
619
1111
|
prepare: carryState
|
|
620
|
-
})
|
|
1112
|
+
})
|
|
1113
|
+
|
|
1114
|
+
/**
|
|
1115
|
+
* An edit to this page's file updates it IN PLACE, instead of reloading it (epic page `review-review`, D10).
|
|
1116
|
+
* - `liveClient()` (`spell/server`, the kit's `src/server/liveClient.ts`) hands over the new version when the file
|
|
1117
|
+
* changes (the page server sends it with the change), and fires a cancelable `spell-server:reloading` on `window`,
|
|
1118
|
+
* `detail` `{ path, html, etag, own, reload() }`: taking it (`preventDefault()`) stops its reload
|
|
1119
|
+
* - `own`: the version this page's own save wrote, which it shows already: only taken as the new baseline
|
|
1120
|
+
* - the patch compares the page's source as it LOADED (fetched once, `SPELL_SERVER.readPage()`, trusted only when
|
|
1121
|
+
* its `ETag` is the one served) with the new source, and changes only what differs in the live page:
|
|
1122
|
+
* the kit's patcher (`patcher`, `PagePatch.page()`), a list of small steps, text edited in place;
|
|
1123
|
+
* everything else keeps its scroll, folds, open panels, focus and typed text
|
|
1124
|
+
* - drawn as ONE short cross-fade when it changes what's on screen (`patcher.redraw()`; epic `epic-engine` I164)
|
|
1125
|
+
* - then re-wires what the runtime built from the markup (`rewire()`) and fires `spell-doc:updated` on `window`,
|
|
1126
|
+
* `detail.changed`: the elements added, replaced or re-attributed
|
|
1127
|
+
* - a full reload instead (`reload()`, which keeps the scroll) when the page can't be patched safely:
|
|
1128
|
+
* - not `<ui-section>` markup (the saga pages), a CHEATSHEET's filter, or a script besides the bundle and
|
|
1129
|
+
* highlight.js (it may have built from the markup): never taken. An INERT script (a data block,
|
|
1130
|
+
* `<script type="text/plain">`: an epic page's "Plan hung?" prompt) never runs, so it doesn't count
|
|
1131
|
+
* - stylesheets, scripts or anything outside `main` changed (but `<body>`'s attributes: patched too, e.g. a plan
|
|
1132
|
+
* doc's `data-recent-since`, which every edit may move; not its `class`), more than half of `main` changed,
|
|
1133
|
+
* the source as loaded couldn't be read, or the patch threw
|
|
1134
|
+
* - BODIES from files (`<ui-section source>`, `<ui-accordion source>`: a split epic page's parts) live their own
|
|
1135
|
+
* life (`wireSourceBodies()`): the patch leaves what a host loaded alone (`isSourceHost()`), a changed body file
|
|
1136
|
+
* re-fetches its open host in place, and each body that loads re-wires the page (`refresh()`)
|
|
1137
|
+
* - an epic page in `<epic-*>` markup (epic `epic-components`): its elements are patched, never replaced
|
|
1138
|
+
* (`EPIC_TAG`), their page state kept (`EPIC_PAGE_STATE`);
|
|
1139
|
+
* their parts (`<epic-item source>` ...) live the bodies' life above
|
|
1140
|
+
* - returns `{ ready(page), refresh(changed) }`: `start()` hands over what it wired; a change waits for it.
|
|
1141
|
+
* `refresh()` re-wires after `changed` elements changed under the runtime (a body loaded), in turn with updates
|
|
1142
|
+
*/
|
|
621
1143
|
function wireLiveUpdate(main) {
|
|
622
|
-
const server = window.SPELL_SERVER
|
|
623
|
-
let ready =
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
let queue = Promise.resolve()
|
|
627
|
-
const live = { ready, refresh }
|
|
628
|
-
wireSourceBodies(main, live, enqueue)
|
|
629
|
-
wireLiveCounts(main, refresh)
|
|
630
|
-
if (!server?.readPage || !canPatch(main)) return live
|
|
1144
|
+
const server = window.SPELL_SERVER
|
|
1145
|
+
let ready = () => {}
|
|
1146
|
+
const started = new Promise((resolve) => (ready = resolve))
|
|
1147
|
+
// one update at a time, in order: patches, re-fetched bodies, re-wiring
|
|
1148
|
+
let queue = Promise.resolve()
|
|
1149
|
+
const live = { ready, refresh }
|
|
1150
|
+
wireSourceBodies(main, live, enqueue)
|
|
1151
|
+
wireLiveCounts(main, refresh)
|
|
1152
|
+
if (!server?.readPage || !canPatch(main)) return live
|
|
1153
|
+
// the source as loaded: null when it can't be trusted (the file changed before it was read)
|
|
631
1154
|
let base = server.readPage().then(
|
|
632
|
-
({ html, etag }) => etag && etag === server.etag ? html : null,
|
|
1155
|
+
({ html, etag }) => (etag && etag === server.etag ? html : null),
|
|
633
1156
|
() => null
|
|
634
|
-
)
|
|
1157
|
+
)
|
|
635
1158
|
addEventListener("spell-server:reloading", (event) => {
|
|
636
|
-
const { html, reload, own } = event.detail ?? {}
|
|
637
|
-
if (typeof html !== "string" || typeof reload !== "function") return
|
|
638
|
-
event.preventDefault()
|
|
639
|
-
queue = queue.then(() => update(html, reload, own)).catch(() => reload())
|
|
640
|
-
})
|
|
641
|
-
return live
|
|
1159
|
+
const { html, reload, own } = event.detail ?? {}
|
|
1160
|
+
if (typeof html !== "string" || typeof reload !== "function") return
|
|
1161
|
+
event.preventDefault()
|
|
1162
|
+
queue = queue.then(() => update(html, reload, own)).catch(() => reload())
|
|
1163
|
+
})
|
|
1164
|
+
return live
|
|
1165
|
+
|
|
1166
|
+
/**
|
|
1167
|
+
* Patch the page to `html`, then re-wire it; reload when it can't be patched.
|
|
1168
|
+
* - `own`: the page shows it already (its own save): only the new baseline
|
|
1169
|
+
*/
|
|
642
1170
|
async function update(html, reload, own) {
|
|
643
1171
|
if (own) {
|
|
644
|
-
base = Promise.resolve(html)
|
|
645
|
-
return
|
|
1172
|
+
base = Promise.resolve(html)
|
|
1173
|
+
return
|
|
646
1174
|
}
|
|
647
|
-
const [before, page] = await Promise.all([base, started])
|
|
648
|
-
|
|
649
|
-
|
|
1175
|
+
const [before, page] = await Promise.all([base, started])
|
|
1176
|
+
// no motion while the page takes the change: it's the file, not the reader, moving things
|
|
1177
|
+
quietFor(QUIET_PATCH_MS)
|
|
1178
|
+
let patched = null
|
|
650
1179
|
try {
|
|
651
|
-
patched =
|
|
652
|
-
before
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
1180
|
+
patched =
|
|
1181
|
+
before === null
|
|
1182
|
+
? null
|
|
1183
|
+
: await patcher.redraw({
|
|
1184
|
+
before: parse(before),
|
|
1185
|
+
after: parse(html),
|
|
1186
|
+
live: page.main,
|
|
1187
|
+
mainOf: mainIn,
|
|
1188
|
+
top: () => stuckBottom(page.main)
|
|
1189
|
+
})
|
|
658
1190
|
} catch (error) {
|
|
659
|
-
|
|
660
|
-
|
|
1191
|
+
// says WHY, so a page that keeps falling back to its reload can be fixed (the reload waits until out of sight)
|
|
1192
|
+
console.warn("live update: can't patch this page in place; it reloads once out of sight:", error)
|
|
1193
|
+
return reload()
|
|
661
1194
|
}
|
|
662
1195
|
if (!patched) {
|
|
663
1196
|
console.warn(
|
|
664
1197
|
`live update: can't patch this page in place (${before === null ? "its source as loaded is unknown" : "its head or shell changed, or too much of it"}); it reloads once out of sight`
|
|
665
|
-
)
|
|
666
|
-
return reload()
|
|
1198
|
+
)
|
|
1199
|
+
return reload()
|
|
667
1200
|
}
|
|
668
|
-
base = Promise.resolve(html)
|
|
669
|
-
await rewire(page, patched.changed)
|
|
1201
|
+
base = Promise.resolve(html)
|
|
1202
|
+
await rewire(page, patched.changed)
|
|
670
1203
|
}
|
|
671
|
-
|
|
1204
|
+
|
|
1205
|
+
/** Re-wire the page once it's started, after `changed` (elements) changed: queued behind the updates. */
|
|
672
1206
|
function refresh(changed) {
|
|
673
|
-
enqueue(async () => rewire(await started, changed))
|
|
1207
|
+
enqueue(async () => rewire(await started, changed))
|
|
674
1208
|
}
|
|
675
|
-
|
|
1209
|
+
|
|
1210
|
+
/** Run `job` (async) after every update queued before it; a failure doesn't stop the queue. */
|
|
676
1211
|
function enqueue(job) {
|
|
677
|
-
queue = queue.then(job).catch(() =>
|
|
1212
|
+
queue = queue.then(job).catch(() => undefined)
|
|
678
1213
|
}
|
|
679
|
-
__name(enqueue, "enqueue");
|
|
680
1214
|
}
|
|
681
|
-
|
|
1215
|
+
|
|
1216
|
+
/**
|
|
1217
|
+
* An epic page's blocks' counts changing with no change to the markup (`epic-count-changed`, epic `epic-engine` I147):
|
|
1218
|
+
* an item or phase being worked on, an urgency not applied yet -- the review inbox's, which the blocks follow live.
|
|
1219
|
+
* - the page is re-wired once per frame of such changes (`refresh([])`): the toolbar's badges counted again from each
|
|
1220
|
+
* block's `contentsEntry`, the same live state its chips draw (Owen, 2026-10-26: "badges don't match up")
|
|
1221
|
+
*/
|
|
682
1222
|
function wireLiveCounts(main, refresh) {
|
|
683
|
-
let queued = false
|
|
1223
|
+
let queued = false
|
|
684
1224
|
main.addEventListener("epic-count-changed", () => {
|
|
685
|
-
if (queued) return
|
|
686
|
-
queued = true
|
|
1225
|
+
if (queued) return
|
|
1226
|
+
queued = true
|
|
687
1227
|
requestAnimationFrame(() => {
|
|
688
|
-
queued = false
|
|
689
|
-
refresh([])
|
|
690
|
-
})
|
|
691
|
-
})
|
|
1228
|
+
queued = false
|
|
1229
|
+
refresh([])
|
|
1230
|
+
})
|
|
1231
|
+
})
|
|
692
1232
|
}
|
|
693
|
-
|
|
694
|
-
|
|
1233
|
+
|
|
1234
|
+
/** A script Spell UI adds to a page as it needs it (`bundle-spell-ui.js`): it only defines data, never reads the markup. */
|
|
1235
|
+
const LAZY_SCRIPT = /\/assets\/(lazy|emoji)\//
|
|
1236
|
+
|
|
1237
|
+
/**
|
|
1238
|
+
* Can this page be patched in place?
|
|
1239
|
+
* - `<ui-section>` markup (or an epic page in `<epic-*>` markup: its `<epic-page>`)
|
|
1240
|
+
* - no CHEATSHEET filter
|
|
1241
|
+
* - no script but the bundle, highlight.js, what the page server injects,
|
|
1242
|
+
* component packs (`<ui-components source="x.pack.js">`'s script, which only defines elements),
|
|
1243
|
+
* the engines and emoji names Spell UI loads as it needs them (`LAZY_SCRIPT`; without them, a page with a
|
|
1244
|
+
* `<ui-markdown>` reloaded on every edit, Owen 2026-11-01: in the side bar, back to its top)
|
|
1245
|
+
* and inert data blocks (`PagePatch.isInert()`: epic pages' "Plan hung?" notice keeps its prompt in one)
|
|
1246
|
+
*/
|
|
695
1247
|
function canPatch(main) {
|
|
696
|
-
if (!main.querySelector(":scope > :is(ui-section, epic-page)")) return false
|
|
697
|
-
if (document.querySelector("[data-spell-filter], [data-spell-filter-badge]")) return false
|
|
1248
|
+
if (!main.querySelector(":scope > :is(ui-section, epic-page)")) return false
|
|
1249
|
+
if (document.querySelector("[data-spell-filter], [data-spell-filter-badge]")) return false
|
|
698
1250
|
return Array.from(document.scripts).every((script) => {
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
if (
|
|
702
|
-
|
|
703
|
-
|
|
1251
|
+
// one the page server added to every page (`PageServer.withPageScripts()`, spell-app's spell colours): in the
|
|
1252
|
+
// source the patch compares too; without this, every epic page reloaded on every edit (2026-10-25)
|
|
1253
|
+
if (script.hasAttribute("data-spell-page-script")) return true
|
|
1254
|
+
const src = script.getAttribute("src")
|
|
1255
|
+
if (!src) return PagePatch.isInert(script) || script.textContent.includes("SPELL_SERVER")
|
|
1256
|
+
return (
|
|
1257
|
+
/^\/api\/server\//.test(src) ||
|
|
1258
|
+
/(^|\/)(spell-ui|highlight(\.min)?|[\w-]+\.pack)\.js$/.test(src) ||
|
|
1259
|
+
LAZY_SCRIPT.test(src)
|
|
1260
|
+
)
|
|
1261
|
+
})
|
|
704
1262
|
}
|
|
705
|
-
|
|
1263
|
+
|
|
1264
|
+
////////////////
|
|
1265
|
+
// ## Bodies from files
|
|
1266
|
+
////////////////
|
|
1267
|
+
|
|
1268
|
+
/**
|
|
1269
|
+
* Hosts whose body comes from a file, in step with the files and the page:
|
|
1270
|
+
* `<ui-section source>`, `<ui-accordion source>`, and an epic page's parts
|
|
1271
|
+
* (`epics/<name>/parts/<id>.html`, epic `claude-design` P3, on its `<epic-*>` blocks and items).
|
|
1272
|
+
* - a body loads (the first open or a re-fetch): the page is re-wired around it (`live.refresh()`):
|
|
1273
|
+
* - `ui-loaded` (`LOADED`), from a Spell UI host or an `<epic-*>` block
|
|
1274
|
+
* the outline (headings inside), contents, counts, item filters, code colors
|
|
1275
|
+
* - a body's FILE changed (the page server's `spell-server:changed`, `liveClient.ts`): a host that has loaded it
|
|
1276
|
+
* re-fetches it in place (`reload()`), the reading position kept (`PagePatch.readingAnchor()`), the old body on screen
|
|
1277
|
+
* until the new one is in, then a short cross-fade (`PagePatch.crossFade()`, I164); one that hasn't drops the
|
|
1278
|
+
* cached copy, so its first open fetches the new one
|
|
1279
|
+
* - `enqueue`: the live update's queue (`wireLiveUpdate()`): a re-fetch waits for a patch in flight
|
|
1280
|
+
*/
|
|
706
1281
|
function wireSourceBodies(main, live, enqueue) {
|
|
707
1282
|
main.addEventListener(LOADED, (event) => {
|
|
708
|
-
const host = event.target
|
|
709
|
-
if (host instanceof Element && host.hasAttribute("source") && main.contains(host)) live.refresh([host])
|
|
710
|
-
})
|
|
1283
|
+
const host = event.target
|
|
1284
|
+
if (host instanceof Element && host.hasAttribute("source") && main.contains(host)) live.refresh([host])
|
|
1285
|
+
})
|
|
711
1286
|
addEventListener("spell-server:changed", (event) => {
|
|
712
|
-
const path = event.detail?.path
|
|
713
|
-
if (typeof path !== "string") return
|
|
714
|
-
const changed = decodeURIComponent(path)
|
|
1287
|
+
const path = event.detail?.path
|
|
1288
|
+
if (typeof path !== "string") return
|
|
1289
|
+
const changed = decodeURIComponent(path)
|
|
715
1290
|
for (const host of main.querySelectorAll("[source]")) {
|
|
716
|
-
const url = sourceUrl(host)
|
|
717
|
-
if (!url || decodeURIComponent(url.pathname) !== changed) continue
|
|
718
|
-
if (hasLoaded(host)) enqueue(() => reloadBody(host))
|
|
719
|
-
else forgetSource(url.href)
|
|
1291
|
+
const url = sourceUrl(host)
|
|
1292
|
+
if (!url || decodeURIComponent(url.pathname) !== changed) continue
|
|
1293
|
+
if (hasLoaded(host)) enqueue(() => reloadBody(host))
|
|
1294
|
+
else forgetSource(url.href)
|
|
720
1295
|
}
|
|
721
|
-
})
|
|
1296
|
+
})
|
|
1297
|
+
|
|
1298
|
+
/**
|
|
1299
|
+
* Re-fetch `host`'s body, keeping the line being read where it is.
|
|
1300
|
+
* - what had the focus inside it, a note box being typed in: focused again, its caret where it was
|
|
1301
|
+
* - `dock()` puts the same box back;
|
|
1302
|
+
* an `<epic-item>`'s is in its shadow root, which the reload may hide for a moment
|
|
1303
|
+
*/
|
|
722
1304
|
async function reloadBody(host) {
|
|
723
|
-
const anchor = PagePatch.readingAnchor(main, stuckBottom(main))
|
|
724
|
-
const active = host.contains(document.activeElement) ? deepActiveElement() : null
|
|
725
|
-
const caret = active && "selectionStart" in active ? [active.selectionStart, active.selectionEnd] : null
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
1305
|
+
const anchor = PagePatch.readingAnchor(main, stuckBottom(main))
|
|
1306
|
+
const active = host.contains(document.activeElement) ? deepActiveElement() : null
|
|
1307
|
+
const caret = active && "selectionStart" in active ? [active.selectionStart, active.selectionEnd] : null
|
|
1308
|
+
// the body goes in on the host's `ui-loaded`, which can come after `reload()` resolves;
|
|
1309
|
+
// the runtime's pieces go back on it (`live.refresh()`): wait for it (2s at most), then for them
|
|
1310
|
+
const loaded =
|
|
1311
|
+
active &&
|
|
1312
|
+
new Promise((done) => {
|
|
1313
|
+
host.addEventListener(LOADED, done, { once: true })
|
|
1314
|
+
setTimeout(done, 2000)
|
|
1315
|
+
})
|
|
1316
|
+
// the old body stays up until the new one is in, then one short cross-fade (I164): never the host's loading look
|
|
730
1317
|
await PagePatch.crossFade(async () => {
|
|
731
|
-
const swapped = loaded || bodyIn(host)
|
|
732
|
-
await host.reload?.()
|
|
733
|
-
await swapped
|
|
734
|
-
PagePatch.keepAnchor(anchor)
|
|
735
|
-
}, PagePatch.isOnScreen(host))
|
|
736
|
-
if (!active) return
|
|
737
|
-
await loaded
|
|
738
|
-
for (let frame = 0; frame < 60 && !active.isConnected; frame++) await nextFrame(1)
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
active.
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
}
|
|
746
|
-
|
|
1318
|
+
const swapped = loaded || bodyIn(host)
|
|
1319
|
+
await host.reload?.()
|
|
1320
|
+
await swapped
|
|
1321
|
+
PagePatch.keepAnchor(anchor)
|
|
1322
|
+
}, PagePatch.isOnScreen(host))
|
|
1323
|
+
if (!active) return
|
|
1324
|
+
await loaded
|
|
1325
|
+
for (let frame = 0; frame < 60 && !active.isConnected; frame++) await nextFrame(1)
|
|
1326
|
+
// the host draws what it hid while loading (a frame): hidden, the box can't take the focus
|
|
1327
|
+
await nextFrame(1)
|
|
1328
|
+
if (!active.isConnected || deepActiveElement() === active) return
|
|
1329
|
+
active.focus({ preventScroll: true })
|
|
1330
|
+
if (caret) active.setSelectionRange(...caret)
|
|
1331
|
+
}
|
|
1332
|
+
}
|
|
1333
|
+
|
|
1334
|
+
/** Resolves once `host`'s body is in (its `ui-loaded`), or after `BODY_WAIT_MS` at most. */
|
|
747
1335
|
function bodyIn(host) {
|
|
748
1336
|
return new Promise((done) => {
|
|
749
|
-
host.addEventListener(LOADED, done, { once: true })
|
|
750
|
-
setTimeout(done, BODY_WAIT_MS)
|
|
751
|
-
})
|
|
1337
|
+
host.addEventListener(LOADED, done, { once: true })
|
|
1338
|
+
setTimeout(done, BODY_WAIT_MS)
|
|
1339
|
+
})
|
|
752
1340
|
}
|
|
753
|
-
|
|
1341
|
+
|
|
1342
|
+
/** The element with the focus, inside shadow roots too (`document.activeElement` stops at their hosts). */
|
|
754
1343
|
function deepActiveElement() {
|
|
755
|
-
let active = document.activeElement
|
|
756
|
-
while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement
|
|
757
|
-
return active
|
|
1344
|
+
let active = document.activeElement
|
|
1345
|
+
while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement
|
|
1346
|
+
return active
|
|
758
1347
|
}
|
|
759
|
-
|
|
1348
|
+
|
|
1349
|
+
/** Absolute URL of `host`'s `source`, when it's on this page's origin; else null. */
|
|
760
1350
|
function sourceUrl(host) {
|
|
761
1351
|
try {
|
|
762
|
-
const url = new URL(host.getAttribute("source"), document.baseURI)
|
|
763
|
-
return url.origin === location.origin ? url : null
|
|
1352
|
+
const url = new URL(host.getAttribute("source"), document.baseURI)
|
|
1353
|
+
return url.origin === location.origin ? url : null
|
|
764
1354
|
} catch {
|
|
765
|
-
return null
|
|
1355
|
+
return null
|
|
766
1356
|
}
|
|
767
1357
|
}
|
|
768
|
-
|
|
1358
|
+
|
|
1359
|
+
/** Has `host` started on its body (loading, loaded, or failed: then a re-fetch tries again)? */
|
|
769
1360
|
function hasLoaded(host) {
|
|
770
1361
|
try {
|
|
771
|
-
return host.matches(":state(loaded), :state(loading), :state(error)")
|
|
1362
|
+
return host.matches(":state(loaded), :state(loading), :state(error)")
|
|
772
1363
|
} catch {
|
|
773
|
-
return false
|
|
1364
|
+
return false
|
|
774
1365
|
}
|
|
775
1366
|
}
|
|
776
|
-
|
|
1367
|
+
|
|
1368
|
+
/** Drop `url` from UI's cache of fetched files (`UI.sources`), so the next load fetches it. */
|
|
777
1369
|
function forgetSource(url) {
|
|
778
1370
|
try {
|
|
779
|
-
void window.SpellUI?.UI?.load?.()?.then((ui) => ui.sources.forget(url))
|
|
1371
|
+
void window.SpellUI?.UI?.load?.()?.then((ui) => ui.sources.forget(url))
|
|
780
1372
|
} catch {
|
|
1373
|
+
// no UI yet: nothing cached either
|
|
781
1374
|
}
|
|
782
1375
|
}
|
|
783
|
-
|
|
1376
|
+
|
|
1377
|
+
/**
|
|
1378
|
+
* The host whose unloaded body holds element `id`: its `data-part-ids` (the ids inside, written by
|
|
1379
|
+
* `PlanParts`; an epic page's `<epic-*>`: `part-ids`), when the element isn't in the page yet; else null.
|
|
1380
|
+
*/
|
|
784
1381
|
function hostHolding(main, id) {
|
|
785
|
-
if (!id || document.getElementById(id)) return null
|
|
786
|
-
const ids =
|
|
787
|
-
return
|
|
788
|
-
(
|
|
789
|
-
|
|
1382
|
+
if (!id || document.getElementById(id)) return null
|
|
1383
|
+
const ids = (host) => (host.getAttribute("data-part-ids") ?? host.getAttribute("part-ids") ?? "").split(/\s+/)
|
|
1384
|
+
return (
|
|
1385
|
+
Array.from(main.querySelectorAll("[source]:is([data-part-ids], [part-ids])")).find((host) =>
|
|
1386
|
+
ids(host).includes(id)
|
|
1387
|
+
) ?? null
|
|
1388
|
+
)
|
|
790
1389
|
}
|
|
791
|
-
|
|
1390
|
+
|
|
1391
|
+
/** Parse a page's HTML into an inert document. */
|
|
792
1392
|
function parse(html) {
|
|
793
|
-
return new DOMParser().parseFromString(html, "text/html")
|
|
1393
|
+
return new DOMParser().parseFromString(html, "text/html")
|
|
794
1394
|
}
|
|
795
|
-
|
|
1395
|
+
|
|
1396
|
+
/** A document's (or body's) `main`, as `start()` finds it. */
|
|
796
1397
|
function mainIn(root) {
|
|
797
|
-
return root.querySelector("main.spell-doc-main") ?? root.querySelector("main")
|
|
1398
|
+
return root.querySelector("main.spell-doc-main") ?? root.querySelector("main")
|
|
798
1399
|
}
|
|
799
|
-
|
|
1400
|
+
|
|
1401
|
+
/**
|
|
1402
|
+
* Is `element` a host whose body comes from a file (`source`), so that only its SLOTTED children (icon, header) are
|
|
1403
|
+
* the page's source? Its body is the file's (`wireSourceBodies()`): the patch leaves it alone.
|
|
1404
|
+
* - not an accordion host (`<ui-accordion source>`): a `MANAGERS` element, replaced whole as ever, its open panel
|
|
1405
|
+
* carried over, so it loads its body again
|
|
1406
|
+
*/
|
|
800
1407
|
function isSourceHost(element) {
|
|
801
|
-
return element.hasAttribute("source") && !element.matches(MANAGERS)
|
|
1408
|
+
return element.hasAttribute("source") && !element.matches(MANAGERS)
|
|
802
1409
|
}
|
|
803
|
-
|
|
1410
|
+
|
|
1411
|
+
/**
|
|
1412
|
+
* Give `copy`, a new or replacing element not yet in the page, the reader's state (the patcher's `prepare()`):
|
|
1413
|
+
* - folds: every section keeps its fold, new ones fold as `carryFolds()` says
|
|
1414
|
+
* - `<epic-*>` page state: `carryEpicState()`
|
|
1415
|
+
* - the kit's shared rules carry the rest: open panels, typed text (`PagePatch.keepReaderState()`)
|
|
1416
|
+
*/
|
|
804
1417
|
function carryState(copy) {
|
|
805
|
-
carryFolds(copy)
|
|
806
|
-
carryEpicState(copy)
|
|
1418
|
+
carryFolds(copy)
|
|
1419
|
+
carryEpicState(copy)
|
|
807
1420
|
}
|
|
808
|
-
|
|
1421
|
+
|
|
1422
|
+
/**
|
|
1423
|
+
* Fold every collapsible section in `copy` as the reader has it: as the live one with its `id`, else as saved
|
|
1424
|
+
* (`spell-folds:<path>`), else an epic page's start-folded (`wireFolds()`); else the markup's `open` stands.
|
|
1425
|
+
*/
|
|
809
1426
|
function carryFolds(copy) {
|
|
810
|
-
const saved = readJSON(`${FOLD_KEY_PREFIX}${location.pathname}`)
|
|
811
|
-
const planDoc = document.body.classList.contains("plan-doc")
|
|
1427
|
+
const saved = readJSON(`${FOLD_KEY_PREFIX}${location.pathname}`)
|
|
1428
|
+
const planDoc = document.body.classList.contains("plan-doc")
|
|
812
1429
|
for (const section of PagePatch.withSelf(copy, "ui-section[collapsible]")) {
|
|
813
|
-
const old = section.id ? document.getElementById(section.id) : null
|
|
814
|
-
if (old?.localName === "ui-section") foldAttribute(section, isCollapsed(old))
|
|
815
|
-
else if (section.id && section.id in saved) foldAttribute(section, !!saved[section.id])
|
|
816
|
-
else if (planDoc) foldAttribute(section, true)
|
|
1430
|
+
const old = section.id ? document.getElementById(section.id) : null
|
|
1431
|
+
if (old?.localName === "ui-section") foldAttribute(section, isCollapsed(old))
|
|
1432
|
+
else if (section.id && section.id in saved) foldAttribute(section, !!saved[section.id])
|
|
1433
|
+
else if (planDoc) foldAttribute(section, true)
|
|
817
1434
|
}
|
|
818
1435
|
}
|
|
819
|
-
|
|
1436
|
+
|
|
1437
|
+
/**
|
|
1438
|
+
* Give every `<epic-*>` element with an `id` in `copy` the page state (`EPIC_PAGE_STATE`: `open` ...) of the live one
|
|
1439
|
+
* with that `id` and tag; a new one starts as its markup says (folded: `open` is never in the file).
|
|
1440
|
+
*/
|
|
820
1441
|
function carryEpicState(copy) {
|
|
821
1442
|
for (const element of PagePatch.withSelf(copy, "[id]")) {
|
|
822
|
-
if (!EPIC_TAG.test(element.localName)) continue
|
|
823
|
-
const old = document.getElementById(element.id)
|
|
824
|
-
if (old?.localName !== element.localName) continue
|
|
1443
|
+
if (!EPIC_TAG.test(element.localName)) continue
|
|
1444
|
+
const old = document.getElementById(element.id)
|
|
1445
|
+
if (old?.localName !== element.localName) continue
|
|
825
1446
|
for (const name of EPIC_PAGE_STATE) {
|
|
826
|
-
const value = old.getAttribute(name)
|
|
827
|
-
if (value === null) element.removeAttribute(name)
|
|
828
|
-
else element.setAttribute(name, value)
|
|
1447
|
+
const value = old.getAttribute(name)
|
|
1448
|
+
if (value === null) element.removeAttribute(name)
|
|
1449
|
+
else element.setAttribute(name, value)
|
|
829
1450
|
}
|
|
830
1451
|
}
|
|
831
1452
|
}
|
|
832
|
-
|
|
1453
|
+
|
|
1454
|
+
/**
|
|
1455
|
+
* After a patch, redo what the runtime built from the markup, as `start()` did:
|
|
1456
|
+
* - the outline (ids for new entries), counts, item filters
|
|
1457
|
+
* - the toolbar, rebuilt only when its entries, icons or counts changed (`railKey()`)
|
|
1458
|
+
* - sticky lines, re-tracked when new sections came in
|
|
1459
|
+
* - code colors and copy buttons (`addCodeCopies()`) in what's new; scroll-follow re-read
|
|
1460
|
+
* - then `spell-doc:updated` on `window`, `detail.changed`
|
|
1461
|
+
* - `page`: what `start()` wired (`{ main, rail, sticky, follow, entries }`); updated here
|
|
1462
|
+
*/
|
|
833
1463
|
async function rewire(page, changed) {
|
|
834
|
-
const { main } = page
|
|
835
|
-
quietFor(QUIET_PATCH_MS)
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
const
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
page.entries =
|
|
1464
|
+
const { main } = page
|
|
1465
|
+
quietFor(QUIET_PATCH_MS)
|
|
1466
|
+
// an epic page's blocks take the change in a microtask (Solid batches): each `contentsEntry` reads it after
|
|
1467
|
+
if (main.querySelector("epic-page")) await nextFrame(1)
|
|
1468
|
+
const outline = outlineOf(main)
|
|
1469
|
+
const counts = countItems(outline)
|
|
1470
|
+
wireItemFilters(main)
|
|
1471
|
+
highlightIn(changed)
|
|
1472
|
+
addCodeCopies(main)
|
|
1473
|
+
editMarkdownInPlace(changed)
|
|
1474
|
+
const entries = railKey(outline, counts)
|
|
1475
|
+
if (entries !== page.entries) page.rail = buildNavigation(main, outline, counts)
|
|
1476
|
+
page.entries = entries
|
|
846
1477
|
if (changed.some((node) => PagePatch.withSelf(node, "ui-section").length))
|
|
847
|
-
page.sticky = trackStickyHeights(main, outline)
|
|
848
|
-
page.follow.rescan(page.rail)
|
|
849
|
-
await nextFrame(UNFOLD_FRAMES)
|
|
850
|
-
page.sticky.measure()
|
|
851
|
-
page.follow?.update()
|
|
852
|
-
dispatchEvent(new CustomEvent("spell-doc:updated", { detail: { changed } }))
|
|
853
|
-
}
|
|
854
|
-
|
|
1478
|
+
page.sticky = trackStickyHeights(main, outline)
|
|
1479
|
+
page.follow.rescan(page.rail)
|
|
1480
|
+
await nextFrame(UNFOLD_FRAMES)
|
|
1481
|
+
page.sticky.measure()
|
|
1482
|
+
page.follow?.update()
|
|
1483
|
+
dispatchEvent(new CustomEvent("spell-doc:updated", { detail: { changed } }))
|
|
1484
|
+
}
|
|
1485
|
+
|
|
1486
|
+
/** What the toolbar is built from, as one string: entries, labels, icons, what needs Owen. */
|
|
855
1487
|
function railKey(outline, counts) {
|
|
856
|
-
return JSON.stringify(outline.groups.map(entry))
|
|
1488
|
+
return JSON.stringify(outline.groups.map(entry))
|
|
1489
|
+
|
|
1490
|
+
/**
|
|
1491
|
+
* One top-level entry: its id, label, icon and state, how many of its items need Owen (and how), and how many of
|
|
1492
|
+
* its phases run now.
|
|
1493
|
+
*/
|
|
857
1494
|
function entry(node) {
|
|
858
|
-
const count = counts.get(node.element)
|
|
1495
|
+
const count = counts.get(node.element)
|
|
859
1496
|
return [
|
|
860
1497
|
node.id,
|
|
861
1498
|
node.label,
|
|
@@ -864,28 +1501,52 @@ function railKey(outline, counts) {
|
|
|
864
1501
|
count?.attention ?? 0,
|
|
865
1502
|
count?.replied ?? 0,
|
|
866
1503
|
count?.running ?? 0
|
|
867
|
-
]
|
|
1504
|
+
]
|
|
868
1505
|
}
|
|
869
|
-
__name(entry, "entry");
|
|
870
1506
|
}
|
|
871
|
-
|
|
1507
|
+
|
|
1508
|
+
/** Color the code blocks in `elements` that aren't yet (`highlight()` colored the rest at load). */
|
|
872
1509
|
function highlightIn(elements) {
|
|
873
|
-
const hljs = globalThis.hljs
|
|
874
|
-
if (!hljs?.highlightElement) return
|
|
1510
|
+
const hljs = globalThis.hljs
|
|
1511
|
+
if (!hljs?.highlightElement) return
|
|
875
1512
|
for (const element of elements)
|
|
876
1513
|
for (const code of PagePatch.withSelf(element, "pre code"))
|
|
877
1514
|
try {
|
|
878
|
-
if (!code.dataset.highlighted) hljs.highlightElement(code)
|
|
1515
|
+
if (!code.dataset.highlighted) hljs.highlightElement(code)
|
|
879
1516
|
} catch {
|
|
1517
|
+
// plain monospace is fine
|
|
880
1518
|
}
|
|
881
1519
|
}
|
|
882
|
-
|
|
1520
|
+
|
|
1521
|
+
////////////////
|
|
1522
|
+
// ## Outline
|
|
1523
|
+
////////////////
|
|
1524
|
+
|
|
1525
|
+
/**
|
|
1526
|
+
* The page's outline, from either markup (see the header): what the toolbar, the counts, scroll-follow
|
|
1527
|
+
* and the anchors work from.
|
|
1528
|
+
* - SECTIONS markup (`main > ui-section`, or an epic page's `<epic-page>`): top-level sections are the groups
|
|
1529
|
+
* - their entries, at any depth:
|
|
1530
|
+
* nested sections, and the h3s / h4s in a section's own content (CHEATSHEET cards, sub-sub-items)
|
|
1531
|
+
* - an h4 right after an h3 of the same section goes under it
|
|
1532
|
+
* - an epic page's sections are its folding blocks
|
|
1533
|
+
* (`EPIC_FOLDS`: the Overview and its parts, the sections, the phases)
|
|
1534
|
+
* - HEADINGS markup: h2s are the groups, h3s their entries, h4s under the h3 before them
|
|
1535
|
+
* - a node: `{ element, id, label, glyph, children }` -- `glyph` the name of its (first) `<ui-icon>`, for the toolbar
|
|
1536
|
+
* - returns `{ sections, groups, orphans, targets, entryOf, groupOf, folded }`:
|
|
1537
|
+
* - `orphans`: entries before or outside any group
|
|
1538
|
+
* - `targets`: selector of every entry's element, for scroll-follow
|
|
1539
|
+
* - `entryOf(element)`: the entry holding `element`, which a jump to it makes current
|
|
1540
|
+
* - `groupOf(entry)`: its top-level element, for the toolbar
|
|
1541
|
+
* - `folded(element)`: hidden by a folded section around it (SECTIONS; HEADINGS hide those with `display`)
|
|
1542
|
+
* - SIDE EFFECT: gives an entry with no `id` a slug of its label (`-2`, `-3` ... when taken)
|
|
1543
|
+
*/
|
|
883
1544
|
function outlineOf(main) {
|
|
884
|
-
const sections = !!main.querySelector(":scope > :is(ui-section, epic-page)")
|
|
885
|
-
const groups = []
|
|
886
|
-
const orphans = []
|
|
887
|
-
if (sections) readSections()
|
|
888
|
-
else readHeadings()
|
|
1545
|
+
const sections = !!main.querySelector(":scope > :is(ui-section, epic-page)")
|
|
1546
|
+
const groups = []
|
|
1547
|
+
const orphans = []
|
|
1548
|
+
if (sections) readSections()
|
|
1549
|
+
else readHeadings()
|
|
889
1550
|
return {
|
|
890
1551
|
sections,
|
|
891
1552
|
groups,
|
|
@@ -894,1072 +1555,1752 @@ function outlineOf(main) {
|
|
|
894
1555
|
entryOf,
|
|
895
1556
|
groupOf,
|
|
896
1557
|
folded
|
|
897
|
-
}
|
|
1558
|
+
}
|
|
1559
|
+
|
|
1560
|
+
/**
|
|
1561
|
+
* SECTIONS: every section, h3 and h4 in `main`, under the section it's in.
|
|
1562
|
+
* - not the headings in a plan item's earlier versions (`<epic-original>`): earlier text, not the page's
|
|
1563
|
+
* - not what an epic page's STAGE hides (`<epic-page stage>`, epic `epic-engine` P29; `PageStages.hides()`):
|
|
1564
|
+
* the toolbar lists only what shows
|
|
1565
|
+
*/
|
|
898
1566
|
function readSections() {
|
|
899
|
-
const nodes =
|
|
1567
|
+
const nodes = new Map()
|
|
900
1568
|
const elements = Array.from(main.querySelectorAll(`${SECTIONS}, h3, h4`)).filter(
|
|
901
1569
|
(element) => !element.closest("epic-original") && !PageStages.hides(element)
|
|
902
|
-
)
|
|
1570
|
+
)
|
|
903
1571
|
for (const element of elements) {
|
|
904
|
-
const node = nodeOf(element)
|
|
905
|
-
nodes.set(element, node)
|
|
906
|
-
const owner = element.parentElement?.closest(SECTIONS)
|
|
907
|
-
const list = owner ? nodes.get(owner).children : element.matches(SECTIONS) ? groups : orphans
|
|
908
|
-
const last = list.at(-1)
|
|
909
|
-
if (element.localName === "h4" && last?.element.localName === "h3") last.children.push(node)
|
|
910
|
-
else list.push(node)
|
|
1572
|
+
const node = nodeOf(element)
|
|
1573
|
+
nodes.set(element, node)
|
|
1574
|
+
const owner = element.parentElement?.closest(SECTIONS)
|
|
1575
|
+
const list = owner ? nodes.get(owner).children : element.matches(SECTIONS) ? groups : orphans
|
|
1576
|
+
const last = list.at(-1)
|
|
1577
|
+
if (element.localName === "h4" && last?.element.localName === "h3") last.children.push(node)
|
|
1578
|
+
else list.push(node)
|
|
911
1579
|
}
|
|
912
1580
|
}
|
|
913
|
-
|
|
1581
|
+
|
|
1582
|
+
/** HEADINGS: h2 / h3 / h4 in document order. */
|
|
914
1583
|
function readHeadings() {
|
|
915
1584
|
for (const heading of main.querySelectorAll("h2, h3, h4")) {
|
|
916
|
-
const node = nodeOf(heading)
|
|
917
|
-
const group = groups.at(-1)
|
|
918
|
-
if (heading.localName === "h2") groups.push(node)
|
|
919
|
-
else if (heading.localName === "h3") (group?.children ?? orphans).push(node)
|
|
1585
|
+
const node = nodeOf(heading)
|
|
1586
|
+
const group = groups.at(-1)
|
|
1587
|
+
if (heading.localName === "h2") groups.push(node)
|
|
1588
|
+
else if (heading.localName === "h3") (group?.children ?? orphans).push(node)
|
|
920
1589
|
else {
|
|
921
|
-
const parent = group?.children.at(-1)
|
|
922
|
-
if (parent?.element.localName === "h3") parent.children.push(node)
|
|
923
|
-
else (group?.children ?? orphans).push(node)
|
|
1590
|
+
const parent = group?.children.at(-1)
|
|
1591
|
+
if (parent?.element.localName === "h3") parent.children.push(node)
|
|
1592
|
+
else (group?.children ?? orphans).push(node)
|
|
924
1593
|
}
|
|
925
1594
|
}
|
|
926
1595
|
}
|
|
927
|
-
|
|
1596
|
+
|
|
1597
|
+
/** The entry a jump to `element` makes current: itself, else its section's (heading's) entry. */
|
|
928
1598
|
function entryOf(element) {
|
|
929
|
-
if (sections) return element.closest(`${SECTIONS}, h3, h4`)
|
|
930
|
-
if (/^H[234]$/.test(element.tagName)) return element
|
|
931
|
-
return element.closest("section")?.querySelector(":scope > ui-sticky > :is(h2, h3)") ?? null
|
|
1599
|
+
if (sections) return element.closest(`${SECTIONS}, h3, h4`)
|
|
1600
|
+
if (/^H[234]$/.test(element.tagName)) return element
|
|
1601
|
+
return element.closest("section")?.querySelector(":scope > ui-sticky > :is(h2, h3)") ?? null
|
|
932
1602
|
}
|
|
933
|
-
|
|
1603
|
+
|
|
1604
|
+
/** The top-level element `entry` is in: the outermost section, or the h2. */
|
|
934
1605
|
function groupOf(entry) {
|
|
935
|
-
if (!sections) return entry.localName === "h2" ? entry : entry.closest("section.s2")?.querySelector("h2")
|
|
936
|
-
let top = null
|
|
1606
|
+
if (!sections) return entry.localName === "h2" ? entry : entry.closest("section.s2")?.querySelector("h2")
|
|
1607
|
+
let top = null
|
|
937
1608
|
for (let section = entry.closest(SECTIONS); section; section = section.parentElement?.closest(SECTIONS))
|
|
938
|
-
top = section
|
|
939
|
-
return top
|
|
1609
|
+
top = section
|
|
1610
|
+
return top
|
|
940
1611
|
}
|
|
941
|
-
|
|
1612
|
+
|
|
1613
|
+
/** Is `element` inside a folded section (not counting itself)? */
|
|
942
1614
|
function folded(element) {
|
|
943
|
-
if (!sections) return false
|
|
944
|
-
for (let section = element.parentElement?.closest(SECTIONS); section;
|
|
945
|
-
if (isCollapsed(section)) return true
|
|
946
|
-
section = section.parentElement?.closest(SECTIONS)
|
|
1615
|
+
if (!sections) return false
|
|
1616
|
+
for (let section = element.parentElement?.closest(SECTIONS); section;) {
|
|
1617
|
+
if (isCollapsed(section)) return true
|
|
1618
|
+
section = section.parentElement?.closest(SECTIONS)
|
|
947
1619
|
}
|
|
948
|
-
return false
|
|
1620
|
+
return false
|
|
949
1621
|
}
|
|
950
|
-
__name(folded, "folded");
|
|
951
1622
|
}
|
|
952
|
-
|
|
1623
|
+
|
|
1624
|
+
/**
|
|
1625
|
+
* An outline node for a heading, a `<ui-section>` or an epic page's block; gives it an id if it has none.
|
|
1626
|
+
* - a block: what its host says (`contentsEntry`), its id before it has drawn
|
|
1627
|
+
*/
|
|
953
1628
|
function nodeOf(element) {
|
|
954
1629
|
if (element.matches(EPIC_FOLDS)) {
|
|
955
|
-
const entry = element.contentsEntry
|
|
956
|
-
return { element, id: element.id, label: entry?.label ?? element.id, glyph: entry?.icon, children: [] }
|
|
1630
|
+
const entry = element.contentsEntry
|
|
1631
|
+
return { element, id: element.id, label: entry?.label ?? element.id, glyph: entry?.icon, children: [] }
|
|
957
1632
|
}
|
|
958
|
-
const section = element.localName === "ui-section"
|
|
959
|
-
const label = section ? sectionLabel(element) : labelOf(element)
|
|
960
|
-
if (!element.id) element.id = uniqueId(headingSlug(label) || "section")
|
|
961
|
-
const glyph = section
|
|
962
|
-
|
|
1633
|
+
const section = element.localName === "ui-section"
|
|
1634
|
+
const label = section ? sectionLabel(element) : labelOf(element)
|
|
1635
|
+
if (!element.id) element.id = uniqueId(headingSlug(label) || "section")
|
|
1636
|
+
const glyph = section
|
|
1637
|
+
? (element.querySelector(':scope > ui-icon[slot="icon"]')?.getAttribute("name") ?? element.getAttribute("icon"))
|
|
1638
|
+
: element.querySelector("ui-icon")?.getAttribute("name")
|
|
1639
|
+
return { element, id: element.id, label, glyph: glyph || undefined, children: [] }
|
|
963
1640
|
}
|
|
964
|
-
|
|
1641
|
+
|
|
1642
|
+
/** A `<ui-section>`'s label: its `label`, else the text of its `slot="label"` child. */
|
|
965
1643
|
function sectionLabel(section) {
|
|
966
|
-
const label = section.getAttribute("label")?.trim()
|
|
967
|
-
if (label) return label
|
|
968
|
-
const slotted = section.querySelector(':scope > [slot="label"]')
|
|
969
|
-
return slotted ? labelOf(slotted) : ""
|
|
1644
|
+
const label = section.getAttribute("label")?.trim()
|
|
1645
|
+
if (label) return label
|
|
1646
|
+
const slotted = section.querySelector(':scope > [slot="label"]')
|
|
1647
|
+
return slotted ? labelOf(slotted) : ""
|
|
970
1648
|
}
|
|
971
|
-
|
|
1649
|
+
|
|
1650
|
+
/** `id`, or `id-2`, `id-3` ... if the page already has it. */
|
|
972
1651
|
function uniqueId(id) {
|
|
973
|
-
let candidate = id
|
|
974
|
-
for (let n = 2; document.getElementById(candidate); n++) candidate = `${id}-${n}
|
|
975
|
-
return candidate
|
|
1652
|
+
let candidate = id
|
|
1653
|
+
for (let n = 2; document.getElementById(candidate); n++) candidate = `${id}-${n}`
|
|
1654
|
+
return candidate
|
|
976
1655
|
}
|
|
977
|
-
|
|
1656
|
+
|
|
1657
|
+
/**
|
|
1658
|
+
* Is `section` folded? A `<ui-section>`: not `open`, by the property, else (not upgraded yet) `open="false"`;
|
|
1659
|
+
* an epic page's block (or item): not `open`, by the property, else the attribute.
|
|
1660
|
+
*/
|
|
978
1661
|
function isCollapsed(section) {
|
|
979
1662
|
if (section.matches(EPIC_OPENERS))
|
|
980
|
-
return !(typeof section.open === "boolean" ? section.open : section.hasAttribute("open"))
|
|
981
|
-
return typeof section.open === "boolean" ? !section.open : section.getAttribute("open") === "false"
|
|
1663
|
+
return !(typeof section.open === "boolean" ? section.open : section.hasAttribute("open"))
|
|
1664
|
+
return typeof section.open === "boolean" ? !section.open : section.getAttribute("open") === "false"
|
|
982
1665
|
}
|
|
983
|
-
|
|
1666
|
+
|
|
1667
|
+
/**
|
|
1668
|
+
* Fold or unfold a section without an event: `open` (a `<ui-section>`, and an epic page's blocks and
|
|
1669
|
+
* items) is controlled, so writing it announces nothing.
|
|
1670
|
+
*/
|
|
984
1671
|
function setCollapsed(section, collapsed) {
|
|
985
|
-
if (section.matches(EPIC_OPENERS)) section.toggleAttribute("open", !collapsed)
|
|
986
|
-
else foldAttribute(section, collapsed)
|
|
1672
|
+
if (section.matches(EPIC_OPENERS)) section.toggleAttribute("open", !collapsed)
|
|
1673
|
+
else foldAttribute(section, collapsed)
|
|
987
1674
|
}
|
|
988
|
-
|
|
1675
|
+
|
|
1676
|
+
/** Fold a `<ui-section>` (`open="false"`) or open it (no `open`: open is its default), by the attribute. */
|
|
989
1677
|
function foldAttribute(section, isFolded) {
|
|
990
|
-
if (isFolded) section.setAttribute("open", "false")
|
|
991
|
-
else section.removeAttribute("open")
|
|
1678
|
+
if (isFolded) section.setAttribute("open", "false")
|
|
1679
|
+
else section.removeAttribute("open")
|
|
992
1680
|
}
|
|
993
|
-
|
|
1681
|
+
|
|
1682
|
+
/**
|
|
1683
|
+
* The shadow title bar of a `<ui-section>` (its public `title` part), once it has rendered; an epic page's block's:
|
|
1684
|
+
* the one of the `<ui-section>` it draws in its own shadow root.
|
|
1685
|
+
*/
|
|
994
1686
|
function titleOf(section) {
|
|
995
|
-
const inner = section.matches(EPIC_FOLDS) ? section.shadowRoot?.querySelector("ui-section") : section
|
|
996
|
-
return inner?.shadowRoot?.querySelector('[part~="title"]') ?? null
|
|
1687
|
+
const inner = section.matches(EPIC_FOLDS) ? section.shadowRoot?.querySelector("ui-section") : section
|
|
1688
|
+
return inner?.shadowRoot?.querySelector('[part~="title"]') ?? null
|
|
997
1689
|
}
|
|
998
|
-
|
|
1690
|
+
|
|
1691
|
+
////////////////
|
|
1692
|
+
// ## Text
|
|
1693
|
+
////////////////
|
|
1694
|
+
|
|
1695
|
+
/** A heading's label: its text without badges, whitespace collapsed. */
|
|
999
1696
|
function labelOf(heading) {
|
|
1000
|
-
const clone = heading.cloneNode(true)
|
|
1001
|
-
for (const badge of clone.querySelectorAll(".tag, ui-label")) badge.remove()
|
|
1002
|
-
return clone.textContent.replace(/\s+/g, " ").trim()
|
|
1697
|
+
const clone = heading.cloneNode(true)
|
|
1698
|
+
for (const badge of clone.querySelectorAll(".tag, ui-label")) badge.remove()
|
|
1699
|
+
return clone.textContent.replace(/\s+/g, " ").trim()
|
|
1003
1700
|
}
|
|
1004
|
-
|
|
1701
|
+
|
|
1702
|
+
/** A heading's id from its `label`: the kit's `slug()`, cut at 48. */
|
|
1005
1703
|
function headingSlug(label) {
|
|
1006
|
-
return slug(label).slice(0, 48)
|
|
1704
|
+
return slug(label).slice(0, 48)
|
|
1007
1705
|
}
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1706
|
+
|
|
1707
|
+
////////////////
|
|
1708
|
+
// ## Counts
|
|
1709
|
+
////////////////
|
|
1710
|
+
|
|
1711
|
+
/**
|
|
1712
|
+
* Item statuses that DON'T count as open: finished (`done`), made moot (`canceled`), and a plan's answered
|
|
1713
|
+
* questions (`decided`) -- in "Questions" only the questions waiting on the reader are open.
|
|
1714
|
+
* - `spell/epic/tool/planDoc.types` `CLOSED` is the same set
|
|
1715
|
+
*/
|
|
1716
|
+
const CLOSED = new Set(["done", "decided", "canceled"])
|
|
1717
|
+
|
|
1718
|
+
/**
|
|
1719
|
+
* An epic page's block's items that need Owen, when its `contentsEntry` count doesn't say:
|
|
1720
|
+
* its own items (`COUNTED` in `spell-epic`'s `EpicSection.types.ts`) the `epic` tool marked
|
|
1721
|
+
* - `attention` (red)
|
|
1722
|
+
* - or `replied` (orange: Claude answered with options, the person's turn to pick; `EpicItem.types.ts` `NEEDS_PERSON`).
|
|
1723
|
+
*/
|
|
1724
|
+
const EPIC_ATTENTION =
|
|
1725
|
+
':scope > epic-item:is([state="attention"], [state="replied"]), :scope > epic-phase[state="attention"]'
|
|
1726
|
+
|
|
1727
|
+
/**
|
|
1728
|
+
* Of those, the ones Claude answered with options, waiting on the person's pick (`replied`, orange):
|
|
1729
|
+
* the plan-doc toolbar shows them apart from the urgent ones (red; `buildToolbar()`).
|
|
1730
|
+
*/
|
|
1731
|
+
const EPIC_REPLIED = ':scope > :is(epic-item, epic-phase)[state="replied"]'
|
|
1732
|
+
|
|
1733
|
+
/**
|
|
1734
|
+
* The Phases section's phases running now (`status="active"`): the toolbar's blue badge on the Phases button
|
|
1735
|
+
* (epic `epic-engine` P43; Owen, 2026-10-25: "blue badge for the number of things currently running")
|
|
1736
|
+
*/
|
|
1737
|
+
const EPIC_RUNNING = ':scope > epic-phase[status="active"]'
|
|
1738
|
+
|
|
1739
|
+
/** A count pill's tooltip: "2 need you", "1 needs you". */
|
|
1013
1740
|
function needYou({ attention }) {
|
|
1014
|
-
return `${attention} ${attention === 1 ? "needs" : "need"} you
|
|
1741
|
+
return `${attention} ${attention === 1 ? "needs" : "need"} you`
|
|
1015
1742
|
}
|
|
1016
|
-
|
|
1743
|
+
|
|
1744
|
+
/**
|
|
1745
|
+
* Each top-level section's items -- `[data-status]` elements, not counting ones inside another --
|
|
1746
|
+
* as `{ open, total, attention }`, by the group's element (the `<ui-section>`, or the h2).
|
|
1747
|
+
* - "open": any status but `CLOSED`'s
|
|
1748
|
+
* - "attention": the items that need the person (`stateOf()`: the toolbar's red badge, Q20 of epic `epic-components`)
|
|
1749
|
+
* - sections without items are left out; nested sections get no count of their own
|
|
1750
|
+
* - the Epics index's epic cards, the saga pages' items
|
|
1751
|
+
* - an epic page's sections count themselves (`<epic-section>`, on their titles): their count is read from their
|
|
1752
|
+
* hosts' `contentsEntry`, never written;
|
|
1753
|
+
* its `attention` too, else the items' `state="attention"` (`EPIC_ATTENTION`);
|
|
1754
|
+
* and `replied`, how many of those wait on Owen's pick (else `EPIC_REPLIED`: the toolbar's orange badge);
|
|
1755
|
+
* and `running`, the Phases section's phases at work now (else `EPIC_RUNNING`: the toolbar's blue badge, P43;
|
|
1756
|
+
* the host's own counts a phase being worked on too, I147)
|
|
1757
|
+
* - the host's counts are its items AS DRAWN (`DrawnState`): an item being worked on counts blue, never red
|
|
1758
|
+
* - SIDE EFFECT: writes `open/total` on the section's title: its `badge` (SECTIONS), or a `ui-label.spell-count`
|
|
1759
|
+
* at the right of the h2 (HEADINGS); callable again (it replaces both)
|
|
1760
|
+
*/
|
|
1017
1761
|
function countItems(outline) {
|
|
1018
|
-
const counts =
|
|
1762
|
+
const counts = new Map()
|
|
1019
1763
|
for (const { element } of outline.groups) {
|
|
1020
1764
|
if (element.matches(EPIC_FOLDS)) {
|
|
1021
|
-
const count = element.contentsEntry?.count
|
|
1765
|
+
const count = element.contentsEntry?.count
|
|
1022
1766
|
if (count) {
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
const
|
|
1026
|
-
|
|
1767
|
+
// the block's own, as drawn (`EpicSection.countOf()`: live, an item being worked on blue, not red); else
|
|
1768
|
+
// the markup's
|
|
1769
|
+
const attention = count.attention ?? element.querySelectorAll(EPIC_ATTENTION).length
|
|
1770
|
+
const replied = count.replied ?? Math.min(attention, element.querySelectorAll(EPIC_REPLIED).length)
|
|
1771
|
+
const running = count.running ?? element.querySelectorAll(EPIC_RUNNING).length
|
|
1772
|
+
counts.set(element, { ...count, attention, replied, running })
|
|
1027
1773
|
}
|
|
1028
|
-
continue
|
|
1774
|
+
continue
|
|
1029
1775
|
}
|
|
1030
|
-
const section = outline.sections ? element : headingSection(element)
|
|
1031
|
-
if (!section) continue
|
|
1032
|
-
const items = Array.from(section.querySelectorAll("[data-status]")).filter((item) => outermost(item, section))
|
|
1033
|
-
if (!items.length) continue
|
|
1034
|
-
const open = items.filter((item) => !CLOSED.has(item.dataset.status)).length
|
|
1035
|
-
const attention = items.filter((item) => stateOf(item) === "attention").length
|
|
1036
|
-
counts.set(element, { open, total: items.length, attention })
|
|
1776
|
+
const section = outline.sections ? element : headingSection(element)
|
|
1777
|
+
if (!section) continue
|
|
1778
|
+
const items = Array.from(section.querySelectorAll("[data-status]")).filter((item) => outermost(item, section))
|
|
1779
|
+
if (!items.length) continue
|
|
1780
|
+
const open = items.filter((item) => !CLOSED.has(item.dataset.status)).length
|
|
1781
|
+
const attention = items.filter((item) => stateOf(item) === "attention").length
|
|
1782
|
+
counts.set(element, { open, total: items.length, attention })
|
|
1037
1783
|
if (outline.sections) {
|
|
1038
|
-
element.setAttribute("badge", `${open}/${items.length}`)
|
|
1039
|
-
continue
|
|
1784
|
+
element.setAttribute("badge", `${open}/${items.length}`)
|
|
1785
|
+
continue
|
|
1040
1786
|
}
|
|
1041
|
-
element.querySelector(":scope > ui-label.spell-count")?.remove()
|
|
1042
|
-
const label = document.createElement("ui-label")
|
|
1043
|
-
label.className = "spell-count"
|
|
1044
|
-
label.setAttribute("size", "tiny")
|
|
1045
|
-
label.setAttribute("appearance", "basic")
|
|
1046
|
-
label.title = `${open} open of ${items.length}
|
|
1047
|
-
label.textContent = `${open}/${items.length}
|
|
1048
|
-
element.append(label)
|
|
1049
|
-
}
|
|
1050
|
-
return counts
|
|
1051
|
-
}
|
|
1052
|
-
|
|
1787
|
+
element.querySelector(":scope > ui-label.spell-count")?.remove()
|
|
1788
|
+
const label = document.createElement("ui-label")
|
|
1789
|
+
label.className = "spell-count"
|
|
1790
|
+
label.setAttribute("size", "tiny")
|
|
1791
|
+
label.setAttribute("appearance", "basic")
|
|
1792
|
+
label.title = `${open} open of ${items.length}`
|
|
1793
|
+
label.textContent = `${open}/${items.length}`
|
|
1794
|
+
element.append(label)
|
|
1795
|
+
}
|
|
1796
|
+
return counts
|
|
1797
|
+
}
|
|
1798
|
+
|
|
1799
|
+
/** The `section.s2` an h2 heads (`section > ui-sticky.spell-h2 > h2`), else null. */
|
|
1053
1800
|
function headingSection(h2) {
|
|
1054
|
-
const sticky = h2.parentElement
|
|
1055
|
-
return sticky?.matches("section > ui-sticky.spell-h2") ? sticky.parentElement : null
|
|
1801
|
+
const sticky = h2.parentElement
|
|
1802
|
+
return sticky?.matches("section > ui-sticky.spell-h2") ? sticky.parentElement : null
|
|
1056
1803
|
}
|
|
1057
|
-
|
|
1804
|
+
|
|
1805
|
+
/** Is `item` the outermost `[data-status]` within `section` (not an item's part)? */
|
|
1058
1806
|
function outermost(item, section) {
|
|
1059
|
-
const outer = item.parentElement?.closest("[data-status]")
|
|
1060
|
-
return !outer || !section.contains(outer)
|
|
1807
|
+
const outer = item.parentElement?.closest("[data-status]")
|
|
1808
|
+
return !outer || !section.contains(outer)
|
|
1061
1809
|
}
|
|
1062
|
-
|
|
1063
|
-
|
|
1810
|
+
|
|
1811
|
+
////////////////
|
|
1812
|
+
// ## Item states and filter
|
|
1813
|
+
////////////////
|
|
1814
|
+
|
|
1815
|
+
/**
|
|
1816
|
+
* Where an item stands, in the colours Owen reads at a glance: `[state, tooltip words]` (an id chip's tooltip,
|
|
1817
|
+
* `stateTip()`; the filter's chips are `<epic-state-filter>`'s, in its order, `FILTER_STATES`).
|
|
1818
|
+
* - the colour scheme (Q20 of epic `epic-components`, 2026-10-08; `templates/epics/plan-doc.md`, "Colours"):
|
|
1819
|
+
* attention red, progress blue (Claude is working on it), open yellow, recent green, old grey;
|
|
1820
|
+
* `spell-doc.css`'s `--spell-state-*` tokens
|
|
1821
|
+
* - for the Epics index's epic cards (`.spell-epics`) and the saga pages' items (`.plan-items`, coloured by
|
|
1822
|
+
* `goals.css`); an epic page's items colour and filter themselves (`<epic-item>`, `<epic-section>`)
|
|
1823
|
+
* - `data-state` when the page writes one; else from the status (`stateOf()`)
|
|
1824
|
+
*/
|
|
1825
|
+
const ITEM_STATES = [
|
|
1064
1826
|
["attention", "needs you"],
|
|
1065
1827
|
["progress", "Claude is working on it"],
|
|
1066
1828
|
["open", "open, still undecided"],
|
|
1067
1829
|
["recent", "decided or done"],
|
|
1068
1830
|
["old", "no longer relevant"]
|
|
1069
|
-
]
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1831
|
+
]
|
|
1832
|
+
|
|
1833
|
+
/**
|
|
1834
|
+
* A closed item's state, by its status:
|
|
1835
|
+
* - decided or done stay `recent` (green) however old
|
|
1836
|
+
* - only `canceled` is `old` (grey: no longer relevant)
|
|
1837
|
+
* - Owen, 2026-10-08; `spell-epic` `PlanReader.itemState()`, the same rule
|
|
1838
|
+
*/
|
|
1839
|
+
const CLOSED_STATES = { done: "recent", decided: "recent", canceled: "old" }
|
|
1840
|
+
|
|
1841
|
+
/** The state names, for checking a `data-state`. */
|
|
1842
|
+
const STATE_NAMES = new Set(ITEM_STATES.map(([state]) => state))
|
|
1843
|
+
|
|
1844
|
+
/** The saga pages' items, and the index's epic cards: what states and the filter apply to. */
|
|
1845
|
+
const STATE_ITEMS = ":is(.plan-items, .spell-epics) > [data-status]"
|
|
1846
|
+
|
|
1847
|
+
/** The saga pages' items that wait on Owen while open: their questions (`/goals` talks them through with him). */
|
|
1848
|
+
const ASKS_PERSON = '.plan-items[data-kind="question"] > *'
|
|
1849
|
+
|
|
1850
|
+
/**
|
|
1851
|
+
* An item's state: its `data-state`, else (the index's epic cards, the saga pages' items) from its status:
|
|
1852
|
+
* `done` / `decided` are `recent`, `canceled` `old` (`CLOSED_STATES`); an open goals question (`ASKS_PERSON`)
|
|
1853
|
+
* `attention`; anything else `open`.
|
|
1854
|
+
*/
|
|
1074
1855
|
function stateOf(item) {
|
|
1075
|
-
const state = item.dataset.state
|
|
1076
|
-
if (STATE_NAMES.has(state)) return state
|
|
1077
|
-
if (CLOSED.has(item.dataset.status)) return CLOSED_STATES[item.dataset.status]
|
|
1078
|
-
return item.matches(ASKS_PERSON) ? "attention" : "open"
|
|
1856
|
+
const state = item.dataset.state
|
|
1857
|
+
if (STATE_NAMES.has(state)) return state
|
|
1858
|
+
if (CLOSED.has(item.dataset.status)) return CLOSED_STATES[item.dataset.status]
|
|
1859
|
+
return item.matches(ASKS_PERSON) ? "attention" : "open"
|
|
1079
1860
|
}
|
|
1080
|
-
|
|
1861
|
+
|
|
1862
|
+
/**
|
|
1863
|
+
* An item's id chip's tooltip: where it stands in words, then its review marks (Owen, 2026-10-04), e.g.
|
|
1864
|
+
* "Needs your attention · not reviewed yet", "Decided or reviewed recently · reviewed 2026-10-03".
|
|
1865
|
+
*/
|
|
1081
1866
|
function stateTip(item) {
|
|
1082
|
-
const words = ITEM_STATES.find(([state]) => state === item.dataset.spellState)?.[1] ?? ""
|
|
1083
|
-
const parts = [words.charAt(0).toUpperCase() + words.slice(1)]
|
|
1084
|
-
const { reviewed, deferred, queued, work, status } = item.dataset
|
|
1085
|
-
if (queued) parts.push(`to do: ${work || "queued"}`)
|
|
1086
|
-
if (reviewed) parts.push(`reviewed ${reviewed}`)
|
|
1087
|
-
else if (deferred) parts.push(`deferred ${deferred}`)
|
|
1088
|
-
else if (status === "open") parts.push("not reviewed yet")
|
|
1089
|
-
return parts.join(" · ")
|
|
1090
|
-
}
|
|
1091
|
-
|
|
1867
|
+
const words = ITEM_STATES.find(([state]) => state === item.dataset.spellState)?.[1] ?? ""
|
|
1868
|
+
const parts = [words.charAt(0).toUpperCase() + words.slice(1)]
|
|
1869
|
+
const { reviewed, deferred, queued, work, status } = item.dataset
|
|
1870
|
+
if (queued) parts.push(`to do: ${work || "queued"}`)
|
|
1871
|
+
if (reviewed) parts.push(`reviewed ${reviewed}`)
|
|
1872
|
+
else if (deferred) parts.push(`deferred ${deferred}`)
|
|
1873
|
+
else if (status === "open") parts.push("not reviewed yet")
|
|
1874
|
+
return parts.join(" · ")
|
|
1875
|
+
}
|
|
1876
|
+
|
|
1877
|
+
/**
|
|
1878
|
+
* Mark every item's state as `data-spell-state` (`stateOf()`), so CSS has ONE attribute to color by;
|
|
1879
|
+
* an item's id chip (`.plan-id`, the saga pages') says it in words.
|
|
1880
|
+
* - SIDE EFFECT: sets `data-spell-state`;
|
|
1881
|
+
* callable again (a page updated in place: a replaced item comes back without it)
|
|
1882
|
+
*/
|
|
1092
1883
|
function markItemStates(main) {
|
|
1093
1884
|
for (const item of main.querySelectorAll(STATE_ITEMS)) {
|
|
1094
|
-
item.dataset.spellState = stateOf(item)
|
|
1095
|
-
const chip = item.querySelector(".plan-id")
|
|
1096
|
-
if (chip) chip.title = stateTip(item)
|
|
1885
|
+
item.dataset.spellState = stateOf(item)
|
|
1886
|
+
const chip = item.querySelector(".plan-id")
|
|
1887
|
+
if (chip) chip.title = stateTip(item)
|
|
1097
1888
|
}
|
|
1098
1889
|
}
|
|
1099
|
-
|
|
1890
|
+
|
|
1891
|
+
/**
|
|
1892
|
+
* The status filter on every top-level `<ui-section>` with a filterable list
|
|
1893
|
+
* (the index's `.spell-epics`, a `.plan-items` list, each holding `[data-status]` children):
|
|
1894
|
+
* - its chips are the epics pack's `<epic-state-filter>` (epic `epic-engine` P3):
|
|
1895
|
+
* the ONE chip element, an epic page's too
|
|
1896
|
+
* - a chip per state the section has items in, in its colour, with how many (Owen, 2026-10-10: no filter icon)
|
|
1897
|
+
* - SOLID while its items show, OUTLINED while hidden
|
|
1898
|
+
* - a click (`epic-state-changed`), by the one rule (`StateFilter.nextShown()`, in the element):
|
|
1899
|
+
* - everything showing: only that state
|
|
1900
|
+
* - else a hidden state shows too, and a shown one hides
|
|
1901
|
+
* - the only one showing: everything again
|
|
1902
|
+
* - an ⌥-click: only that state, whatever showed (epic `epic-engine` I166: the element's `shown` says so)
|
|
1903
|
+
* - in the title's `actions` slot (`.spell-item-filter`); `spell-doc.css` puts it left of the count badge
|
|
1904
|
+
* - a filtered list shows "3 hidden · show all" under it (`<epic-hidden-note class="spell-hidden-note">`):
|
|
1905
|
+
* a click there (`epic-all-showing`) shows all
|
|
1906
|
+
* - the choice: `data-show="<states shown>"` on the section (none for all),
|
|
1907
|
+
* `data-spell-hidden` on the items it hides (CSS hides them)
|
|
1908
|
+
* - remembered per page (`localStorage`, `{ [section id]: [states] }`); all by default
|
|
1909
|
+
* - an epic page's sections filter themselves (`<epic-section>`), with the same element
|
|
1910
|
+
* - SIDE EFFECT: marks the items' states (`markItemStates()`), adds the chips and notes to the page;
|
|
1911
|
+
* callable again (it replaces the ones it added)
|
|
1912
|
+
*/
|
|
1100
1913
|
function wireItemFilters(main) {
|
|
1101
|
-
const key = `${ITEM_FILTER_KEY_PREFIX}${location.pathname}
|
|
1102
|
-
const saved = readJSON(key)
|
|
1103
|
-
for (const old of main.querySelectorAll(":scope > ui-section > .spell-item-filter, .spell-hidden-note")) old.remove()
|
|
1104
|
-
markItemStates(main)
|
|
1914
|
+
const key = `${ITEM_FILTER_KEY_PREFIX}${location.pathname}`
|
|
1915
|
+
const saved = readJSON(key)
|
|
1916
|
+
for (const old of main.querySelectorAll(":scope > ui-section > .spell-item-filter, .spell-hidden-note")) old.remove()
|
|
1917
|
+
markItemStates(main)
|
|
1105
1918
|
for (const section of main.querySelectorAll(":scope > ui-section[id]")) {
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
__name(choose, "choose");
|
|
1112
|
-
const lists = Array.from(section.querySelectorAll(".plan-items, .spell-epics")).filter(
|
|
1113
|
-
(list) => list.querySelector(":scope > [data-status]")
|
|
1114
|
-
);
|
|
1115
|
-
if (!lists.length) continue;
|
|
1116
|
-
const counts = /* @__PURE__ */ new Map();
|
|
1919
|
+
const lists = Array.from(section.querySelectorAll(".plan-items, .spell-epics")).filter((list) =>
|
|
1920
|
+
list.querySelector(":scope > [data-status]")
|
|
1921
|
+
)
|
|
1922
|
+
if (!lists.length) continue
|
|
1923
|
+
const counts = new Map()
|
|
1117
1924
|
for (const item of lists.flatMap(itemsOf))
|
|
1118
|
-
counts.set(item.dataset.spellState, (counts.get(item.dataset.spellState) ?? 0) + 1)
|
|
1119
|
-
const states = [...counts.keys()]
|
|
1925
|
+
counts.set(item.dataset.spellState, (counts.get(item.dataset.spellState) ?? 0) + 1)
|
|
1926
|
+
const states = [...counts.keys()]
|
|
1120
1927
|
const chips = el("epic-state-filter", {
|
|
1121
1928
|
class: "spell-item-filter",
|
|
1122
1929
|
slot: "actions",
|
|
1123
1930
|
counts: [...counts].map(([state, count]) => `${state}:${count}`).join(" "),
|
|
1124
1931
|
"data-spell-added": true
|
|
1125
|
-
})
|
|
1126
|
-
chips.addEventListener("epic-state-changed", (event) => choose(event.detail.shown))
|
|
1932
|
+
})
|
|
1933
|
+
chips.addEventListener("epic-state-changed", (event) => choose(event.detail.shown))
|
|
1127
1934
|
const notes = lists.map((list) => {
|
|
1128
|
-
const note = el("epic-hidden-note", { class: "spell-hidden-note", hidden: true, "data-spell-added": true })
|
|
1129
|
-
note.addEventListener("epic-all-showing", () => choose(states))
|
|
1130
|
-
list.after(note)
|
|
1131
|
-
return note
|
|
1132
|
-
})
|
|
1133
|
-
section.append(chips)
|
|
1134
|
-
const filter = { section, lists, notes, chips, states }
|
|
1135
|
-
const remembered = Array.isArray(saved[section.id]) ? saved[section.id].filter((state) => counts.has(state)) : []
|
|
1136
|
-
showItems(filter, remembered.length ? remembered : states)
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1935
|
+
const note = el("epic-hidden-note", { class: "spell-hidden-note", hidden: true, "data-spell-added": true })
|
|
1936
|
+
note.addEventListener("epic-all-showing", () => choose(states))
|
|
1937
|
+
list.after(note)
|
|
1938
|
+
return note
|
|
1939
|
+
})
|
|
1940
|
+
section.append(chips)
|
|
1941
|
+
const filter = { section, lists, notes, chips, states }
|
|
1942
|
+
const remembered = Array.isArray(saved[section.id]) ? saved[section.id].filter((state) => counts.has(state)) : []
|
|
1943
|
+
showItems(filter, remembered.length ? remembered : states)
|
|
1944
|
+
|
|
1945
|
+
/** The reader picked the states `shown`: apply them and remember. */
|
|
1946
|
+
function choose(shown) {
|
|
1947
|
+
showItems(filter, shown)
|
|
1948
|
+
saved[section.id] = shown
|
|
1949
|
+
writeJSON(key, saved)
|
|
1950
|
+
}
|
|
1951
|
+
}
|
|
1952
|
+
}
|
|
1953
|
+
|
|
1954
|
+
/**
|
|
1955
|
+
* Show the items of the states `shown` in a filter's section (`{ section, lists, notes, chips, states }`).
|
|
1956
|
+
* - its chips say which (`shown`, none while every state shows)
|
|
1957
|
+
* - an "N hidden" note under each list that hides any
|
|
1958
|
+
*/
|
|
1140
1959
|
function showItems({ section, lists, notes, chips, states }, shown) {
|
|
1141
|
-
const showing = new Set(shown)
|
|
1142
|
-
const everything = states.every((state) => showing.has(state))
|
|
1960
|
+
const showing = new Set(shown)
|
|
1961
|
+
const everything = states.every((state) => showing.has(state))
|
|
1143
1962
|
if (everything) {
|
|
1144
|
-
delete section.dataset.show
|
|
1145
|
-
chips.removeAttribute("shown")
|
|
1963
|
+
delete section.dataset.show
|
|
1964
|
+
chips.removeAttribute("shown")
|
|
1146
1965
|
} else {
|
|
1147
|
-
section.dataset.show = [...showing].join(" ")
|
|
1148
|
-
chips.setAttribute("shown", section.dataset.show)
|
|
1966
|
+
section.dataset.show = [...showing].join(" ")
|
|
1967
|
+
chips.setAttribute("shown", section.dataset.show)
|
|
1149
1968
|
}
|
|
1150
1969
|
lists.forEach((list, index) => {
|
|
1151
|
-
let hidden = 0
|
|
1970
|
+
let hidden = 0
|
|
1152
1971
|
for (const item of itemsOf(list)) {
|
|
1153
|
-
const hide = !showing.has(item.dataset.spellState)
|
|
1154
|
-
item.toggleAttribute("data-spell-hidden", hide)
|
|
1155
|
-
if (hide) hidden
|
|
1972
|
+
const hide = !showing.has(item.dataset.spellState)
|
|
1973
|
+
item.toggleAttribute("data-spell-hidden", hide)
|
|
1974
|
+
if (hide) hidden++
|
|
1156
1975
|
}
|
|
1157
|
-
notes[index].hidden = hidden === 0
|
|
1158
|
-
notes[index].setAttribute("count", String(hidden))
|
|
1159
|
-
})
|
|
1976
|
+
notes[index].hidden = hidden === 0
|
|
1977
|
+
notes[index].setAttribute("count", String(hidden))
|
|
1978
|
+
})
|
|
1160
1979
|
}
|
|
1161
|
-
|
|
1980
|
+
|
|
1981
|
+
/** A filterable list's items: its `[data-status]` children. */
|
|
1162
1982
|
function itemsOf(list) {
|
|
1163
|
-
return Array.from(list.querySelectorAll(":scope > [data-status]"))
|
|
1983
|
+
return Array.from(list.querySelectorAll(":scope > [data-status]"))
|
|
1164
1984
|
}
|
|
1165
|
-
|
|
1985
|
+
|
|
1986
|
+
////////////////
|
|
1987
|
+
// ## Editing in place
|
|
1988
|
+
////////////////
|
|
1989
|
+
|
|
1990
|
+
/**
|
|
1991
|
+
* Every `<ui-markdown>` of a page the page server may save is edited where it's drawn: ⌥-click a paragraph, a
|
|
1992
|
+
* heading, a list item or a table cell (epic `epic-engine` P60, request r53; Owen: "click in e.g. a table cell and
|
|
1993
|
+
* edit the text there directly, auto-save immediately").
|
|
1994
|
+
* - `editable` set on each in `nodes` without one of its own, so `editable="tabs"` stays
|
|
1995
|
+
* - only when the page says it may be saved (`SPELL_SERVER.writable`: its file in the page server's writable
|
|
1996
|
+
* folders); from disk, or a page outside them, nothing changes
|
|
1997
|
+
* - the live page only: the page's file never holds it, so a live update never takes it away (the patch compares
|
|
1998
|
+
* the file's versions); a block a patch brings in gets it here (`rewire()`)
|
|
1999
|
+
* - a plain click reads as before: ⌥ is the only way in, so no pencil and no mode
|
|
2000
|
+
*/
|
|
1166
2001
|
function editMarkdownInPlace(nodes) {
|
|
1167
|
-
if (!window.SPELL_SERVER?.writable) return
|
|
2002
|
+
if (!window.SPELL_SERVER?.writable) return
|
|
1168
2003
|
for (const node of nodes) {
|
|
1169
2004
|
for (const markdown of PagePatch.withSelf(node, "ui-markdown"))
|
|
1170
|
-
if (!markdown.hasAttribute("editable")) markdown.setAttribute("editable", "")
|
|
2005
|
+
if (!markdown.hasAttribute("editable")) markdown.setAttribute("editable", "")
|
|
1171
2006
|
}
|
|
1172
2007
|
}
|
|
1173
|
-
|
|
2008
|
+
|
|
2009
|
+
////////////////
|
|
2010
|
+
// ## Steps
|
|
2011
|
+
////////////////
|
|
2012
|
+
|
|
2013
|
+
/**
|
|
2014
|
+
* A `<ui-steps>` too long for one row goes vertical, one step per row, as wide as the column, with no arrows.
|
|
2015
|
+
* - horizontal, its steps wrap, each with the arrow pointing at the next step, over nothing, and its text wherever
|
|
2016
|
+
* its number's width leaves it
|
|
2017
|
+
* - measured as each shows and changes width: a folded section's has no size until it opens
|
|
2018
|
+
* - a page's own `direction` is left alone
|
|
2019
|
+
*/
|
|
1174
2020
|
function stackWrappedSteps(main) {
|
|
1175
|
-
const widths =
|
|
2021
|
+
const widths = new WeakMap()
|
|
1176
2022
|
const watch = new ResizeObserver(async (entries) => {
|
|
1177
2023
|
for (const { target, contentRect } of entries) {
|
|
1178
|
-
if (!contentRect.width || widths.get(target) === contentRect.width) continue
|
|
1179
|
-
widths.set(target, contentRect.width)
|
|
1180
|
-
target.removeAttribute("direction")
|
|
1181
|
-
target.removeAttribute("fluid")
|
|
1182
|
-
await nextFrame(1)
|
|
1183
|
-
const tops = [...target.children].map((step) => step.shadowRoot?.querySelector('[part~="step"]'))
|
|
1184
|
-
const rows = new Set(tops.map((each) => each?.getBoundingClientRect().top))
|
|
1185
|
-
if (rows.size < 2) continue
|
|
1186
|
-
target.setAttribute("direction", "vertical")
|
|
1187
|
-
target.setAttribute("fluid", "")
|
|
2024
|
+
if (!contentRect.width || widths.get(target) === contentRect.width) continue
|
|
2025
|
+
widths.set(target, contentRect.width)
|
|
2026
|
+
target.removeAttribute("direction")
|
|
2027
|
+
target.removeAttribute("fluid")
|
|
2028
|
+
await nextFrame(1)
|
|
2029
|
+
const tops = [...target.children].map((step) => step.shadowRoot?.querySelector('[part~="step"]'))
|
|
2030
|
+
const rows = new Set(tops.map((each) => each?.getBoundingClientRect().top))
|
|
2031
|
+
if (rows.size < 2) continue
|
|
2032
|
+
target.setAttribute("direction", "vertical")
|
|
2033
|
+
target.setAttribute("fluid", "")
|
|
1188
2034
|
}
|
|
1189
|
-
})
|
|
1190
|
-
for (const steps of main.querySelectorAll("ui-steps:not([direction])")) watch.observe(steps)
|
|
2035
|
+
})
|
|
2036
|
+
for (const steps of main.querySelectorAll("ui-steps:not([direction])")) watch.observe(steps)
|
|
1191
2037
|
}
|
|
1192
|
-
|
|
2038
|
+
|
|
2039
|
+
////////////////
|
|
2040
|
+
// ## Toolbar
|
|
2041
|
+
////////////////
|
|
2042
|
+
|
|
2043
|
+
/**
|
|
2044
|
+
* The page's navigation: an epic page's toolbar (`buildToolbar()`), else the page toolbar (`buildPageToolbar()`).
|
|
2045
|
+
* - both the SAME element, Spell UI's menu (`toolbarMenu()`): a guide's and an epic page's band look and behave alike
|
|
2046
|
+
* - returns the menu, whose `[data-rail]` items scroll-follow marks `selected`; none without top-level sections
|
|
2047
|
+
* - `data-rail`: the name the floating rail gave them (gone since epic `airplane` P8)
|
|
2048
|
+
* - kept, as scroll-follow, a details page's `<epic-ask>` and `check-spell.js` read it
|
|
2049
|
+
*/
|
|
1193
2050
|
function buildNavigation(main, outline, counts) {
|
|
1194
|
-
const page = document.body.classList.contains("plan-doc") ? main.querySelector("epic-page") : null
|
|
1195
|
-
return page ? buildToolbar(page, outline, counts) : buildPageToolbar(main, outline, counts)
|
|
2051
|
+
const page = document.body.classList.contains("plan-doc") ? main.querySelector("epic-page") : null
|
|
2052
|
+
return page ? buildToolbar(page, outline, counts) : buildPageToolbar(main, outline, counts)
|
|
1196
2053
|
}
|
|
1197
|
-
|
|
2054
|
+
|
|
2055
|
+
/**
|
|
2056
|
+
* Every other page's navigation: a row of buttons, one per top-level section, in the sticky page header,
|
|
2057
|
+
* in place of the floating rail.
|
|
2058
|
+
* - Owen, 2026-10-10: "Make the floating sidebar in guides a sticky top toolbar like the epic page.
|
|
2059
|
+
* Have section titles in this one"
|
|
2060
|
+
* - each: the section's mark and its title, a link to it (`wireAnchors()` lands it);
|
|
2061
|
+
* scroll-follow marks the current one `selected`, by `data-rail`
|
|
2062
|
+
* - the mark: an item's number, an icon, a number or a letter
|
|
2063
|
+
* (`titledItems()`, `spell-doc-toolbar.js`, which Epic UI's pages build theirs with too)
|
|
2064
|
+
* - a red badge: how many of its items need Owen (`counts`, `attention`); none, none
|
|
2065
|
+
* - its titles fit the row, as Spell UI's `<ui-toolbar shrinkable>` fits them (`toolbarMenu()`):
|
|
2066
|
+
* - too long for the row, the longest end in `...` first
|
|
2067
|
+
* - when one would be cut under 50px, they go: the buttons show their marks only, the title as their tooltip
|
|
2068
|
+
* - narrower still, every button folds into one `...` button, whose menu holds them all
|
|
2069
|
+
* - where: the last row of the sticky page header (`ui-sticky.spell-h1 > header.spell-page-head`),
|
|
2070
|
+
* so it sticks with it and the titles stick below it
|
|
2071
|
+
* - a page without one (the saga pages, a cheat sheet): the last row of its filter bar (`.spell-filter`),
|
|
2072
|
+
* else a sticky bar of its own before the first section
|
|
2073
|
+
* (`.spell-toolbar-alone`, measured as the filter bar is: `trackStickyHeights()`)
|
|
2074
|
+
* - HEADINGS (the saga pages): only the h2s that head a sticky section
|
|
2075
|
+
* - callable again (a page updated in place): replaces the toolbar it built before
|
|
2076
|
+
* - SIDE EFFECT: adds the menu inside `main`, marked `data-spell-added` so the live patch steps around it;
|
|
2077
|
+
* removes a hand-written `.spell-toc-open` (pages before 2026-10-01 had a "Contents" button)
|
|
2078
|
+
*/
|
|
1198
2079
|
function buildPageToolbar(main, outline, counts) {
|
|
1199
|
-
const groups = outline.sections ? outline.groups : outline.groups.filter((group) => headingSection(group.element))
|
|
2080
|
+
const groups = outline.sections ? outline.groups : outline.groups.filter((group) => headingSection(group.element))
|
|
1200
2081
|
const items = titledItems(groups, (element) => {
|
|
1201
|
-
const count = counts.get(element)
|
|
1202
|
-
return count?.attention ? [["urgent", count.attention, needYou(count)]] : []
|
|
1203
|
-
})
|
|
2082
|
+
const count = counts.get(element)
|
|
2083
|
+
return count?.attention ? [["urgent", count.attention, needYou(count)]] : []
|
|
2084
|
+
})
|
|
1204
2085
|
if (!items.length) {
|
|
1205
|
-
removeToolbar()
|
|
1206
|
-
return
|
|
2086
|
+
removeToolbar()
|
|
2087
|
+
return undefined
|
|
1207
2088
|
}
|
|
1208
|
-
const toolbar = toolbarMenu(items, { titled: true })
|
|
1209
|
-
const head =
|
|
1210
|
-
|
|
2089
|
+
const toolbar = toolbarMenu(items, { titled: true })
|
|
2090
|
+
const head =
|
|
2091
|
+
main.querySelector(":scope > ui-sticky.spell-h1 > .spell-page-head") ?? main.querySelector(".spell-filter")
|
|
2092
|
+
if (head) head.append(toolbar)
|
|
1211
2093
|
else {
|
|
1212
|
-
toolbar.classList.add("spell-toolbar-alone")
|
|
1213
|
-
const first = groups[0].element
|
|
1214
|
-
(outline.sections ? first : headingSection(first) ?? first).before(toolbar)
|
|
2094
|
+
toolbar.classList.add("spell-toolbar-alone")
|
|
2095
|
+
const first = groups[0].element
|
|
2096
|
+
;(outline.sections ? first : (headingSection(first) ?? first)).before(toolbar)
|
|
1215
2097
|
}
|
|
1216
|
-
return toolbar
|
|
2098
|
+
return toolbar
|
|
1217
2099
|
}
|
|
1218
|
-
|
|
2100
|
+
|
|
2101
|
+
/**
|
|
2102
|
+
* An EPIC PAGE's navigation (epic `airplane` P8, Owen 2026-10-10: "The contents sidebar on the epic page should be a
|
|
2103
|
+
* sticky top toolbar instead"): a row of buttons across the bottom of `<epic-page>`'s sticky header, one per
|
|
2104
|
+
* top-level block (Overview, Phases, Questions ... Log), in place of the floating rail it had before.
|
|
2105
|
+
* - each: the block's icon, a link to it (`wireAnchors()` lands it); its title without its number (`Questions`)
|
|
2106
|
+
* only as its tooltip and name (Owen, 2026-10-10: "lose the titles ... when I click on the thing it goes to that
|
|
2107
|
+
* section anyway"); scroll-follow marks the current one `selected`, by `data-rail` (as the rail's)
|
|
2108
|
+
* - BADGES: how many of the block's items wait on Owen, from `counts` (none: no badge)
|
|
2109
|
+
* - red: urgent (`state="attention"`)
|
|
2110
|
+
* - orange: Claude answered with options, their turn to pick (`state="replied"`)
|
|
2111
|
+
* - blue: the Phases button's, how many phases run now (`status="active"`; epic `epic-engine` P43)
|
|
2112
|
+
* - several kinds: every one, red first, then orange, then blue
|
|
2113
|
+
* - over the icon's top right, a third of a badge on the icon: every button is the same width, badge or not
|
|
2114
|
+
* (Owen, 2026-10-10: "Make badge 1/3 way overlap the icon")
|
|
2115
|
+
* - in the header's `toolbar` slot (`<epic-page>`'s): it sticks with the header,
|
|
2116
|
+
* and the header's measured height, where every title below sticks (`--epic-stack`), takes it in
|
|
2117
|
+
* - `<epic-page>` draws the rest of that row at its right:
|
|
2118
|
+
* the page's state filter, collapse-all, the new item button
|
|
2119
|
+
* - a window too narrow for every button:
|
|
2120
|
+
* the row scrolls sideways (`spell-toolbar.css`), the current button scrolled into view
|
|
2121
|
+
* - callable again (a page updated in place): replaces the toolbar built before
|
|
2122
|
+
* - SIDE EFFECT: appends the menu to `page`, marked `data-spell-added` so the live patch steps around it
|
|
2123
|
+
*/
|
|
1219
2124
|
function buildToolbar(page, outline, counts) {
|
|
1220
2125
|
const items = outline.groups.map(({ element, id, label, glyph }) => {
|
|
1221
|
-
const count = counts.get(element)
|
|
1222
|
-
const replied = count?.replied ?? 0
|
|
1223
|
-
const urgent = (count?.attention ?? 0) - replied
|
|
1224
|
-
const name = shortLabel(label)
|
|
1225
|
-
const running = count?.running ?? 0
|
|
1226
|
-
const waits = replied === 1 ? "waits" : "wait"
|
|
2126
|
+
const count = counts.get(element)
|
|
2127
|
+
const replied = count?.replied ?? 0
|
|
2128
|
+
const urgent = (count?.attention ?? 0) - replied
|
|
2129
|
+
const name = shortLabel(label)
|
|
2130
|
+
const running = count?.running ?? 0
|
|
2131
|
+
const waits = replied === 1 ? "waits" : "wait"
|
|
1227
2132
|
return toolbarItem({
|
|
1228
2133
|
id,
|
|
1229
2134
|
tip: name,
|
|
1230
2135
|
glyph,
|
|
1231
2136
|
// no icon: the label's first letter stands in
|
|
1232
|
-
mark: glyph ?
|
|
2137
|
+
mark: glyph ? undefined : el("b", { slot: "icon" }, name.charAt(0)),
|
|
1233
2138
|
badges: [
|
|
1234
2139
|
["urgent", urgent, `${urgent} urgent`],
|
|
1235
2140
|
["replied", replied, `${replied} replied: ${waits} for your pick`],
|
|
1236
2141
|
["running", running, `${running} running now`]
|
|
1237
2142
|
].filter(([, number]) => number > 0)
|
|
1238
|
-
})
|
|
1239
|
-
})
|
|
2143
|
+
})
|
|
2144
|
+
})
|
|
1240
2145
|
if (!items.length) {
|
|
1241
|
-
removeToolbar()
|
|
1242
|
-
return
|
|
2146
|
+
removeToolbar()
|
|
2147
|
+
return undefined
|
|
1243
2148
|
}
|
|
1244
|
-
const toolbar = toolbarMenu(items, { titled: false })
|
|
1245
|
-
toolbar.slot = "toolbar"
|
|
1246
|
-
page.append(toolbar)
|
|
1247
|
-
return toolbar
|
|
2149
|
+
const toolbar = toolbarMenu(items, { titled: false })
|
|
2150
|
+
toolbar.slot = "toolbar"
|
|
2151
|
+
page.append(toolbar)
|
|
2152
|
+
return toolbar
|
|
1248
2153
|
}
|
|
1249
|
-
|
|
2154
|
+
|
|
2155
|
+
// the menu itself, its items, fitting their titles and the jump key: `spell-doc-toolbar.js`, which Epic UI's pages
|
|
2156
|
+
// load too (epic `epic-engine` T11)
|
|
2157
|
+
|
|
2158
|
+
////////////////
|
|
2159
|
+
// ## Folding
|
|
2160
|
+
////////////////
|
|
2161
|
+
|
|
2162
|
+
/**
|
|
2163
|
+
* Every section folds, and the reader's folds are remembered per page (`localStorage`, `{ [id]: folded }`).
|
|
2164
|
+
* - SECTIONS: `<ui-section collapsible>` folds itself;
|
|
2165
|
+
* this restores the saved folds (else the markup's `open` stands)
|
|
2166
|
+
* and saves the reader's toggles (`ui-opening` / `ui-closing`; an `<epic-*>` block's `ui-opening` / `ui-closing`)
|
|
2167
|
+
* - an EPIC PAGE (`body.plan-doc`): every section and sub-section not in the saved folds starts FOLDED,
|
|
2168
|
+
* whatever its markup says: Owen opens what he wants to read (2026-10-03)
|
|
2169
|
+
* - a link to an id inside still lands (`reveal()` unfolds around it)
|
|
2170
|
+
* - its `<epic-*>` blocks start folded by themselves;
|
|
2171
|
+
* the ones the reader left open open again (`restoreEpicFolds()`, before they draw),
|
|
2172
|
+
* but the Log, which starts folded on every load (`STAYS_FOLDED`),
|
|
2173
|
+
* and their toggles are saved as a section's
|
|
2174
|
+
* - HEADINGS: a chevron button starts each h2 / h3,
|
|
2175
|
+
* and a click anywhere on the heading (not on a link or button in it) toggles it too;
|
|
2176
|
+
* folded: `section.spell-folded`, all but the heading hidden by CSS.
|
|
2177
|
+
* Starts folded as saved, else when the section says `data-fold="closed"`.
|
|
2178
|
+
* - `reveal()` unfolding for a link is never saved
|
|
2179
|
+
* - returns `{ reveal(element) }`: unfold every section hiding `element` (an epic page's blocks and items too, and
|
|
2180
|
+
* a phase's folded fields: `<epic-field>`'s `reveal()`), and open its own panel, or itself if it's a folded plan item;
|
|
2181
|
+
* true when it unfolded something (it draws a little later)
|
|
2182
|
+
* - a `<ui-section>` unfolds WITHOUT its height animation (`--ui-section-duration: 0s` on `main` for a few frames):
|
|
2183
|
+
* the jump measures the target once it has drawn,
|
|
2184
|
+
* and a growing box would move it (scroll anchoring) after the page has landed
|
|
2185
|
+
* - `kept`: the folds a live reload puts back (`takeKeptFolds()`), over the saved ones and the markup's
|
|
2186
|
+
* - callable again (a page updated in place): drops the listeners of the call before (`foldWiring`);
|
|
2187
|
+
* a heading that has its chevron keeps it
|
|
2188
|
+
*/
|
|
2189
|
+
/**
|
|
2190
|
+
* ONE button that opens or folds every section and sub-section, first in the toolbar's tools (`toolbarTools()`).
|
|
2191
|
+
* - Owen, 2026-11-01: "single expand/collapse button"
|
|
2192
|
+
* - any section folded: double chevron down, Expand all; all open: up, Collapse all (`wireFolds()`' `foldAll()`)
|
|
2193
|
+
* - not an epic page: its own toolbar has one (`<epic-page>`)
|
|
2194
|
+
* - added once: a toolbar built anew keeps it
|
|
2195
|
+
*/
|
|
1250
2196
|
function addFoldAll(main, folds) {
|
|
1251
|
-
const tools = toolbarTools(main.querySelector(".spell-toolbar"))
|
|
1252
|
-
if (!tools || document.body.classList.contains("plan-doc") || tools.querySelector(".spell-toolbar-fold")) return
|
|
1253
|
-
if (!main.querySelector("ui-section[collapsible]")) return
|
|
1254
|
-
const anyFolded =
|
|
1255
|
-
const item = el("ui-button", { class: "spell-toolbar-fold", appearance: "circular basic", size: "mini" })
|
|
1256
|
-
const show =
|
|
1257
|
-
const tip = anyFolded() ? "Expand all" : "Collapse all"
|
|
1258
|
-
item.setAttribute("icon", anyFolded() ? "angles down" : "angles up")
|
|
1259
|
-
item.title = tip
|
|
1260
|
-
item.setAttribute("aria-label", tip)
|
|
1261
|
-
titleInside(item)
|
|
1262
|
-
}
|
|
1263
|
-
item.addEventListener("click", () => folds.foldAll(!anyFolded()))
|
|
1264
|
-
new MutationObserver(show).observe(main, { attributes: true, attributeFilter: ["open"], subtree: true })
|
|
1265
|
-
show()
|
|
1266
|
-
tools.prepend(item)
|
|
1267
|
-
}
|
|
1268
|
-
|
|
2197
|
+
const tools = toolbarTools(main.querySelector(".spell-toolbar"))
|
|
2198
|
+
if (!tools || document.body.classList.contains("plan-doc") || tools.querySelector(".spell-toolbar-fold")) return
|
|
2199
|
+
if (!main.querySelector("ui-section[collapsible]")) return
|
|
2200
|
+
const anyFolded = () => [...main.querySelectorAll("ui-section[collapsible]")].some(isCollapsed)
|
|
2201
|
+
const item = el("ui-button", { class: "spell-toolbar-fold", appearance: "circular basic", size: "mini" })
|
|
2202
|
+
const show = () => {
|
|
2203
|
+
const tip = anyFolded() ? "Expand all" : "Collapse all"
|
|
2204
|
+
item.setAttribute("icon", anyFolded() ? "angles down" : "angles up")
|
|
2205
|
+
item.title = tip
|
|
2206
|
+
item.setAttribute("aria-label", tip)
|
|
2207
|
+
titleInside(item)
|
|
2208
|
+
}
|
|
2209
|
+
item.addEventListener("click", () => folds.foldAll(!anyFolded()))
|
|
2210
|
+
new MutationObserver(show).observe(main, { attributes: true, attributeFilter: ["open"], subtree: true })
|
|
2211
|
+
show()
|
|
2212
|
+
tools.prepend(item)
|
|
2213
|
+
}
|
|
2214
|
+
|
|
1269
2215
|
function wireFolds(main, outline, kept) {
|
|
1270
|
-
foldWiring?.abort()
|
|
1271
|
-
foldWiring = new AbortController()
|
|
1272
|
-
const { signal } = foldWiring
|
|
1273
|
-
const key = `${FOLD_KEY_PREFIX}${location.pathname}
|
|
1274
|
-
const saved = readJSON(key)
|
|
1275
|
-
if (outline.sections) wireSectionFolds()
|
|
1276
|
-
else wireHeadingFolds()
|
|
1277
|
-
return { reveal, foldAll, outermostFolded }
|
|
2216
|
+
foldWiring?.abort()
|
|
2217
|
+
foldWiring = new AbortController()
|
|
2218
|
+
const { signal } = foldWiring
|
|
2219
|
+
const key = `${FOLD_KEY_PREFIX}${location.pathname}`
|
|
2220
|
+
const saved = readJSON(key)
|
|
2221
|
+
if (outline.sections) wireSectionFolds()
|
|
2222
|
+
else wireHeadingFolds()
|
|
2223
|
+
return { reveal, foldAll, outermostFolded }
|
|
2224
|
+
|
|
2225
|
+
/**
|
|
2226
|
+
* The outermost fold hiding `element`, if any: its comments show after that fold's title (`drawPromoted()`).
|
|
2227
|
+
*/
|
|
1278
2228
|
function outermostFolded(element) {
|
|
1279
|
-
const folds = outline.sections ? `ui-section, ${EPIC_OPENERS}` : "section.spell-folded"
|
|
1280
|
-
let found
|
|
2229
|
+
const folds = outline.sections ? `ui-section, ${EPIC_OPENERS}` : "section.spell-folded"
|
|
2230
|
+
let found
|
|
1281
2231
|
for (let section = element.closest(folds); section; section = section.parentElement?.closest(folds))
|
|
1282
|
-
if (!outline.sections || isCollapsed(section)) found = section
|
|
1283
|
-
return found
|
|
2232
|
+
if (!outline.sections || isCollapsed(section)) found = section
|
|
2233
|
+
return found
|
|
1284
2234
|
}
|
|
1285
|
-
|
|
2235
|
+
|
|
2236
|
+
/**
|
|
2237
|
+
* Fold (`isFolded`) or open every section and sub-section at once, without their height animation, remembered as
|
|
2238
|
+
* the reader's folds: the toolbar's Collapse all / Expand all (`addFoldAll()`).
|
|
2239
|
+
* - folding them all shows the page from its top: every title, folded, fits in a window or two
|
|
2240
|
+
*/
|
|
1286
2241
|
function foldAll(isFolded) {
|
|
1287
|
-
main.style.setProperty("--ui-section-duration", "0s")
|
|
2242
|
+
main.style.setProperty("--ui-section-duration", "0s")
|
|
1288
2243
|
for (const section of main.querySelectorAll("ui-section[collapsible]")) {
|
|
1289
|
-
setCollapsed(section, isFolded)
|
|
1290
|
-
if (section.id) saved[section.id] = isFolded
|
|
2244
|
+
setCollapsed(section, isFolded)
|
|
2245
|
+
if (section.id) saved[section.id] = isFolded
|
|
1291
2246
|
}
|
|
1292
|
-
writeJSON(key, saved)
|
|
1293
|
-
if (isFolded) scrollTo({ top: 0, behavior: "instant" })
|
|
1294
|
-
requestAnimationFrame(() => requestAnimationFrame(() => main.style.removeProperty("--ui-section-duration")))
|
|
2247
|
+
writeJSON(key, saved)
|
|
2248
|
+
if (isFolded) scrollTo({ top: 0, behavior: "instant" })
|
|
2249
|
+
requestAnimationFrame(() => requestAnimationFrame(() => main.style.removeProperty("--ui-section-duration")))
|
|
1295
2250
|
}
|
|
1296
|
-
|
|
2251
|
+
|
|
2252
|
+
/** SECTIONS: restore the saved folds (an epic page: the rest start folded), save the reader's. */
|
|
1297
2253
|
function wireSectionFolds() {
|
|
1298
|
-
const startFolded = document.body.classList.contains("plan-doc")
|
|
2254
|
+
const startFolded = document.body.classList.contains("plan-doc")
|
|
1299
2255
|
for (const section of main.querySelectorAll("ui-section[collapsible][id]"))
|
|
1300
|
-
if (kept && section.id in kept) setCollapsed(section, !kept[section.id])
|
|
1301
|
-
else if (section.id in saved) setCollapsed(section, !!saved[section.id])
|
|
1302
|
-
else if (startFolded) setCollapsed(section, true)
|
|
1303
|
-
for (const name of [...OPENING, ...CLOSING]) main.addEventListener(name, onToggle, { signal })
|
|
1304
|
-
for (const name of CLOSING) main.addEventListener(name, holdWhileFolding, { signal })
|
|
2256
|
+
if (kept && section.id in kept) setCollapsed(section, !kept[section.id])
|
|
2257
|
+
else if (section.id in saved) setCollapsed(section, !!saved[section.id])
|
|
2258
|
+
else if (startFolded) setCollapsed(section, true)
|
|
2259
|
+
for (const name of [...OPENING, ...CLOSING]) main.addEventListener(name, onToggle, { signal })
|
|
2260
|
+
for (const name of CLOSING) main.addEventListener(name, holdWhileFolding, { signal })
|
|
1305
2261
|
}
|
|
1306
|
-
|
|
2262
|
+
|
|
2263
|
+
/**
|
|
2264
|
+
* Any fold closing (a section, an epic page's Overview part, phase or item): its header stays where it is on screen
|
|
2265
|
+
* while the content folds away under it.
|
|
2266
|
+
* - why: the browser's scroll anchoring kept something BELOW the fold in place instead, so the clicked header slid
|
|
2267
|
+
* down hundreds of pixels as its body shrank, then wobbled (Owen, 2026-10-10: "the 1.1 sections bounce when
|
|
2268
|
+
* closed"; measured: the header moved 336 -> 692px)
|
|
2269
|
+
* - anchoring is off for the page while it folds; each frame, the header is put back where it was
|
|
2270
|
+
* - starts after the toggle's own handlers (a microtask): `keepTitlePut()` / an item's `keepLinePut()` may first
|
|
2271
|
+
* scroll a STUCK title into place, and that's the place kept
|
|
2272
|
+
* - near the end of a short page (everything else folded), the page would get shorter than where it's scrolled to,
|
|
2273
|
+
* and the browser pulls it back: the header jumps down. So the page keeps its height (`min-height`) until the
|
|
2274
|
+
* reader scrolls back far enough for the shorter page to hold him
|
|
2275
|
+
* - stops after `FOLD_HOLD_MS`, or at once when the reader scrolls
|
|
2276
|
+
* - ONLY a fold's closing (a section, an epic block, an accordion): a `<ui-popup>` sends a cancelable `ui-closing`
|
|
2277
|
+
* as it hides, and a hidden popup's top is 0, so holding it scrolled the page to the top (epic `epic-engine` r5)
|
|
2278
|
+
*/
|
|
1307
2279
|
function holdWhileFolding(event) {
|
|
1308
|
-
if (event.defaultPrevented || !event.cancelable || !(event.target instanceof Element)) return
|
|
1309
|
-
const element = event.target
|
|
1310
|
-
if (!element.matches(FOLDING) || !element.getClientRects().length) return
|
|
2280
|
+
if (event.defaultPrevented || !event.cancelable || !(event.target instanceof Element)) return
|
|
2281
|
+
const element = event.target
|
|
2282
|
+
if (!element.matches(FOLDING) || !element.getClientRects().length) return
|
|
1311
2283
|
queueMicrotask(() => {
|
|
1312
|
-
const root = document.documentElement
|
|
1313
|
-
const before = element.getBoundingClientRect().top
|
|
1314
|
-
const until = performance.now() + FOLD_HOLD_MS
|
|
1315
|
-
let stopped = false
|
|
1316
|
-
const stop =
|
|
1317
|
-
addEventListener("wheel", stop, { once: true, passive: true })
|
|
1318
|
-
addEventListener("touchmove", stop, { once: true, passive: true })
|
|
1319
|
-
root.style.overflowAnchor = "none"
|
|
1320
|
-
root.style.minHeight = `${root.scrollHeight}px
|
|
1321
|
-
const hold =
|
|
1322
|
-
const off = element.getBoundingClientRect().top - before
|
|
1323
|
-
if (!stopped && Math.abs(off) >= 1) scrollTo({ top: scrollY + off, behavior: "instant" })
|
|
1324
|
-
if (!stopped && performance.now() < until) return requestAnimationFrame(hold)
|
|
1325
|
-
root.style.overflowAnchor = ""
|
|
1326
|
-
removeEventListener("wheel", stop)
|
|
1327
|
-
removeEventListener("touchmove", stop)
|
|
1328
|
-
releaseHeight(root)
|
|
1329
|
-
}
|
|
1330
|
-
requestAnimationFrame(hold)
|
|
1331
|
-
})
|
|
1332
|
-
}
|
|
1333
|
-
|
|
2284
|
+
const root = document.documentElement
|
|
2285
|
+
const before = element.getBoundingClientRect().top
|
|
2286
|
+
const until = performance.now() + FOLD_HOLD_MS
|
|
2287
|
+
let stopped = false
|
|
2288
|
+
const stop = () => (stopped = true)
|
|
2289
|
+
addEventListener("wheel", stop, { once: true, passive: true })
|
|
2290
|
+
addEventListener("touchmove", stop, { once: true, passive: true })
|
|
2291
|
+
root.style.overflowAnchor = "none"
|
|
2292
|
+
root.style.minHeight = `${root.scrollHeight}px`
|
|
2293
|
+
const hold = () => {
|
|
2294
|
+
const off = element.getBoundingClientRect().top - before
|
|
2295
|
+
if (!stopped && Math.abs(off) >= 1) scrollTo({ top: scrollY + off, behavior: "instant" })
|
|
2296
|
+
if (!stopped && performance.now() < until) return requestAnimationFrame(hold)
|
|
2297
|
+
root.style.overflowAnchor = ""
|
|
2298
|
+
removeEventListener("wheel", stop)
|
|
2299
|
+
removeEventListener("touchmove", stop)
|
|
2300
|
+
releaseHeight(root)
|
|
2301
|
+
}
|
|
2302
|
+
requestAnimationFrame(hold)
|
|
2303
|
+
})
|
|
2304
|
+
}
|
|
2305
|
+
|
|
2306
|
+
/**
|
|
2307
|
+
* Let the page take its natural height again once that no longer pulls the reader back: at once if it fits where
|
|
2308
|
+
* he's scrolled to, else as soon as he scrolls up far enough.
|
|
2309
|
+
* - the held height only ever shrinks to the window's bottom (`scrollY + clientHeight`), never below:
|
|
2310
|
+
* the page is then exactly as tall as it must be to stay where it's scrolled;
|
|
2311
|
+
* if it's still taller than that, the content is, and the hold can go
|
|
2312
|
+
* - NEVER measures the natural height by taking the hold off for a moment: that layout alone makes the browser
|
|
2313
|
+
* clamp the scroll to the shorter page, and the reader dropped by however much shorter it was (I7 of `airplane`:
|
|
2314
|
+
* the line of an item a link had landed near the page's end fell 20-80px when the hold ended)
|
|
2315
|
+
*/
|
|
1334
2316
|
function releaseHeight(root) {
|
|
1335
|
-
const release =
|
|
1336
|
-
const bottom = scrollY + root.clientHeight
|
|
1337
|
-
if (bottom < parseFloat(root.style.minHeight)) root.style.minHeight = `${bottom}px
|
|
1338
|
-
if (root.scrollHeight <= bottom + 1) return false
|
|
1339
|
-
root.style.minHeight = ""
|
|
1340
|
-
removeEventListener("scroll", release)
|
|
1341
|
-
return true
|
|
1342
|
-
}
|
|
1343
|
-
if (!release()) addEventListener("scroll", release, { passive: true })
|
|
1344
|
-
}
|
|
1345
|
-
|
|
2317
|
+
const release = () => {
|
|
2318
|
+
const bottom = scrollY + root.clientHeight
|
|
2319
|
+
if (bottom < parseFloat(root.style.minHeight)) root.style.minHeight = `${bottom}px`
|
|
2320
|
+
if (root.scrollHeight <= bottom + 1) return false
|
|
2321
|
+
root.style.minHeight = ""
|
|
2322
|
+
removeEventListener("scroll", release)
|
|
2323
|
+
return true
|
|
2324
|
+
}
|
|
2325
|
+
if (!release()) addEventListener("scroll", release, { passive: true })
|
|
2326
|
+
}
|
|
2327
|
+
|
|
2328
|
+
/**
|
|
2329
|
+
* The reader folded or unfolded a section (accordions' `ui-opening` / `ui-closing` bubble here too: not ours).
|
|
2330
|
+
* - an opening that can't be cancelled is the BROWSER's reveal (find-in-page, a `#hash` load):
|
|
2331
|
+
* not saved, as a link's unfold isn't
|
|
2332
|
+
*/
|
|
1346
2333
|
function onToggle(event) {
|
|
1347
|
-
const section = event.target
|
|
1348
|
-
if (event.defaultPrevented || !event.cancelable || !section.matches?.(SECTIONS) || !section.id) return
|
|
1349
|
-
saved[section.id] = !event.detail?.open
|
|
1350
|
-
writeJSON(key, saved)
|
|
1351
|
-
if (!event.detail?.open) keepTitlePut(section)
|
|
2334
|
+
const section = event.target
|
|
2335
|
+
if (event.defaultPrevented || !event.cancelable || !section.matches?.(SECTIONS) || !section.id) return
|
|
2336
|
+
saved[section.id] = !event.detail?.open
|
|
2337
|
+
writeJSON(key, saved)
|
|
2338
|
+
if (!event.detail?.open) keepTitlePut(section)
|
|
1352
2339
|
}
|
|
1353
|
-
|
|
2340
|
+
|
|
2341
|
+
/**
|
|
2342
|
+
* Folding a section the reader is INSIDE (its title stuck, its top scrolled past): scroll at once so the title
|
|
2343
|
+
* stays where it's stuck, and the content folds away below it.
|
|
2344
|
+
* - why: else the title drops back to the section's top, far above, and the page slides up after the
|
|
2345
|
+
* shrinking content (Owen's "bounce", 2026-10-04)
|
|
2346
|
+
*/
|
|
1354
2347
|
function keepTitlePut(section) {
|
|
1355
|
-
const title = titleOf(section)
|
|
1356
|
-
if (!title) return
|
|
1357
|
-
const stuckAt = title.getBoundingClientRect().top
|
|
1358
|
-
const top = section.getBoundingClientRect().top
|
|
1359
|
-
if (top >= stuckAt - 1) return
|
|
1360
|
-
scrollTo({ top: scrollY + top - stuckAt, behavior: "instant" })
|
|
1361
|
-
}
|
|
1362
|
-
|
|
2348
|
+
const title = titleOf(section)
|
|
2349
|
+
if (!title) return
|
|
2350
|
+
const stuckAt = title.getBoundingClientRect().top
|
|
2351
|
+
const top = section.getBoundingClientRect().top
|
|
2352
|
+
if (top >= stuckAt - 1) return
|
|
2353
|
+
scrollTo({ top: scrollY + top - stuckAt, behavior: "instant" })
|
|
2354
|
+
}
|
|
2355
|
+
|
|
2356
|
+
/** HEADINGS: a chevron on every h2 / h3 of a sticky section. */
|
|
1363
2357
|
function wireHeadingFolds() {
|
|
1364
2358
|
for (const sticky of main.querySelectorAll("section > ui-sticky:is(.spell-h2, .spell-h3)")) {
|
|
1365
|
-
const heading = sticky.firstElementChild
|
|
1366
|
-
if (!heading?.id || heading.querySelector(":scope > ui-button.spell-fold")) continue
|
|
1367
|
-
const section = sticky.parentElement
|
|
1368
|
-
const button = document.createElement("ui-button")
|
|
1369
|
-
button.className = "spell-fold"
|
|
1370
|
-
|
|
1371
|
-
const
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
heading.
|
|
1376
|
-
|
|
1377
|
-
|
|
2359
|
+
const heading = sticky.firstElementChild
|
|
2360
|
+
if (!heading?.id || heading.querySelector(":scope > ui-button.spell-fold")) continue
|
|
2361
|
+
const section = sticky.parentElement
|
|
2362
|
+
const button = document.createElement("ui-button")
|
|
2363
|
+
button.className = "spell-fold"
|
|
2364
|
+
// its tooltip the browser's own, on the button the pointer lands on ("TOOLTIPS"; a `<ui-popup>` before I32)
|
|
2365
|
+
const tip = "Fold / unfold"
|
|
2366
|
+
const attributes = { circular: "", basic: "", size: "mini", icon: "chevron down", title: tip, "aria-label": tip }
|
|
2367
|
+
for (const [name, value] of Object.entries(attributes)) button.setAttribute(name, value)
|
|
2368
|
+
titleInside(button)
|
|
2369
|
+
heading.prepend(button)
|
|
2370
|
+
heading.classList.add("spell-foldable")
|
|
2371
|
+
if (kept && heading.id in kept) setFolded(section, !kept[heading.id])
|
|
2372
|
+
else setFolded(section, heading.id in saved ? !!saved[heading.id] : section.dataset.fold === "closed")
|
|
1378
2373
|
heading.addEventListener("click", (event) => {
|
|
1379
|
-
|
|
2374
|
+
// the chevron's own `<button>` (in its shadow root) comes first in the path: look for the HOST
|
|
2375
|
+
const path = event.composedPath()
|
|
1380
2376
|
if (!path.includes(button)) {
|
|
1381
|
-
const before = path.slice(0, Math.max(0, path.indexOf(heading)))
|
|
1382
|
-
if (before.some((node) => node instanceof Element && node.matches("a, ui-button, button"))) return
|
|
2377
|
+
const before = path.slice(0, Math.max(0, path.indexOf(heading)))
|
|
2378
|
+
if (before.some((node) => node instanceof Element && node.matches("a, ui-button, button"))) return
|
|
1383
2379
|
}
|
|
1384
|
-
event.preventDefault()
|
|
1385
|
-
const folded = !section.classList.contains("spell-folded")
|
|
1386
|
-
setFolded(section, folded)
|
|
1387
|
-
saved[heading.id] = folded
|
|
1388
|
-
writeJSON(key, saved)
|
|
1389
|
-
})
|
|
2380
|
+
event.preventDefault()
|
|
2381
|
+
const folded = !section.classList.contains("spell-folded")
|
|
2382
|
+
setFolded(section, folded)
|
|
2383
|
+
saved[heading.id] = folded
|
|
2384
|
+
writeJSON(key, saved)
|
|
2385
|
+
})
|
|
1390
2386
|
}
|
|
1391
2387
|
}
|
|
1392
|
-
|
|
2388
|
+
|
|
2389
|
+
/**
|
|
2390
|
+
* Unfold every section around `element`; open `element`'s own folded panel.
|
|
2391
|
+
* - `self: false`: only what's AROUND it -- a folded section, or an item's closed panel, stays as it is
|
|
2392
|
+
*/
|
|
1393
2393
|
function reveal(element, { self = true } = {}) {
|
|
1394
|
-
|
|
1395
|
-
|
|
2394
|
+
// on an epic page: shown even where its page's stage, or its section's state filter, hides it (epic `epic-engine`
|
|
2395
|
+
// I191: a To review chip's J2, in the Judgement calls a page still agreeing its phases hides)
|
|
2396
|
+
const shown = !!element.closest("epic-section")?.showLinked?.(element)
|
|
2397
|
+
let unfolded = false
|
|
1396
2398
|
if (outline.sections) {
|
|
1397
|
-
const folds = `ui-section, ${EPIC_OPENERS}
|
|
1398
|
-
for (
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
|
|
1402
|
-
|
|
2399
|
+
const folds = `ui-section, ${EPIC_OPENERS}`
|
|
2400
|
+
for (
|
|
2401
|
+
let section = self ? element.closest(folds) : element.parentElement?.closest(folds);
|
|
2402
|
+
section;
|
|
2403
|
+
section = section.parentElement?.closest(folds)
|
|
2404
|
+
) {
|
|
2405
|
+
if (!isCollapsed(section)) continue
|
|
2406
|
+
if (!unfolded) main.style.setProperty("--ui-section-duration", "0s")
|
|
2407
|
+
setCollapsed(section, false)
|
|
2408
|
+
unfolded = true
|
|
1403
2409
|
}
|
|
1404
|
-
if (unfolded) void nextFrame(UNFOLD_FRAMES + 1).then(() => main.style.removeProperty("--ui-section-duration"))
|
|
2410
|
+
if (unfolded) void nextFrame(UNFOLD_FRAMES + 1).then(() => main.style.removeProperty("--ui-section-duration"))
|
|
1405
2411
|
} else {
|
|
1406
|
-
for (
|
|
1407
|
-
|
|
2412
|
+
for (
|
|
2413
|
+
let section = element.closest("section.spell-folded");
|
|
2414
|
+
section;
|
|
2415
|
+
section = section.parentElement?.closest("section.spell-folded")
|
|
2416
|
+
)
|
|
2417
|
+
setFolded(section, false)
|
|
1408
2418
|
}
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1412
|
-
|
|
1413
|
-
|
|
1414
|
-
|
|
1415
|
-
|
|
1416
|
-
|
|
1417
|
-
|
|
1418
|
-
|
|
1419
|
-
|
|
2419
|
+
// a folded field around it (a phase's Symptom, Goal ...; epic `epic-engine` I167): opened, never remembered
|
|
2420
|
+
for (
|
|
2421
|
+
let field = self ? element.closest(FIELDS_THAT_FOLD) : element.parentElement?.closest(FIELDS_THAT_FOLD);
|
|
2422
|
+
field;
|
|
2423
|
+
field = field.parentElement?.closest(FIELDS_THAT_FOLD)
|
|
2424
|
+
)
|
|
2425
|
+
if (field.component?.reveal?.()) unfolded = true
|
|
2426
|
+
const panel = self ? element.querySelector(":scope > ui-accordion > ui-title") : null
|
|
2427
|
+
if (panel && !isPanelOpen(panel)) setPanel(panel, true)
|
|
2428
|
+
// an id INSIDE a closed panel (an old decision's `#d7`, now the answer card in its question):
|
|
2429
|
+
// open the panels around it, or the jump lands on nothing
|
|
2430
|
+
for (
|
|
2431
|
+
let content = element.closest("ui-accordion > ui-content");
|
|
2432
|
+
content;
|
|
2433
|
+
content = content.parentElement.parentElement?.closest("ui-accordion > ui-content")
|
|
2434
|
+
) {
|
|
2435
|
+
const accordion = content.parentElement
|
|
2436
|
+
const contents = Array.from(accordion.children).filter((child) => child.localName === "ui-content")
|
|
2437
|
+
const title = titlesOf(accordion)[contents.indexOf(content)]
|
|
2438
|
+
if (!title || isPanelOpen(title)) continue
|
|
2439
|
+
setPanel(title, true)
|
|
2440
|
+
unfolded = true
|
|
1420
2441
|
}
|
|
1421
|
-
return unfolded || shown
|
|
2442
|
+
return unfolded || shown
|
|
1422
2443
|
}
|
|
1423
|
-
__name(reveal, "reveal");
|
|
1424
2444
|
}
|
|
1425
|
-
|
|
2445
|
+
|
|
2446
|
+
/**
|
|
2447
|
+
* Keep every fold as it is as the page goes (`pagehide`), for a LIVE reload to put back (`takeKeptFolds()`):
|
|
2448
|
+
* `{ [id]: open }` in `sessionStorage`, of every section, folding heading, epic page block and ITEM with an id.
|
|
2449
|
+
* - why: the saved folds (`spell-folds:<path>`) hold only what the reader folded or unfolded himself,
|
|
2450
|
+
* never an item nor what a link opened; a reload for new code must come back as he left it (I23 of `epic-engine`)
|
|
2451
|
+
* - written on every `pagehide`; read only after a live reload:
|
|
2452
|
+
* a reload the reader asks for starts from the saved folds, as before
|
|
2453
|
+
* - storage blocked: kept for this page only (`PrefStore`), so a live reload starts from the saved folds
|
|
2454
|
+
*/
|
|
1426
2455
|
function keepFoldsForReload(main) {
|
|
1427
2456
|
addEventListener("pagehide", () => {
|
|
1428
|
-
const folds = {}
|
|
2457
|
+
const folds = {}
|
|
1429
2458
|
for (const block of main.querySelectorAll(`ui-section[collapsible][id], ${EPIC_OPENERS}`))
|
|
1430
|
-
if (block.id) folds[block.id] = !isCollapsed(block)
|
|
2459
|
+
if (block.id) folds[block.id] = !isCollapsed(block)
|
|
1431
2460
|
for (const heading of main.querySelectorAll(".spell-foldable[id]"))
|
|
1432
|
-
folds[heading.id] = !heading.parentElement.parentElement.classList.contains("spell-folded")
|
|
1433
|
-
|
|
1434
|
-
|
|
2461
|
+
folds[heading.id] = !heading.parentElement.parentElement.classList.contains("spell-folded")
|
|
2462
|
+
// storage blocked: kept for this page only, so a live reload starts from the saved folds
|
|
2463
|
+
PrefStore.setAt(`${KEPT_FOLDS_KEY_PREFIX}${location.pathname}`, folds, "session")
|
|
2464
|
+
})
|
|
1435
2465
|
}
|
|
1436
|
-
|
|
2466
|
+
|
|
2467
|
+
/**
|
|
2468
|
+
* The folds `keepFoldsForReload()` kept as the page last went, when this load is a LIVE reload (`live`);
|
|
2469
|
+
* else `undefined`. Forgets them either way.
|
|
2470
|
+
*/
|
|
1437
2471
|
function takeKeptFolds(live) {
|
|
1438
|
-
const key = `${KEPT_FOLDS_KEY_PREFIX}${location.pathname}
|
|
1439
|
-
const kept = live ? PrefStore.getAt(key, "session") :
|
|
1440
|
-
PrefStore.setAt(key,
|
|
1441
|
-
return kept && typeof kept === "object" ? kept :
|
|
2472
|
+
const key = `${KEPT_FOLDS_KEY_PREFIX}${location.pathname}`
|
|
2473
|
+
const kept = live ? PrefStore.getAt(key, "session") : undefined
|
|
2474
|
+
PrefStore.setAt(key, undefined, "session")
|
|
2475
|
+
return kept && typeof kept === "object" ? kept : undefined
|
|
1442
2476
|
}
|
|
1443
|
-
|
|
2477
|
+
|
|
2478
|
+
/**
|
|
2479
|
+
* HEADINGS: fold or unfold `section`:
|
|
2480
|
+
* its class, its chevron (down / right) and the chevron's state for screen readers.
|
|
2481
|
+
*/
|
|
1444
2482
|
function setFolded(section, folded) {
|
|
1445
|
-
section.classList.toggle("spell-folded", folded)
|
|
1446
|
-
const button = section.querySelector(":scope > ui-sticky > * > ui-button.spell-fold")
|
|
1447
|
-
if (!button) return
|
|
1448
|
-
button.setAttribute("icon", folded ? "chevron right" : "chevron down")
|
|
1449
|
-
button.setAttribute("aria-label", folded ? "Unfold section" : "Fold section")
|
|
1450
|
-
button.setAttribute("aria-expanded", String(!folded))
|
|
1451
|
-
}
|
|
1452
|
-
|
|
1453
|
-
|
|
2483
|
+
section.classList.toggle("spell-folded", folded)
|
|
2484
|
+
const button = section.querySelector(":scope > ui-sticky > * > ui-button.spell-fold")
|
|
2485
|
+
if (!button) return
|
|
2486
|
+
button.setAttribute("icon", folded ? "chevron right" : "chevron down")
|
|
2487
|
+
button.setAttribute("aria-label", folded ? "Unfold section" : "Fold section")
|
|
2488
|
+
button.setAttribute("aria-expanded", String(!folded))
|
|
2489
|
+
}
|
|
2490
|
+
|
|
2491
|
+
////////////////
|
|
2492
|
+
// ## Sticky headers
|
|
2493
|
+
////////////////
|
|
2494
|
+
|
|
2495
|
+
/** `trackStickyHeights()`'s current observer: disconnected when it runs again. */
|
|
2496
|
+
let stickyObserver
|
|
2497
|
+
|
|
2498
|
+
/**
|
|
2499
|
+
* Where each sticky title sticks: below the fixed site header (`siteHeaderHeight()`), then whatever sticks above
|
|
2500
|
+
* every section -- the page header (`ui-sticky.spell-h1`) and the CHEATSHEET's filter bar (`.spell-filter`), whose
|
|
2501
|
+
* heights are `--spell-top` on `main`.
|
|
2502
|
+
* - SECTIONS: sets each top-level `<ui-section>`'s `offset`; nested ones stack themselves below their parents'.
|
|
2503
|
+
* Writes `--spell-section-top` (where its title sticks) and `--spell-stack` (the bottom of its stack of stuck
|
|
2504
|
+
* titles) on every section, which `scroll-margin-top` reads (`spell-doc.css`): a section lands at its sticky
|
|
2505
|
+
* line, anything in it below its stack.
|
|
2506
|
+
* - HEADINGS: h2s below the bar, h3s just below their section's h2; sets each sticky's `offset`, and
|
|
2507
|
+
* `--spell-h2-h` / `--spell-h3-h` on the sections, which the headings' `scroll-margin-top` reads
|
|
2508
|
+
* - also sticks the page header just below the site header (its `offset`), and writes
|
|
2509
|
+
* the page header's height as `--spell-head-h` on `main` (the filter bar sticks below it)
|
|
2510
|
+
* - NOTE: the `offset`s are from the VIEWPORT top, so they include the site header; the CSS variables (and so
|
|
2511
|
+
* every `scroll-margin-top`) leave it OUT, as the browser adds it (see "Landing" in the header)
|
|
2512
|
+
* - re-measured whenever a title changes size (fonts loading, the window narrowing and titles wrapping)
|
|
2513
|
+
* - returns `{ measure, offsetFor }`: `offsetFor(target)` is how far below the viewport top it should land
|
|
2514
|
+
* - callable again (a page updated in place): disconnects the previous call's observer (`stickyObserver`)
|
|
2515
|
+
*/
|
|
1454
2516
|
function trackStickyHeights(main, outline) {
|
|
1455
|
-
const head = main.querySelector(":scope > ui-sticky.spell-h1")
|
|
1456
|
-
|
|
1457
|
-
const
|
|
1458
|
-
const
|
|
1459
|
-
const
|
|
1460
|
-
|
|
1461
|
-
|
|
1462
|
-
stickyObserver
|
|
2517
|
+
const head = main.querySelector(":scope > ui-sticky.spell-h1")
|
|
2518
|
+
// the filter bar, or a page toolbar sticking by itself (`buildPageToolbar()`): never both
|
|
2519
|
+
const bar = main.querySelector(".spell-filter, nav.spell-toolbar-alone")
|
|
2520
|
+
const h2Stickies = outline.sections ? [] : Array.from(main.querySelectorAll("ui-sticky.spell-h2"))
|
|
2521
|
+
const h3Stickies = outline.sections ? [] : Array.from(main.querySelectorAll("ui-sticky.spell-h3"))
|
|
2522
|
+
const sections = outline.sections ? Array.from(main.querySelectorAll("ui-section")) : []
|
|
2523
|
+
// called again after an in-place update: the previous call's observer stops first
|
|
2524
|
+
stickyObserver?.disconnect()
|
|
2525
|
+
const observer = new ResizeObserver(() => measure())
|
|
2526
|
+
stickyObserver = observer
|
|
1463
2527
|
for (const sticky of [head, ...h2Stickies, ...h3Stickies]) {
|
|
1464
|
-
const heading = sticky?.firstElementChild
|
|
1465
|
-
if (heading) observer.observe(heading)
|
|
2528
|
+
const heading = sticky?.firstElementChild
|
|
2529
|
+
if (heading) observer.observe(heading)
|
|
1466
2530
|
}
|
|
1467
|
-
if (bar) observer.observe(bar)
|
|
1468
|
-
measure()
|
|
1469
|
-
return { measure, offsetFor }
|
|
2531
|
+
if (bar) observer.observe(bar)
|
|
2532
|
+
measure()
|
|
2533
|
+
return { measure, offsetFor }
|
|
2534
|
+
|
|
2535
|
+
/** The site header and what sticks above the sections; then each section's (heading's) sticky line. */
|
|
1470
2536
|
function measure() {
|
|
1471
|
-
const header = siteHeaderHeight()
|
|
1472
|
-
const headHeight = head ? heightOf(head) : 0
|
|
1473
|
-
const top = Math.round(headHeight + (bar ? bar.getBoundingClientRect().height : 0))
|
|
1474
|
-
setPixels(main, "--spell-head-h", headHeight)
|
|
1475
|
-
setPixels(main, "--spell-top", top)
|
|
1476
|
-
if (head) setOffset(head, header)
|
|
1477
|
-
if (outline.sections) measureSections(header, top)
|
|
1478
|
-
else measureHeadings(header, top)
|
|
1479
|
-
}
|
|
1480
|
-
|
|
2537
|
+
const header = siteHeaderHeight()
|
|
2538
|
+
const headHeight = head ? heightOf(head) : 0
|
|
2539
|
+
const top = Math.round(headHeight + (bar ? bar.getBoundingClientRect().height : 0))
|
|
2540
|
+
setPixels(main, "--spell-head-h", headHeight)
|
|
2541
|
+
setPixels(main, "--spell-top", top)
|
|
2542
|
+
if (head) setOffset(head, header)
|
|
2543
|
+
if (outline.sections) measureSections(header, top)
|
|
2544
|
+
else measureHeadings(header, top)
|
|
2545
|
+
}
|
|
2546
|
+
|
|
2547
|
+
/**
|
|
2548
|
+
* SECTIONS: top-level `offset`s, and each section's sticky line and stack bottom, parents first.
|
|
2549
|
+
* - `header`: the site header's height; `top`: what sticks below it, above every section
|
|
2550
|
+
*/
|
|
1481
2551
|
function measureSections(header, top) {
|
|
1482
|
-
const bottoms =
|
|
2552
|
+
const bottoms = new Map()
|
|
1483
2553
|
for (const section of sections) {
|
|
1484
|
-
const parent = section.parentElement?.closest("ui-section")
|
|
1485
|
-
const line = parent ? bottoms.get(parent) ?? top : top
|
|
1486
|
-
const title = titleOf(section)
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
|
|
1491
|
-
setPixels(section, "--spell-
|
|
1492
|
-
|
|
2554
|
+
const parent = section.parentElement?.closest("ui-section")
|
|
2555
|
+
const line = parent ? (bottoms.get(parent) ?? top) : top
|
|
2556
|
+
const title = titleOf(section)
|
|
2557
|
+
// a title renders once UI has loaded: observe it when it's there (observing twice is a no-op)
|
|
2558
|
+
if (title) observer.observe(title)
|
|
2559
|
+
const height = title && section.hasAttribute("sticky") ? title.getBoundingClientRect().height : 0
|
|
2560
|
+
bottoms.set(section, line + height)
|
|
2561
|
+
setPixels(section, "--spell-section-top", line)
|
|
2562
|
+
setPixels(section, "--spell-stack", line + height)
|
|
2563
|
+
if (!parent) setOffset(section, header + top)
|
|
1493
2564
|
}
|
|
1494
2565
|
}
|
|
1495
|
-
|
|
2566
|
+
|
|
2567
|
+
/** HEADINGS: the h2 / h3 stickies' `offset`s and heights. */
|
|
1496
2568
|
function measureHeadings(header, top) {
|
|
1497
2569
|
for (const sticky of h2Stickies) {
|
|
1498
|
-
sticky.parentElement.style.setProperty("--spell-h2-h", `${heightOf(sticky)}px`)
|
|
1499
|
-
setOffset(sticky, header + top)
|
|
2570
|
+
sticky.parentElement.style.setProperty("--spell-h2-h", `${heightOf(sticky)}px`)
|
|
2571
|
+
setOffset(sticky, header + top)
|
|
1500
2572
|
}
|
|
1501
2573
|
for (const sticky of h3Stickies) {
|
|
1502
|
-
sticky.parentElement.style.setProperty("--spell-h3-h", `${heightOf(sticky)}px`)
|
|
1503
|
-
setOffset(sticky, header + top + h2HeightAbove(sticky))
|
|
2574
|
+
sticky.parentElement.style.setProperty("--spell-h3-h", `${heightOf(sticky)}px`)
|
|
2575
|
+
setOffset(sticky, header + top + h2HeightAbove(sticky))
|
|
1504
2576
|
}
|
|
1505
2577
|
}
|
|
1506
|
-
|
|
2578
|
+
|
|
2579
|
+
/** How far below the viewport top a target lands (`landingLine()`). */
|
|
1507
2580
|
function offsetFor(target) {
|
|
1508
|
-
return landingLine(target)
|
|
2581
|
+
return landingLine(target)
|
|
1509
2582
|
}
|
|
1510
|
-
__name(offsetFor, "offsetFor");
|
|
1511
2583
|
}
|
|
1512
|
-
|
|
2584
|
+
|
|
2585
|
+
/**
|
|
2586
|
+
* How far below the viewport top `target` lands, px:
|
|
2587
|
+
* - inside an epic page (`<epic-page>`): where the titles stuck over it end, the `--epic-stack` it inherits (a block's
|
|
2588
|
+
* own title sticks there; anything else lands `EPIC_LAND_GAP` below), and below its item's line when it's in an
|
|
2589
|
+
* item's details (the line sticks there too)
|
|
2590
|
+
* - else: the site header, then its own `scroll-margin-top` (CSS derives it from the sections)
|
|
2591
|
+
*/
|
|
1513
2592
|
function landingLine(target) {
|
|
1514
|
-
const stack = target.closest("epic-page")
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
1521
|
-
|
|
2593
|
+
const stack = target.closest("epic-page")
|
|
2594
|
+
? parseFloat(getComputedStyle(target).getPropertyValue("--epic-stack"))
|
|
2595
|
+
: NaN
|
|
2596
|
+
if (Number.isNaN(stack)) return siteHeaderHeight() + (parseFloat(getComputedStyle(target).scrollMarginTop) || 0)
|
|
2597
|
+
if (target.matches(EPIC_OPENERS)) return stack
|
|
2598
|
+
const item = target.parentElement?.closest("epic-item")
|
|
2599
|
+
const line = item?.shadowRoot?.querySelector('[part~="line"]')
|
|
2600
|
+
return stack + EPIC_LAND_GAP + (line ? line.getBoundingClientRect().height : 0)
|
|
2601
|
+
}
|
|
2602
|
+
|
|
2603
|
+
/**
|
|
2604
|
+
* Height of the fixed `<spell-site-header>` on top of the page, px: its `--spell-site-header-height` on `:root`.
|
|
2605
|
+
* - 0 when the page has none (or it isn't defined yet): then everything sticks at the viewport top, as before
|
|
2606
|
+
*/
|
|
1522
2607
|
function siteHeaderHeight() {
|
|
1523
|
-
const value = getComputedStyle(document.documentElement).getPropertyValue("--spell-site-header-height")
|
|
1524
|
-
return parseFloat(value) || 0
|
|
2608
|
+
const value = getComputedStyle(document.documentElement).getPropertyValue("--spell-site-header-height")
|
|
2609
|
+
return parseFloat(value) || 0
|
|
1525
2610
|
}
|
|
1526
|
-
|
|
2611
|
+
|
|
2612
|
+
/** Write `pixels` as custom property `name` on `element`, unless it's already that. */
|
|
1527
2613
|
function setPixels(element, name, pixels) {
|
|
1528
|
-
const value = `${Math.round(pixels * 100) / 100}px
|
|
1529
|
-
if (element.style.getPropertyValue(name) !== value) element.style.setProperty(name, value)
|
|
2614
|
+
const value = `${Math.round(pixels * 100) / 100}px`
|
|
2615
|
+
if (element.style.getPropertyValue(name) !== value) element.style.setProperty(name, value)
|
|
1530
2616
|
}
|
|
1531
|
-
|
|
2617
|
+
|
|
2618
|
+
/**
|
|
2619
|
+
* A sticky's (top-level section's) `offset`, in whole pixels;
|
|
2620
|
+
* re-setting the same value would restart its observer for nothing.
|
|
2621
|
+
*/
|
|
1532
2622
|
function setOffset(sticky, offset) {
|
|
1533
|
-
const text = String(Math.round(offset))
|
|
1534
|
-
if (sticky.getAttribute("offset") !== text) sticky.setAttribute("offset", text)
|
|
2623
|
+
const text = String(Math.round(offset))
|
|
2624
|
+
if (sticky.getAttribute("offset") !== text) sticky.setAttribute("offset", text)
|
|
1535
2625
|
}
|
|
1536
|
-
|
|
2626
|
+
|
|
2627
|
+
/** Height of a sticky's heading (the sticky host is `display: contents`, so measure what it holds). */
|
|
1537
2628
|
function heightOf(sticky) {
|
|
1538
|
-
return sticky.firstElementChild?.getBoundingClientRect().height ?? 0
|
|
2629
|
+
return sticky.firstElementChild?.getBoundingClientRect().height ?? 0
|
|
1539
2630
|
}
|
|
1540
|
-
|
|
2631
|
+
|
|
2632
|
+
/** Height of the h2 whose section holds `sticky`'s section: where an h3 sticks. */
|
|
1541
2633
|
function h2HeightAbove(sticky) {
|
|
1542
2634
|
for (let section = sticky.parentElement?.parentElement; section; section = section.parentElement) {
|
|
1543
|
-
const h2 = section.querySelector(":scope > ui-sticky.spell-h2")
|
|
1544
|
-
if (h2) return heightOf(h2)
|
|
2635
|
+
const h2 = section.querySelector(":scope > ui-sticky.spell-h2")
|
|
2636
|
+
if (h2) return heightOf(h2)
|
|
1545
2637
|
}
|
|
1546
|
-
return 0
|
|
2638
|
+
return 0
|
|
1547
2639
|
}
|
|
1548
|
-
|
|
2640
|
+
|
|
2641
|
+
////////////////
|
|
2642
|
+
// ## Anchors
|
|
2643
|
+
////////////////
|
|
2644
|
+
|
|
2645
|
+
/**
|
|
2646
|
+
* Same-page links to anything with an id in `main` (a section, a heading, a plan item) jump there ourselves, and
|
|
2647
|
+
* the toolbar follows AT ONCE.
|
|
2648
|
+
* - a section lands with its title at its sticky line; anything else below every stuck title above it (both by
|
|
2649
|
+
* the site header plus their `scroll-margin-top`, "Landing" in the header): the browser's own jump would add
|
|
2650
|
+
* the stuck titles' scroll padding (they reserve it) on top
|
|
2651
|
+
* - HEADINGS: a STICKY heading's jump goes to its section: a stuck heading already "is" at the top, so the
|
|
2652
|
+
* browser's own jump to it does nothing -- e.g. the toolbar's entry of the section you're reading
|
|
2653
|
+
* - every jump lands through Spell UI's `HashLanding`, by this page's rules (its `use()`, here):
|
|
2654
|
+
* folded sections around the target unfold first, and a target that is a folded item opens (`folds.reveal()`);
|
|
2655
|
+
* an unfolded `<ui-section>` draws on the next frames, so the jump lands once it has, and once more as the page
|
|
2656
|
+
* settles (`SETTLE_MS` twice) unless the reader moved meanwhile
|
|
2657
|
+
* - the page lands its hashes itself: a `<ui-toc>` or `<ui-docs-api>` on it leaves them to it
|
|
2658
|
+
* - the target's entry becomes the current one even when the page can't scroll it up to its line (the last
|
|
2659
|
+
* short sections), until the user scrolls on (`follow.pin()`)
|
|
2660
|
+
* - `hashchange` / `popstate` (back, forward, a typed hash) jump the same way
|
|
2661
|
+
* - in a frame (VS Code's view), the parent's `{ spell: "go", hash }` too: the view showing the page it already
|
|
2662
|
+
* shows, at an id (`packages/vscode/src/DocView.ts`); a history entry, as a click's
|
|
2663
|
+
* - a jump that moves the address says so (`spell-doc:scrolled-to`): `pushState()` fires no `hashchange`
|
|
2664
|
+
* - returns `{ jump, go, canGo }`:
|
|
2665
|
+
* - `jump(id, { unfoldTarget })`: `unfoldTarget: false` unfolds only what's AROUND a folded target section
|
|
2666
|
+
* (`land()`: a reload lands on the section being read as it was, folded or not)
|
|
2667
|
+
* - `go(id)`: as a click on a link to `#id` (a history entry, then the jump), resolving once landed;
|
|
2668
|
+
* `canGo(id)`: is there one to land on
|
|
2669
|
+
*/
|
|
1549
2670
|
function wireAnchors(main, outline, sticky, follow, folds) {
|
|
1550
2671
|
const landing = HashLanding.forDocument(document).use({
|
|
1551
2672
|
// the page has drawn already (`start()`)
|
|
1552
|
-
whenReady:
|
|
1553
|
-
reveal:
|
|
2673
|
+
whenReady: () => Promise.resolve(),
|
|
2674
|
+
reveal: (target, { opensTarget }) => folds.reveal(target, { self: opensTarget }),
|
|
1554
2675
|
revealFrames: UNFOLD_FRAMES,
|
|
1555
|
-
lineFor:
|
|
1556
|
-
topOf:
|
|
2676
|
+
lineFor: (target) => sticky.offsetFor(target),
|
|
2677
|
+
topOf: (target) => topOf(boxOf(target)),
|
|
1557
2678
|
// the target's entry is the current one, even where the page can't scroll it up to its line
|
|
1558
|
-
onLanded:
|
|
1559
|
-
const entry = outline.entryOf(target)
|
|
1560
|
-
if (entry) follow?.pin(entry)
|
|
1561
|
-
},
|
|
1562
|
-
settleSeconds: SETTLE_MS * 2 /
|
|
1563
|
-
})
|
|
2679
|
+
onLanded: (target) => {
|
|
2680
|
+
const entry = outline.entryOf(target)
|
|
2681
|
+
if (entry) follow?.pin(entry)
|
|
2682
|
+
},
|
|
2683
|
+
settleSeconds: (SETTLE_MS * 2) / 1000
|
|
2684
|
+
})
|
|
1564
2685
|
document.addEventListener("click", (event) => {
|
|
1565
|
-
if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey) return
|
|
1566
|
-
const id = targetIdOf(event)
|
|
1567
|
-
if (!id || !(targetIn(id) || hostHolding(main, id))) return
|
|
1568
|
-
event.preventDefault()
|
|
1569
|
-
go(id)
|
|
1570
|
-
})
|
|
1571
|
-
addEventListener("popstate", () => jump(hashId()))
|
|
1572
|
-
addEventListener("hashchange", () => jump(hashId()))
|
|
1573
|
-
if (window.parent !== window) addEventListener("message", onMessage)
|
|
1574
|
-
return { jump, go, canGo:
|
|
2686
|
+
if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey) return
|
|
2687
|
+
const id = targetIdOf(event)
|
|
2688
|
+
if (!id || !(targetIn(id) || hostHolding(main, id))) return
|
|
2689
|
+
event.preventDefault()
|
|
2690
|
+
go(id)
|
|
2691
|
+
})
|
|
2692
|
+
addEventListener("popstate", () => jump(hashId()))
|
|
2693
|
+
addEventListener("hashchange", () => jump(hashId()))
|
|
2694
|
+
if (window.parent !== window) addEventListener("message", onMessage)
|
|
2695
|
+
return { jump, go, canGo: (id) => !!(targetIn(id) || hostHolding(main, id)) }
|
|
2696
|
+
|
|
2697
|
+
/**
|
|
2698
|
+
* Follow a same-page link to `id`: a history entry (unless the address is there already), then the jump.
|
|
2699
|
+
* - Resolves once it has landed (`jump()`).
|
|
2700
|
+
*/
|
|
1575
2701
|
function go(id) {
|
|
1576
2702
|
if (hashId() !== id) {
|
|
1577
|
-
history.pushState(null, "", `#${id}`)
|
|
1578
|
-
dispatchEvent(new Event("spell-doc:scrolled-to"))
|
|
2703
|
+
history.pushState(null, "", `#${id}`)
|
|
2704
|
+
dispatchEvent(new Event("spell-doc:scrolled-to"))
|
|
1579
2705
|
}
|
|
1580
|
-
return jump(id)
|
|
2706
|
+
return jump(id)
|
|
1581
2707
|
}
|
|
1582
|
-
|
|
2708
|
+
|
|
2709
|
+
/** The frame's parent posted `{ spell: "go", hash }`: go there, as a link to it would. */
|
|
1583
2710
|
function onMessage(event) {
|
|
1584
|
-
const data = event.data
|
|
1585
|
-
if (event.source !== window.parent || data?.spell !== "go" || typeof data.hash !== "string") return
|
|
1586
|
-
const id = addressedId(TocIndex.decode(data.hash.replace(/^#/, "")))
|
|
1587
|
-
if (targetIn(id) || hostHolding(main, id)) go(id)
|
|
2711
|
+
const data = event.data
|
|
2712
|
+
if (event.source !== window.parent || data?.spell !== "go" || typeof data.hash !== "string") return
|
|
2713
|
+
const id = addressedId(TocIndex.decode(data.hash.replace(/^#/, "")))
|
|
2714
|
+
if (targetIn(id) || hostHolding(main, id)) go(id)
|
|
1588
2715
|
}
|
|
1589
|
-
|
|
2716
|
+
|
|
2717
|
+
/**
|
|
2718
|
+
* Scroll to `id` and make its entry the current one; once what it unfolded has drawn.
|
|
2719
|
+
* Returns a promise that settles once it has landed (or found nothing to land on).
|
|
2720
|
+
* - `id` inside a body not loaded yet (a split epic page's part: an Overview `h4`, an old `#d7` answer card):
|
|
2721
|
+
* its host loads the body first (`hostHolding()`, `load()`), then the jump goes on (caveat C8 of `claude-design`)
|
|
2722
|
+
*/
|
|
1590
2723
|
function jump(id, { unfoldTarget = true } = {}) {
|
|
1591
|
-
const target = targetIn(id)
|
|
2724
|
+
const target = targetIn(id)
|
|
1592
2725
|
if (!target) {
|
|
1593
|
-
const host = hostHolding(main, id)
|
|
1594
|
-
if (!host?.load) return Promise.resolve()
|
|
2726
|
+
const host = hostHolding(main, id)
|
|
2727
|
+
if (!host?.load) return Promise.resolve()
|
|
1595
2728
|
return host.load().then(
|
|
1596
|
-
() => targetIn(id) ? jump(id, { unfoldTarget }) :
|
|
1597
|
-
() =>
|
|
1598
|
-
)
|
|
2729
|
+
() => (targetIn(id) ? jump(id, { unfoldTarget }) : undefined),
|
|
2730
|
+
() => undefined
|
|
2731
|
+
)
|
|
1599
2732
|
}
|
|
1600
|
-
|
|
1601
|
-
|
|
1602
|
-
|
|
1603
|
-
|
|
2733
|
+
// what a jump unfolds opens at once, without the fold animation, so the page gets there quickly (Owen,
|
|
2734
|
+
// 2026-10-04): `spell-doc.css` zeroes `--ui-section-duration` under `data-spell-jumping`
|
|
2735
|
+
const root = document.documentElement
|
|
2736
|
+
root.setAttribute("data-spell-jumping", "")
|
|
2737
|
+
setTimeout(() => root.removeAttribute("data-spell-jumping"), SETTLE_MS)
|
|
2738
|
+
return landing.land(target, { opensTarget: unfoldTarget }).then(() => undefined)
|
|
1604
2739
|
}
|
|
1605
|
-
|
|
2740
|
+
|
|
2741
|
+
/** The `id` a click goes to: a same-page `#hash` link's. */
|
|
1606
2742
|
function targetIdOf(event) {
|
|
1607
2743
|
for (const node of event.composedPath()) {
|
|
1608
|
-
if (!(node instanceof Element)) continue
|
|
1609
|
-
const href = node.getAttribute("href")
|
|
2744
|
+
if (!(node instanceof Element)) continue
|
|
2745
|
+
const href = node.getAttribute("href")
|
|
1610
2746
|
if (node.localName === "a" && href?.startsWith("#") && href.length > 1)
|
|
1611
|
-
return addressedId(decodeURIComponent(href.slice(1)))
|
|
2747
|
+
return addressedId(decodeURIComponent(href.slice(1)))
|
|
1612
2748
|
}
|
|
1613
|
-
return
|
|
2749
|
+
return undefined
|
|
1614
2750
|
}
|
|
1615
|
-
|
|
2751
|
+
|
|
2752
|
+
/** The element with `id` in `main`, if any. */
|
|
1616
2753
|
function targetIn(id) {
|
|
1617
|
-
const element = id ? document.getElementById(id) : null
|
|
1618
|
-
return element && main.contains(element) ? element : null
|
|
2754
|
+
const element = id ? document.getElementById(id) : null
|
|
2755
|
+
return element && main.contains(element) ? element : null
|
|
1619
2756
|
}
|
|
1620
|
-
__name(targetIn, "targetIn");
|
|
1621
2757
|
}
|
|
1622
|
-
|
|
2758
|
+
|
|
2759
|
+
/**
|
|
2760
|
+
* The box a jump to `target` measures: its own; a HEADINGS sticky heading's SECTION (it can't be measured where it is
|
|
2761
|
+
* while stuck). Where it lands is `offsetFor()`'s: the site header and its `scroll-margin-top`.
|
|
2762
|
+
*/
|
|
1623
2763
|
function boxOf(target) {
|
|
1624
|
-
return target.parentElement?.localName === "ui-sticky" ? target.parentElement.parentElement : target
|
|
2764
|
+
return target.parentElement?.localName === "ui-sticky" ? target.parentElement.parentElement : target
|
|
1625
2765
|
}
|
|
1626
|
-
|
|
2766
|
+
|
|
2767
|
+
/**
|
|
2768
|
+
* Viewport top of `element`'s box;
|
|
2769
|
+
* for a host with no box of its own (`display: contents`, e.g. `<ui-item>`), of what it holds.
|
|
2770
|
+
*/
|
|
1627
2771
|
function topOf(element) {
|
|
1628
|
-
if (element.getClientRects().length) return element.getBoundingClientRect().top
|
|
1629
|
-
const range = document.createRange()
|
|
1630
|
-
range.selectNodeContents(element)
|
|
1631
|
-
return range.getBoundingClientRect().top
|
|
2772
|
+
if (element.getClientRects().length) return element.getBoundingClientRect().top
|
|
2773
|
+
const range = document.createRange()
|
|
2774
|
+
range.selectNodeContents(element)
|
|
2775
|
+
return range.getBoundingClientRect().top
|
|
1632
2776
|
}
|
|
1633
|
-
|
|
2777
|
+
|
|
2778
|
+
////////////////
|
|
2779
|
+
// ## Short addresses
|
|
2780
|
+
////////////////
|
|
2781
|
+
|
|
2782
|
+
/**
|
|
2783
|
+
* Links to a SHORT ADDRESS (epic `epic-workflow` P15, J32), `<a href="SAGA:/drawable-spell/python-target#T1">`,
|
|
2784
|
+
* become links to the page and its `#id` (`EpicAddress`), so a page may link either way:
|
|
2785
|
+
* - the epic or saga page, from the checkout's root (`PageTargets.rootUrlOf()`), opening in that epic's tab (as every
|
|
2786
|
+
* link to an epic page) unless the link names one; the page there lands on the id, loading its part first
|
|
2787
|
+
* - into THIS page: a `#id` link, which `wireAnchors()` lands on
|
|
2788
|
+
* - every such link as the page starts, and one added later as it's clicked (before the anchors see the click)
|
|
2789
|
+
* - a malformed address, or no root to build from: left as it is
|
|
2790
|
+
*/
|
|
1634
2791
|
function wireAddresses() {
|
|
1635
|
-
const root = PageTargets.rootUrlOf(document)
|
|
1636
|
-
if (!root) return
|
|
1637
|
-
const here = EpicAddress.pageOf(location.href, root)
|
|
1638
|
-
for (const link of document.querySelectorAll("a[href]")) rewrite(link)
|
|
2792
|
+
const root = PageTargets.rootUrlOf(document)
|
|
2793
|
+
if (!root) return
|
|
2794
|
+
const here = EpicAddress.pageOf(location.href, root)
|
|
2795
|
+
for (const link of document.querySelectorAll("a[href]")) rewrite(link)
|
|
1639
2796
|
document.addEventListener(
|
|
1640
2797
|
"click",
|
|
1641
2798
|
(event) => {
|
|
1642
2799
|
for (const node of event.composedPath())
|
|
1643
|
-
if (node instanceof Element && node.localName === "a" && node.hasAttribute("href")) return rewrite(node)
|
|
2800
|
+
if (node instanceof Element && node.localName === "a" && node.hasAttribute("href")) return rewrite(node)
|
|
1644
2801
|
},
|
|
1645
2802
|
{ capture: true }
|
|
1646
|
-
)
|
|
2803
|
+
)
|
|
2804
|
+
|
|
2805
|
+
/** `link`'s address, if it has one, as the page and `#id` it means. */
|
|
1647
2806
|
function rewrite(link) {
|
|
1648
|
-
const href = link.getAttribute("href")
|
|
1649
|
-
if (!EpicAddress.isAddress(href)) return
|
|
1650
|
-
let address
|
|
2807
|
+
const href = link.getAttribute("href")
|
|
2808
|
+
if (!EpicAddress.isAddress(href)) return
|
|
2809
|
+
let address
|
|
1651
2810
|
try {
|
|
1652
|
-
address = EpicAddress.parse(href)
|
|
2811
|
+
address = EpicAddress.parse(href)
|
|
1653
2812
|
} catch {
|
|
1654
|
-
return
|
|
2813
|
+
return
|
|
1655
2814
|
}
|
|
1656
|
-
const samePage = address.page === here
|
|
1657
|
-
link.setAttribute("href", samePage ? `#${address.id ?? ""}` : address.hrefFrom(root))
|
|
1658
|
-
if (!samePage && !link.hasAttribute("target")) link.setAttribute("target", address.epic ?? `saga-${address.saga}`)
|
|
1659
|
-
link.setAttribute("data-spell-address", href)
|
|
2815
|
+
const samePage = address.page === here
|
|
2816
|
+
link.setAttribute("href", samePage ? `#${address.id ?? ""}` : address.hrefFrom(root))
|
|
2817
|
+
if (!samePage && !link.hasAttribute("target")) link.setAttribute("target", address.epic ?? `saga-${address.saga}`)
|
|
2818
|
+
link.setAttribute("data-spell-address", href)
|
|
1660
2819
|
}
|
|
1661
|
-
__name(rewrite, "rewrite");
|
|
1662
2820
|
}
|
|
1663
|
-
|
|
2821
|
+
|
|
2822
|
+
// ## Jump to an item (Cmd / Ctrl + K): `wireJumpKey()`, in `spell-doc-toolbar.js`
|
|
2823
|
+
|
|
2824
|
+
////////////////
|
|
2825
|
+
// ## Paging
|
|
2826
|
+
////////////////
|
|
2827
|
+
|
|
2828
|
+
/**
|
|
2829
|
+
* Page Down / Page Up / Space / Shift+Space page the document ourselves, so a page always continues just below the
|
|
2830
|
+
* stuck titles.
|
|
2831
|
+
* - why: the browser pages by the `scroll-padding-top` of where it STARTS (`StickyWatch`'s stuck edge), but paging
|
|
2832
|
+
* down can stick more titles (entering a nested section), which then cover the old bottom lines
|
|
2833
|
+
* - down: the old viewport bottom lands just below the lowest title stuck at the NEW position (`stuckBottom()`,
|
|
2834
|
+
* measured there: a sticky box's position is computed in layout, so an instant scroll and a read find it);
|
|
2835
|
+
* up: the old first line below the stuck titles lands at the viewport bottom
|
|
2836
|
+
* - measured with instant scrolls, then put back and scrolled there for real (smooth, unless reduced motion):
|
|
2837
|
+
* nothing paints in between
|
|
2838
|
+
* - left to the browser:
|
|
2839
|
+
* modifier keys, a key in a field, button, link or a scrolling box of its own (a wide `pre`), an open dialog
|
|
2840
|
+
*/
|
|
1664
2841
|
function wirePaging(main) {
|
|
1665
|
-
const keys = { PageDown: 1, PageUp: -1, " ": 1 }
|
|
2842
|
+
const keys = { PageDown: 1, PageUp: -1, " ": 1 }
|
|
1666
2843
|
document.addEventListener("keydown", (event) => {
|
|
1667
|
-
let direction = keys[event.key]
|
|
1668
|
-
if (!direction || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return
|
|
1669
|
-
if (event.key === " " && event.shiftKey) direction = -1
|
|
1670
|
-
if (document.querySelector("dialog[open]") || !pageOwnsKey(event, event.key === " ")) return
|
|
1671
|
-
event.preventDefault()
|
|
1672
|
-
const from = scrollY
|
|
1673
|
-
const to = direction > 0 ? pageDownTo() : pageUpTo()
|
|
1674
|
-
if (Math.abs(to - from) < 1) return
|
|
1675
|
-
const smooth = !matchMedia("(prefers-reduced-motion: reduce)").matches
|
|
1676
|
-
scrollTo({ top: from, behavior: "instant" })
|
|
1677
|
-
scrollTo({ top: to, behavior: smooth ? "smooth" : "instant" })
|
|
1678
|
-
})
|
|
2844
|
+
let direction = keys[event.key]
|
|
2845
|
+
if (!direction || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return
|
|
2846
|
+
if (event.key === " " && event.shiftKey) direction = -1
|
|
2847
|
+
if (document.querySelector("dialog[open]") || !pageOwnsKey(event, event.key === " ")) return
|
|
2848
|
+
event.preventDefault()
|
|
2849
|
+
const from = scrollY
|
|
2850
|
+
const to = direction > 0 ? pageDownTo() : pageUpTo()
|
|
2851
|
+
if (Math.abs(to - from) < 1) return
|
|
2852
|
+
const smooth = !matchMedia("(prefers-reduced-motion: reduce)").matches
|
|
2853
|
+
scrollTo({ top: from, behavior: "instant" })
|
|
2854
|
+
scrollTo({ top: to, behavior: smooth ? "smooth" : "instant" })
|
|
2855
|
+
})
|
|
2856
|
+
|
|
2857
|
+
/**
|
|
2858
|
+
* Where Page Down goes: the old viewport bottom just below the titles stuck THERE (settles in a few tries).
|
|
2859
|
+
* - the furthest try that leaves the old bottom uncovered: where the old bottom IS a title, the two positions
|
|
2860
|
+
* either side of its sticking alternate, and the nearer one shows it below the stack instead of stuck on it
|
|
2861
|
+
*/
|
|
1679
2862
|
function pageDownTo() {
|
|
1680
|
-
const bottom = scrollY + innerHeight
|
|
1681
|
-
const max = document.documentElement.scrollHeight - innerHeight
|
|
1682
|
-
let top = scrollY
|
|
1683
|
-
let best = top
|
|
2863
|
+
const bottom = scrollY + innerHeight
|
|
2864
|
+
const max = document.documentElement.scrollHeight - innerHeight
|
|
2865
|
+
let top = scrollY
|
|
2866
|
+
let best = top
|
|
1684
2867
|
for (let tries = 0; tries < 4; tries++) {
|
|
1685
|
-
const next = clamp(bottom - stuckBottom(main), 0, max)
|
|
1686
|
-
if (Math.abs(next - top) < 1) break
|
|
1687
|
-
top = next
|
|
1688
|
-
scrollTo({ top, behavior: "instant" })
|
|
1689
|
-
if (bottom - top >= stuckBottom(main) - 1) best = Math.max(best, top)
|
|
2868
|
+
const next = clamp(bottom - stuckBottom(main), 0, max)
|
|
2869
|
+
if (Math.abs(next - top) < 1) break
|
|
2870
|
+
top = next
|
|
2871
|
+
scrollTo({ top, behavior: "instant" })
|
|
2872
|
+
if (bottom - top >= stuckBottom(main) - 1) best = Math.max(best, top)
|
|
1690
2873
|
}
|
|
1691
|
-
return best
|
|
2874
|
+
return best
|
|
1692
2875
|
}
|
|
1693
|
-
|
|
2876
|
+
|
|
2877
|
+
/** Where Page Up goes: the first line below the stuck titles to the viewport bottom. */
|
|
1694
2878
|
function pageUpTo() {
|
|
1695
|
-
return Math.max(0, scrollY + stuckBottom(main) - innerHeight)
|
|
2879
|
+
return Math.max(0, scrollY + stuckBottom(main) - innerHeight)
|
|
1696
2880
|
}
|
|
1697
|
-
__name(pageUpTo, "pageUpTo");
|
|
1698
2881
|
}
|
|
1699
|
-
|
|
2882
|
+
|
|
2883
|
+
/**
|
|
2884
|
+
* Whether a paging key belongs to the page: not to a field or a box that scrolls on its own;
|
|
2885
|
+
* Space not to a control either (it presses a button, follows a link).
|
|
2886
|
+
*/
|
|
1700
2887
|
function pageOwnsKey(event, space) {
|
|
1701
2888
|
for (const node of event.composedPath()) {
|
|
1702
|
-
if (!(node instanceof Element) || node === document.body || node === document.documentElement) continue
|
|
1703
|
-
if (node.isContentEditable || node.matches(FIELDS) || space && node.matches(CONTROLS)) return false
|
|
1704
|
-
const overflow = getComputedStyle(node).overflowY
|
|
1705
|
-
if ((overflow === "auto" || overflow === "scroll") && node.scrollHeight > node.clientHeight) return false
|
|
2889
|
+
if (!(node instanceof Element) || node === document.body || node === document.documentElement) continue
|
|
2890
|
+
if (node.isContentEditable || node.matches(FIELDS) || (space && node.matches(CONTROLS))) return false
|
|
2891
|
+
const overflow = getComputedStyle(node).overflowY
|
|
2892
|
+
if ((overflow === "auto" || overflow === "scroll") && node.scrollHeight > node.clientHeight) return false
|
|
1706
2893
|
}
|
|
1707
|
-
return true
|
|
2894
|
+
return true
|
|
1708
2895
|
}
|
|
1709
|
-
|
|
1710
|
-
|
|
2896
|
+
|
|
2897
|
+
/** What Space presses. */
|
|
2898
|
+
const CONTROLS = "a[href], button, summary, [tabindex], ui-button, ui-checkbox, ui-title, ui-item"
|
|
2899
|
+
|
|
2900
|
+
/**
|
|
2901
|
+
* The bottom of the lowest box stuck at the top now, from the viewport top: the site header, the page header, the
|
|
2902
|
+
* filter bar, every stuck (or being pushed out) section title or sticky heading in `main`.
|
|
2903
|
+
* - a sticky box is stuck when it sits at (or above: pushed out by its section's end) its computed `top`
|
|
2904
|
+
*/
|
|
1711
2905
|
function stuckBottom(main) {
|
|
1712
|
-
let bottom = siteHeaderHeight()
|
|
1713
|
-
const boxes = Array.from(main.querySelectorAll(".spell-filter"))
|
|
2906
|
+
let bottom = siteHeaderHeight()
|
|
2907
|
+
const boxes = Array.from(main.querySelectorAll(".spell-filter"))
|
|
2908
|
+
// a `<ui-sticky>` host is `display: contents`: the box that sticks is its shadow `sticky` part
|
|
1714
2909
|
for (const sticky of main.querySelectorAll("ui-sticky"))
|
|
1715
|
-
boxes.push(sticky.shadowRoot?.querySelector('[part~="sticky"]'))
|
|
1716
|
-
for (const section of main.querySelectorAll(`ui-section[sticky], ${EPIC_FOLDS}`)) boxes.push(titleOf(section))
|
|
2910
|
+
boxes.push(sticky.shadowRoot?.querySelector('[part~="sticky"]'))
|
|
2911
|
+
for (const section of main.querySelectorAll(`ui-section[sticky], ${EPIC_FOLDS}`)) boxes.push(titleOf(section))
|
|
2912
|
+
// an epic page's page header and its toolbar's bar under it (the title between them scrolls away);
|
|
2913
|
+
// an OPEN item's line sticks below the titles (a closed one's isn't sticky: skipped)
|
|
1717
2914
|
for (const page of main.querySelectorAll("epic-page"))
|
|
1718
|
-
boxes.push(...page.shadowRoot?.querySelectorAll('[part~="header"], [part~="bar"]') ?? [])
|
|
1719
|
-
for (const item of main.querySelectorAll("epic-item")) boxes.push(item.shadowRoot?.querySelector('[part~="line"]'))
|
|
2915
|
+
boxes.push(...(page.shadowRoot?.querySelectorAll('[part~="header"], [part~="bar"]') ?? []))
|
|
2916
|
+
for (const item of main.querySelectorAll("epic-item")) boxes.push(item.shadowRoot?.querySelector('[part~="line"]'))
|
|
1720
2917
|
for (const box of boxes) {
|
|
1721
|
-
if (!box) continue
|
|
1722
|
-
const style = getComputedStyle(box)
|
|
1723
|
-
const line = parseFloat(style.top)
|
|
1724
|
-
if (style.position !== "sticky" || Number.isNaN(line)) continue
|
|
1725
|
-
const rect = box.getBoundingClientRect()
|
|
1726
|
-
if (rect.height && rect.top <= line + 1 && rect.bottom > bottom) bottom = rect.bottom
|
|
2918
|
+
if (!box) continue
|
|
2919
|
+
const style = getComputedStyle(box)
|
|
2920
|
+
const line = parseFloat(style.top)
|
|
2921
|
+
if (style.position !== "sticky" || Number.isNaN(line)) continue
|
|
2922
|
+
const rect = box.getBoundingClientRect()
|
|
2923
|
+
if (rect.height && rect.top <= line + 1 && rect.bottom > bottom) bottom = rect.bottom
|
|
1727
2924
|
}
|
|
1728
|
-
return bottom
|
|
2925
|
+
return bottom
|
|
1729
2926
|
}
|
|
1730
|
-
|
|
2927
|
+
|
|
2928
|
+
/** The URL's `#hash` as an id, or ""; an old phase address as the phase's id (`addressedId()`). */
|
|
1731
2929
|
function hashId() {
|
|
1732
|
-
return addressedId(TocIndex.decode(location.hash.slice(1)))
|
|
2930
|
+
return addressedId(TocIndex.decode(location.hash.slice(1)))
|
|
1733
2931
|
}
|
|
1734
|
-
|
|
2932
|
+
|
|
2933
|
+
/**
|
|
2934
|
+
* The id an address names on this page: `id`, unless it's an OLD phase id (`p7`, from before stable phase ids, epic
|
|
2935
|
+
* `epic-workflow` P15) that no element has: then the 7th phase's id (`p-epic-migrate`), so old links and bookmarks
|
|
2936
|
+
* still land. As `spell-epic` `PhaseIds.landing()`.
|
|
2937
|
+
*/
|
|
1735
2938
|
function addressedId(id) {
|
|
1736
|
-
if (document.getElementById(id)) return id
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
2939
|
+
if (document.getElementById(id)) return id
|
|
2940
|
+
// ids in any case (`#T1` ~== `#t1`, epic `epic-workflow` J32): the page's own spelling when it has no other
|
|
2941
|
+
const n = /^p(\d+)$/i.exec(id)?.[1]
|
|
2942
|
+
if (!n) return id.toLowerCase()
|
|
2943
|
+
return (
|
|
2944
|
+
document.querySelectorAll('epic-page > epic-section[kind="phases"] > epic-phase')[Number(n) - 1]?.id ??
|
|
2945
|
+
id.toLowerCase()
|
|
2946
|
+
)
|
|
1740
2947
|
}
|
|
1741
|
-
|
|
2948
|
+
|
|
2949
|
+
////////////////
|
|
2950
|
+
// ## Scroll-follow
|
|
2951
|
+
////////////////
|
|
2952
|
+
|
|
2953
|
+
/**
|
|
2954
|
+
* Mark the toolbar's entry of the section being read, and let the address follow it.
|
|
2955
|
+
* - "Current": the last entry (section, heading) whose top has reached its landing line (the site header and its
|
|
2956
|
+
* `scroll-margin-top`, plus a little); entries hidden by the filter or inside a folded section don't count
|
|
2957
|
+
* - the toolbar's entry of the current entry's top-level section is `selected`
|
|
2958
|
+
* - the ADDRESS follows too, once `followAddress()` has been called (`land()`, after the page has landed):
|
|
2959
|
+
* the current entry's `#id` replaces the URL's hash (`history.replaceState()`: no history entry, no jump);
|
|
2960
|
+
* not while a followed link is pinned (its click set the hash), and no hash above the first entry;
|
|
2961
|
+
* - so a reload, or VS Code restarting the view, lands on the section being read
|
|
2962
|
+
* - `replaceState()` fires no `hashchange`: `spell-doc:scrolled-to` on `window` tells the live client, which tells
|
|
2963
|
+
* VS Code's view (`liveClient.ts` `reportPlace()`)
|
|
2964
|
+
* - returns `{ update, pin, followAddress, rescan }`:
|
|
2965
|
+
* - `pin(entry)` makes it current until the page scrolls again (a link was followed)
|
|
2966
|
+
* - `rescan(rail)` reads the entries and the toolbar again: the page was updated in place (`rewire()`)
|
|
2967
|
+
*/
|
|
1742
2968
|
function followScroll(main, outline, rail) {
|
|
1743
|
-
let headings = []
|
|
1744
|
-
let railItems = []
|
|
1745
|
-
let active = null
|
|
1746
|
-
let scheduled = false
|
|
1747
|
-
let pinned = null
|
|
1748
|
-
let addressing = false
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
addEventListener("
|
|
1752
|
-
|
|
2969
|
+
let headings = []
|
|
2970
|
+
let railItems = []
|
|
2971
|
+
let active = null
|
|
2972
|
+
let scheduled = false
|
|
2973
|
+
let pinned = null
|
|
2974
|
+
let addressing = false
|
|
2975
|
+
|
|
2976
|
+
rescan(rail)
|
|
2977
|
+
addEventListener("scroll", schedule, { passive: true })
|
|
2978
|
+
addEventListener("resize", schedule, { passive: true })
|
|
2979
|
+
return { update, pin, followAddress, rescan }
|
|
2980
|
+
|
|
2981
|
+
/** Read the entries and the toolbar's items; a rebuilt toolbar gets its mark again on the next update. */
|
|
1753
2982
|
function rescan(nextRail) {
|
|
1754
|
-
headings = Array.from(main.querySelectorAll(outline.targets))
|
|
1755
|
-
const items = Array.from(nextRail?.querySelectorAll("[data-rail]") ?? [])
|
|
1756
|
-
if (items[0] !== railItems[0]) active = null
|
|
1757
|
-
railItems = items
|
|
2983
|
+
headings = Array.from(main.querySelectorAll(outline.targets))
|
|
2984
|
+
const items = Array.from(nextRail?.querySelectorAll("[data-rail]") ?? [])
|
|
2985
|
+
if (items[0] !== railItems[0]) active = null
|
|
2986
|
+
railItems = items
|
|
1758
2987
|
}
|
|
1759
|
-
|
|
2988
|
+
|
|
2989
|
+
/** From now on, the address follows the current entry. */
|
|
1760
2990
|
function followAddress() {
|
|
1761
|
-
addressing = true
|
|
1762
|
-
update()
|
|
2991
|
+
addressing = true
|
|
2992
|
+
update()
|
|
1763
2993
|
}
|
|
1764
|
-
|
|
2994
|
+
|
|
2995
|
+
/** At most one update per frame. */
|
|
1765
2996
|
function schedule() {
|
|
1766
|
-
if (scheduled) return
|
|
1767
|
-
scheduled = true
|
|
2997
|
+
if (scheduled) return
|
|
2998
|
+
scheduled = true
|
|
1768
2999
|
requestAnimationFrame(() => {
|
|
1769
|
-
scheduled = false
|
|
1770
|
-
update()
|
|
1771
|
-
})
|
|
3000
|
+
scheduled = false
|
|
3001
|
+
update()
|
|
3002
|
+
})
|
|
1772
3003
|
}
|
|
1773
|
-
|
|
3004
|
+
|
|
3005
|
+
/** Find the current heading and mark it; a pinned one stays while the page hasn't scrolled. */
|
|
1774
3006
|
function update() {
|
|
1775
|
-
if (pinned && Math.abs(scrollY - pinned.scrollY) < 2) return setActive(pinned.heading)
|
|
1776
|
-
pinned = null
|
|
3007
|
+
if (pinned && Math.abs(scrollY - pinned.scrollY) < 2) return setActive(pinned.heading)
|
|
3008
|
+
pinned = null
|
|
3009
|
+
// Spell UI's rule for the section being read (`TocIndex.reached()`), each heading's line its landing line:
|
|
3010
|
+
// a heading without a box is hidden by the filter; one replaced by an in-place update waits for `rescan()`;
|
|
3011
|
+
// one laid out in a folded box isn't shown
|
|
1777
3012
|
const reached = TocIndex.reached(
|
|
1778
3013
|
headings,
|
|
1779
3014
|
(heading) => landingLine(heading) + 4,
|
|
1780
3015
|
(heading) => heading.isConnected && !outline.folded(heading)
|
|
1781
|
-
)
|
|
1782
|
-
setActive(reached ?? headings[0])
|
|
1783
|
-
writeAddress(reached?.id ?? "")
|
|
3016
|
+
)
|
|
3017
|
+
setActive(reached ?? headings[0])
|
|
3018
|
+
writeAddress(reached?.id ?? "")
|
|
1784
3019
|
}
|
|
1785
|
-
|
|
3020
|
+
|
|
3021
|
+
/**
|
|
3022
|
+
* Put `#id` in the address ("": no hash) without a history entry or a jump, and say so (`spell-doc:scrolled-to`).
|
|
3023
|
+
* - only once `followAddress()` was called, and only when it changes
|
|
3024
|
+
*/
|
|
1786
3025
|
function writeAddress(id) {
|
|
1787
|
-
if (!addressing || hashId() === id) return
|
|
1788
|
-
history.replaceState(history.state, "", `${location.pathname}${location.search}${id ? `#${id}` : ""}`)
|
|
1789
|
-
dispatchEvent(new Event("spell-doc:scrolled-to"))
|
|
3026
|
+
if (!addressing || hashId() === id) return
|
|
3027
|
+
history.replaceState(history.state, "", `${location.pathname}${location.search}${id ? `#${id}` : ""}`)
|
|
3028
|
+
dispatchEvent(new Event("spell-doc:scrolled-to"))
|
|
1790
3029
|
}
|
|
1791
|
-
|
|
3030
|
+
|
|
3031
|
+
/** Mark the toolbar's entry of `heading`'s top-level section. */
|
|
1792
3032
|
function setActive(heading) {
|
|
1793
|
-
if (!heading || heading === active) return
|
|
1794
|
-
active = heading
|
|
1795
|
-
const group = outline.groupOf(heading)
|
|
1796
|
-
for (const item of railItems) item.toggleAttribute("selected", item.dataset.rail === group?.id)
|
|
3033
|
+
if (!heading || heading === active) return
|
|
3034
|
+
active = heading
|
|
3035
|
+
const group = outline.groupOf(heading)
|
|
3036
|
+
for (const item of railItems) item.toggleAttribute("selected", item.dataset.rail === group?.id)
|
|
1797
3037
|
}
|
|
1798
|
-
|
|
3038
|
+
|
|
3039
|
+
/** `heading` is current, wherever it is, until the page scrolls from here. */
|
|
1799
3040
|
function pin(heading) {
|
|
1800
|
-
pinned = { heading, scrollY }
|
|
1801
|
-
setActive(heading)
|
|
3041
|
+
pinned = { heading, scrollY }
|
|
3042
|
+
setActive(heading)
|
|
1802
3043
|
}
|
|
1803
|
-
__name(pin, "pin");
|
|
1804
3044
|
}
|
|
1805
|
-
|
|
3045
|
+
|
|
3046
|
+
////////////////
|
|
3047
|
+
// ## Panels
|
|
3048
|
+
////////////////
|
|
3049
|
+
|
|
3050
|
+
/** Is `title`'s panel open? */
|
|
1806
3051
|
function isPanelOpen(title) {
|
|
1807
|
-
return openIndexes(title.parentElement).includes(titlesOf(title.parentElement).indexOf(title))
|
|
3052
|
+
return openIndexes(title.parentElement).includes(titlesOf(title.parentElement).indexOf(title))
|
|
1808
3053
|
}
|
|
1809
|
-
|
|
3054
|
+
|
|
3055
|
+
/** Open or close `title`'s panel, keeping the accordion's other panels as they are. */
|
|
1810
3056
|
function setPanel(title, open) {
|
|
1811
|
-
const accordion = title.parentElement
|
|
1812
|
-
const index = titlesOf(accordion).indexOf(title)
|
|
1813
|
-
const indexes = new Set(openIndexes(accordion))
|
|
1814
|
-
if (open) indexes.add(index)
|
|
1815
|
-
else indexes.delete(index)
|
|
1816
|
-
accordion.open = [...indexes].sort((a, b) => a - b).join(" ")
|
|
1817
|
-
}
|
|
1818
|
-
|
|
3057
|
+
const accordion = title.parentElement
|
|
3058
|
+
const index = titlesOf(accordion).indexOf(title)
|
|
3059
|
+
const indexes = new Set(openIndexes(accordion))
|
|
3060
|
+
if (open) indexes.add(index)
|
|
3061
|
+
else indexes.delete(index)
|
|
3062
|
+
accordion.open = [...indexes].sort((a, b) => a - b).join(" ")
|
|
3063
|
+
}
|
|
3064
|
+
|
|
3065
|
+
/** An accordion's open panel indexes, from its `open` property (or attribute, before it upgraded). */
|
|
1819
3066
|
function openIndexes(accordion) {
|
|
1820
|
-
const text = accordion.open ?? accordion.getAttribute("open") ?? ""
|
|
1821
|
-
return String(text)
|
|
3067
|
+
const text = accordion.open ?? accordion.getAttribute("open") ?? ""
|
|
3068
|
+
return String(text)
|
|
3069
|
+
.split(/[\s,]+/)
|
|
3070
|
+
.filter((word) => /^\d+$/.test(word))
|
|
3071
|
+
.map(Number)
|
|
1822
3072
|
}
|
|
1823
|
-
|
|
3073
|
+
|
|
3074
|
+
/** The `<ui-title>` children of `accordion`: one per panel, in order. */
|
|
1824
3075
|
function titlesOf(accordion) {
|
|
1825
|
-
return Array.from(accordion.children).filter((child) => child.localName === "ui-title")
|
|
3076
|
+
return Array.from(accordion.children).filter((child) => child.localName === "ui-title")
|
|
1826
3077
|
}
|
|
1827
|
-
|
|
3078
|
+
|
|
3079
|
+
////////////////
|
|
3080
|
+
// ## CHEATSHEET filter
|
|
3081
|
+
////////////////
|
|
3082
|
+
|
|
3083
|
+
/**
|
|
3084
|
+
* `ui-input[data-spell-filter]` shows only the cards holding every typed word, and `ui-select[data-spell-filter-badge]`
|
|
3085
|
+
* only those with a `ui-label` badge of the chosen text ("" = any); sections without a visible card hide too, and
|
|
3086
|
+
* so do their toolbar buttons.
|
|
3087
|
+
* - reads values from the events' `detail`: during `ui-typed` / `ui-changed` the element's `value` is still the old one
|
|
3088
|
+
* - SIDE EFFECT: remembers the typed filter (not the badge) in `localStorage` (when the browser allows it), per
|
|
3089
|
+
* page: under the input's `data-spell-filter` value, or `FILTER_KEY_PREFIX` + the page's path
|
|
3090
|
+
*/
|
|
1828
3091
|
function wireFilter(main) {
|
|
1829
|
-
const input = document.querySelector("ui-input[data-spell-filter]")
|
|
1830
|
-
const badge = document.querySelector("ui-select[data-spell-filter-badge]")
|
|
1831
|
-
if (!input && !badge) return
|
|
1832
|
-
const named = input?.dataset.spellFilter
|
|
1833
|
-
const key = `${FILTER_KEY_PREFIX}${named || location.pathname}
|
|
1834
|
-
|
|
1835
|
-
|
|
1836
|
-
const
|
|
1837
|
-
|
|
1838
|
-
)
|
|
1839
|
-
|
|
1840
|
-
|
|
1841
|
-
|
|
1842
|
-
|
|
1843
|
-
|
|
1844
|
-
|
|
3092
|
+
const input = document.querySelector("ui-input[data-spell-filter]")
|
|
3093
|
+
const badge = document.querySelector("ui-select[data-spell-filter-badge]")
|
|
3094
|
+
if (!input && !badge) return
|
|
3095
|
+
const named = input?.dataset.spellFilter
|
|
3096
|
+
const key = `${FILTER_KEY_PREFIX}${named || location.pathname}`
|
|
3097
|
+
// TODO: drop the move once every browser has opened the page since epic `prefs-and-undo` P4
|
|
3098
|
+
if (named) PrefStore.moveOldKey(named, key)
|
|
3099
|
+
const cards = Array.from(main.querySelectorAll("ui-card"))
|
|
3100
|
+
// HEADINGS' `section`s, or `<ui-section>`s (`:host([hidden])` hides one)
|
|
3101
|
+
const sections = Array.from(main.querySelectorAll("section, ui-section")).filter((section) =>
|
|
3102
|
+
section.querySelector("ui-card")
|
|
3103
|
+
)
|
|
3104
|
+
const empty = document.getElementById("empty")
|
|
3105
|
+
let typed = input ? readSaved(key) : ""
|
|
3106
|
+
let chosen = String(badge?.value ?? "")
|
|
3107
|
+
/** Folded sections the filter unfolded, to fold back when it's cleared. */
|
|
3108
|
+
const filterOpened = new Set()
|
|
3109
|
+
input?.addEventListener("ui-typed", onType)
|
|
3110
|
+
input?.addEventListener("ui-changed", onType)
|
|
1845
3111
|
badge?.addEventListener("ui-changed", (event) => {
|
|
1846
|
-
chosen = String(event.detail?.value ?? badge.value ?? "")
|
|
1847
|
-
apply()
|
|
1848
|
-
})
|
|
1849
|
-
if (typed) input.value = typed
|
|
1850
|
-
if (typed || chosen) apply()
|
|
3112
|
+
chosen = String(event.detail?.value ?? badge.value ?? "")
|
|
3113
|
+
apply()
|
|
3114
|
+
})
|
|
3115
|
+
if (typed) input.value = typed
|
|
3116
|
+
if (typed || chosen) apply()
|
|
3117
|
+
|
|
3118
|
+
/** The typed filter changed: apply and save it. */
|
|
1851
3119
|
function onType(event) {
|
|
1852
|
-
typed = String(event.detail?.value ?? input.value ?? "")
|
|
1853
|
-
apply()
|
|
1854
|
-
PrefStore.setAt(key, typed)
|
|
3120
|
+
typed = String(event.detail?.value ?? input.value ?? "")
|
|
3121
|
+
apply()
|
|
3122
|
+
PrefStore.setAt(key, typed)
|
|
1855
3123
|
}
|
|
1856
|
-
|
|
3124
|
+
|
|
3125
|
+
/**
|
|
3126
|
+
* Hide what doesn't match.
|
|
3127
|
+
* - while a filter is set, a folded section holding a match unfolds
|
|
3128
|
+
* (not saved: sections start folded, so matches would hide in them);
|
|
3129
|
+
* clearing the filter folds back the ones it opened
|
|
3130
|
+
*/
|
|
1857
3131
|
function apply() {
|
|
1858
|
-
const words = typed.toLowerCase().split(/\s+/).filter(Boolean)
|
|
1859
|
-
const wanted = chosen.trim().toLowerCase()
|
|
1860
|
-
let shown = 0
|
|
3132
|
+
const words = typed.toLowerCase().split(/\s+/).filter(Boolean)
|
|
3133
|
+
const wanted = chosen.trim().toLowerCase()
|
|
3134
|
+
let shown = 0
|
|
1861
3135
|
for (const card of cards) {
|
|
1862
|
-
const content = card.textContent.toLowerCase()
|
|
1863
|
-
const badges = Array.from(card.querySelectorAll("ui-label"), (label) => label.textContent.trim().toLowerCase())
|
|
1864
|
-
card.hidden = !words.every((word) => content.includes(word)) || !!wanted && !badges.includes(wanted)
|
|
1865
|
-
if (!card.hidden) shown
|
|
3136
|
+
const content = card.textContent.toLowerCase()
|
|
3137
|
+
const badges = Array.from(card.querySelectorAll("ui-label"), (label) => label.textContent.trim().toLowerCase())
|
|
3138
|
+
card.hidden = !words.every((word) => content.includes(word)) || (!!wanted && !badges.includes(wanted))
|
|
3139
|
+
if (!card.hidden) shown++
|
|
1866
3140
|
}
|
|
1867
|
-
const filtering = words.length > 0 || !!wanted
|
|
3141
|
+
const filtering = words.length > 0 || !!wanted
|
|
1868
3142
|
for (const section of sections) {
|
|
1869
|
-
section.hidden = !section.querySelector("ui-card:not([hidden])")
|
|
1870
|
-
if (section.localName !== "ui-section") continue
|
|
3143
|
+
section.hidden = !section.querySelector("ui-card:not([hidden])")
|
|
3144
|
+
if (section.localName !== "ui-section") continue
|
|
1871
3145
|
if (filtering && !section.hidden && isCollapsed(section)) {
|
|
1872
|
-
setCollapsed(section, false)
|
|
1873
|
-
filterOpened.add(section)
|
|
3146
|
+
setCollapsed(section, false)
|
|
3147
|
+
filterOpened.add(section)
|
|
1874
3148
|
} else if (!filtering && filterOpened.has(section)) {
|
|
1875
|
-
setCollapsed(section, true)
|
|
1876
|
-
filterOpened.delete(section)
|
|
3149
|
+
setCollapsed(section, true)
|
|
3150
|
+
filterOpened.delete(section)
|
|
1877
3151
|
}
|
|
1878
3152
|
}
|
|
1879
|
-
if (empty) empty.hidden = shown > 0
|
|
3153
|
+
if (empty) empty.hidden = shown > 0
|
|
1880
3154
|
for (const item of document.querySelectorAll("nav.spell-toolbar [data-rail]")) {
|
|
1881
|
-
item.hidden = !!document.getElementById(item.dataset.rail)?.closest("[hidden]")
|
|
3155
|
+
item.hidden = !!document.getElementById(item.dataset.rail)?.closest("[hidden]")
|
|
1882
3156
|
}
|
|
1883
3157
|
}
|
|
1884
|
-
__name(apply, "apply");
|
|
1885
3158
|
}
|
|
1886
|
-
|
|
3159
|
+
|
|
3160
|
+
/** The filter saved under `key`, or "": none, or storage blocked. */
|
|
1887
3161
|
function readSaved(key) {
|
|
1888
|
-
const saved = PrefStore.getAt(key)
|
|
1889
|
-
if (typeof saved === "string") return saved
|
|
1890
|
-
|
|
3162
|
+
const saved = PrefStore.getAt(key)
|
|
3163
|
+
if (typeof saved === "string") return saved
|
|
3164
|
+
// typed before P4 of epic `prefs-and-undo` as plain digits (`123`), it reads back as a number
|
|
3165
|
+
return typeof saved === "number" ? `${saved}` : ""
|
|
1891
3166
|
}
|
|
1892
|
-
|
|
3167
|
+
|
|
3168
|
+
////////////////
|
|
3169
|
+
// ## Page notes
|
|
3170
|
+
////////////////
|
|
3171
|
+
|
|
3172
|
+
/**
|
|
3173
|
+
* PAGE NOTES (epic `airplane`, P3): notes written INTO a page, `<spell-notes>` / `<spell-note>`.
|
|
3174
|
+
* - the markup and its rules: `src/tools/PageNotes.js`
|
|
3175
|
+
* - each drawn as a folded card (`drawNoteCards()`),
|
|
3176
|
+
* its head line an `<epic-page-note-head>` (the epics pack; epic `epic-engine` P3)
|
|
3177
|
+
* - READ ONLY since P11: comments (below) replaced the bubbles and the Note pill that wrote them;
|
|
3178
|
+
* the notes already written still show, and `epic notes` still answers them
|
|
3179
|
+
* - every page, `file://` too; drawn again on `spell-doc:updated` (an answer changes the page)
|
|
3180
|
+
*/
|
|
1893
3181
|
function wireNotes(main) {
|
|
1894
|
-
drawNoteCards(main)
|
|
1895
|
-
addEventListener("spell-doc:updated", () => drawNoteCards(main))
|
|
3182
|
+
drawNoteCards(main)
|
|
3183
|
+
addEventListener("spell-doc:updated", () => drawNoteCards(main))
|
|
1896
3184
|
}
|
|
1897
|
-
|
|
3185
|
+
|
|
3186
|
+
/**
|
|
3187
|
+
* Give each `<spell-note>` its head line, again after every update (the status or replies may have changed):
|
|
3188
|
+
* an `<epic-page-note-head>`, "Note · 10/10 14:02", the first line of the note while folded, its status, how many
|
|
3189
|
+
* replies.
|
|
3190
|
+
* - a click on it folds and unfolds the card (the note's `open`, which a live patch keeps)
|
|
3191
|
+
*/
|
|
1898
3192
|
function drawNoteCards(main) {
|
|
1899
3193
|
for (const note of main.querySelectorAll("spell-note")) {
|
|
1900
|
-
note.querySelector(":scope > epic-page-note-head")?.remove()
|
|
3194
|
+
note.querySelector(":scope > epic-page-note-head")?.remove()
|
|
1901
3195
|
const head = el("epic-page-note-head", {
|
|
1902
3196
|
"data-spell-added": true,
|
|
1903
|
-
at: note.getAttribute("at") ??
|
|
3197
|
+
at: note.getAttribute("at") ?? undefined,
|
|
1904
3198
|
status: note.getAttribute("status") || "new",
|
|
1905
3199
|
replies: note.querySelectorAll(":scope > spell-note-reply").length,
|
|
1906
3200
|
preview: noteText(note).split("\n")[0],
|
|
1907
3201
|
open: note.hasAttribute("open")
|
|
1908
|
-
})
|
|
3202
|
+
})
|
|
1909
3203
|
for (const type of ["epic-note-opened", "epic-note-closed"])
|
|
1910
|
-
head.addEventListener(type, (event) => note.toggleAttribute("open", !!event.detail?.open))
|
|
1911
|
-
note.prepend(head)
|
|
3204
|
+
head.addEventListener(type, (event) => note.toggleAttribute("open", !!event.detail?.open))
|
|
3205
|
+
note.prepend(head)
|
|
1912
3206
|
}
|
|
1913
3207
|
}
|
|
1914
|
-
|
|
3208
|
+
|
|
3209
|
+
////////////////
|
|
3210
|
+
// ## Screenshots full size
|
|
3211
|
+
////////////////
|
|
3212
|
+
|
|
3213
|
+
/**
|
|
3214
|
+
* SCREENSHOTS open full size (epic `epic-engine` I129; Owen, 2026-10-25: "Can't click on images in the page to
|
|
3215
|
+
* expand so I can't tell"): ONE pair of listeners for the whole page, `ImageZoom`'s.
|
|
3216
|
+
* - a click on a zoomable image shows it in `<ui-zoom>`, its link never followed (a `target="_blank"` one too)
|
|
3217
|
+
* - the pointer over one marks it `data-ui-zoom`, the zoom-in cursor (`spell-doc.css`); a patch keeps the mark
|
|
3218
|
+
* (`KEPT_ATTRIBUTES`)
|
|
3219
|
+
* - a request's thumbnail takes its own click first (`<epic-field>`): this one sees it prevented, and leaves it
|
|
3220
|
+
*/
|
|
1915
3221
|
function wireImageZoom() {
|
|
1916
|
-
document.addEventListener("click", ImageZoom.onClick)
|
|
1917
|
-
document.addEventListener("pointerover", ImageZoom.onPointerOver, { passive: true })
|
|
3222
|
+
document.addEventListener("click", ImageZoom.onClick)
|
|
3223
|
+
document.addEventListener("pointerover", ImageZoom.onPointerOver, { passive: true })
|
|
1918
3224
|
}
|
|
1919
|
-
|
|
3225
|
+
|
|
3226
|
+
////////////////
|
|
3227
|
+
// ## The Epics page's sort
|
|
3228
|
+
////////////////
|
|
3229
|
+
|
|
3230
|
+
/**
|
|
3231
|
+
* The Epics page's SORT buttons: an `<epic-sort>` (the epics pack, epic `epic-engine` P3) in the page header,
|
|
3232
|
+
* beside the New epic pill.
|
|
3233
|
+
* - Owen, 2026-10-13: "Add buttons to epics header to sort by date or alphabetical, within the sessions"
|
|
3234
|
+
* - only where the page has an `<epic-list>`, which follows it
|
|
3235
|
+
* - the elements do the rest: the buttons, remembering, the sorting, the groups, the saga chips, the stars
|
|
3236
|
+
* - callable again (a page updated in place): one at most
|
|
3237
|
+
* - SIDE EFFECT: adds it to the header, marked `data-spell-added` so the live patch steps around it
|
|
3238
|
+
*/
|
|
1920
3239
|
function wireEpicSort(main) {
|
|
1921
|
-
const head = main.querySelector(".spell-page-head")
|
|
1922
|
-
if (!head || !main.querySelector("epic-list") || head.querySelector("epic-sort")) return
|
|
1923
|
-
addHeadTool(head, el("epic-sort", { "data-spell-added": true }), "page")
|
|
1924
|
-
}
|
|
1925
|
-
|
|
1926
|
-
|
|
1927
|
-
|
|
1928
|
-
|
|
3240
|
+
const head = main.querySelector(".spell-page-head")
|
|
3241
|
+
if (!head || !main.querySelector("epic-list") || head.querySelector("epic-sort")) return
|
|
3242
|
+
addHeadTool(head, el("epic-sort", { "data-spell-added": true }), "page")
|
|
3243
|
+
}
|
|
3244
|
+
|
|
3245
|
+
////////////////
|
|
3246
|
+
// ## New epic
|
|
3247
|
+
////////////////
|
|
3248
|
+
|
|
3249
|
+
/** The page server's New epic route (`src/tool/epicRoutes.ts`). */
|
|
3250
|
+
const NEW_EPIC_API = "/api/epics/new"
|
|
3251
|
+
|
|
3252
|
+
/** `localStorage` key of the New epic box's unsaved text (`{ title, prompt }`), one for every Epics page. */
|
|
3253
|
+
const NEW_EPIC_DRAFT_KEY = "spell-epics:new-epic-draft"
|
|
3254
|
+
|
|
3255
|
+
/** Its key before epic `prefs-and-undo` P4, with no store: moved to `NEW_EPIC_DRAFT_KEY` once. */
|
|
3256
|
+
const OLD_NEW_EPIC_DRAFT_KEY = "spell-new-epic-draft"
|
|
3257
|
+
|
|
3258
|
+
/**
|
|
3259
|
+
* NEW EPIC (epic `airplane` P7): on the Epics page (`epics/index.html`), a New epic pill in the page header.
|
|
3260
|
+
* - its box: a title and the kickoff prompt (a textarea that grows with its text); ⌘ / Ctrl Enter saves
|
|
3261
|
+
* - the page server writes a FUTURE epic at once (`epicRoutes.ts`): no Claude needed, so it works on a plane;
|
|
3262
|
+
* the home page is rewritten, so the new card shows here with its seedling; `/airplane land` offers to start it
|
|
3263
|
+
* - only served by the page server with a token: from `file://`, no pill
|
|
3264
|
+
* - what's typed and not saved is kept (`NEW_EPIC_DRAFT_KEY`) until it's saved
|
|
3265
|
+
*/
|
|
1929
3266
|
function wireNewEpic(main) {
|
|
1930
|
-
if (!/(^|\/)epics\/(index\.html)?$/.test(location.pathname)) return
|
|
1931
|
-
if (!ServerLink.isServed()) return
|
|
1932
|
-
const head = main.querySelector(".spell-page-head")
|
|
1933
|
-
if (!head || head.querySelector(".spell-new-epic")) return
|
|
1934
|
-
|
|
3267
|
+
if (!/(^|\/)epics\/(index\.html)?$/.test(location.pathname)) return
|
|
3268
|
+
if (!ServerLink.isServed()) return
|
|
3269
|
+
const head = main.querySelector(".spell-page-head")
|
|
3270
|
+
if (!head || head.querySelector(".spell-new-epic")) return
|
|
3271
|
+
// the browser's own tooltip, a `title` (Owen, 2026-10-10: never a `<ui-popup>` as a tooltip)
|
|
3272
|
+
const tip = "Write an idea down as a future epic"
|
|
1935
3273
|
const button = el(
|
|
1936
3274
|
"ui-button",
|
|
1937
3275
|
{ appearance: "circular basic", size: "tiny", icon: "seedling", title: tip },
|
|
1938
3276
|
"New epic"
|
|
1939
|
-
)
|
|
1940
|
-
button.addEventListener("click", openNewEpicBox)
|
|
1941
|
-
titleInside(button)
|
|
1942
|
-
addHeadTool(head, el("span", { class: "spell-new-epic", "data-spell-added": true }, button), "page")
|
|
3277
|
+
)
|
|
3278
|
+
button.addEventListener("click", openNewEpicBox)
|
|
3279
|
+
titleInside(button)
|
|
3280
|
+
addHeadTool(head, el("span", { class: "spell-new-epic", "data-spell-added": true }, button), "page")
|
|
1943
3281
|
}
|
|
1944
|
-
|
|
3282
|
+
|
|
3283
|
+
/** Open the New epic box, with the draft typed so far. */
|
|
1945
3284
|
function openNewEpicBox() {
|
|
1946
|
-
const box = newEpicBox()
|
|
1947
|
-
|
|
1948
|
-
|
|
1949
|
-
const
|
|
1950
|
-
title
|
|
1951
|
-
|
|
1952
|
-
|
|
3285
|
+
const box = newEpicBox()
|
|
3286
|
+
// TODO: drop the move once every browser has opened the Epics page since epic `prefs-and-undo` P4
|
|
3287
|
+
PrefStore.moveOldKey(OLD_NEW_EPIC_DRAFT_KEY, NEW_EPIC_DRAFT_KEY)
|
|
3288
|
+
const draft = readJSON(NEW_EPIC_DRAFT_KEY)
|
|
3289
|
+
const [title, prompt] = box.querySelectorAll("input, textarea")
|
|
3290
|
+
title.value = typeof draft.title === "string" ? draft.title : ""
|
|
3291
|
+
prompt.value = typeof draft.prompt === "string" ? draft.prompt : ""
|
|
3292
|
+
box.visible = true
|
|
1953
3293
|
requestAnimationFrame(() => {
|
|
1954
|
-
growField(prompt)
|
|
1955
|
-
(title.value ? prompt : title).focus()
|
|
1956
|
-
})
|
|
3294
|
+
growField(prompt)
|
|
3295
|
+
;(title.value ? prompt : title).focus()
|
|
3296
|
+
})
|
|
1957
3297
|
}
|
|
1958
|
-
|
|
3298
|
+
|
|
3299
|
+
/** The New epic box, made once (outside `main`: a live patch never sees it). */
|
|
1959
3300
|
function newEpicBox() {
|
|
1960
|
-
let box = document.getElementById("spell-new-epic-box")
|
|
1961
|
-
if (box) return box
|
|
1962
|
-
const template = document.createElement("template")
|
|
3301
|
+
let box = document.getElementById("spell-new-epic-box")
|
|
3302
|
+
if (box) return box
|
|
3303
|
+
const template = document.createElement("template")
|
|
1963
3304
|
template.innerHTML = `<ui-modal id="spell-new-epic-box" class="spell-note-box" size="small" closable>
|
|
1964
3305
|
<ui-header><ui-icon name="seedling"></ui-icon> A new epic</ui-header>
|
|
1965
3306
|
<ui-content>
|
|
@@ -1972,59 +3313,63 @@ function newEpicBox() {
|
|
|
1972
3313
|
<ui-button class="spell-note-cancel" appearance="circular basic">Cancel</ui-button>
|
|
1973
3314
|
<ui-button class="spell-note-save" appearance="circular" color="primary" icon="seedling">Make the epic</ui-button>
|
|
1974
3315
|
</ui-actions>
|
|
1975
|
-
</ui-modal
|
|
1976
|
-
box = template.content.firstElementChild
|
|
1977
|
-
const [title, prompt] = box.querySelectorAll("input, textarea")
|
|
1978
|
-
const save = box.querySelector(".spell-note-save")
|
|
1979
|
-
const close =
|
|
1980
|
-
const keep =
|
|
1981
|
-
const submit =
|
|
1982
|
-
if (!title.value.trim()) return title.focus()
|
|
1983
|
-
save.setAttribute("loading", "")
|
|
3316
|
+
</ui-modal>`
|
|
3317
|
+
box = template.content.firstElementChild
|
|
3318
|
+
const [title, prompt] = box.querySelectorAll("input, textarea")
|
|
3319
|
+
const save = box.querySelector(".spell-note-save")
|
|
3320
|
+
const close = () => (box.visible = false)
|
|
3321
|
+
const keep = () => writeJSON(NEW_EPIC_DRAFT_KEY, { title: title.value, prompt: prompt.value })
|
|
3322
|
+
const submit = async () => {
|
|
3323
|
+
if (!title.value.trim()) return title.focus()
|
|
3324
|
+
save.setAttribute("loading", "")
|
|
1984
3325
|
try {
|
|
1985
3326
|
const { name } = await ServerLink.forPage().post(NEW_EPIC_API, {
|
|
1986
3327
|
title: title.value.trim(),
|
|
1987
3328
|
prompt: prompt.value.trim()
|
|
1988
|
-
})
|
|
1989
|
-
writeJSON(NEW_EPIC_DRAFT_KEY, {})
|
|
1990
|
-
close()
|
|
1991
|
-
noteToast(`Future epic ${name} written down`, "success")
|
|
3329
|
+
})
|
|
3330
|
+
writeJSON(NEW_EPIC_DRAFT_KEY, {})
|
|
3331
|
+
close()
|
|
3332
|
+
noteToast(`Future epic ${name} written down`, "success")
|
|
1992
3333
|
} catch (error) {
|
|
1993
|
-
noteToast(`Couldn't make the epic: ${error.message}`, "error")
|
|
3334
|
+
noteToast(`Couldn't make the epic: ${error.message}`, "error")
|
|
1994
3335
|
} finally {
|
|
1995
|
-
save.removeAttribute("loading")
|
|
3336
|
+
save.removeAttribute("loading")
|
|
1996
3337
|
}
|
|
1997
|
-
}
|
|
1998
|
-
title.addEventListener("input", keep)
|
|
3338
|
+
}
|
|
3339
|
+
title.addEventListener("input", keep)
|
|
1999
3340
|
prompt.addEventListener("input", () => {
|
|
2000
|
-
growField(prompt)
|
|
2001
|
-
keep()
|
|
2002
|
-
})
|
|
3341
|
+
growField(prompt)
|
|
3342
|
+
keep()
|
|
3343
|
+
})
|
|
2003
3344
|
for (const field of [title, prompt])
|
|
2004
3345
|
field.addEventListener("keydown", (event) => {
|
|
2005
|
-
if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) void submit()
|
|
2006
|
-
})
|
|
2007
|
-
save.addEventListener("click", () => void submit())
|
|
2008
|
-
box.querySelector(".spell-note-cancel").addEventListener("click", close)
|
|
2009
|
-
document.body.append(box)
|
|
2010
|
-
return box
|
|
2011
|
-
}
|
|
2012
|
-
|
|
3346
|
+
if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) void submit()
|
|
3347
|
+
})
|
|
3348
|
+
save.addEventListener("click", () => void submit())
|
|
3349
|
+
box.querySelector(".spell-note-cancel").addEventListener("click", close)
|
|
3350
|
+
document.body.append(box)
|
|
3351
|
+
return box
|
|
3352
|
+
}
|
|
3353
|
+
|
|
3354
|
+
/**
|
|
3355
|
+
* A note's text as typed: paragraphs split by blank lines, `<br>` a newline, `<code>` in backticks;
|
|
3356
|
+
* its head and replies left out. `PageNotes.js` `textOf()` is the same, on the server.
|
|
3357
|
+
*/
|
|
2013
3358
|
function noteText(note) {
|
|
2014
|
-
const blocks = []
|
|
3359
|
+
const blocks = []
|
|
2015
3360
|
for (const child of note.childNodes) {
|
|
2016
|
-
if (child.nodeType === Node.ELEMENT_NODE && child.matches("epic-page-note-head, spell-note-reply")) continue
|
|
2017
|
-
const words = child.nodeType === Node.ELEMENT_NODE ? inlineText(child) : child.textContent
|
|
2018
|
-
if (words.trim()) blocks.push(words.trim())
|
|
3361
|
+
if (child.nodeType === Node.ELEMENT_NODE && child.matches("epic-page-note-head, spell-note-reply")) continue
|
|
3362
|
+
const words = child.nodeType === Node.ELEMENT_NODE ? inlineText(child) : child.textContent
|
|
3363
|
+
if (words.trim()) blocks.push(words.trim())
|
|
2019
3364
|
}
|
|
2020
|
-
return blocks.join("\n\n")
|
|
3365
|
+
return blocks.join("\n\n")
|
|
3366
|
+
|
|
3367
|
+
/** `node`'s text: `<br>` a newline, `<code>` in backticks, white space as one space. */
|
|
2021
3368
|
function inlineText(node) {
|
|
2022
|
-
if (node.nodeType === Node.TEXT_NODE) return node.textContent.replace(/\s+/g, " ")
|
|
2023
|
-
if (node.nodeType !== Node.ELEMENT_NODE) return ""
|
|
2024
|
-
if (node.localName === "br") return "\n"
|
|
2025
|
-
const inner = Array.from(node.childNodes, inlineText).join("")
|
|
2026
|
-
return node.localName === "code" ? `\`${inner}\`` : inner
|
|
3369
|
+
if (node.nodeType === Node.TEXT_NODE) return node.textContent.replace(/\s+/g, " ")
|
|
3370
|
+
if (node.nodeType !== Node.ELEMENT_NODE) return ""
|
|
3371
|
+
if (node.localName === "br") return "\n"
|
|
3372
|
+
const inner = Array.from(node.childNodes, inlineText).join("")
|
|
3373
|
+
return node.localName === "code" ? `\`${inner}\`` : inner
|
|
2027
3374
|
}
|
|
2028
|
-
__name(inlineText, "inlineText");
|
|
2029
3375
|
}
|
|
2030
|
-
__name(noteText, "noteText");
|