explico 0.12.0 → 0.13.1

package/docs/authoring/components.md

@@ -117,7 +117,7 @@ prints `§ 1.1.2` ([structure.md § Section numbers](structure.md#section-number
 | --- | --- | --- | --- |
 | `<Table id="…" caption="…" short="…">` | `explico/components/table/Table.astro` | `tab-` | [structure.md](structure.md#numbering), [V rules](visualizations.md) |
 | `<Figure id="…" caption="…" short="…" previewable defaultOpen rememberState>`, with an optional `slot="tools"` | `explico/components/figure/Figure.astro` | `fig-` | [structure.md](structure.md#numbering), [V2](visualizations.md#v2)/[V3](visualizations.md#v3) |
-| `<Diagram id="…" caption="…" short="…" nodes={…} edges={…}>` | `explico/components/diagram/Diagram.astro` | `dia-` | [V1](visualizations.md#v1) |
+| `<Diagram id="…" caption="…" short="…" nodes={…} edges={…}>` | `explico/components/diagram/Diagram.astro` | `dia-` | [V1](visualizations.md#v1)/[V8](visualizations.md#v8) |
 | A display equation with `\label{eq:key}` and `\caption{…}` | `remark-math` (built in) | `eq-` | [N5](notation.md#n5), [structure.md](structure.md#numbering) |
 
 ### The caption pair
@@ -129,16 +129,31 @@ title bar: its number sits in its caption line.
 
 | Float | Long caption — where it shows | Short caption — where it shows |
 | --- | --- | --- |
-| `<Figure>` | `caption`: below the figure, after `Figure 2.2.1` and its chain icon | `short`: opens the caption line as its bold title, and heads the `[[fig-…]]` preview card |
+| `<Figure>` | `caption`: below the figure, after `Figure 2.2.1` | `short`: opens the caption line as its bold title, and heads the `[[fig-…]]` preview card |
 | `<Diagram>` | `caption`: below the graph, the same caption line as a figure; its right end holds a widen button ↔ while the graph is wider than the column | `short`: opens the caption line as its bold title, and heads the `[[dia-…]]` preview card |
 | `<Table>` | `caption`: above the table (the LaTeX table convention), after `Table 2.2.1`; its right end holds the fold button (and a widen button ↔ when the table is wider than the column); stays with the header row when the table is folded | `short`: opens the caption line as its bold title, and heads the `[[tab-…]]` preview card |
 | Display equation | none — an equation takes a short caption only | `\caption{…}` inside the `$$…$$`, stripped before KaTeX like `\label{}`: heads the `[[eq-…]]` preview card and names the copy action ("Copy LaTeX — Range formula") |
 | `<Memo>` | `caption` (required): the memo's bar, and the head of its marker's preview | `short`: the marker's tooltip |
 | `<CompactExamples>` | none | `short` (required, with `id`): the set's topic — its heading, after the engine's "Example" badge and number |
 
+**A float's number has a toolbar.** Hovering or focusing the number of an
+equation, a figure, a table or a diagram shows Pin and Dock just above it
+and Copy link just below it; none of them covers the number. Pin and Dock
+keep the float's own preview card, next to the float or beside the article;
+Copy link copies the float's link, named by its number and short caption,
+as a heading's chain icon does. A click on the number itself only puts its
+anchor in the address bar. An equation's Copy LaTeX sits on its bottom
+border, under the number, and shows while the equation is hovered. A touch
+screen has no toolbar: a long press on the number offers the browser's own
+"Copy link" (`float-toolbar.ts`).
+
 `caption` is required wherever it exists; `short` is optional everywhere but
 on a `<CompactExamples>`, whose heading it is, and is what
 [rule S1](structure-rules.md#s1) measures — the long caption is never capped.
+Write both as quoted strings: `short={"…"}` renders, but the manifest reads
+only a quoted prop, so a reference's card, a copied link and the "Figures and
+tables" page would name the float without it (`fig-unread-prop` and its kin,
+a warning). Use typographic quotes (‘’ “”) inside one.
 
 A figure's, a table's or a diagram's `short` is its name wherever the page
 names it: the bold title that opens its caption line — "**Sampled flight
@@ -156,7 +171,7 @@ is shown.
 
 - **A figure or a diagram never hides by itself.** It is laid out as LaTeX
   lays a figure out, in every state: its picture, then its caption line —
-  number, chain icon, caption. To let a reader fold one away, wrap it in a
+  number, caption. To let a reader fold one away, wrap it in a
   [`<Fold>`](#folding-content-away-fold) or put it in a collapsible (or
   `[card]`) section ([structure.md § Collapsing](structure.md#collapsing-two-mechanisms)).
 - **A lab's tools follow the caption, and only they fold.** A `<Figure>`'s
@@ -184,7 +199,38 @@ _Enforcement._ A `<Figure title>`, a `<Diagram label>` (or `title`,
 `ex-removed-prop` in `pnpm validate:content` (the keyed-floats invariant),
 and the component itself when it renders. A `<CompactExamples>` with no `id`
 or no `short` fails the same way (`ex-missing-prop`). An equation's `\caption{}` that is inline, repeated
-or empty fails the page build.
+or empty fails the page build. A `<Table>` holds one table: a second
+inside it fails `pnpm validate:content` (`tab-several-tables`), since the float
+has one number and one caption and every export would keep only the first.
+
+### Props are plain text
+
+A quoted prop — `caption="…"`, `short="…"`, a `<Memo>`'s `caption`, a
+`<ShortNote>`'s `title`, a `<Fold>`'s `label` — reaches the page as the
+text it holds. KaTeX, `[[…]]` references and `[@…]` citations run on the
+lesson's Markdown, never inside a prop, so `short="Speed $v$"` would show
+"Speed $v$" in the caption line, the preview card and the "Figures and
+tables" page. Write a symbol in a prop in Unicode or words
+(`short="Launch speed v₀"`), and reference or cite from the prose next to
+the component, where the symbol, the link and the citation render. Rule N9
+does not apply in a prop for the same reason.
+
+_Enforcement._ Always on (invariant `prop-text`): `$…$`, `[[…]]` or `[@…]`
+in a quoted prop of a lesson's JSX fails `pnpm validate:content` with
+`markup-in-prop` at its line (`gate-prop-text.ts`). The math gates do not
+read prop strings, so the symbol in one needs no notation entry.
+
+### Braces in prose
+
+MDX reads `{…}` in a lesson's text as JavaScript: `The set {a} has one
+element` renders nothing for `{a}` and fails the build with "a is not
+defined". Write `\{a\}` for braces in the text, and a set as math,
+`$\{a\}$` (in LaTeX, plain braces only group: `${a}$` reads "a"). A
+directive's attributes, `:::note{icon=""}`, are not prose.
+
+_Enforcement._ Always on (invariant `prop-text`): a brace pair in the
+prose fails `pnpm validate:content` with `mdx-expression` at its line
+(`gate-mdx-expression.ts`).
 
 ### The "Figures and tables" page
 
@@ -200,7 +246,6 @@ group lists the page beside the curriculum map and the glossary:
 ---
 title: Figures and tables
 description: Every numbered figure, table and diagram of the course.
-editorialStatus: draft
 ---
 
 import FloatIndex from 'explico/components/FloatIndex.astro';
@@ -218,11 +263,71 @@ elsewhere — the machinery a bare `title` tooltip deliberately skips.
 | `[[key]]` in prose, before first math use | `content/notation/*.md` entry | One-meaning-per-glyph hover card everywhere `$key$`-bound math appears on the page | [N4](notation.md#n4) |
 | `\explain{key}{latex}` inside `$…$` | Same notation entry | Escape hatch for a compound/colliding symbol only, not the default bind | [N4](notation.md#n4) |
 | A bare all-caps/dotted term (`OLS`, `w.r.t.`) in prose | `content/abbreviations/*.md`, or `course.settings.json` `rules.N14.allow` | Hover/click card on first occurrence, linked to the glossary page | [N14](notation.md#n14) |
-| `[@source-id]` or `[@source-id; §1.2]` | `content/sources/*.json` | Numbered `[n]` superscript linking to a References section, with a hover/pin panel | `src/reference/remark-citation.mjs` |
+| `[@source-id]`, `[@source-id; §1.2]`, or several as Pandoc writes them, `[@a; @b; p. 7]` | `content/sources/*.json` | Numbered `[n]` superscript linking to a References section, with a hover/pin panel; one per source | `src/reference/remark-citation.mjs` |
 | `[[sec-slug]]` or `[[lesson/slug#sec-slug]]` | A top-level heading; its anchor is the slug | `§ 1.1.2` linking to the section, with a hover card of its title and first paragraph | [structure.md § Section numbers](structure.md#section-numbers) |
 | `[[ex-id]]` or `[[lesson/slug#ex-id]]` | A `<CompactExamples id>` | `Example 1.1.1` linking to the set, with a hover card of its title and its examples' names | [§ Knowledge checks and worked examples](#knowledge-checks-and-worked-examples) |
 | `[[check-id]]` or `[[lesson/slug#check-id]]` | An assessment id in the lesson's `.checks.yml` | `Knowledge check 1.1.1` linking to the check, with a hover card of its title and its number of questions | [structure.md § Knowledge checks](structure.md#knowledge-checks) |
 
+A reference to another lesson's float, `[[lesson/slug#eq-…]]` and the rest,
+previews it from that lesson, symbols and all: each symbol in the preview
+opens the card that lesson gives it, even one the citing page never uses, so
+there is no notation to copy over. One of that lesson's own symbols says so
+on its card: "Defined in Position and Coordinate Systems · means this only
+there".
+
+A citation is a link of its own, so it cannot sit in a link's text:
+`[as measured in [@id]](https://…)` fails `pnpm validate:content`
+(`citation-in-link`); cite after the link, `[as measured](https://…) [@id]`.
+
+The prefixes `eq-`, `tab-`, `fig-`, `dia-`, `ex-`, `check-`, `sec-` and
+`memo-` belong to these references, so no notation key starts with one: a
+`[[ex-ante]]` is read as a worked-example reference and never reaches an
+`ex-ante` entry. Such a key fails `validate:content` where it is defined
+(`invalid-key`), and `pnpm content new term` refuses it; name the entry
+`exante` or `ante-expectation` instead.
+
+### Carrying cards
+
+A reader keeps a card by clicking its trigger (pinned), docking it beside the
+article, or dragging it somewhere. A pinned card whose trigger the reader
+folds away — its section collapsed, its fold closed — waits out of sight and
+comes back beside the trigger when it opens again; a docked or dragged card
+stays where the reader put it. With **Carry cards** on, a kept card stays
+on screen: it scrolls with its trigger until it reaches the top or the bottom
+edge of the window and stays there, and follows its trigger again once the
+trigger comes back. Cards held at one edge stack in the order they were
+opened; when they are taller than the window, the older ones collapse to
+their header row, and a click opens one again.
+
+The switch sits with the side column's controls, beside "Article left", while
+the column is in use; otherwise it shows alone at the article's top right
+while a card is kept. Its tooltip says what it does. It is off until a reader
+turns it on, and their choice is remembered. A course can start every reader
+with it on:
+
+```json
+"cards": { "carry": true }
+```
+
+in `course.settings.json` (`CourseConfig.cards`).
+
+With carrying on, the kept cards also come along to every page of the course,
+however the reader gets there. On the page a card was opened on, it attaches
+to its trigger again; on any other page it is rebuilt from that page and held
+at the edge of the window it was at. A figure card brings its plot as it was
+drawn. Closing a card ends its journey. Each browser tab keeps its own cards,
+and a new tab starts with the ones the reader carried last.
+
+With carrying on, every kept card also links back to where it was opened:
+"Opened at § 2.1.1" beside its "Go to …" link, or "Opened at (2.1.3)" for a
+card opened from inside a numbered equation. The link goes to the section's
+anchor, and with JavaScript to the trigger itself, which lights up a moment.
+
+Nothing in a course's content has to change for this: every card layer
+registers on every page (`LessonFooter.astro`) and can rebuild its cards from
+another page (`CardSource.build`). The rules are K1–K8 in
+`src/components/card-carry.ts` and `heldAt` in `card-placement.ts`.
+
 ## Knowledge checks and worked examples
 
 | Component | Import | Notes | Doc |