explico 0.5.0 → 0.6.0

package/src/components/notation/NotationLayer.astro

@@ -42,6 +42,10 @@ export interface Props {
    * links to reveal an explanation on hover.
    */
   presentation?: 'full' | 'panel';
+  /** Author-chosen state for a reader with nothing saved yet. Default: `false` (closed) — see `docs/authoring` on `CourseConfig.disclosureDefaults`. */
+  defaultOpen?: boolean;
+  /** Persist the reader's open/closed choice across visits, per page. Default: `true`. */
+  rememberState?: boolean;
 }
 
 import NotationMath from './NotationMath.astro';
@@ -55,6 +59,8 @@ const {
   label = 'Notation used on this page',
   glossaryHref = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`,
   presentation = 'full',
+  defaultOpen = false,
+  rememberState = true,
 } = Astro.props;
 
 const panelOnly = presentation === 'panel';
@@ -111,16 +117,16 @@ for (const gloss of glossItems) {
       class:list={['notation-layer', panelOnly && 'notation-layer--panel-only']}
       data-notation-layer
       data-notation-layer-id={id}
-      aria-labelledby={panelOnly ? undefined : `${id}-heading`}
-      aria-label={panelOnly ? 'Notation explanations' : undefined}
+      aria-label={panelOnly ? 'Notation explanations' : label}
     >
-      {!panelOnly && (
-        <h2 id={`${id}-heading`} class="notation-layer-heading">
-          Page notation
-        </h2>
-      )}
-
-      <details class="notation-list" hidden={panelOnly}>
+      <div class="notation-list-titlebar">
+      <details
+        class="notation-list"
+        id={id}
+        hidden={panelOnly}
+        data-remember-state={String(rememberState)}
+        open={defaultOpen}
+      >
         <summary>
           {label} <span class="notation-count">({items.length})</span>
         </summary>
@@ -183,16 +189,6 @@ for (const gloss of glossItems) {
                     <strong>Units:</strong> {definition.units}
                   </p>
                 )}
-                <button
-                  class="notation-pin"
-                  type="button"
-                  data-notation-control={definition.key}
-                  aria-expanded="false"
-                  aria-pressed="false"
-                  hidden
-                >
-                  Pin explanation
-                </button>
               </dd>
             </div>
           ))}
@@ -216,14 +212,32 @@ for (const gloss of glossItems) {
           </div>
         ))}
       </details>
+      {!panelOnly && (
+        <a
+          class="notation-list-anchor"
+          href={`#${id}`}
+          aria-label={`${label}, titled section`}
+        >
+          <svg
+            aria-hidden="true"
+            width="16"
+            height="16"
+            viewBox="0 0 24 24"
+            fill="currentColor"
+            ><path
+              d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42"
+            ></path></svg
+          >
+        </a>
+      )}
+      </div>
 
       {!panelOnly && (
         <p class="notation-enhancement-help" data-notation-help hidden>
           Point to a marked symbol for a quick explanation, or use the list
           above — pointing at a symbol inside an open card explains that one
-          too, alongside it. Click a symbol, or select “Pin explanation”, to
-          keep a card open; click the card (or its “×”) to close it, or press
-          Escape.
+          too, alongside it. Click a symbol to keep its card open; click the
+          card (or its “×”) to close it, or press Escape.
         </p>
       )}
 
