explico 0.7.0 → 0.11.0

package/docs/authoring/components.md

@@ -65,7 +65,7 @@ still applies is N9/N14 against the *visible* text, as above.
 | Component | Import | What it's for | Doc |
 | --- | --- | --- | --- |
 | `<ShortNote id="…" title="…" description="…">` | `explico/components/memo/ShortNote.astro` | An inline, click-to-expand aside that replaces its own trigger text in place — "the smaller, genuinely inline interaction." No number, no cross-page reference. | [structure.md](structure.md#detailed-memos-and-inline-short-notes) |
-| `<Memo id="…" title="…" description="…">` | `explico/components/memo/Memo.astro` | A collapsible, independently-numbered card for optional depth (derivation, proof, edge case) that would otherwise bloat the main argument. Cited with `[[memo-id]]`. | [structure.md](structure.md#detailed-memos-and-inline-short-notes) |
+| `<Memo id="…" caption="…" short="…">` | `explico/components/memo/Memo.astro` | A collapsible, lettered side-note for optional depth (derivation, proof, edge case) that would otherwise bloat the main argument. Cited with `[[memo-id]]`, which prints its superscript letter. | [structure.md](structure.md#detailed-memos-and-inline-short-notes) |
 
 Both differ from a bare `title` tooltip in the same way: they hold real,
 possibly multi-paragraph Markdown content (including equations, tables,
@@ -73,35 +73,141 @@ figures), are addressable (`id`, a permalink), and are meant to be found
 again — a `title` tooltip is disposable and invisible outside a hover/focus
 event.
 
+### Folding content away: `<Fold>`
+
+| Component | Import | What it's for | Doc |
+| --- | --- | --- | --- |
+| `<Fold label="…" defaultOpen rememberState>` | `explico/components/fold/Fold.astro` | Lets a reader fold away a stretch of the lesson — most often one figure, diagram or table — where it stands. No heading, number or marker. | [structure.md](structure.md#collapsing-two-mechanisms) |
+
+```mdx
+<Fold>
+<Diagram id="launch-angle-dependency" … />
+</Fold>
+```
+
+A fold has a bar with the section chevron and, while folded, the "Hidden
+here: 1 diagram" line; the reader's choice is remembered per page, a deep
+link or find-in-page opens it, and it prints as shown. The bar, set at the
+size of the text it folds, is the `label`; without one it names the numbered
+floats inside by number and short caption — "Diagram 2.2.1 Inputs to the
+launch-angle search" — and is then their name: their caption lines drop the
+bold short-caption title that would repeat it. A fold with neither fails the
+build (`fold-unnamed`). It starts folded unless
+`defaultOpen`, or the course's `disclosure.folds`, says otherwise.
+
+A float never folds by itself — a figure or a diagram is always its picture
+and its caption line — so a fold is how one becomes collapsible outside a
+collapsible section. Choose it over a `<Memo>` when the content belongs where
+it stands and needs no other name: a fold is not an aside (no frame, no
+tint: the plain tier, like the float it holds), puts no letter in the text,
+has no `[[…]]` key, is not in "On this page" and takes no outline number.
+The floats inside keep their numbers and their `[[…]]` references; a
+reference to one previews it in a card and marks the fold's bar.
+
 ## Numbered floats
 
-Each of these gets a `‹part›.‹n›` number (its own counter, independent of the
-others — see [structure.md § Numbering](structure.md#numbering)), a stable
-`#anchor`, and same-page/cross-page reference syntax `[[prefix-id]]` /
-`[[lesson/slug#prefix-id]]`.
+Each of these gets a `‹part›.‹chapter›.‹n›` number (its own counter,
+independent of the others — see [structure.md § Numbering](structure.md#numbering)),
+a stable `#anchor` named after its `id`, and same-page/cross-page reference
+syntax `[[prefix-id]]` / `[[lesson/slug#prefix-id]]`. A section is citable the
+same way, by its heading's anchor: `[[sec-two-ways-to-name-the-same-point]]`
+prints `§ 1.1.2` ([structure.md § Section numbers](structure.md#section-numbers)).
 
 | Component | Import | Prefix | Doc |
 | --- | --- | --- | --- |
-| `<Table id="…" caption="…">` | `explico/components/table/Table.astro` | `tab-` | [structure.md](structure.md#numbering), [V rules](visualizations.md) |
-| `<Figure id="…" title="…" caption="…" previewable>` | `explico/components/figure/Figure.astro` | `fig-` | [structure.md](structure.md#numbering), [V2](visualizations.md#v2)/[V3](visualizations.md#v3) |
-| `<Diagram id="…" label="…" nodes={…} edges={…}>` | `explico/components/diagram/Diagram.astro` | `dia-` | [V1](visualizations.md#v1) |
-| A display equation with `\label{eq:key}` | `remark-math` (built in) | `eq-` | [N5](notation.md#n5), [structure.md](structure.md#numbering) |
-
-Two naming traps worth flagging for an AI author:
-
-- **`<Figure title="…">` is a visible short label in the collapsible title
-  bar, not the HTML `title` attribute's hover tooltip.** It always renders on
-  the page; it is a different feature from the [native tooltip](#inline-zero-registration)
-  above even though it reuses the same prop name. Keep it short — the whole
-  caption sentence does not belong here; see [S1](structure-rules.md#s1). An
-  omitted `title` silently falls back to `caption` in full, which is exactly
-  the failure S1 exists to catch.
+| `<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) |
+| 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
+
+Every float is named the same way, LaTeX's `\caption[short]{long}`: a long
+**`caption`** and an optional **`short`** caption. Nothing else names a float
+— no `title`, no `label`, no `summary` — and a figure or a diagram has no
+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 |
+| `<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 |
+
+`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.
+
+A figure's, a table's or a diagram's `short` is its name wherever the page
+names it (docs/plans/figures-and-short-captions.md, decision 9): the bold
+title that opens its caption line — "**Sampled flight data.** Position, …",
+with a period added unless it ends in punctuation of its own — a folded
+section's "Hidden here: **Figure 2.1.1** Projectile trajectory explorer, 2
+paragraphs", a `<Fold>`'s bar, and a copied link, which says "Link copied ·
+Figure 2.1.1 · Projectile trajectory explorer" and pastes into a document as
+a link reading "Figure 2.1.1, Projectile trajectory explorer". A float
+without one is named by its number alone, and counted, not named, in a
+folded section's line. So give each figure, table and diagram a `short`
+that names it, and write the long caption to go on from that name instead
+of restating it ([rule S9](structure-rules.md#s9)). A memo's or an
+equation's `short` stays optional: its caption already names it where it
+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
+  [`<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
+  default slot is its picture; a `tools` slot (`<Fragment slot="tools">…`,
+  or an island with `slot="tools"`) renders after the caption line in a tray
+  of its own. The fold button ⌃ / ⌄ ends the caption line; folded, the tools
+  leave a "Hidden here: 2 sliders, 1 equation" line that unfolds them. On a
+  `<Figure>`, `defaultOpen` (default: the course's `disclosure.figures`) and
+  `rememberState` (default `true`) are about the tools; a figure without
+  them has no button and no tray, and a `<Diagram>` has neither prop. The
+  caption line ends with a live clause a lab writes with `setFigureState`
+  ([visualizations.md § V3](visualizations.md#v3)).
+- **A lab has no title or caption of its own.** The `<Figure>` around it
+  names the whole ([visualizations.md § Labs](visualizations.md#v3)).
 - **A raw Markdown pipe table or a raw `<table>`, or a `<Diagram>` with no
   `id`,** renders fine but never enters keyed-float validation — no number,
   no `[[…]]` target. Wrap it (`<Table>`/`<Figure>`) or give the diagram an
   `id` if it needs to be referenced. See [structure.md § Raw and unwrapped
   floats](structure.md#raw-and-unwrapped-floats).
 
+_Enforcement._ A `<Figure title>`, a `<Diagram label>` (or `title`,
+`defaultOpen`, `rememberState`), a `<Memo title>` / `description` and a
+`<CompactExamples summary>` fail the build with the edit to make: `fig-removed-prop` / `dia-removed-prop` /
+`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.
+
+### The "Figures and tables" page
+
+`explico/components/FloatIndex.astro` lists every numbered figure, table and
+diagram that has an `id` — LaTeX's `\listoffigures` and `\listoftables` in
+one — by part and chapter, each entry its number linked to the float and its
+short caption; a float without one is listed by its long caption, muted, or
+by its number alone when its captions live in a wrapper component. Put it on
+a top-level page named `figures-and-tables.mdx`, and the sidebar's Reference
+group lists the page beside the curriculum map and the glossary:
+
+```mdx
+---
+title: Figures and tables
+description: Every numbered figure, table and diagram of the course.
+editorialStatus: draft
+---
+
+import FloatIndex from 'explico/components/FloatIndex.astro';
+
+<FloatIndex />
+```
+
 ## Reference systems
 
 These bind a term to a definition that a reader can hover *and* look up
@@ -111,15 +217,59 @@ 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.config.ts` `abbreviations.allow` | Hover/click card on first occurrence, linked to the glossary page | [N14](notation.md#n14) |
+| 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` |
+| `[[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) |
 
 ## Knowledge checks and worked examples
 
 | Component | Import | Notes | Doc |
 | --- | --- | --- | --- |
-| `<AssessmentSet />` | `explico/components/assessments/AssessmentSet.astro` | Renders every check listed in the lesson's colocated `.checks.yml`; do not add a separate heading for it | [structure.md § Knowledge checks](structure.md#knowledge-checks) |
-| `<CompactExample>` / `<CompactExamples>` | `explico/components/examples/CompactExample.astro` | Worked-example cards; a `<Diagram>` nested inside one is invisible to diagram numbering (see the raw/unwrapped note above) | [structure.md](structure.md#raw-and-unwrapped-floats) |
+| `<AssessmentSet />` | `explico/components/assessments/AssessmentSet.astro` | Renders every check listed in the lesson's colocated `.checks.yml`, each under its own heading; do not add a heading for it | [structure.md § Knowledge checks](structure.md#knowledge-checks) |
+| `<CompactExamples id short>` + `<CompactExample label>` | `explico/components/examples/CompactExamples.astro`, `…/CompactExample.astro` | A numbered set of worked examples, one tab each; do not add a heading for it. A `<Diagram>` nested inside one is invisible to diagram numbering (see the raw/unwrapped note above) | [structure.md § Worked examples](structure.md#worked-examples) |
+
+**You write the topic; the engine writes the kind.** A knowledge check and a
+worked-example set each draw their own `<h2>`: the kind's icon, then your
+title, with a small label naming the kind and its number — "KNOWLEDGE CHECK
+1.1.1", "EXAMPLE 1.1.1" — in the card's top-right corner. The check's title
+is the `title` of its assessment file, the set's is its `short`. Write the
+topic alone ("Position and coordinates"), never "Knowledge check: …" or
+"Worked examples".
+
+```mdx
+<CompactExamples id="coordinate-conversions" short="Calculation examples between coordinate systems">
+<CompactExample label="Cartesian to polar">
+…
+</CompactExample>
+<CompactExample label="Polar to Cartesian">
+…
+</CompactExample>
+</CompactExamples>
+```
+
+renders as **⊞ Calculation examples between coordinate systems** under an
+"EXAMPLE 1.1.1" corner label, with the examples as tabs below it. The label
+sits outside the text flow, so the title keeps the whole line.
+
+- **Numbered like a float, shown like a section.** A set is `Example
+  ‹part›.‹chapter›.‹n›` and a check `Knowledge check ‹part›.‹chapter›.‹n›`, each
+  counting on its own (`numbering.floats`). The numbers follow the section
+  numbers' rules, since both blocks are sections of the page: shown on a wide
+  screen, in print and on a folded bar, hidden on a narrow screen, and never
+  when `numbering.sections.show` is off — then `[[ex-…]]` and `[[check-…]]`
+  print the title instead of the number.
+- **Sections of the outline.** Each heading is a `##`: "On this page" lists
+  it by its title with the badge's icon, it ends the section before it, it
+  folds with the section chevron (`disclosure.knowledgeChecks`,
+  `disclosure.workedExamples`), its chain icon copies its link, and rules
+  [S6](structure-rules.md#s6) and [S7](structure-rules.md#s7) read it as a
+  `##` — place a set where a `##` section could start, and write no heading
+  directly above it.
+- **The label's form is a course setting**, `blockLabels`: `icon-word` (the
+  default) or `icon`, which leaves the corner label to the number and keeps
+  the word for a screen reader.
 
 ## Choosing between the "explain a term" options
 
@@ -136,3 +286,9 @@ From lightest to heaviest — pick the first one that's actually enough:
 4. **`<Memo>`** — numbered, permalinked, holds real sub-content (proofs,
    figures, tables). Use when the aside is long enough to be its own small
    section.
+
+Industry jargon — an informal expression with no standard definition — is
+not explained by a tooltip or an abbreviation card alone. It gets a
+`<ShortNote>` or `<Memo>` labelled "Industry jargon" that states its
+approximate meaning, context of use, and standardization; see
+[P6](prose.md#p6).