explico 0.8.0 → 0.11.0

package/src/components/BlockHeading.astro

@@ -0,0 +1,113 @@
+---
+/**
+ * The `<h2>` a knowledge check (`AssessmentSet.astro`) and a worked-example
+ * set (`CompactExamples.astro`) draw where their tag stands
+ * (docs/plans/titles-and-containers.md Part 6, Q11). The author writes only
+ * the topic; the engine names the kind and the number:
+ *
+ *                                            KNOWLEDGE CHECK 1.1.1
+ *   ✓ Position and coordinates
+ *
+ * The kind's icon leads the title, which is one line of inline text, not a
+ * flex row, so it stays whole when it fits and wraps word by word when it
+ * does not. The badge — the kind's word and the number — is a small label in
+ * the card's top-right corner (`global.css`), out of the text flow, so the
+ * title keeps the whole line. Its source order still names the heading
+ * "Knowledge check 1.1.1 Position and coordinates". The word is for a screen
+ * reader only when the course sets `blockLabels: "icon"`. The number shows,
+ * and hides, by the section rules (`global.css`: on a wide screen, in print
+ * and on a folded bar; never when `numbering.sections.show` is off, which
+ * also leaves `data-‹kind›-number` off the heading, so no number-form alias
+ * resolves to it).
+ *
+ * The wrapper is the same `.sl-heading-wrapper` a Markdown heading gets
+ * (`rehype-heading-anchors.mjs`), chain icon included, so
+ * `CollapsibleSections.astro` folds and cards it and `HeadingAnchorEnhancer`
+ * copies its link. "On this page" lists it through the manifest's
+ * `titledBlocks` (`LayoutPageSidebar.astro`), by its title with the badge's
+ * icon — the same two icons as below, as CSS masks (`--block-kind-icon` in
+ * `global.css`).
+ */
+import { BLOCK_KINDS, blockHeadingSettings, type BlockKind } from './block-heading';
+
+interface Props {
+  kind: BlockKind;
+  /** The heading's `id`: `check-‹id›` or `ex-‹id›`. */
+  anchorId: string;
+  /** The author's topical title. */
+  title: string;
+  /** The block's number (`1.1.1`), when it has one. */
+  number?: string | undefined;
+  /** Whether the section folds (`data-collapsible`). */
+  collapsible: boolean;
+  /** A folding section's first-visit state (`data-default-open`). */
+  defaultOpen: boolean;
+  /** Keep the reader's open/closed choice (`data-remember-state`). Default `true`. */
+  rememberState?: boolean;
+  /** `data-card`: `CollapsibleSections` cards heading and section in this tier. */
+  card?: 'accent' | undefined;
+  /** `data-section-to-end`: the section is the rest of the block's container. */
+  sectionToEnd?: boolean;
+  /** Extra classes on the wrapper. */
+  class?: string;
+}
+
+const {
+  kind,
+  anchorId,
+  title,
+  number,
+  collapsible,
+  defaultOpen,
+  rememberState = true,
+  card,
+  sectionToEnd = false,
+  class: className,
+} = Astro.props;
+
+const { labels, showNumbers } = await blockHeadingSettings();
+const { word, numberAttribute } = BLOCK_KINDS[kind];
+const shown = showNumbers && number ? number : undefined;
+const name = shown ? `${word} ${shown}: ${title}` : `${word}: ${title}`;
+---
+
+<div
+  class:list={['sl-heading-wrapper', 'level-h2', 'block-heading-wrapper', className]}
+  data-collapsible={String(collapsible)}
+  data-default-open={String(defaultOpen)}
+  data-remember-state={String(rememberState)}
+  data-card={card}
+  {...sectionToEnd ? { 'data-section-to-end': '' } : {}}
+>
+  <h2
+    id={anchorId}
+    class="block-heading"
+    data-block-kind={kind}
+    {...shown ? { [numberAttribute]: shown } : {}}
+  >
+    <span class:list={['block-badge', `block-badge--${kind}`]} data-labels={labels}
+      ><span class:list={['block-badge__word', { 'sr-only': labels === 'icon' }]}>{word}</span
+      >{shown && <span class="block-heading__number">{` ${shown}`}</span>}</span
+    >{' '}{
+      kind === 'check' ? (
+        <svg class="block-heading__icon" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M2 8.5l4 4 8-9" />
+        </svg>
+      ) : (
+        <svg class="block-heading__icon" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round">
+          <rect x="2" y="2" width="12" height="12" rx="2" />
+          <path d="M5 8h6M8 5v6" />
+        </svg>
+      )
+    }<span class="block-heading__title">{title}</span>
+  </h2>
+  <a class="sl-anchor-link" href={`#${anchorId}`}
+    ><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"
+        ></path></svg
+      ></span
+    ><span class="sr-only" data-pagefind-ignore>Link to {name}</span></a
+  >
+</div>