@@ -270,6 +284,7 @@ for (const gloss of glossItems) {
 
 <script>
   import { createPopupStack, closestElement } from '../popup-stack';
+  import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
 
   const triggerSelector = '[data-notation-key]';
 
@@ -296,10 +311,6 @@ for (const gloss of glossItems) {
     );
     if (!template) return;
 
-    const controls = Array.from(
-      root.querySelectorAll<HTMLButtonElement>('[data-notation-control]'),
-    );
-
     // Static triggers, computed once: markers embedded in prose or an
     // equation, and the symbol glyphs in the "Notation used on this page"
     // list. These get the always-on `.notation-trigger` cursor/hover
@@ -324,20 +335,32 @@ for (const gloss of glossItems) {
     for (const trigger of highlightTargets) {
       trigger.classList.add('notation-trigger');
     }
-    for (const control of controls) control.hidden = false;
     const help = root.querySelector<HTMLElement>('[data-notation-help]');
     if (help) help.hidden = false;
 
-    const keyFor = (element: HTMLElement | null) =>
-      element?.dataset.notationKey ??
-      element?.dataset.notationControl ??
-      element?.dataset.notationLink ??
-      null;
+    // The visible list's own symbol glyphs are the only keyboard path to
+    // pinning a card from this list (the old "Pin explanation" button was
+    // the other one, and is gone) — make them a real, labelled, Enter/Space-
+    // operable control rather than a mouse-only `<span>`. `symbolTriggers`
+    // (defined above) is already scoped to entries inside this list.
+    for (const trigger of symbolTriggers) {
+      const key = trigger.dataset.notationKey ?? '';
+      const entryLabel =
+        entries.get(key)?.querySelector<HTMLElement>('[data-notation-link]')
+          ?.textContent?.trim() ?? key;
+      trigger.setAttribute('role', 'button');
+      trigger.tabIndex = 0;
+      trigger.setAttribute('aria-pressed', 'false');
+      trigger.setAttribute('aria-label', `Pin the ${entryLabel} explanation`);
+      trigger.addEventListener('keydown', (event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        event.preventDefault();
+        trigger.click();
+      });
+    }
 
-    const controlFrom = (node: EventTarget | null) => {
-      const candidate = closestElement(node, '[data-notation-control]');
-      return candidate && root.contains(candidate) ? candidate : null;
-    };
+    const keyFor = (element: HTMLElement | null) =>
+      element?.dataset.notationKey ?? element?.dataset.notationLink ?? null;
 
     const staticLinkFrom = (node: EventTarget | null) => {
       const candidate = closestElement(node, '[data-notation-link]');
@@ -357,7 +380,7 @@ for (const gloss of glossItems) {
     };
 
     const triggerFrom = (node: EventTarget | null) =>
-      controlFrom(node) ?? staticLinkFrom(node) ?? symbolFrom(node);
+      staticLinkFrom(node) ?? symbolFrom(node);
 
     const labelOf = (entry: HTMLElement, key: string) =>
       entry
@@ -465,21 +488,6 @@ for (const gloss of glossItems) {
       return el;
     };
 
-    const updateControls = (
-      open: ReadonlySet<string>,
-      pinned: ReadonlySet<string>,
-    ) => {
-      for (const control of controls) {
-        const key = control.dataset.notationControl ?? '';
-        const selected = pinned.has(key);
-        control.setAttribute('aria-pressed', String(selected));
-        control.setAttribute('aria-expanded', String(open.has(key)));
-        control.textContent = selected
-          ? 'Unpin explanation'
-          : 'Pin explanation';
-      }
-    };
-
     createPopupStack({
       // Popups are `position: fixed` and float above everything regardless
       // of DOM placement — *except* z-index only ever wins within its own
@@ -493,7 +501,6 @@ for (const gloss of glossItems) {
       triggerFrom,
       keyFor,
       createPopup,
-      pinControlFrom: controlFrom,
       onChange: (open, pinned) => {
         for (const trigger of highlightTargets) {
           trigger.classList.toggle(
@@ -501,15 +508,44 @@ for (const gloss of glossItems) {
             open.has(trigger.dataset.notationKey ?? ''),
           );
         }
-        updateControls(open, pinned);
+        for (const trigger of symbolTriggers) {
+          trigger.setAttribute(
+            'aria-pressed',
+            String(pinned.has(trigger.dataset.notationKey ?? '')),
+          );
+        }
       },
     });
   }
 
+  function setupNotationDisclosure(details: HTMLDetailsElement) {
+    if (details.dataset.disclosureWired === 'true') return;
+    details.dataset.disclosureWired = 'true';
+
+    // Same convention as `Figure.astro`: the SSR-rendered `open` attribute
+    // already carries the author's `defaultOpen` prop verbatim.
+    const defaultOpen = details.open;
+    if (details.dataset.rememberState === 'true') {
+      wirePersistedDetails(details, `notation:${details.id}`, defaultOpen);
+    }
+
+    // Deep-linking to `#page-notation` (the anchor link, or a shared URL)
+    // must reveal it even if a reader left it collapsed.
+    const openIfTargeted = () => {
+      if (location.hash === `#${details.id}`) details.open = true;
+    };
+    openIfTargeted();
+    window.addEventListener('hashchange', openIfTargeted);
+  }
+
   for (const root of document.querySelectorAll<HTMLElement>(
     '[data-notation-layer]',
   )) {
     setupNotationLayer(root);
+    const details = root.querySelector<HTMLDetailsElement>(
+      ':scope > .notation-list-titlebar > .notation-list[id]',
+    );
+    if (details) setupNotationDisclosure(details);
   }
 </script>
 
@@ -526,9 +562,13 @@ for (const gloss of glossItems) {
       margin: 0;
     }
 
-    .notation-layer-heading {
-      margin: 0 0 0.65rem;
-      font-size: var(--sl-text-lg);
+    /* Positioning context for `.notation-list-anchor`, mirroring
+       `Figure.astro`'s `.keyed-figure__titlebar` — the anchor link is a DOM
+       sibling of `<details>`, not nested inside `<summary>` (a focusable `<a>`
+       inside `<summary>` trips axe's `nested-interactive` check the same way
+       it would there). */
+    .notation-list-titlebar {
+      position: relative;
     }
 
     .notation-list {
@@ -539,8 +579,52 @@ for (const gloss of glossItems) {
 
     .notation-list > summary {
       padding: 0.8rem 1rem;
+      padding-inline-end: 2.2rem;
       cursor: pointer;
       font-weight: 600;
+      font-size: var(--sl-text-lg);
+    }
+
+    .notation-list-anchor {
+      position: absolute;
+      top: 0.9rem;
+      inset-inline-end: 1rem;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 1em;
+      height: 1em;
+      font-size: var(--sl-text-lg);
+      color: var(--sl-color-gray-3);
+      text-decoration: none;
+      -webkit-user-select: none;
+      user-select: none;
+    }
+
+    .notation-list-anchor svg {
+      width: 0.7em;
+      height: 0.7em;
+    }
+
+    .notation-list-anchor:hover,
+    .notation-list-anchor:focus-visible {
+      color: var(--sl-color-text-accent);
+    }
+
+    .notation-list-anchor:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 0.15rem;
+    }
+
+    @media (hover: hover) {
+      .notation-list-anchor {
+        opacity: 0;
+      }
+
+      .notation-list-anchor:focus-visible,
+      .notation-list-titlebar:hover .notation-list-anchor {
+        opacity: 1;
+      }
     }
 
     .notation-count,
@@ -594,14 +678,28 @@ for (const gloss of glossItems) {
       cursor: help;
     }
 
+    /* Entries in the visible list are keyboard-operable (Enter/Space pins
+       the same card a click would) now that the list has no separate "Pin
+       explanation" button of its own — see the setup script below. */
+    .notation-entry .notation-symbol-trigger {
+      cursor: pointer;
+    }
+
     .notation-symbol-trigger:hover,
+    .notation-symbol-trigger:focus-visible,
     .notation-symbol-trigger.is-notation-active {
       background: var(--sl-color-accent-low);
       box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
     }
 
+    .notation-symbol-trigger:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 0.1em;
+    }
+
     @media (forced-colors: active) {
       .notation-symbol-trigger:hover,
+      .notation-symbol-trigger:focus-visible,
       .notation-symbol-trigger.is-notation-active {
         outline: 2px solid Highlight;
         color: HighlightText;
@@ -634,24 +732,6 @@ for (const gloss of glossItems) {
       color: var(--sl-color-text);
     }
 
-    .notation-pin {
-      justify-self: start;
-      padding: 0.25rem 0.55rem;
-      border: 1px solid var(--sl-color-gray-5);
-      border-radius: 0.35rem;
-      color: var(--sl-color-text-accent);
-      background: var(--sl-color-bg);
-      font: inherit;
-      font-size: var(--sl-text-sm);
-      cursor: pointer;
-    }
-
-    .notation-pin:hover,
-    .notation-pin[aria-pressed='true'] {
-      border-color: var(--sl-color-accent);
-      background: var(--sl-color-accent-low);
-    }
-
     .notation-enhancement-help {
       margin: 0.55rem 0 0;
       font-size: var(--sl-text-xs);

package/src/components/starlight/LessonFooter.astro

@@ -40,8 +40,10 @@ const lessonId = isLessonSlug(routeSlug)
 const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
 
 const definitions: NotationLayerDefinition[] = [];
+let notationDefaultOpen = false;
 if (lessonId) {
   const manifest = await loadManifest();
+  notationDefaultOpen = manifest.disclosureDefaults.notation;
   const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
   const routeData = Astro.locals.starlightRoute.entry.data as {
     notation?: { local?: readonly { key?: unknown }[] };
@@ -80,7 +82,7 @@ if (lessonId) {
 }
 ---
 
-<NotationLayer definitions={definitions} />
+<NotationLayer definitions={definitions} defaultOpen={notationDefaultOpen} />
 {lessonId && <CitationLayer />}
 {lessonId && <AbbreviationLayer />}
 {lessonId && <KeyedFloatEnhancer />}

package/src/content-config.ts

@@ -196,6 +196,21 @@ const assessmentItemBase = z.object({
   explanation: z.string().min(1),
 });
 
+/**
+ * `AssessmentSet.astro` renders the numbered heading itself — `<h2>Knowledge
+ * check {number} — {title}</h2>` — so `title` must be just the topic. A title
+ * that repeats the "Knowledge check" label duplicates it on every page that
+ * uses `AssessmentSet` (the standalone `AssessmentRunner` heading fallback
+ * reads fine either way, so this only bites the common path).
+ */
+const assessmentTitle = z
+  .string()
+  .min(1)
+  .refine((value) => !/^knowledge check\b/i.test(value), {
+    message:
+      'Assessment title must not start with "Knowledge check" — AssessmentSet already renders "Knowledge check {number} — {title}", so a title with the same prefix duplicates it. Use just the topic, e.g. "AIC and KL risk".',
+  });
+
 const assessments = defineCollection({
   loader: glob({
     pattern: '**/*.json',
@@ -203,7 +218,7 @@ const assessments = defineCollection({
   }),
   schema: z.object({
     id,
-    title: z.string().min(1),
+    title: assessmentTitle,
     editorialStatus,
     items: z
       .array(

package/src/reference/gate-heading-length.ts

@@ -0,0 +1,131 @@
+/**
+ * The heading/title-length gate (rule S1): no Markdown heading (`##`
+ * through `######`) and no `<Figure title>`, `<Diagram label>`, `<Memo
+ * title>`, or `<ShortNote title>` may run past `HEADING_LENGTH_LIMIT`
+ * characters. A long heading or float title is usually a full sentence that
+ * belongs in the body paragraph (for a heading) or the `caption` (for a
+ * float) instead — see docs/authoring/structure-rules.md#s1.
+ *
+ * `<Table>` is deliberately not covered: it has only a `caption`, no
+ * separate `title`, and that caption is the LaTeX-convention full sentence
+ * shown above the table — capping it would fight the rule that puts it
+ * there. `<Figure>`'s `caption` is the same full sentence; only its short
+ * `title` (the text on the collapsible title bar) is in scope.
+ *
+ * A lesson's own `#` (its `frontmatter.title`, rendered as the page H1 by
+ * Starlight) is Review-only — it never appears in `lesson.body`, so this
+ * build-time gate, which only scans body text, cannot see it.
+ *
+ * Ships straight as an error, same as N9/N14: no partial corpus to absorb,
+ * no `lint-ignore.yml` entry.
+ */
+import { stripFencedCode } from './equations.mjs';
+import type { MathGateDiagnostic } from './gate-math';
+import { lineOf } from './gate-prose-notation';
+import type { NotationLessonInput } from './types';
+
+export const HEADING_LENGTH_LIMIT = 65;
+
+// ATX heading: 1-6 `#`, then the text, with any trailing closing `#`s
+// trimmed off (the `# text #` form CommonMark also allows).
+const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
+
+// The JSX attribute that reads as a float's own short title, per component.
+// `Table` has no entry — see the module doc comment.
+const TITLE_ATTRIBUTE_BY_TAG: Record<string, string> = {
+  Figure: 'title',
+  Diagram: 'label',
+  Memo: 'title',
+  ShortNote: 'title',
+};
+
+interface Finding {
+  readonly index: number;
+  readonly token: string;
+  readonly message: string;
+}
+
+function readAttribute(attributesSource: string, name: string): string | undefined {
+  const pattern = new RegExp(`\\b${name}\\s*=\\s*(["'])([^"']*)\\1`);
+  const match = pattern.exec(attributesSource);
+  return match ? match[2] : undefined;
+}
+
+function overLimitMessage(kind: string, text: string): string {
+  return (
+    `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ` +
+    `${HEADING_LENGTH_LIMIT}-character limit (rule S1). Shorten it and move ` +
+    'the rest into the paragraph or caption that follows.'
+  );
+}
+
+function headingFindings(text: string): Finding[] {
+  const out: Finding[] = [];
+  const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(text))) {
+    const level = match[1]?.length ?? 1;
+    const title = (match[2] ?? '').trim();
+    if (title.length > HEADING_LENGTH_LIMIT) {
+      out.push({
+        index: match.index,
+        token: title,
+        message: overLimitMessage(`${'#'.repeat(level)} heading`, title),
+      });
+    }
+  }
+  return out;
+}
+
+function floatTitleFindings(text: string): Finding[] {
+  const out: Finding[] = [];
+  for (const [tagName, attribute] of Object.entries(TITLE_ATTRIBUTE_BY_TAG)) {
+    const opening = new RegExp(`<${tagName}\\b([^>]*)>`, 'g');
+    let match: RegExpExecArray | null;
+    while ((match = opening.exec(text))) {
+      const value = readAttribute(match[1] ?? '', attribute)?.trim();
+      if (value && value.length > HEADING_LENGTH_LIMIT) {
+        out.push({
+          index: match.index,
+          token: value,
+          message: overLimitMessage(`<${tagName} ${attribute}>`, value),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/** Every S1 finding in one lesson body, in source order. */
+function findingsIn(text: string): Finding[] {
+  return [...headingFindings(text), ...floatTitleFindings(text)].sort(
+    (a, b) => a.index - b.index,
+  );
+}
+
+/**
+ * Scan every lesson body for a heading or a keyed float's title running past
+ * `HEADING_LENGTH_LIMIT` characters. Returns one `MathGateDiagnostic`
+ * (context `'structure'`, always an error) per finding.
+ */
+export function gateHeadingLength(
+  lessons: readonly NotationLessonInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const lesson of lessons) {
+    const text = stripFencedCode(lesson.body);
+    for (const finding of findingsIn(text)) {
+      diagnostics.push({
+        context: 'structure',
+        severity: 'error',
+        file: lesson.source.file,
+        line: lineOf(lesson.body, finding.index),
+        token: finding.token,
+        message: finding.message,
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/gate-math.ts

@@ -20,7 +20,7 @@ import type {
 } from './types';
 
 export interface MathGateDiagnostic {
-  readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation';
+  readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
   /**
    * Body / component-slot math blocks the build (the render path needs every
    * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
@@ -38,7 +38,11 @@ export interface MathGateDiagnostic {
    * same change that introduced the check. `abbreviation` (N14,
    * `gate-abbreviations.ts`) is the same "ships straight as an error" story
    * for a different shape of plain-text token — an unexplained acronym or
-   * dotted abbreviation, rather than a mis-typed quantity/unit.
+   * dotted abbreviation, rather than a mis-typed quantity/unit. `structure`
+   * (S1, `gate-heading-length.ts`) is unrelated to notation — it caps how
+   * long a heading or a keyed float's title may run — but reuses this same
+   * diagnostic shape and the one `manifest.diagnostics.math` array rather
+   * than adding a second array the CLI has to know about.
    */
   readonly severity: 'error' | 'warning';
   readonly file: string;
@@ -53,6 +57,7 @@ const SEVERITY: Record<MathGateDiagnostic['context'], 'error' | 'warning'> = {
   assessment: 'error',
   prose: 'error',
   abbreviation: 'error',
+  structure: 'error',
 };
 
 interface AssessmentItemLike {