Repository navigation
Speculative Document Components
Speculative. A proposal, not adopted.
A document (a guide page, a notebook) is prose with expressions in it, and it also needs parts that are not mathematics: a callout, a collapsible section, tabs, a caption, content that only makes sense with a live client. Today these come from the site generator (VitePress containers, Vue components, <ClientOnly>), so they exist only on the web site, they are not expressions, and reduce(expr, env) cannot give them a print, terminal or static reading. This page proposes heads for the ones that earn it, chosen by what neighbouring systems share, and a condition on the environment that replaces ClientOnly.
"Measured" means read or counted from the tree at origin/main; every measured claim carries a path:line, or a git grep count over a stated pathspec. Claims about other systems are "from memory": I did not fetch their documentation, so the survey table is unverified and each cell wants a check before the page is published. "Assumed" means reasoned and not run; nothing here was built, tested or executed (no node_modules in the tree).
Add three things, in this order, and stop there for now.
-
WhenCan(capability, body, fallback): a headreduceresolves against the environment, plus one new preset for a page as built (no engine, no interaction, static). It is the conditionClientOnlystands for, stated as a capability the environment lacks, not a framework. -
Callout(body, Kind -> …, Title -> …): a new head, a taggedPanelBoxthe wayLabeledis a tagged grid, written in markdown by a container so today's:::tipkeeps working as sugar. -
OpenerView(summary, body, Opened -> True)and thenTabView: Wolfram's names for disclosure and tabs, each a new box primitive (opener-view-box,tab-view-box) because each has state and an ARIA pattern.
Captions stay Labeled; layout stays Row/Column/Grid; inputs stay the control heads. Footnotes, includes, citations, badges, cards and margin notes are not heads: they are prose- or build-level, or site chrome (§5).
Document-level heads already declared (all held inert, Wolfram's own, as their records say, e.g. packages/formats/reference/Panel/index.md:1-5):
| Head | Lowers to | Tag | Where |
|---|---|---|---|
Row, Column, Grid
|
RowBox, GridBox carrying the head in a TagBox
|
row-box, grid-box
|
packages/boxes/src/notation-layout.ts:236 |
Labeled |
a grid of body and caption, TagBoxed "Labeled" (Top/Bottom/Left/Right) |
grid-box |
packages/boxes/src/notation-layout.ts:209-232 |
Panel |
PanelBox (options Background, FrameMargins, ImageSize) |
panel-box |
packages/boxes/src/notation-layout.ts:164, packages/frontend/src/box-render.ts:120-127
|
Tooltip |
TooltipBox, rendered with data-tip and tabindex="0"
|
tooltip-box |
packages/frontend/src/box-render.ts:176-177 |
PaneSelector |
PaneSelectorBox, panes keyed by value, a Dynamic binding picks |
pane-selector-box |
packages/boxes/src/notation-layout.ts:181, packages/boxes/src/box.ts:72
|
StringTemplate |
TextData with $…$ islands and {…} holes |
none (prose) | packages/boxes/src/notation-prose.ts:51-59 |
Cell, Show, Notebook
|
notatio-cell, notatio-cell/show, dynamic-module-box; Cell and Show are held |
notatio-* |
packages/frontend/src/symbols.ts:1196-1206, :1292
|
controls (Slider, SetterBar, Toggler, …), Dynamic, Manipulate
|
control boxes | *-box |
packages/formats/src/graphics.ts:131-159 |
The box tag rule is one function, boxTag, over heads ending in Box (packages/frontend/src/box-tags.ts:11-22). A head that is not a box primitive (Row, Column, Labeled) rides on a TagBox and has no tag of its own.
Not heads. git ls-files | grep '/reference/<Name>/index.md' finds no record for OpenerView, TabView, Framed, Style, Item, Hyperlink, Button, Legended, Pane, Spacer, Figure, Caption, Callout, Badge, Aside, Footnote. Wolfram has the names OpenerView (packages/wolfram/src/system-names.ts:5078), TabView (:6854), Tooltip (:7113), Panel (:5224), Labeled (:3996), Framed (:2886), Item (:3842), Style (:6691), Hyperlink (:3464), Legended (:4082), Deploy (:1990), Interpretation (:3761). It has none for callout, badge, caption or footnote.
Site-only, measured.
-
Theme components (
web/.vitepress/theme/components/, 27.vuefiles, ~5,400 lines): reference and symbol pages (ReferencePage1,061 lines,ReferenceIndex,ReferenceCatalog,FieldPage,ComponentPage,ComponentIndex,CliReference,Crosswalk,AboutPanel,CarrierFields,ExampleAlternatives), demos (Story,StoryCard,Stories,TryIt,LiveInput,SourceOutput,ElementsDemo,EnvironmentPreview,GlyphGallery,FunctionView,Playground), the cross-reference controlSymbol, and chrome (SiteFooter,FullWindowButton,ReviewPanel,NotatioPrerendered). None is a callout, tab set or badge;Story/StoryCardare the nearest (below). -
Containers in markdown:
git grep -E '^:::'over*.mdfinds five, all VitePress defaults, none configured: four::: tip(packages/cli/README.md:8,packages/components/docs/manipulate.md:21,web/playground/inspirations/ganja.md:90,:112) and one::: warning(web/worksheet/index.md:14).markdown.configinstalls only the repository's five markdown-it plugins (web/.vitepress/config.mts:367-376). -
Not used in markdown:
::: details,::: danger,::: info, code groups, GitHub-style> [!NOTE]alerts,<details>, footnotes,<Badge>(eachgit grepover*.mdreturned nothing).Badgeis whitelisted as a Vue component (web/.vitepress/notatio-markup.ts:36-37) but has no use. -
Tabs and disclosure exist only in Vue:
<details>/<summary>for the source of a story (web/.vitepress/theme/components/Story.vue:198-225,StoryCard.vue:70-89), and a source tab strip withrole="tablist"/role="tab"/aria-selected(StoryCard.vue:72-78); agrep aria-over the two files finds onlyaria-hiddenandaria-selected. -
<Story>is the most used construct: 290 opening tags across the package docs and web pages (git grep -h -o -E '<[A-Z][A-Za-z]+'overweb/**.md,packages/**/docs/**.md,packages/**/README.md;<ClientOnlyis 28,<Symbol21,<Show19). It is a titled card holding a live canvas and a collapsible source with a tab per written form: a figure with a caption, a disclosure and tabs in one. -
ClientOnly: 28 opening tags in markdown (git grep -c '^\s*<ClientOnly>' -- '*.md':torus-knots.md8,worksheet.md6,explore/zeta2,explore/polylog2, and one each inlorenz.md,bench,index,notebook,worksheet,explore/lerchphiand four reference indexes) and 13 in the theme (ReferencePage.vue4; one each inElementsDemo,EnvironmentPreview,FieldPage,FunctionView,GlyphGallery,LiveInput,SourceOutput,StoryCard,TryIt; a raw-cof 14 includes a comment atStory.vue:75). Tallying the tags named within two lines after each markdown opener:notatio-worksheet9,graphics-3d-box9,notatio-manipulate5,ReferenceCatalog4,notatio-complex-plot3, then one each ofnotatio-notebook,notatio-collection-table,BenchViewer(a two-line window can catch two tags of one block, so the tally is indicative). Each guards something that mounts a custom element or a component that does, and each of those needs a kernel or a browser canvas. -
Why: the theme is server-rendered, and the packages that define custom elements touch
HTMLElementon import, which fails the server chunk silently; the theme reaches them only throughimport()inonMounted(web/.vitepress/theme/ssr-imports.test.ts:1-5). That explains the Vue guards. Whether a markdown page needs the guard around a bare custom-element tag is not determined:isCustomElementalready lets Vue passnotatio-*and box tags through (web/.vitepress/config.mts:381-382), and the wiki's Figures page says a page needs noClientOnlybecause the tags say what runs where. The wiki's Kernels page (§9) writes prerendered output "outside<ClientOnly>". -
Markup already reads heads in markdown: a PascalCase tag that is a declared head or a graphics head is read as an expression, unless a Vue component claims the name (
web/.vitepress/notatio-markup.ts:25-70). So a new head inGRAPHICS_HEADS(packages/formats/src/graphics.ts) or the manifest is usable as<Callout>in a page with no further wiring, subject to the prose limit in §4.
Drift noticed. The wiki's Rendering-Environments page says treeOf is "decided and not yet built"; it is at packages/frontend/src/vdom.ts:176.
Legend: ● a named construct in the system's document layer (markup, directive or shortcode) or a documented class; ○ only by raw HTML, a user component, or a third-party package; – none. All cells are from memory, not fetched; a ? marks the ones I am least sure of. The system's own name is in the cell.
| Component | VitePress | MDX | Observable | Jupyter (MyST / Jupyter Book) | Quarto | Wolfram notebooks | Typst | Pluto |
|---|---|---|---|---|---|---|---|---|
| Callout / admonition | ● ::: tip, warning, danger, info; > [!NOTE] alerts |
○ (user component) | ● CSS classes note, tip, warning, caution (?) |
● {note}, {tip}, {warning}, {danger}, {hint}, {important}, {caution}, {seealso}, {attention}, {error}
|
● .callout-note, -tip, -warning, -important, -caution
|
○ Panel, Framed
|
○ packages | ● !!! kind "title"
|
| Collapsible | ● ::: details
|
○ <details>
|
○ <details>
|
● {dropdown}
|
● callout collapse
|
● OpenerView, closed cell groups |
– | ○ <details>
|
| Tabs | ● ::: code-group (code only) |
○ | – | ● {tab-set}/{tab-item}, ipywidgets Tab
|
● .panel-tabset
|
● TabView
|
– | – |
| Synced tab groups | ● code groups sync by label | – | – | ● :sync: key |
● group=
|
– | – | – |
| Badge | ● <Badge type text>
|
– | – | ● {bdg-*}
|
– | – | – | – |
| Figure with caption | – | ○ <figure>
|
○ <figure>, Plot caption
|
● {figure}
|
● {#fig-x}
|
● Labeled (caption only) |
● figure(caption:)
|
– |
| Cross-reference | – | – | – | ● {numref}, {ref}
|
● @fig-x
|
– (CellTags + Hyperlink) |
● @label
|
– |
| Code group | ● ::: code-group
|
– | – | ○ via tab-set | ○ via tabset | – | – | – |
| Cards | ○ home-page features | – | ● .card
|
● {card}
|
– | – | – | – |
| Columns / grid | – | ○ | ● .grid classes |
● {grid}
|
● layout-ncol, .column-*
|
● Row, Column, Grid
|
● grid, columns
|
– |
| Margin note / aside | – | – | – | ● {margin}, {sidebar}
|
● .column-margin, .aside
|
– | ○ packages | – |
| Footnote | ● [^1]
|
○ remark-gfm | ○ (?) | ● [^1]
|
● [^1], margin placement |
– | ● footnote
|
● [^1]
|
| Citation | – | – | – | ● {cite} + BibTeX |
● @key, CSL |
– | ● cite, bibliography
|
– |
| Embed | ○ | ○ | ○ FileAttachment
|
● IFrame, YouTubeVideo
|
● {{< video >}}
|
○ | – | ● PlutoUI.Resource
|
| Inputs / widgets | – | ○ JSX | ● Inputs.*, view
|
● ipywidgets | ● OJS inputs | ● Manipulate, controls |
– | ● @bind, PlutoUI |
| Conditional on output | ● ClientOnly (client vs SSR) |
– | – | ● {only}, cell tags remove-input
|
● .content-visible when-format
|
○ $Notebooks, Deploy
|
● context + target()
|
– |
| Include | ● <!--@include: -->
|
● import of .mdx
|
○ modules | ● {include}
|
● {{< include >}}
|
– | ● #include
|
– |
Counting ● only (a named construct in the document layer or a documented class, not raw HTML or packages):
- In five or more (the shared core): callout (VitePress, Observable, MyST, Quarto, Pluto), columns/grid (Observable, MyST, Quarto, Wolfram, Typst), footnote (VitePress, MyST, Quarto, Typst, Pluto), inputs/widgets (Observable, Jupyter, Quarto, Wolfram, Pluto), include (VitePress, MDX, MyST, Quarto, Typst).
-
In two to four: collapsible 4 (7 counting raw
<details>), tabs 4, figure with caption 4, conditional on output format 4 (5 if Wolfram's programmatic$Notebookscounts), synced tabs 3, cross-reference 3, citation 3, embed 3, badge 2, cards 2, margin note 2. - One: code group (it is tabs over code blocks).
What the counts say, honestly: the five-of-eight rule picks out callouts and layout, and four things that are not document structure for us (footnote and include are prose and build features; inputs already exist as heads). Collapsible, tabs, figure caption and conditional content sit at four, and the systems missing them are missing them for reasons that do not carry over: MDX and Pluto have no document layer of their own, Typst targets paper (and has context/target() for the cases that differ), Observable leaves them to HTML. I recommend them on that ground, not on the count. Badge and cards are two of eight: site chrome (§5).
Rules applied: no abbreviations, never lowercase, American spelling, options are Rules, a boolean option defaults to False (so Opened -> True, never Closed -> False), and an option key is never a domain name (so not Group).
| Component | Head | Source of the name | Signature | Lowers to |
|---|---|---|---|---|
| Callout |
Callout (new) |
Quarto's name (from memory); Wolfram has none, Panel is the nearest |
Callout(body…, Kind -> Note, Title -> "…"); Kind is one of Note, Tip, Important, Warning, Caution
|
a PanelBox carrying Callout and its kind in a TagBox, as Labeled carries its head (notation-layout.ts:232); element panel-box
|
| Collapsible | OpenerView |
Wolfram, system-names.ts:5078
|
OpenerView(summary, body…, Opened -> True) |
new OpenerViewBox, element opener-view-box
|
| Tabs | TabView |
Wolfram, system-names.ts:6854
|
TabView([label -> pane, …], Selected -> label, Linked -> "name"); the rule list has the shape PaneSelector already takes (notation-layout.ts:181-198) |
new TabViewBox, element tab-view-box
|
| Caption |
Labeled (exists) |
Wolfram | Labeled(body, caption, Bottom) |
as today |
| Condition |
WhenCan (new) |
none |
WhenCan(capability, body, fallback) (§3) |
resolved by reduce; never reaches a box |
| Layout |
Row, Column, Grid (exist) |
Wolfram | as today | as today |
| Inputs | the control heads, Manipulate (exist) |
Wolfram | as today | as today |
Why a TagBox for Callout and real primitives for the other two: Row, Column, Labeled and now Callout are arrangements with no state, so the head rides on an existing box and no tag is added (notation-layout.ts:1-4). PaneSelectorBox, TooltipBox and the controls are primitives because the element holds state or behavior (box.ts:71-72). Disclosure and tabs have both, so they follow PaneSelectorBox. (Assumed: that the new primitives are added to ARITY, which BOX_HEADS derives from, box.ts:133, :210.)
Linked carries a synced tab group (VitePress, MyST and Quarto each have one, §1): every TabView on a page with the same value selects the same label. It is a string, not a domain word. The name is open (§7).
How each environment shows them (reduce rewrites to ordinary heads; the element is only the web's reading):
| web (interactive) | print, paged | terminal (tty, pipe) | built page, no client | |
|---|---|---|---|---|
Callout |
framed block, a label from Kind and Title in the text, never color alone |
same frame, label kept | the label as a line, body indented; Note: / Warning: marker |
same as web |
OpenerView |
opener-view-box over native <details>/<summary>; closed unless Opened -> True
|
open: reduce writes Column(summary, body) (paper cannot toggle, and a closed section silently loses content) |
open, summary as a heading line | the <details> works without script |
TabView |
tab strip and one pane | every pane in sequence under its label: Column(Labeled(pane, label, Top), …), the shape reduce already uses for sampled controls (reduce.ts:430) |
the same sequence | first pane shown, others hidden until the element upgrades, as pane-selector-box does (packages/frontend/src/box-styles.ts:66-80) |
WhenCan |
the body where the capability holds, else the fallback | by the print preset | by the preset | by the built-page preset (§3) |
The print and terminal rows are policy I propose; none is built. The "open in print" choice is the one with a cost: a document that hides material by design (an answer key in a closed section) prints it. An option Opened -> False cannot express "stay closed in print", so that is an open question.
What it means in the Environment record's terms. An environment is "a record of what the place a rendering lands can do" (packages/frontend/src/environment.ts:1-5); engine is "is a compute engine present when the reader looks" (:35), and can holds the questions: draw(surface), interact(how), drive, animate (:168-175). ClientOnly asks one of them: can something run here that the server cannot (drive, in practice: the guarded elements are worksheets, manipulates, plots that evaluate; §What exists). So it is already a capability, and can is already the vocabulary.
A gap that must close first. There is no preset for "the page as the build writes it". pageEnvironment() returns WEB when there is no window (environment.ts:185-187), and WEB says engine: true, time: "live" (:50-61). So at build time every control is told it can be driven, which is the case ClientOnly papers over. A preset such as { ...WEB, name: "prerender", engine: false, interaction: ["links"], time: "static", static: { …, controls: "pin" } } (assumed shape) says what a built page can do; controls: "pin" rather than sample so first paint matches the live element's initial state and does not reflow on mount (the wiki's Kernels page says a Manipulate prerenders "at its controls' initial values"; PIPE already sets controls: "pin", environment.ts:99). drawnAsWritten iterates ENVIRONMENTS only for the ones that can.drive (reduce.ts:497-502), so adding a non-driving preset to ENVIRONMENTS (environment.ts:110) leaves it alone; the reduce golden ("every corpus line under every preset", wiki) would regenerate. (Assumed, not run.)
Three shapes weighed.
-
An option on the content head,
Static -> fallback. The repo already has aStaticoption on controls, whose value is a reading name or a count (reduce.ts:49,:83,:95). Generalized to an expression it attaches the fallback to the thing it replaces and needs no new head. But it answers one question only (can this be driven), each head must opt in, and an element written as markup (<notatio-worksheet>) has no option slot. It also gives a callout or a tab set no way to say "print this other thing". -
A condition head,
WhenCan(capability, body, fallback). A closed vocabulary of capabilities mirroringcan:Drive,Animate,Draw(Surface),Interact(How).reducereplaces the node withbodyif the environment can, elsefallback(or nothing). It works over any content, answers any capability, and the author reads it as the sentence it is: show this where the environment can drive, else that. Costs: a new head, andreducemust resolve it beforedeclarations/staticControls, becausedeclarationswalks the whole tree (reduce.ts:78-80stops only at held heads) and a control in the discarded branch would otherwise contribute a pin caption.reduceiscontrolled = can.drive(env) ? expr : staticControls(expr, env)thensurfaces(reduce.ts:475-478), so the resolution goes in front. -
PaneSelectorover the environment. Reuse an existing head:PaneSelector([Print -> a, _ -> b], Environment). It adds no head, but it keys on environment names, and environments are records that detectors spread into variants (browserEnvironment,environment.ts:147-154), so a rule keyed on"print"misses a custom environment; andPaneSelector's selector is a binding the element follows at run time (notation-layout.ts:181-198), which mixes the build-time and run-time readings under one head.
Recommended: shape 2. It reuses the capability vocabulary instead of enumerating environments, and it is the same top-down rewrite reduce already does. Shape 1 stays as it is for controls. Wolfram's precedents, from memory: Deploy freezes dynamic content into its static display; Interpretation pairs a display with a value; If[$Notebooks, …] tests the front end, but in the kernel, per session rather than per reader. None is a head that takes a fallback by capability, so the name is ours; WhenCan is a placeholder (§7).
How it reduces, worked. WhenCan(Drive, Cell(Manipulate(…)), Labeled(Plot(…), "k = 2", Bottom)):
- under
WEB(can.drivetrue): theCell; theLabeledis dropped unreduced; - under
PRINT,PIPE, the built-page preset: theLabeled; - under
TTY(an engine and keys, socan.driveis true): theCell, which the CLI drives (packages/cli/src/drive.ts, per the wiki).
The built page then holds the fallback, and the element or the page's own re-reduce for WEB replaces it on load. The swap belongs to the custom element, not to Vue (Vue sees only tags it was told are custom, config.mts:381-382), so it does not hydrate against a different tree. Whether that holds for every case is untested.
What WhenCan does not replace. The theme's 13 Vue guards exist for an import-time reason (ssr-imports.test.ts:1-5), which an expression cannot lift. They stay until the theme loads its elements lazily everywhere. For markdown, <ClientOnly> stays VitePress's; I propose migrating one page (worksheet.md, six uses) before touching the rest, and measuring whether the guard is needed at all around a bare custom element (open).
| Surface | State | Support first? |
|---|---|---|
Markdown container (::: callout warning Title, plus today's ::: tip, ::: warning) |
five uses in the tree; VitePress's own container plugin, nothing configured |
Yes, for Callout and OpenerView. The container body is block markdown; a build step reads it with the existing markdown-to-boxes reader (readMarkdown, packages/boxes/src/render/markdown.ts:243, which returns TextCells) and wraps it in the head. Today's :::tip/:::warning map to Callout with Kind -> Tip/Warning; info to Note, danger to Caution (assumed mapping) |
Vdom markup (<Callout Kind="Warning">…</Callout>) |
already works for any declared head (notatio-markup.ts:25-70) |
Second, and the limit matters: a text run in markup is split into whitespace-separated atoms (the wiki's Vdom page), so prose paragraphs in a body do not survive. Bodies written this way hold heads (StringTemplate("…"), a Labeled), not markdown |
| Epsil in a cell | cells hold an expression; Cell/Show are held (symbols.ts:1292) |
Last. A callout in a notebook is a TextCell question (§Open): the notebook's prose cells, not an output |
Precedence: a name VitePress or Vue owns stays theirs (VUE_COMPONENTS, notatio-markup.ts:25-47); Badge and ClientOnly are in it today. A head named Callout, OpenerView or TabView collides with no entry.
Accessibility the elements must implement (from memory of the WAI-ARIA authoring practices; verify before building):
-
Disclosure. A button that toggles and exposes its state (
aria-expanded, andaria-controlswhen it is not a native<details>); Enter and Space toggle. Native<details>/<summary>gives this without script, and survives a no-client page. That is whyopener-view-boxwraps it. -
Tabs.
role="tablist"ofrole="tab"elements each witharia-selectedandaria-controls, and arole="tabpanel"witharia-labelledby; one tab in the tab order (rovingtabindex), Left/Right (and Home/End) move between tabs; Tab moves into the panel. The only tabs here today setroleandaria-selectedand nothing else I found (StoryCard.vue:72-78). -
Callout. Not a live region (
role="alert"is wrong for static text). A labeledrole="note"region, with the kind carried by the text and not only by color or an icon, so print and terminal readings agree. -
Tooltip (existing) is
tabindex="0"withdata-tip(box-render.ts:177) and noaria-describedbythat I can find; not part of this proposal, a gap worth noting.
- Accretion. Each head is a commitment the printers, the terminal host and the markup reader must keep. The survey's counts say most candidates are not worth one; the lean (§6) adds three and names the rest as not heads.
-
A second list to update.
substitutetreats a hardcoded set of layout heads,Row,Column,Grid,Panel,Labeled(reduce.ts:262), specially: controls removed from a layout are pruned. A head not in that set falls to the generic branch, where a removed control is replaced by its variable name (reduce.ts, last line ofsubstitute), so a slider inside a newCalloutwould print as the bare symbolk.LAYOUT_HEADSin boxes (notation-layout.ts:247) is a separate list, andARRANGINGreads it (reduce.tsnearasWritten). Each new head needs adding to both, or the two lists become one helper first (the repo's rule: a fact several routes need lives in one helper). -
Overlap with VitePress.
:::tipand<ClientOnly>work today. The proposal keeps them working and makes them sugar; the risk is two spellings for years. The benefit appears only when a page is read somewhere other than the site (a notebook,toMarkdown, print). - Hydration. A built page that prints a fallback and a client that swaps it is a mismatch if Vue owns the node. The swap must be the element's (§3).
-
Prose bodies. Block markdown inside a head is the unproven link:
readMarkdownyieldsTextCells, and nothing yet places them inside aPanelBox(assumed). -
Not site chrome as structure. Cards, hero sections, feature grids, footers, badges and the review panel are chrome: two of eight systems have cards or badges, and a badge is a
Styleon text. They stay in the theme. Also not heads: footnotes and citations (prose-level, markdown plugins), includes (a build feature), embeds (raw HTML), margin notes (two of eight, no print or terminal reading), figure numbering and cross-reference (three of eight;Labeledcovers the caption). -
Storyis the test, not the first target. It is a figure plus disclosure plus tabs (290 uses). IfLabeled,OpenerViewandTabViewcannot express it, the vocabulary is wrong; but it is a Vue component with stories data behind it (StoryCard.vue), so it is not migrated in the first slice.
Three slices, each ending green on its own. Names below are proposals; nothing in this list exists.
-
The built-page preset and
WhenCan.-
packages/frontend/src/environment.ts: the preset;pageEnvironmentunchanged for the browser.packages/frontend/src/reduce.ts: resolveWhenCanfirst inreduce(:475). - Declare the head: add to
GRAPHICS_HEADS(packages/formats/src/graphics.ts) and a recordpackages/formats/reference/WhenCan/index.mdwith examples. - Tests:
packages/frontend/tests/reduce.test.tsand its golden (reduce.golden.json) for the new preset; an example per capability, withknown-style expectations, in the record.
-
-
Callout.-
packages/boxes/src/notation-layout.ts: a rule besideLabeled; add toLAYOUT_NOTATION, and toLAYOUTinreduce.ts:262. - Record
packages/formats/reference/Callout/index.mdwith an example whoseboxesshape statesPanelBox;packages/frontend/tests/example-boxes.test.tsholds it. -
web/.vitepress/config.mtsmarkdown.config: a container forcallout(and maptip,warning) calling the markdown reader; the five existing containers keep their spellings.
-
-
OpenerView.- New
OpenerViewBoxinpackages/boxes/src/box.ts(ARITY), a static writer inpackages/frontend/src/box-render.tsemitting<details>, an element file besidepackages/components/src/pane-selector-box.ts, CSS inbox-styles.ts; the static reading inreduce.ts. - Browser behavior in the stories specs (
web/tests/stories/*.spec.ts, run withpnpm --filter @notatio/web run test:stories, perout-layout.spec.ts:5): toggles by pointer and keyboard, exposes its state, prints open. Behavior is asserted as it should be, not as it is.
- New
TabView follows once OpenerView is in; tabs need the larger ARIA pattern and a story-spec for the keyboard. Do not migrate <Story> or the 28 markdown ClientOnly uses in these slices.
-
Name and shape of the condition.
WhenCan(capability, body, fallback), capabilities a closed set (Drive,Animate,Draw(Surface),Interact(How)). Recommend: yes, but settle the spelling before the record is written, since names are hard to change late. CheckWhenCanagainst the no-abbreviation and no-domain-name rules, and thatDriveandInteractare not already symbols. -
A built-page preset, or a flag on
WEB. Recommend a preset:ENVIRONMENTSis a list of whole records, and a flag would need every consumer to know it. -
Does an
OpenerViewprint open? Recommend yes by default, and a per-instanceStatic -> Closedusing the option the repo already has for controls, so an answer key can stay closed. Reason: silent loss on paper is worse than a long page. -
Wolfram's signatures. Wolfram's
OpenerViewtakes a pair,{summary, body}, andTabViewtakes a list of rules or panes (from memory). Recommend adopting the names and our own argument shapes, stating the difference on each record, as other heads here do. -
Calloutkinds. Recommend five:Note,Tip,Important,Warning,Caution(the GitHub alert set, from memory, which Quarto matches). VitePressinforeads asNoteanddangerasCaution. -
Synced tab key.
Linked -> "name"or another word. Recommend deciding withTabView, not now. -
Prose in bodies. Recommend the markdown reader (
readMarkdown) overStringTemplatefor container bodies: it keeps paragraphs, lists and code.StringTemplateis one run of text. -
Is a document a
Notebook? A callout in a notebook is prose, not an output. Recommend deferring to the Docs-as-Notebooks page rather than deciding here. -
Does a markdown page need
ClientOnlyaround a bare custom element at all? Not determined. Recommend testing onworksheet.mdwith the guard removed, in a built page and the dev server, before any migration.
Measured (read or counted at origin/main): the environment record, presets and can (environment.ts:33-175); reduce's order and LAYOUT (reduce.ts:262, :475-478); the layout notation rules (notation-layout.ts:164-236); the box tag rule (box-tags.ts:11-22); TooltipBox/PanelBox rendering (box-render.ts:120-127, :176-177); markup head resolution (notatio-markup.ts:25-70); the markdown plugin list and isCustomElement (config.mts:367-385); the SSR rule (ssr-imports.test.ts:1-5); the count of containers (5), ClientOnly opens (28 in markdown, 13 in the theme), <Story> opens (290), 27 theme components; no records for the missing heads; Wolfram's names (system-names.ts lines above); treeOf at vdom.ts:176.
From memory, unverified: every cell of the survey table and the counts built on it; ARIA practices; the Wolfram signatures and the precedents named in §3.
Assumed: that a built-page preset leaves drawnAsWritten and the reduce golden alone; the container-to-head build step and its use of readMarkdown; the print, terminal and no-client readings; the element implementations and that OpenerViewBox joins ARITY; that resolving WhenCan first is enough to keep pin captions out of the dropped branch; that swapping in the element avoids a hydration mismatch.