package/src/components/CourseContents.astro

@@ -0,0 +1,221 @@
+---
+/**
+ * Every chapter of the course, grouped under its part — the landing page's
+ * answer to "what is in here, and how long is it?".
+ *
+ * A hero that links only the first chapter hides the other eighteen, and a
+ * hand-written list of them goes stale the first time a chapter is renamed.
+ * This reads the manifest: parts in config order, chapters in reading order,
+ * each part heading linking its overview page where one exists, and study
+ * times totalled per part and for the course when every chapter states one.
+ *
+ * Usage, on a splash page:
+ *
+ * ```mdx
+ * import CourseContents from 'explico/components/CourseContents.astro';
+ *
+ * <CourseContents />
+ * ```
+ */
+import { loadManifest } from '../compiler/manifest';
+
+interface Props {
+  /** Heading level for each part's name. Defaults to `h2`. */
+  readonly headingLevel?: 2 | 3;
+  /** Set `false` to drop the per-chapter description column. */
+  readonly descriptions?: boolean;
+}
+
+const { headingLevel = 2, descriptions = true } = Astro.props;
+const Heading = `h${headingLevel}` as 'h2' | 'h3';
+
+const manifest = await loadManifest();
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+const lessonById = new Map(
+  manifest.lessons.map((lesson) => [lesson.id, lesson]),
+);
+
+const parts = manifest.parts
+  .map((part) => ({
+    ...part,
+    chapters: part.lessons
+      .map((id) => lessonById.get(id))
+      .filter(
+        (lesson): lesson is NonNullable<typeof lesson> => lesson !== undefined,
+      ),
+  }))
+  .filter((part) => part.chapters.length > 0);
+
+const chapterCount = parts.reduce(
+  (total, part) => total + part.chapters.length,
+  0,
+);
+// Same rule as a part's own total: state one only when nothing is missing
+// from it.
+const courseMinutes = parts.every((part) => part.studyMinutes !== undefined)
+  ? parts.reduce(
+      (total, part) => ({
+        min: total.min + part.studyMinutes!.min,
+        max: total.max + part.studyMinutes!.max,
+      }),
+      { min: 0, max: 0 },
+    )
+  : undefined;
+
+const minutes = (range: { min: number; max: number }) =>
+  range.min === range.max
+    ? `${range.min} min`
+    : `${range.min}–${range.max} min`;
+
+const hours = (range: { min: number; max: number }) => {
+  const low = Math.round((range.min / 60) * 10) / 10;
+  const high = Math.round((range.max / 60) * 10) / 10;
+  return low === high ? `${low} hours` : `${low}–${high} hours`;
+};
+---
+
+<div class="course-contents not-content">
+  <p class="course-meta">
+    <span>{parts.length} parts</span>
+    <span>{chapterCount} chapters</span>
+    {courseMinutes && <span>{hours(courseMinutes)} of study</span>}
+  </p>
+
+  {
+    parts.map((part) => (
+      <section class="course-part">
+        <Heading id={`contents-${part.dir}`}>
+          {part.overview ? (
+            <a href={`${base}${part.link}`}>{part.label}</a>
+          ) : (
+            part.label
+          )}
+        </Heading>
+        <p class="part-line">
+          <span>
+            Part {part.ordinal} · {part.chapters.length}{' '}
+            {part.chapters.length === 1 ? 'chapter' : 'chapters'}
+          </span>
+          {part.studyMinutes && <span>{minutes(part.studyMinutes)}</span>}
+        </p>
+        <ol aria-labelledby={`contents-${part.dir}`}>
+          {part.chapters.map((lesson) => (
+            <li>
+              <a href={`${base}/${lesson.slug}/`}>{lesson.title}</a>
+              {lesson.studyMinutes && (
+                <span class="chapter-time">{minutes(lesson.studyMinutes)}</span>
+              )}
+              {descriptions && <p>{lesson.description}</p>}
+            </li>
+          ))}
+        </ol>
+      </section>
+    ))
+  }
+</div>
+
+<style>
+  .course-contents {
+    display: grid;
+    gap: 1.75rem;
+    margin-block-start: 1.5rem;
+  }
+
+  .course-meta,
+  .part-line {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+    margin: 0;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-xs);
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+
+  .course-part {
+    display: grid;
+    gap: 0.4rem;
+  }
+
+  .course-part :global(h2),
+  .course-part :global(h3) {
+    margin: 0;
+    font-size: var(--sl-text-lg);
+    line-height: 1.3;
+  }
+
+  .course-part :global(h2) a,
+  .course-part :global(h3) a {
+    text-decoration: none;
+  }
+
+  .course-part :global(h2) a:hover,
+  .course-part :global(h3) a:hover {
+    text-decoration: underline;
+  }
+
+  .course-part ol {
+    counter-reset: chapter;
+    display: grid;
+    gap: 0.1rem;
+    margin: 0.35rem 0 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .course-part li {
+    counter-increment: chapter;
+    display: grid;
+    grid-template-columns: 1.9rem minmax(0, 1fr) auto;
+    gap: 0 0.5rem;
+    margin: 0;
+    padding-block: 0.4rem;
+    border-block-start: 1px solid var(--sl-color-gray-6);
+  }
+
+  .course-part li::before {
+    content: counter(chapter, decimal-leading-zero);
+    color: var(--sl-color-gray-4);
+    font-size: var(--sl-text-xs);
+    font-variant-numeric: tabular-nums;
+    line-height: 1.7;
+  }
+
+  .course-part li > a {
+    text-decoration: none;
+    font-weight: 500;
+  }
+
+  .course-part li > a:hover {
+    text-decoration: underline;
+  }
+
+  .course-part li > .chapter-time {
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-xs);
+    font-variant-numeric: tabular-nums;
+    text-align: end;
+    white-space: nowrap;
+    line-height: 1.7;
+  }
+
+  .course-part li > p {
+    grid-column: 2 / -1;
+    margin: 0;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+    line-height: 1.45;
+  }
+
+  @media (max-width: 40rem) {
+    .course-part li {
+      grid-template-columns: 1.9rem minmax(0, 1fr);
+    }
+
+    .course-part li > .chapter-time {
+      grid-column: 2;
+      text-align: start;
+    }
+  }
+</style>

