explico 0.7.0 → 0.11.0

package/src/components/PartOverview.astro

@@ -0,0 +1,401 @@
+---
+/**
+ * A part's own page: the chapters it holds, in reading order, beside the
+ * dependency rail that says where the part sits in the course.
+ *
+ * Everything here is read from the compiler manifest and the competency
+ * collection — chapter order, titles, descriptions, float counts, and which
+ * parts this one builds on or feeds. A course authors the page's prose; it
+ * never re-types the list, so a renamed chapter or a new prerequisite cannot
+ * leave a stale copy behind on the part page.
+ *
+ * Usage, in `content/docs/<part>/index.mdx`:
+ *
+ * ```mdx
+ * ---
+ * title: 'L1 · Foundations & ANOVA'
+ * description: Where the course fixes its prediction target.
+ * ---
+ *
+ * import PartOverview from 'explico/components/PartOverview.astro';
+ * import PartScope from 'explico/components/PartScope.astro';
+ *
+ * <PartScope>
+ *
+ * Authored introduction — what this part is for. Every part after the first
+ * also opens with a `<PartBridge>` paragraph (rule S2).
+ *
+ * </PartScope>
+ *
+ * <PartOverview
+ *   chain={[
+ *     'The conditional mean minimises squared error',
+ *     'Its residual is orthogonal to every function of X',
+ *     'So total variance splits between and within',
+ *   ]}
+ * />
+ * ```
+ */
+import { getCollection } from 'astro:content';
+import { loadManifest, type ManifestPart } from '../compiler/manifest';
+
+interface Props {
+  /**
+   * The part directory. Defaults to the directory of the page being rendered,
+   * which is what a part's own `index.mdx` wants.
+   */
+  readonly part?: string;
+  /**
+   * The part's argument in order, one step per line — the thread that runs
+   * through its chapters. Authored, because no manifest field knows why one
+   * chapter follows another.
+   */
+  readonly chain?: readonly string[];
+  /** Set `false` to drop the rail and keep only the reading list. */
+  readonly rail?: boolean;
+}
+
+const { part: partProp, chain = [], rail = true } = Astro.props;
+
+const routeSlug = Astro.locals.starlightRoute.entry.id;
+const partDir = partProp ?? routeSlug.replace(/\/index$/, '').split('/')[0];
+
+const [manifest, competencyEntries] = await Promise.all([
+  loadManifest(),
+  getCollection('competencies'),
+]);
+
+const part = manifest.parts.find((entry) => entry.dir === partDir);
+if (!part) {
+  throw new Error(
+    `<PartOverview> found no part "${partDir}". Parts come from ` +
+      '`courseConfig.parts`; pass `part="<dir>"` when rendering this ' +
+      'component outside a part directory.',
+  );
+}
+
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+const lessonById = new Map(
+  manifest.lessons.map((lesson) => [lesson.id, lesson]),
+);
+const chapters = part.lessons
+  .map((id) => lessonById.get(id))
+  .filter((lesson): lesson is NonNullable<typeof lesson> => lesson !== undefined);
+
+const competencyById = new Map(
+  competencyEntries.map(({ data }) => [data.id, data]),
+);
+
+const taught = new Set(chapters.flatMap((lesson) => lesson.teaches));
+const required = new Set(
+  chapters.flatMap((lesson) => lesson.requires).filter((id) => !taught.has(id)),
+);
+
+/** The part each competency is taught in — how a rail edge finds its page. */
+const partByCompetency = new Map<string, ManifestPart>();
+for (const other of manifest.parts) {
+  for (const lessonId of other.lessons) {
+    for (const competencyId of lessonById.get(lessonId)?.teaches ?? []) {
+      if (!partByCompetency.has(competencyId)) {
+        partByCompetency.set(competencyId, other);
+      }
+    }
+  }
+}
+
+const partsFor = (competencyIds: Iterable<string>): ManifestPart[] => {
+  const seen = new Map<string, ManifestPart>();
+  for (const id of competencyIds) {
+    const owner = partByCompetency.get(id);
+    if (owner && owner.dir !== part.dir) seen.set(owner.dir, owner);
+  }
+  return [...seen.values()].sort((a, b) => a.ordinal - b.ordinal);
+};
+
+const buildsOn = partsFor(required);
+const leadsTo = manifest.parts
+  .filter((other) => other.dir !== part.dir)
+  .filter((other) =>
+    other.lessons.some((lessonId) =>
+      (lessonById.get(lessonId)?.requires ?? []).some((id) => taught.has(id)),
+    ),
+  )
+  .sort((a, b) => a.ordinal - b.ordinal);
+
+const outcomes = [...taught]
+  .map((id) => competencyById.get(id)?.outcome)
+  .filter((outcome): outcome is string => typeof outcome === 'string');
+
+const equationCount = chapters.reduce(
+  (total, lesson) => total + lesson.equations.length,
+  0,
+);
+const checkCount = chapters.reduce(
+  (total, lesson) => total + lesson.knowledgeChecks.length,
+  0,
+);
+
+const partLink = (target: ManifestPart) =>
+  target.overview ? `${base}${target.link}` : undefined;
+
+/** `30–40 min`, or `40 min` when the estimate is a single number. */
+const minutes = (range: { min: number; max: number }) =>
+  range.min === range.max
+    ? `${range.min} min`
+    : `${range.min}–${range.max} min`;
+const hasRail =
+  rail &&
+  (chain.length > 0 ||
+    outcomes.length > 0 ||
+    buildsOn.length > 0 ||
+    leadsTo.length > 0);
+---
+
+<div class="part-overview not-content" data-rail={hasRail ? '' : undefined}>
+  <p class="part-meta">
+    <span>Part {part.ordinal} of {manifest.parts.length}</span>
+    <span>{chapters.length} {chapters.length === 1 ? 'chapter' : 'chapters'}</span>
+    {part.studyMinutes && <span>{minutes(part.studyMinutes)}</span>}
+    {equationCount > 0 && <span>{equationCount} numbered equations</span>}
+    {
+      checkCount > 0 && (
+        <span>
+          {checkCount} knowledge {checkCount === 1 ? 'check' : 'checks'}
+        </span>
+      )
+    }
+  </p>
+
+  <div class="part-body">
+    <ol class="part-chapters">
+      {
+        chapters.map((lesson) => (
+          <li>
+            <a href={`${base}/${lesson.slug}/`}>{lesson.title}</a>
+            <p>{lesson.description}</p>
+            <p class="chapter-meta">
+              {lesson.studyMinutes && (
+                <span class="chapter-time">{minutes(lesson.studyMinutes)}</span>
+              )}
+              {lesson.equations.length > 0 && (
+                <span>
+                  {lesson.equations.length} equation
+                  {lesson.equations.length === 1 ? '' : 's'}
+                </span>
+              )}
+              {lesson.knowledgeChecks.length > 0 && (
+                <span>
+                  {lesson.knowledgeChecks.length} check
+                  {lesson.knowledgeChecks.length === 1 ? '' : 's'}
+                </span>
+              )}
+              {lesson.status !== 'reviewed' && <span>{lesson.status}</span>}
+            </p>
+          </li>
+        ))
+      }
+    </ol>
+
+    {
+      hasRail && (
+        <aside class="part-rail ex-tier-meta" aria-label={`About ${part.label}`}>
+          {chain.length > 0 && (
+            <section>
+              <h2>The argument</h2>
+              <ol class="part-chain">
+                {chain.map((step) => (
+                  <li>{step}</li>
+                ))}
+              </ol>
+            </section>
+          )}
+          {outcomes.length > 0 && (
+            <section>
+              <h2>After this part you can</h2>
+              <ul>
+                {outcomes.map((outcome) => (
+                  <li>{outcome}</li>
+                ))}
+              </ul>
+            </section>
+          )}
+          {buildsOn.length > 0 && (
+            <section>
+              <h2>Builds on</h2>
+              <ul>
+                {buildsOn.map((other) => (
+                  <li>
+                    {partLink(other) ? (
+                      <a href={partLink(other)}>{other.label}</a>
+                    ) : (
+                      other.label
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )}
+          {leadsTo.length > 0 && (
+            <section>
+              <h2>Leads to</h2>
+              <ul>
+                {leadsTo.map((other) => (
+                  <li>
+                    {partLink(other) ? (
+                      <a href={partLink(other)}>{other.label}</a>
+                    ) : (
+                      other.label
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )}
+        </aside>
+      )
+    }
+  </div>
+</div>
+
+<style>
+  .part-overview {
+    margin-block-start: 1.5rem;
+  }
+
+  .part-meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.3rem 1rem;
+    margin: 0 0 1.25rem;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-xs);
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+
+  .part-body {
+    display: grid;
+    gap: 1.75rem;
+    align-items: start;
+  }
+
+  .part-overview[data-rail] .part-body {
+    grid-template-columns: minmax(0, 1.5fr) minmax(0, 1fr);
+  }
+
+  @media (max-width: 62rem) {
+    .part-overview[data-rail] .part-body {
+      grid-template-columns: minmax(0, 1fr);
+    }
+  }
+
+  .part-chapters {
+    counter-reset: chapter;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    border-block-start: 1px solid var(--sl-color-gray-5);
+  }
+
+  .part-chapters > li {
+    counter-increment: chapter;
+    display: grid;
+    grid-template-columns: 2.25rem minmax(0, 1fr);
+    gap: 0.15rem 0.5rem;
+    margin: 0;
+    padding-block: 0.85rem;
+    border-block-end: 1px solid var(--sl-color-gray-5);
+  }
+
+  .part-chapters > li::before {
+    content: counter(chapter, decimal-leading-zero);
+    grid-row: 1 / span 3;
+    color: var(--sl-color-text-accent);
+    font-variant-numeric: tabular-nums;
+    font-size: var(--sl-text-xs);
+    line-height: 1.7;
+  }
+
+  .part-chapters > li > a {
+    font-weight: 600;
+    text-decoration: none;
+  }
+
+  .part-chapters > li > a:hover,
+  .part-chapters > li > a:focus-visible {
+    text-decoration: underline;
+  }
+
+  .part-chapters > li > p {
+    margin: 0;
+    color: var(--sl-color-gray-2);
+    font-size: var(--sl-text-sm);
+    line-height: 1.5;
+  }
+
+  .chapter-meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.2rem 0.75rem;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-xs);
+  }
+
+  .chapter-meta:empty {
+    display: none;
+  }
+
+  /* The estimate is the number a reader plans around, so it leads the row. */
+  .chapter-time {
+    color: var(--sl-color-text-accent);
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* Part logistics: the meta tier (`ex-tier-meta`, `surfaces.css`) draws
+     the rail's surface, border and radius. */
+  .part-rail {
+    display: grid;
+    gap: 1rem;
+    padding: 1rem 1.1rem;
+  }
+
+  .part-rail section {
+    display: grid;
+    gap: 0.4rem;
+  }
+
+  .part-rail h2 {
+    margin: 0;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-xs);
+    font-weight: 500;
+    letter-spacing: 0.07em;
+    text-transform: uppercase;
+  }
+
+  .part-rail ul,
+  .part-rail ol {
+    margin: 0;
+    padding-inline-start: 1.1rem;
+    display: grid;
+    gap: 0.3rem;
+    font-size: var(--sl-text-sm);
+    line-height: 1.45;
+  }
+
+  .part-rail li {
+    margin: 0;
+  }
+
+  .part-chain {
+    list-style: none;
+    padding-inline-start: 0;
+  }
+
+  .part-chain > li + li::before {
+    content: '\2193';
+    display: block;
+    color: var(--sl-color-gray-4);
+    line-height: 1.1;
+  }
+</style>

package/src/components/PartScope.astro

@@ -0,0 +1,27 @@
+---
+/**
+ * The paragraph on a part's overview page that says what this part itself
+ * covers — the question it answers, and how its chapters answer it. Rule S2
+ * requires one on every part page, after `<PartBridge>` when there is one;
+ * `gate-part-pages.ts` checks that it holds one paragraph within the course's
+ * `partPages.scope` word range.
+ *
+ * Usage, in `content/docs/<part>/index.mdx`:
+ *
+ * ```mdx
+ * import PartScope from 'explico/components/PartScope.astro';
+ *
+ * <PartScope>
+ *
+ * This part applies those results to one problem: a projectile launched over
+ * level ground. …
+ *
+ * </PartScope>
+ * ```
+ *
+ * Keep a blank line inside each tag, so the paragraph is parsed as Markdown
+ * and its math and `[[key]]` references render.
+ */
+---
+
+<div class="part-intro part-scope" data-part-intro="scope"><slot /></div>

package/src/components/abbreviation/AbbreviationLayer.astro

@@ -1,18 +1,18 @@
 ---
 /**
- * Hover/pin panel for the inline abbreviation links `remarkAbbreviations`
- * emits (N14, close sibling of `CitationLayer.astro`). The links are real
- * anchors to the glossary's "Abbreviations" section and work with no
- * JavaScript; this island only adds a quick look at the resolution without
- * leaving the reader's place.
+ * Cards for the inline abbreviation links `remarkAbbreviations` emits (N14,
+ * close sibling of `CitationLayer.astro`). The links are real anchors to the
+ * glossary's "Abbreviations" section and work with no JavaScript; this
+ * island only adds a quick look at the resolution without leaving the
+ * reader's place.
  *
  * The abbreviations table is small by nature (a name + one-line resolution
  * each), so unlike the math-notation layer this renders every entry
  * unconditionally on every lesson page — one hidden block per entry — rather
- * than computing a per-page dependency closure. The panel reads its content
+ * than computing a per-page dependency closure. A card reads its content
  * from that static markup, never from a second serialized copy of the table.
- * Positioning, pin, Escape, and outside-close come from the shared
- * `HoverPanel` primitive.
+ * Opening, pinning, Escape and placement come from the card manager
+ * (`../card-manager.ts`).
  */
 import { getCollection } from 'astro:content';
 import HoverPanel from '../HoverPanel.astro';
@@ -21,11 +21,11 @@ const entries = await getCollection('abbreviations');
 ---
 
 <HoverPanel id="abbreviation-panel" label="Abbreviation" data-abbreviation-panel>
+  <p class="abbreviation-panel-term" data-panel-term slot="heading"></p>
   <div class="abbreviation-panel-body">
-    <p class="abbreviation-panel-term" data-panel-term></p>
     <p class="abbreviation-panel-expansion" data-panel-expansion></p>
     <a class="abbreviation-panel-jump" data-panel-jump
-      >See it in the glossary</a
+      >Go to the glossary<span aria-hidden="true" data-jump-arrow> →</span></a
     >
   </div>
 </HoverPanel>
@@ -39,55 +39,52 @@ const entries = await getCollection('abbreviations');
 }
 
 <script>
-  import { createHoverPanel, closestElement } from '../hover-panel';
+  import { cloneCardShell, registerCardSource } from '../card-manager';
+  import { wireJumpArrow } from '../card-jump';
 
-  function setup() {
-    const panel = document.querySelector<HTMLElement>(
-      '[data-abbreviation-panel]',
-    );
-    if (!panel || panel.dataset.hoverPanelReady === 'true') return;
-
-    const markers = Array.from(
-      document.querySelectorAll<HTMLAnchorElement>(
-        '.sl-markdown-content a.abbreviation-term[data-abbr-key]',
-      ),
-    );
-    if (markers.length === 0) return;
-    const markerSet = new Set<HTMLElement>(markers);
-
-    const term = panel.querySelector<HTMLElement>('[data-panel-term]')!;
-    const expansion = panel.querySelector<HTMLElement>(
-      '[data-panel-expansion]',
-    )!;
-    const jump = panel.querySelector<HTMLAnchorElement>('[data-panel-jump]')!;
-
-    const markerFrom = (node: EventTarget | null) => {
-      const candidate = closestElement(
-        node,
-        'a.abbreviation-term[data-abbr-key]',
-      );
-      return candidate && markerSet.has(candidate) ? candidate : null;
-    };
+  function closestElement(node: EventTarget | null, selector: string) {
+    return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
+  }
 
-    // Fill the panel from the matching hidden `[data-abbr-entry]` block —
-    // never from a second serialized copy of the table.
-    const render = (marker: HTMLElement, key: string) => {
-      const entry = document.querySelector<HTMLElement>(
-        `[data-abbr-entry="${CSS.escape(key)}"]`,
-      );
-      if (!entry) return false;
+  const entryFor = (key: string) =>
+    document.querySelector<HTMLElement>(`[data-abbr-entry="${CSS.escape(key)}"]`);
+
+  function setup() {
+    const template = document.getElementById('abbreviation-panel');
+    if (
+      !(template instanceof HTMLTemplateElement) ||
+      template.dataset.cardSourceReady === 'true' ||
+      !document.querySelector('a.abbreviation-term[data-abbr-key]')
+    ) {
+      return;
+    }
+    template.dataset.cardSourceReady = 'true';
+
+    // Fill a card from the matching hidden `[data-abbr-entry]` block — never
+    // from a second serialized copy of the table.
+    const render = (key: string, marker: HTMLElement) => {
+      const entry = entryFor(key);
+      const el = cloneCardShell(template);
+      const term = el?.querySelector<HTMLElement>('[data-panel-term]');
+      const expansion = el?.querySelector<HTMLElement>('[data-panel-expansion]');
+      const jump = el?.querySelector<HTMLAnchorElement>('[data-panel-jump]');
+      if (!entry || !el || !term || !expansion || !jump) return null;
 
       term.textContent = marker.textContent ?? '';
       expansion.textContent = entry.textContent ?? '';
       jump.href = marker.getAttribute('href') ?? '#abbreviations';
-      return true;
+      wireJumpArrow(jump);
+      el.setAttribute('aria-label', `Abbreviation: ${term.textContent}`);
+      return el;
     };
 
-    createHoverPanel({
-      panel,
-      groupId: 'abbreviation',
-      triggerFrom: markerFrom,
-      keyFor: (element) => element.dataset.abbrKey ?? null,
+    registerCardSource({
+      layer: 'abbreviation',
+      triggerFrom: (node) => closestElement(node, 'a.abbreviation-term[data-abbr-key]'),
+      itemFor: (marker) => {
+        const key = marker.dataset.abbrKey;
+        return key && entryFor(key) ? key : null;
+      },
       render,
     });
   }
@@ -116,6 +113,7 @@ const entries = await getCollection('abbreviations');
     }
 
     .abbreviation-panel-term {
+      margin: 0;
       font-weight: 600;
     }
 

package/src/components/assessments/AssessmentRunner.tsx

@@ -332,11 +332,6 @@ export default function AssessmentRunner({
   return (
     <section className="assessment-shell" aria-labelledby={headingId}>
       {!labelledBy && <h3 id={headingId}>{title}</h3>}
-      <p className="assessment-progress" aria-live="polite">
-        {answered === 0
-          ? `${items.length} question${items.length === 1 ? '' : 's'}`
-          : `${correct} of ${items.length} correct`}
-      </p>
       <ol className="assessment-list">
         {items.map((item, position) => (
           <Question
@@ -350,6 +345,14 @@ export default function AssessmentRunner({
           />
         ))}
       </ol>
+      {/* The score, once there is one. Empty until the first answer — the
+          list already shows how many questions there are — and under the
+          list, so appearing never pushes down the question just answered.
+          The live region stays in the tree while empty, so the first score
+          is announced. */}
+      <p className="assessment-progress" aria-live="polite">
+        {answered === 0 ? '' : `${correct} of ${items.length} correct`}
+      </p>
     </section>
   );
 }

package/src/components/assessments/AssessmentSet.astro

@@ -1,10 +1,12 @@
 ---
 import { getCollection } from 'astro:content';
 import { loadManifest } from '../../compiler/manifest';
+import { DISCLOSURE_DEFAULTS } from '../../compiler/course-config';
 import type { ContentSegment } from '../../reference/mixed-content';
 import { renderNotationMath } from '../notation/render-notation-math';
 import type { MixedContentNode } from '../notation/render-notation-math';
 import { knowledgeCheckAnchorId } from '../../reference/knowledge-checks.mjs';
+import BlockHeading from '../BlockHeading.astro';
 import AssessmentRunner from './AssessmentRunner';
 
 interface Props {
@@ -26,6 +28,9 @@ const lessonId = Astro.url.pathname
   .replace(/\//g, '.');
 
 const manifest = await loadManifest();
+// A check folds like a section, by the course's `disclosure.knowledgeChecks`
+// (collapsible and open unless the course says otherwise).
+const { knowledgeChecks } = manifest.disclosure ?? DISCLOSURE_DEFAULTS;
 const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
 if (!lesson) {
   throw new Error(
@@ -55,7 +60,9 @@ const entries = ids.map((id, index) => {
     lesson.numbering.checks + lesson.assessments.length + index + 1;
   const number =
     publishedNumber ??
-    (lesson.part > 0 ? `${lesson.part}.${localIndex}` : String(index + 1));
+    (lesson.numbering.prefix
+      ? `${lesson.numbering.prefix}.${localIndex}`
+      : String(index + 1));
   return { entry, number, anchorId: knowledgeCheckAnchorId(id) };
 });
 
@@ -85,34 +92,24 @@ function renderedContent(
 }
 ---
 
+{/* The heading is the engine's (`BlockHeading.astro`): the "Knowledge
+    check" badge and the number before the assessment file's `title`.
+    `card="accent"`: the check is author-marked enrichment, so its heading and
+    questions sit in one accent card (`surfaces.css`), drawn by
+    `CollapsibleSections.astro` the way a `[card]` heading's section is. */}
 {
   entries.map(({ entry, number, anchorId }) => (
     <>
-      <div
-        class="sl-heading-wrapper level-h2 assessment-heading-wrapper"
-        data-collapsible="true"
-        data-default-open="true"
-      >
-        <h2 id={anchorId}>
-          <span class="assessment-heading-number">Knowledge check {number}</span>
-          <span aria-hidden="true"> — </span>
-          {entry.data.title}
-        </h2>
-        <a
-          class="sl-anchor-link"
-          href={`#${anchorId}`}
-          aria-label={`Knowledge check ${number} titled “${entry.data.title}”`}
-        >
-          <span aria-hidden="true" class="sl-anchor-icon">
-            <svg 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" />
-            </svg>
-          </span>
-          <span class="sr-only" data-pagefind-ignore="true">
-            Link to knowledge check {number}: {entry.data.title}
-          </span>
-        </a>
-      </div>
+      <BlockHeading
+        kind="check"
+        anchorId={anchorId}
+        title={entry.data.title}
+        number={number}
+        collapsible={knowledgeChecks.collapsible}
+        defaultOpen={knowledgeChecks.defaultOpen}
+        card="accent"
+        class="assessment-heading-wrapper"
+      />
       <AssessmentRunner
         client:visible
         assessmentId={entry.data.id}