Skip to content

Speculative Document Components

enumeratio edited this page Nov 16, 2026 · 1 revision

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).

Recommendation

Add three things, in this order, and stop there for now.

  1. WhenCan(capability, body, fallback): a head reduce resolves against the environment, plus one new preset for a page as built (no engine, no interaction, static). It is the condition ClientOnly stands for, stated as a capability the environment lacks, not a framework.
  2. Callout(body, Kind -> …, Title -> …): a new head, a tagged PanelBox the way Labeled is a tagged grid, written in markdown by a container so today's :::tip keeps working as sugar.
  3. OpenerView(summary, body, Opened -> True) and then TabView: 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).

What exists

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 .vue files, ~5,400 lines): reference and symbol pages (ReferencePage 1,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 control Symbol, and chrome (SiteFooter, FullWindowButton, ReviewPanel, NotatioPrerendered). None is a callout, tab set or badge; Story/StoryCard are the nearest (below).
  • Containers in markdown: git grep -E '^:::' over *.md finds 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.config installs 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> (each git grep over *.md returned nothing). Badge is 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 with role="tablist"/role="tab"/aria-selected (StoryCard.vue:72-78); a grep aria- over the two files finds only aria-hidden and aria-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]+' over web/**.md, packages/**/docs/**.md, packages/**/README.md; <ClientOnly is 28, <Symbol 21, <Show 19). 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.md 8, worksheet.md 6, explore/zeta 2, explore/polylog 2, and one each in lorenz.md, bench, index, notebook, worksheet, explore/lerchphi and four reference indexes) and 13 in the theme (ReferencePage.vue 4; one each in ElementsDemo, EnvironmentPreview, FieldPage, FunctionView, GlyphGallery, LiveInput, SourceOutput, StoryCard, TryIt; a raw -c of 14 includes a comment at Story.vue:75). Tallying the tags named within two lines after each markdown opener: notatio-worksheet 9, graphics-3d-box 9, notatio-manipulate 5, ReferenceCatalog 4, notatio-complex-plot 3, then one each of notatio-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 HTMLElement on import, which fails the server chunk silently; the theme reaches them only through import() in onMounted (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: isCustomElement already lets Vue pass notatio-* and box tags through (web/.vitepress/config.mts:381-382), and the wiki's Figures page says a page needs no ClientOnly because 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 in GRAPHICS_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.

1. The survey

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} ● ![cap](img){#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 –

Reading it

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 $Notebooks counts), 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).

2. The vocabulary

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.

3. ClientOnly as a condition on the environment

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.

  1. An option on the content head, Static -> fallback. The repo already has a Static option 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".
  2. A condition head, WhenCan(capability, body, fallback). A closed vocabulary of capabilities mirroring can: Drive, Animate, Draw(Surface), Interact(How). reduce replaces the node with body if the environment can, else fallback (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, and reduce must resolve it before declarations/staticControls, because declarations walks the whole tree (reduce.ts:78-80 stops only at held heads) and a control in the discarded branch would otherwise contribute a pin caption. reduce is controlled = can.drive(env) ? expr : staticControls(expr, env) then surfaces (reduce.ts:475-478), so the resolution goes in front.
  3. PaneSelector over 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; and PaneSelector'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.drive true): the Cell; the Labeled is dropped unreduced;
  • under PRINT, PIPE, the built-page preset: the Labeled;
  • under TTY (an engine and keys, so can.drive is true): the Cell, 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).

4. Where an author writes them

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, and aria-controls when 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 why opener-view-box wraps it.
  • Tabs. role="tablist" of role="tab" elements each with aria-selected and aria-controls, and a role="tabpanel" with aria-labelledby; one tab in the tab order (roving tabindex), Left/Right (and Home/End) move between tabs; Tab moves into the panel. The only tabs here today set role and aria-selected and nothing else I found (StoryCard.vue:72-78).
  • Callout. Not a live region (role="alert" is wrong for static text). A labeled role="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" with data-tip (box-render.ts:177) and no aria-describedby that I can find; not part of this proposal, a gap worth noting.

5. Risks, and what not to add

  • 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. substitute treats 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 of substitute), so a slider inside a new Callout would print as the bare symbol k. LAYOUT_HEADS in boxes (notation-layout.ts:247) is a separate list, and ARRANGING reads it (reduce.ts near asWritten). 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. :::tip and <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: readMarkdown yields TextCells, and nothing yet places them inside a PanelBox (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 Style on 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; Labeled covers the caption).
  • Story is the test, not the first target. It is a figure plus disclosure plus tabs (290 uses). If Labeled, OpenerView and TabView cannot 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.

Plan for a builder

Three slices, each ending green on its own. Names below are proposals; nothing in this list exists.

  1. The built-page preset and WhenCan.
    • packages/frontend/src/environment.ts: the preset; pageEnvironment unchanged for the browser. packages/frontend/src/reduce.ts: resolve WhenCan first in reduce (:475).
    • Declare the head: add to GRAPHICS_HEADS (packages/formats/src/graphics.ts) and a record packages/formats/reference/WhenCan/index.md with examples.
    • Tests: packages/frontend/tests/reduce.test.ts and its golden (reduce.golden.json) for the new preset; an example per capability, with known-style expectations, in the record.
  2. Callout.
    • packages/boxes/src/notation-layout.ts: a rule beside Labeled; add to LAYOUT_NOTATION, and to LAYOUT in reduce.ts:262.
    • Record packages/formats/reference/Callout/index.md with an example whose boxes shape states PanelBox; packages/frontend/tests/example-boxes.test.ts holds it.
    • web/.vitepress/config.mts markdown.config: a container for callout (and map tip, warning) calling the markdown reader; the five existing containers keep their spellings.
  3. OpenerView.
    • New OpenerViewBox in packages/boxes/src/box.ts (ARITY), a static writer in packages/frontend/src/box-render.ts emitting <details>, an element file beside packages/components/src/pane-selector-box.ts, CSS in box-styles.ts; the static reading in reduce.ts.
    • Browser behavior in the stories specs (web/tests/stories/*.spec.ts, run with pnpm --filter @notatio/web run test:stories, per out-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.

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.

Open questions, with recommended answers

  1. 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. Check WhenCan against the no-abbreviation and no-domain-name rules, and that Drive and Interact are not already symbols.
  2. A built-page preset, or a flag on WEB. Recommend a preset: ENVIRONMENTS is a list of whole records, and a flag would need every consumer to know it.
  3. Does an OpenerView print open? Recommend yes by default, and a per-instance Static -> Closed using 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.
  4. Wolfram's signatures. Wolfram's OpenerView takes a pair, {summary, body}, and TabView takes 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.
  5. Callout kinds. Recommend five: Note, Tip, Important, Warning, Caution (the GitHub alert set, from memory, which Quarto matches). VitePress info reads as Note and danger as Caution.
  6. Synced tab key. Linked -> "name" or another word. Recommend deciding with TabView, not now.
  7. Prose in bodies. Recommend the markdown reader (readMarkdown) over StringTemplate for container bodies: it keeps paragraphs, lists and code. StringTemplate is one run of text.
  8. 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.
  9. Does a markdown page need ClientOnly around a bare custom element at all? Not determined. Recommend testing on worksheet.md with the guard removed, in a built page and the dev server, before any migration.

Measured versus assumed

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.

Home

Project

Working

Design: every design page, by subject

Clone this wiki locally