package/src/components/CurriculumMap.astro

@@ -65,7 +65,7 @@ const competencyEdges: DiagramEdge[] = competencies.flatMap(({ data }) =>
           if (!lesson || !entry) return null;
           return (
             <li>
-              <article>
+              <article class="ex-tier-meta">
                 <p class="step">Lesson {index + 1}</p>
                 <h3>
                   <a
@@ -130,7 +130,7 @@ const competencyEdges: DiagramEdge[] = competencies.flatMap(({ data }) =>
     competencyNodes.length > 0 && (
       <Diagram
         id="competency-graph"
-        label="Competency dependency graph"
+        caption="The competency dependency graph: an arrow runs from a prerequisite to the competency that builds on it"
         nodes={competencyNodes}
         edges={competencyEdges}
       />
@@ -142,7 +142,7 @@ const competencyEdges: DiagramEdge[] = competencies.flatMap(({ data }) =>
       competencies
         .sort((left, right) => left.data.id.localeCompare(right.data.id))
         .map(({ data }) => (
-          <li>
+          <li class="ex-tier-meta">
             <strong>{data.title}</strong>
             <br />
             <code>{data.id}</code>
@@ -181,12 +181,11 @@ const competencyEdges: DiagramEdge[] = competencies.flatMap(({ data }) =>
     font-weight: 700;
   }
 
+  /* Generated course logistics: the meta tier (`ex-tier-meta`,
+     `surfaces.css`) draws each card's surface, border and radius. */
   .lesson-sequence article,
   .competency-map li {
     padding: 1rem;
-    border: 1px solid var(--sl-color-gray-5);
-    border-radius: 0.55rem;
-    background: var(--sl-color-gray-7);
   }
 
   .lesson-sequence h3,

package/src/components/FloatIndex.astro

@@ -0,0 +1,200 @@
+---
+/**
+ * The course's "Figures and tables" page — LaTeX's `\listoffigures` and
+ * `\listoftables` in one (docs/plans/figures-and-short-captions.md, decision
+ * 9.4): every numbered figure, table and diagram with an `id`, by part and
+ * chapter.
+ *
+ * An entry is the float's number, linked to its place in its chapter, and
+ * its short caption; or its long caption, muted, when it has no short one;
+ * or the number alone when the manifest has neither — a float whose captions
+ * a wrapper component sets (a lab's `DerivationDiagram.astro`) reaches the
+ * manifest without them. A float without an `id` has no stable anchor and
+ * is not in the manifest's lists, so it is not listed.
+ *
+ * Modelled on `CourseContents.astro`: it reads the manifest — parts in
+ * config order, chapters in reading order, then each chapter's figures,
+ * tables and diagrams, by kind and number. A chapter or a part with none is
+ * left out.
+ *
+ * Usage, on a top-level page the sidebar's Reference group lists
+ * (`content/docs/figures-and-tables.mdx`):
+ *
+ * ```mdx
+ * import FloatIndex from 'explico/components/FloatIndex.astro';
+ *
+ * <FloatIndex />
+ * ```
+ */
+import { loadManifest, type ManifestLessonFloat } from '../compiler/manifest';
+import { FLOAT_KIND_WORDS, type FloatKind } from './float-name';
+
+interface Props {
+  /** Heading level for each part's name; a chapter's is one below. Defaults to `h2`. */
+  readonly headingLevel?: 2 | 3;
+}
+
+const { headingLevel = 2 } = Astro.props;
+const PartHeading = `h${headingLevel}` as 'h2' | 'h3';
+const ChapterHeading = `h${headingLevel + 1}` as 'h3' | 'h4';
+
+const manifest = await loadManifest();
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+const lessonById = new Map(manifest.lessons.map((lesson) => [lesson.id, lesson]));
+
+const KINDS = [
+  ['figures', 'fig'],
+  ['tables', 'tab'],
+  ['diagrams', 'dia'],
+] as const satisfies readonly (readonly [string, FloatKind])[];
+
+const byNumber = (a: ManifestLessonFloat, b: ManifestLessonFloat) =>
+  a.number.localeCompare(b.number, undefined, { numeric: true });
+
+const parts = manifest.parts
+  .map((part) => ({
+    ...part,
+    chapters: part.lessons
+      .map((id) => lessonById.get(id))
+      .filter((lesson): lesson is NonNullable<typeof lesson> => lesson !== undefined)
+      .map((lesson, index) => ({
+        lesson,
+        // The chapter's number, as its sections' numbers begin.
+        number: `${part.ordinal}.${index + 1}`,
+        entries: KINDS.flatMap(([field, kind]) =>
+          [...lesson[field]].sort(byNumber).map((float) => ({
+            ...float,
+            label: `${FLOAT_KIND_WORDS[kind]} ${float.number}`,
+            href: `${base}/${lesson.slug}/#${kind}-${float.key}`,
+          })),
+        ),
+      }))
+      .filter((chapter) => chapter.entries.length > 0),
+  }))
+  .filter((part) => part.chapters.length > 0);
+---
+
+<div class="float-index not-content">
+  {
+    parts.length === 0 && (
+      <p class="float-index__empty">No chapter has a numbered figure, table or diagram yet.</p>
+    )
+  }
+  {
+    parts.map((part) => (
+      <section class="float-index__part">
+        <PartHeading id={`floats-${part.dir}`}>{part.label}</PartHeading>
+        {part.chapters.map(({ lesson, number, entries }) => (
+          <section class="float-index__chapter">
+            <ChapterHeading id={`floats-${lesson.slug.replace(/\//g, '-')}`}>
+              <span class="float-index__chapter-number">{number}</span>{' '}
+              <a href={`${base}/${lesson.slug}/`}>{lesson.title}</a>
+            </ChapterHeading>
+            <ol class="float-index__list">
+              {entries.map((entry) => (
+                <li>
+                  <a class="float-index__number" href={entry.href}>
+                    {entry.label}
+                  </a>
+                  {entry.short ? (
+                    <span class="float-index__name">{entry.short}</span>
+                  ) : entry.caption ? (
+                    <span class="float-index__name float-index__name--long">{entry.caption}</span>
+                  ) : null}
+                </li>
+              ))}
+            </ol>
+          </section>
+        ))}
+      </section>
+    ))
+  }
+</div>
+
+<style>
+  .float-index {
+    display: grid;
+    gap: 1.75rem;
+    margin-block-start: 1.5rem;
+  }
+
+  .float-index__part,
+  .float-index__chapter {
+    display: grid;
+    gap: 0.4rem;
+  }
+
+  .float-index__part :global(h2),
+  .float-index__part :global(h3) {
+    margin: 0;
+    font-size: var(--sl-text-lg);
+    line-height: 1.3;
+  }
+
+  .float-index__chapter :global(h3),
+  .float-index__chapter :global(h4) {
+    margin: 0.5rem 0 0;
+    font-size: var(--sl-text-base);
+    line-height: 1.4;
+  }
+
+  .float-index__chapter-number {
+    color: var(--sl-color-gray-3);
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* `not-content` drops Starlight's link colour with the rest of its prose
+     styles; the index keeps the accent for its links. */
+  .float-index__chapter a {
+    color: var(--sl-color-text-accent);
+    text-decoration: none;
+  }
+
+  .float-index__chapter a:hover,
+  .float-index__chapter a:focus-visible {
+    text-decoration: underline;
+  }
+
+  /* One row per float, as a list of figures sets it: the number in a column
+     of its own, the name beside it. */
+  .float-index__list {
+    display: grid;
+    gap: 0;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .float-index__list li {
+    display: grid;
+    grid-template-columns: 8.5rem minmax(0, 1fr);
+    gap: 0 0.75rem;
+    margin: 0;
+    padding-block: 0.35rem;
+    border-block-start: 1px solid var(--sl-color-gray-6);
+    line-height: 1.45;
+  }
+
+  .float-index__number {
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+  }
+
+  /* A float with no short caption is listed by its long one, muted: the
+     name to give it is still to be written. */
+  .float-index__name--long {
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+  }
+
+  .float-index__empty {
+    color: var(--sl-color-gray-3);
+  }
+
+  @media (max-width: 30rem) {
+    .float-index__list li {
+      grid-template-columns: minmax(0, 1fr);
+    }
+  }
+</style>