explico 0.1.0

package/src/components/assessments/AssessmentRunner.tsx

@@ -0,0 +1,320 @@
+import { useEffect, useId, useState } from 'react';
+
+import {
+  noopAnalyticsEmitter,
+  type AnalyticsEmitter,
+} from '../../analytics/AnalyticsEmitter';
+import {
+  noopProgressRepository,
+  type AssessmentAttempt,
+  type ProgressRepository,
+} from '../../progress/ProgressRepository';
+import { useSessionUser } from '../../session/user-context';
+
+interface ChoiceOption {
+  id: string;
+  label: string;
+}
+
+interface AssessmentItemBase {
+  id: string;
+  competencyId?: string;
+  evidenceKind: 'direct' | 'transfer';
+  prompt: string;
+  explanation: string;
+}
+
+interface ChoiceItem extends AssessmentItemBase {
+  type: 'single-choice';
+  options: ChoiceOption[];
+  correctOptionId: string;
+}
+
+interface NumericItem extends AssessmentItemBase {
+  type: 'numeric';
+  answer: { value: number; tolerance: number };
+}
+
+type Item = ChoiceItem | NumericItem;
+
+type Outcome = 'correct' | 'incorrect';
+
+interface Props {
+  /** Assessment collection id — scopes recorded attempts and analytics events. */
+  assessmentId: string;
+  title: string;
+  items: Item[];
+  /**
+   * Seams (Phase H1). Both default to the no-op implementations the static
+   * site ships; a future SSR/LMS host injects real ones without changing the
+   * component. Props exist so tests can observe the calls.
+   */
+  progress?: ProgressRepository;
+  analytics?: AnalyticsEmitter;
+}
+
+const evidenceLabel: Record<AssessmentItemBase['evidenceKind'], string> = {
+  direct: 'Direct',
+  transfer: 'Transfer',
+};
+
+function statusFor(outcome: Outcome | undefined): {
+  tone: 'idle' | 'correct' | 'incorrect';
+  label: string;
+} {
+  if (outcome === 'correct') return { tone: 'correct', label: 'Correct' };
+  if (outcome === 'incorrect') return { tone: 'incorrect', label: 'Revisit' };
+  return { tone: 'idle', label: 'Not answered' };
+}
+
+interface QuestionProps {
+  item: Item;
+  index: number;
+  outcome: Outcome | undefined;
+  onResult: (id: string, outcome: Outcome) => void;
+  onReset: (id: string) => void;
+}
+
+function Question({ item, index, outcome, onResult, onReset }: QuestionProps) {
+  const panelId = useId();
+  const groupName = useId();
+  const inputId = useId();
+  const [open, setOpen] = useState(false);
+  const [choice, setChoice] = useState<string | null>(null);
+  const [numeric, setNumeric] = useState('');
+
+  const checked = outcome !== undefined;
+  const parsed = Number(numeric);
+  const numericFilled = numeric.trim() !== '' && Number.isFinite(parsed);
+  const canCheck =
+    item.type === 'single-choice' ? choice !== null : numericFilled;
+
+  const evaluate = () => {
+    const isCorrect =
+      item.type === 'single-choice'
+        ? choice === item.correctOptionId
+        : numericFilled &&
+          Math.abs(parsed - item.answer.value) <= item.answer.tolerance;
+    onResult(item.id, isCorrect ? 'correct' : 'incorrect');
+  };
+
+  const retry = () => {
+    onReset(item.id);
+    setChoice(null);
+    setNumeric('');
+  };
+
+  const status = statusFor(outcome);
+
+  return (
+    <li className="assessment-item">
+      <h4 className="assessment-item-heading">
+        <button
+          type="button"
+          className="assessment-disclosure"
+          aria-expanded={open}
+          aria-controls={panelId}
+          onClick={() => setOpen((value) => !value)}
+        >
+          <span className="assessment-kind">
+            {evidenceLabel[item.evidenceKind]}
+          </span>
+          <span className="assessment-item-title">Question {index}</span>
+          <span className={`assessment-status is-${status.tone}`}>
+            {status.label}
+          </span>
+          <svg
+            className="assessment-chevron"
+            viewBox="0 0 16 16"
+            width="16"
+            height="16"
+            aria-hidden="true"
+          >
+            <path
+              d="M4 6l4 4 4-4"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+        </button>
+      </h4>
+
+      <div id={panelId} className="assessment-panel" hidden={!open}>
+        <p className="assessment-prompt">{item.prompt}</p>
+
+        {item.type === 'single-choice' ? (
+          <fieldset className="assessment-choices">
+            <legend className="sr-only">
+              Answer options for question {index}
+            </legend>
+            {item.options.map((option) => (
+              <label key={option.id} className="assessment-option">
+                <input
+                  type="radio"
+                  name={groupName}
+                  value={option.id}
+                  checked={choice === option.id}
+                  disabled={checked}
+                  onChange={() => setChoice(option.id)}
+                />
+                {option.label}
+              </label>
+            ))}
+          </fieldset>
+        ) : (
+          <label className="assessment-numeric" htmlFor={inputId}>
+            <span className="sr-only">Numeric answer for question {index}</span>
+            <input
+              id={inputId}
+              type="number"
+              inputMode="decimal"
+              value={numeric}
+              disabled={checked}
+              onChange={(event) => setNumeric(event.currentTarget.value)}
+            />
+          </label>
+        )}
+
+        <div className="assessment-actions">
+          {checked ? (
+            <button type="button" onClick={retry}>
+              Try again
+            </button>
+          ) : (
+            <button type="button" disabled={!canCheck} onClick={evaluate}>
+              Check
+            </button>
+          )}
+        </div>
+
+        <p
+          className={
+            checked
+              ? `assessment-feedback is-${outcome}`
+              : 'assessment-feedback is-idle'
+          }
+          aria-live="polite"
+        >
+          {checked ? (
+            <>
+              <strong>
+                {outcome === 'correct' ? 'Correct.' : 'Not quite.'}
+              </strong>{' '}
+              {item.explanation}
+            </>
+          ) : (
+            'Check your answer to reveal the explanation.'
+          )}
+        </p>
+      </div>
+    </li>
+  );
+}
+
+export default function AssessmentRunner({
+  assessmentId,
+  title,
+  items,
+  progress = noopProgressRepository,
+  analytics = noopAnalyticsEmitter,
+}: Props) {
+  const headingId = useId();
+  const user = useSessionUser();
+  const [results, setResults] = useState<Record<string, Outcome>>({});
+
+  const itemById = new Map(items.map((item) => [item.id, item]));
+
+  // Seed from any previously recorded attempts. The no-op repository returns an
+  // empty snapshot, so this is inert in the static build.
+  useEffect(() => {
+    let live = true;
+    void Promise.resolve(progress.load(user)).then((snapshot) => {
+      if (!live) return;
+      const seeded: Record<string, Outcome> = {};
+      for (const attempt of snapshot.attempts) {
+        if (
+          attempt.assessmentId === assessmentId &&
+          itemById.has(attempt.itemId)
+        ) {
+          seeded[attempt.itemId] = attempt.outcome;
+        }
+      }
+      if (Object.keys(seeded).length > 0) setResults(seeded);
+    });
+    return () => {
+      live = false;
+    };
+    // `assessmentId` and the repository identity are the only real inputs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [assessmentId, progress, user]);
+
+  const answered = Object.keys(results).length;
+  const correct = Object.values(results).filter(
+    (value) => value === 'correct',
+  ).length;
+
+  const report = (id: string, outcome: Outcome) => {
+    setResults((prev) => ({ ...prev, [id]: outcome }));
+    const item = itemById.get(id);
+    const attempt: AssessmentAttempt = {
+      assessmentId,
+      itemId: id,
+      ...(item?.competencyId ? { competencyId: item.competencyId } : {}),
+      evidenceKind: item?.evidenceKind ?? 'direct',
+      outcome,
+      at: Date.now(),
+    };
+    void progress.recordAttempt(user, attempt);
+    analytics.emit({
+      name: 'assessment.attempt',
+      at: attempt.at,
+      props: {
+        assessmentId,
+        itemId: id,
+        outcome,
+        evidenceKind: attempt.evidenceKind,
+      },
+    });
+  };
+  const clear = (id: string) => {
+    setResults((prev) => {
+      const next = { ...prev };
+      delete next[id];
+      return next;
+    });
+    void progress.reset(user, { assessmentId, itemId: id });
+    analytics.emit({
+      name: 'assessment.retry',
+      at: Date.now(),
+      props: { assessmentId, itemId: id },
+    });
+  };
+
+  return (
+    <section className="assessment-shell" aria-labelledby={headingId}>
+      <div className="assessment-header">
+        <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>
+      </div>
+      <ol className="assessment-list">
+        {items.map((item, position) => (
+          <Question
+            key={item.id}
+            item={item}
+            index={position + 1}
+            outcome={results[item.id]}
+            onResult={report}
+            onReset={clear}
+          />
+        ))}
+      </ol>
+    </section>
+  );
+}

package/src/components/assessments/AssessmentSet.astro

@@ -0,0 +1,54 @@
+---
+import { getCollection } from 'astro:content';
+import { loadManifest } from '../../compiler/manifest';
+import AssessmentRunner from './AssessmentRunner';
+
+interface Props {
+  /**
+   * Explicit assessment id. Omitted in lesson bodies (Phase C2): the set is
+   * resolved from the route's colocated `<lesson>.checks.yml` via the manifest.
+   */
+  id?: string;
+}
+
+const explicitId = Astro.props.id;
+
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+const lessonId = Astro.url.pathname
+  .replace(new RegExp(`^${base}/`), '')
+  .replace(/\/$/, '')
+  .replace(/\//g, '.');
+
+let ids: string[];
+if (explicitId) {
+  ids = [explicitId];
+} else {
+  const manifest = await loadManifest();
+  ids = [
+    ...(manifest.lessons.find((lesson) => lesson.id === lessonId)
+      ?.assessments ?? []),
+  ];
+}
+
+const assessments = await getCollection('assessments');
+const entries = ids.map((id) => {
+  const entry = assessments.find((candidate) => candidate.data.id === id);
+  if (!entry) {
+    throw new Error(
+      `AssessmentSet: no assessment collection entry with id "${id}"`,
+    );
+  }
+  return entry;
+});
+---
+
+{
+  entries.map((entry) => (
+    <AssessmentRunner
+      client:visible
+      assessmentId={entry.data.id}
+      title={entry.data.title}
+      items={entry.data.items}
+    />
+  ))
+}

package/src/components/citation/CitationLayer.astro

@@ -0,0 +1,173 @@
+---
+/**
+ * Optional hover/pin panel for the inline `[n]` citation markers that the
+ * `remarkCitation` adapter emits. The markers are real anchor links to the
+ * on-page "References" list and work with no JavaScript; this island only
+ * adds a quick look at the source without leaving the reader's place.
+ *
+ * It reads everything it shows from the page's own static markup — the
+ * marker's `data-*` and the matching `#cite-n` reference-list item — so no
+ * page serializes a second copy of the source database. Positioning, pin,
+ * Escape, and outside-close come from the shared `HoverPanel` primitive.
+ */
+import HoverPanel from '../HoverPanel.astro';
+---
+
+<HoverPanel id="citation-panel" label="Source citation" data-citation-panel>
+  <div class="citation-panel-body">
+    <p class="citation-panel-label" data-panel-label></p>
+    <p class="citation-panel-locator" data-panel-locator hidden></p>
+    <p class="citation-panel-status" data-panel-status hidden></p>
+    <a class="citation-panel-link" data-panel-link hidden>Open source link</a>
+    <a class="citation-panel-jump" data-panel-jump
+      >See it in the reference list</a
+    >
+    <button
+      class="citation-panel-pin"
+      type="button"
+      data-panel-pin
+      aria-pressed="false"
+    >
+      Pin
+    </button>
+  </div>
+</HoverPanel>
+
+<script>
+  import { createHoverPanel, closestElement } from '../hover-panel';
+  import { referenceLabelFromText } from '../../reference/citation-format.mjs';
+
+  function setText(element: HTMLElement, value: string) {
+    element.textContent = value;
+    element.hidden = value.length === 0;
+  }
+
+  function setup() {
+    const panel = document.querySelector<HTMLElement>('[data-citation-panel]');
+    if (!panel || panel.dataset.hoverPanelReady === 'true') return;
+
+    const markers = Array.from(
+      document.querySelectorAll<HTMLAnchorElement>(
+        '.sl-markdown-content a.citation-ref[data-citation-id]',
+      ),
+    );
+    if (markers.length === 0) return;
+    const markerSet = new Set<HTMLElement>(markers);
+
+    const label = panel.querySelector<HTMLElement>('[data-panel-label]')!;
+    const locator = panel.querySelector<HTMLElement>('[data-panel-locator]')!;
+    const status = panel.querySelector<HTMLElement>('[data-panel-status]')!;
+    const link = panel.querySelector<HTMLAnchorElement>('[data-panel-link]')!;
+    const jump = panel.querySelector<HTMLAnchorElement>('[data-panel-jump]')!;
+    const pin = panel.querySelector<HTMLButtonElement>('[data-panel-pin]')!;
+
+    const markerFrom = (node: EventTarget | null) => {
+      const candidate = closestElement(
+        node,
+        'a.citation-ref[data-citation-id]',
+      );
+      return candidate && markerSet.has(candidate) ? candidate : null;
+    };
+
+    // Fill the panel from the marker plus its `#cite-n` reference-list item —
+    // never from a serialized source table.
+    const render = (marker: HTMLElement, number: string) => {
+      const item = document.getElementById(`cite-${number}`);
+      if (!item) return false;
+
+      // The reference list is a tight list, so the `<li>` has no `<p>`
+      // wrapper: clone it and drop the trailing link/status chrome.
+      const line = item.cloneNode(true) as HTMLElement;
+      for (const extra of line.querySelectorAll(
+        '.citation-url, .citation-status, .citation-backref',
+      )) {
+        extra.remove();
+      }
+      const referenceText = line.textContent ?? '';
+      const loc = marker.dataset.citationLocator ?? '';
+
+      label.textContent = referenceLabelFromText(referenceText, loc);
+      setText(locator, loc);
+
+      const sourceStatus = item
+        .querySelector('.citation-status')
+        ?.textContent?.trim();
+      setText(status, sourceStatus ? `Source record: ${sourceStatus}` : '');
+
+      const sourceUrl = item.querySelector<HTMLAnchorElement>('a.citation-url');
+      if (sourceUrl) {
+        link.href = sourceUrl.href;
+        link.hidden = false;
+      } else {
+        link.hidden = true;
+      }
+
+      jump.href = marker.getAttribute('href') ?? '#references';
+      return true;
+    };
+
+    createHoverPanel({
+      panel,
+      triggerFrom: markerFrom,
+      keyFor: (element) => element.dataset.citationNumber ?? null,
+      render,
+      pinControlFrom: (node) => closestElement(node, '[data-panel-pin]'),
+      onSync: ({ pinnedKey }) => {
+        const isPinned = pinnedKey !== null;
+        pin.setAttribute('aria-pressed', String(isPinned));
+        pin.textContent = isPinned ? 'Unpin' : 'Pin';
+      },
+    });
+  }
+
+  setup();
+  document.addEventListener('astro:page-load', setup);
+</script>
+
+<style>
+  @layer starlight.components {
+    .citation-panel-body p {
+      margin: 0 0 0.5rem;
+      line-height: 1.5;
+    }
+
+    .citation-panel-label {
+      font-weight: 600;
+    }
+
+    .citation-panel-locator {
+      color: var(--sl-color-gray-2);
+    }
+
+    .citation-panel-status {
+      color: var(--sl-color-gray-3);
+      font-size: var(--sl-text-xs);
+      text-transform: lowercase;
+    }
+
+    .citation-panel-link,
+    .citation-panel-jump {
+      display: inline-block;
+      margin-inline-end: 0.9rem;
+      font-size: var(--sl-text-xs);
+    }
+
+    .citation-panel-pin {
+      display: block;
+      margin-top: 0.6rem;
+      padding: 0.2rem 0.6rem;
+      border: 1px solid var(--sl-color-gray-5);
+      border-radius: 0.35rem;
+      background: var(--sl-color-bg);
+      color: var(--sl-color-text-accent);
+      font: inherit;
+      font-size: var(--sl-text-xs);
+      cursor: pointer;
+    }
+
+    .citation-panel-pin[aria-pressed='true'] {
+      border-color: var(--sl-color-accent);
+      background: var(--sl-color-accent-low);
+    }
+  }
+</style>

package/src/components/examples/CompactExample.astro

@@ -0,0 +1,34 @@
+---
+interface Props {
+  /** Short, descriptive tab label, for example “Mixed signed cash flows”. */
+  label: string;
+  /** Optional stable anchor for linking directly to this example. */
+  id?: string;
+}
+
+const { label, id } = Astro.props;
+
+if (typeof label !== 'string' || !label.trim()) {
+  throw new Error('CompactExample requires a non-empty `label` prop.');
+}
+---
+
+<section
+  class="compact-example"
+  data-compact-example
+  data-example-label={label}
+  id={id}
+>
+  <h3 class="compact-example__heading">{label}</h3>
+  <slot />
+</section>
+
+<style>
+  .compact-example__heading {
+    margin-block-start: 0;
+  }
+
+  .compact-example > :last-child {
+    margin-block-end: 0;
+  }
+</style>