explico 0.1.0

package/src/components/notation/NotationLayer.astro

@@ -0,0 +1,594 @@
+---
+export type NotationAlignment =
+  | {
+      kind: 'competency';
+      introducedByCompetency: string;
+      introducedInLesson: string;
+    }
+  | { kind: 'general'; rationale: string };
+
+export interface NotationLayerDefinition {
+  key: string;
+  notation: string;
+  label: string;
+  summary: string;
+  formula?: string;
+  units?: string;
+  seeAlso?: readonly string[];
+  alignment?: NotationAlignment;
+  editorialStatus?: 'draft' | 'in-review' | 'reviewed';
+  scope?: 'local' | 'shared';
+  href?: string;
+}
+
+export interface Props {
+  definitions: NotationLayerDefinition[];
+  id?: string;
+  label?: string;
+  glossaryHref?: string;
+  /**
+   * `'full'` (default) renders the visible "Notation used on this page"
+   * disclosure plus the hover panel. `'panel'` renders only the hover panel
+   * and keeps the entry data as a hidden source, for pages that already show
+   * every definition in full (the glossary) but still want marked `[[key]]`
+   * links to reveal an explanation on hover.
+   */
+  presentation?: 'full' | 'panel';
+}
+
+import NotationMath from './NotationMath.astro';
+import HoverPanel from '../HoverPanel.astro';
+
+const {
+  definitions,
+  id = 'page-notation',
+  label = 'Notation used on this page',
+  glossaryHref = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`,
+  presentation = 'full',
+} = Astro.props;
+
+const panelOnly = presentation === 'panel';
+
+const keyPattern = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+const idPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+if (!idPattern.test(id)) {
+  throw new Error(`Unsafe NotationLayer id: ${id}`);
+}
+
+const seen = new Set<string>();
+const items = definitions.map((definition) => {
+  if (!keyPattern.test(definition.key)) {
+    throw new Error(`Unsafe notation key: ${definition.key}`);
+  }
+  if (seen.has(definition.key)) {
+    throw new Error(
+      `Duplicate notation key in NotationLayer: ${definition.key}`,
+    );
+  }
+  seen.add(definition.key);
+
+  const scope = definition.scope ?? 'shared';
+  const href =
+    definition.href ??
+    (scope === 'local'
+      ? `#notation-${definition.key}`
+      : `${glossaryHref}#notation-${definition.key}`);
+
+  return { ...definition, scope, href };
+});
+
+const panelId = `${id}-panel`;
+---
+
+{
+  items.length > 0 && (
+    <section
+      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}
+    >
+      {!panelOnly && (
+        <h2 id={`${id}-heading`} class="notation-layer-heading">
+          Page notation
+        </h2>
+      )}
+
+      <details class="notation-list" hidden={panelOnly}>
+        <summary>
+          {label} <span class="notation-count">({items.length})</span>
+        </summary>
+        <dl>
+          {items.map((definition) => (
+            <div
+              class="notation-entry"
+              id={panelOnly ? undefined : `notation-${definition.key}`}
+              data-notation-entry={definition.key}
+              data-notation-href={definition.href}
+            >
+              <dt>
+                <span
+                  class="notation-symbol-trigger"
+                  data-notation-symbol-trigger
+                  data-notation-key={definition.key}
+                >
+                  <NotationMath
+                    class="notation-symbol"
+                    latex={definition.notation}
+                  />
+                </span>
+                <a
+                  href={definition.href}
+                  data-notation-link={definition.key}
+                  aria-label={`${definition.label}: open the full definition`}
+                >
+                  {definition.label}
+                </a>
+                {definition.editorialStatus &&
+                  definition.editorialStatus !== 'reviewed' && (
+                    <span class="notation-status">
+                      {definition.editorialStatus}
+                    </span>
+                  )}
+              </dt>
+              <dd>
+                <p data-notation-summary>{definition.summary}</p>
+                {definition.formula && (
+                  <span class="notation-formula" data-notation-formula>
+                    <NotationMath latex={definition.formula} />
+                  </span>
+                )}
+                {definition.units && (
+                  <p class="notation-units" data-notation-units>
+                    <strong>Units:</strong> {definition.units}
+                  </p>
+                )}
+                <button
+                  class="notation-pin"
+                  type="button"
+                  data-notation-control={definition.key}
+                  aria-controls={panelId}
+                  aria-expanded="false"
+                  aria-pressed="false"
+                  hidden
+                >
+                  Pin explanation
+                </button>
+              </dd>
+            </div>
+          ))}
+        </dl>
+      </details>
+
+      {!panelOnly && (
+        <p class="notation-enhancement-help" data-notation-help hidden>
+          Point to a marked symbol for a quick explanation, or use the list
+          above. Select “Pin explanation” to keep one open; press Escape to
+          close it.
+        </p>
+      )}
+
+      <HoverPanel id={panelId} label="Notation explanation" data-notation-panel>
+        <div class="notation-panel-body">
+          <header class="notation-panel-heading">
+            <span class="notation-panel-symbol" data-panel-symbol />
+            <h3 data-panel-title />
+          </header>
+          <p data-panel-summary />
+          <div data-panel-formula hidden />
+          <p data-panel-units hidden />
+          <a data-panel-link>Open the full definition</a>
+        </div>
+      </HoverPanel>
+    </section>
+  )
+}
+
+<script>
+  import { createHoverPanel, closestElement } from '../hover-panel';
+
+  const triggerSelector = '[data-notation-key]';
+
+  function setOptionalText(element: HTMLElement, value: string) {
+    element.textContent = value;
+    element.hidden = value.length === 0;
+  }
+
+  function setupNotationLayer(root: HTMLElement) {
+    if (root.dataset.notationEnhanced === 'true') return;
+    root.dataset.notationEnhanced = 'true';
+
+    const entryElements = Array.from(
+      root.querySelectorAll<HTMLElement>('[data-notation-entry]'),
+    );
+    const entries = new Map(
+      entryElements.map((entry) => [entry.dataset.notationEntry ?? '', entry]),
+    );
+    entries.delete('');
+    if (entries.size === 0) return;
+
+    const panel = root.querySelector<HTMLElement>('[data-notation-panel]');
+    const panelSymbol = root.querySelector<HTMLElement>('[data-panel-symbol]');
+    const panelTitle = root.querySelector<HTMLElement>('[data-panel-title]');
+    const panelSummary = root.querySelector<HTMLElement>(
+      '[data-panel-summary]',
+    );
+    const panelFormula = root.querySelector<HTMLElement>(
+      '[data-panel-formula]',
+    );
+    const panelUnits = root.querySelector<HTMLElement>('[data-panel-units]');
+    const panelLink =
+      root.querySelector<HTMLAnchorElement>('[data-panel-link]');
+    if (
+      !panel ||
+      !panelSymbol ||
+      !panelTitle ||
+      !panelSummary ||
+      !panelFormula ||
+      !panelUnits ||
+      !panelLink
+    ) {
+      return;
+    }
+
+    const controls = Array.from(
+      root.querySelectorAll<HTMLButtonElement>('[data-notation-control]'),
+    );
+    const triggers = Array.from(
+      document.querySelectorAll<HTMLElement>(triggerSelector),
+    ).filter(
+      (element) =>
+        !root.contains(element) &&
+        !element.closest('.katex-mathml') &&
+        entries.has(element.dataset.notationKey ?? ''),
+    );
+    const triggerSet = new Set(triggers);
+
+    // Symbol glyphs rendered inside the page-notation list. They live within
+    // `root`, so the external-marker filter above deliberately excludes them;
+    // wire them as their own trigger set so pointing at a listed symbol opens
+    // the same explanation as pointing at one embedded in prose or an equation.
+    const symbolTriggers = Array.from(
+      root.querySelectorAll<HTMLElement>('[data-notation-symbol-trigger]'),
+    ).filter((element) => entries.has(element.dataset.notationKey ?? ''));
+    const symbolTriggerSet = new Set(symbolTriggers);
+    const highlightTargets = [...triggers, ...symbolTriggers];
+
+    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;
+
+    const externalTriggerFrom = (node: EventTarget | null) => {
+      const candidate = closestElement(node, triggerSelector);
+      return candidate && triggerSet.has(candidate) ? candidate : null;
+    };
+
+    const symbolTriggerFrom = (node: EventTarget | null) => {
+      const candidate = closestElement(node, '[data-notation-symbol-trigger]');
+      return candidate && symbolTriggerSet.has(candidate) ? candidate : null;
+    };
+
+    const controlFrom = (node: EventTarget | null) => {
+      const candidate = closestElement(node, '[data-notation-control]');
+      return candidate && root.contains(candidate) ? candidate : null;
+    };
+
+    const staticLinkFrom = (node: EventTarget | null) => {
+      const candidate = closestElement(node, '[data-notation-link]');
+      return candidate && root.contains(candidate) ? candidate : null;
+    };
+
+    const triggerFrom = (node: EventTarget | null) =>
+      controlFrom(node) ??
+      staticLinkFrom(node) ??
+      externalTriggerFrom(node) ??
+      symbolTriggerFrom(node);
+
+    const render = (_anchor: HTMLElement, key: string) => {
+      const entry = entries.get(key);
+      if (!entry) return false;
+
+      const sourceSymbol = entry.querySelector<HTMLElement>('.notation-symbol');
+      panelSymbol.replaceChildren(
+        ...(sourceSymbol
+          ? [sourceSymbol.cloneNode(true)]
+          : [document.createTextNode(entry.dataset.notationEntry ?? key)]),
+      );
+      panelTitle.textContent =
+        entry
+          .querySelector<HTMLAnchorElement>('[data-notation-link]')
+          ?.textContent?.trim() ?? key;
+      panelSummary.textContent =
+        entry
+          .querySelector<HTMLElement>('[data-notation-summary]')
+          ?.textContent?.trim() ?? '';
+      const sourceFormula = entry.querySelector<HTMLElement>(
+        '[data-notation-formula]',
+      );
+      panelFormula.replaceChildren(
+        ...(sourceFormula ? [sourceFormula.cloneNode(true)] : []),
+      );
+      panelFormula.hidden = sourceFormula === null;
+      setOptionalText(
+        panelUnits,
+        entry
+          .querySelector<HTMLElement>('[data-notation-units]')
+          ?.textContent?.trim() ?? '',
+      );
+      panelLink.href = entry.dataset.notationHref ?? `#notation-${key}`;
+      return true;
+    };
+
+    const updateControls = (pinnedKey: string | null, visible: boolean) => {
+      for (const control of controls) {
+        const selected = control.dataset.notationControl === pinnedKey;
+        control.setAttribute('aria-pressed', String(selected));
+        control.setAttribute('aria-expanded', String(selected && visible));
+        control.textContent = selected
+          ? 'Unpin explanation'
+          : 'Pin explanation';
+      }
+    };
+
+    createHoverPanel({
+      panel,
+      root,
+      triggerFrom,
+      keyFor,
+      render,
+      pinControlFrom: controlFrom,
+      onShow: (key) => {
+        for (const trigger of highlightTargets) {
+          trigger.classList.toggle(
+            'is-notation-active',
+            trigger.dataset.notationKey === key,
+          );
+        }
+        panel.dataset.activeNotationKey = key;
+      },
+      onClose: () => {
+        delete panel.dataset.activeNotationKey;
+        for (const trigger of highlightTargets) {
+          trigger.classList.remove('is-notation-active');
+        }
+      },
+      onSync: ({ pinnedKey, visible }) => updateControls(pinnedKey, visible),
+    });
+  }
+
+  for (const root of document.querySelectorAll<HTMLElement>(
+    '[data-notation-layer]',
+  )) {
+    setupNotationLayer(root);
+  }
+</script>
+
+<style>
+  @layer starlight.components {
+    .notation-layer {
+      margin-block: 2.5rem 1rem;
+      color: var(--sl-color-text);
+    }
+
+    /* Panel-only mode contributes just the fixed-position explanation panel;
+       the section itself must take no layout space. */
+    .notation-layer--panel-only {
+      margin: 0;
+    }
+
+    .notation-layer-heading {
+      margin: 0 0 0.65rem;
+      font-size: var(--sl-text-lg);
+    }
+
+    .notation-list {
+      border: 1px solid var(--sl-color-gray-5);
+      border-radius: 0.6rem;
+      background: var(--sl-color-gray-7);
+    }
+
+    .notation-list > summary {
+      padding: 0.8rem 1rem;
+      cursor: pointer;
+      font-weight: 600;
+    }
+
+    .notation-count,
+    .notation-enhancement-help {
+      color: var(--sl-color-gray-3);
+      font-weight: 400;
+    }
+
+    .notation-list dl {
+      display: grid;
+      gap: 0;
+      margin: 0;
+      padding: 0 1rem 1rem;
+    }
+
+    .notation-entry {
+      display: grid;
+      grid-template-columns: minmax(9rem, 0.65fr) minmax(12rem, 1.35fr);
+      gap: 0.5rem 1rem;
+      padding-block: 0.85rem;
+      border-top: 1px solid var(--sl-color-gray-5);
+    }
+
+    .notation-entry dt,
+    .notation-entry dd,
+    .notation-entry p {
+      margin: 0;
+    }
+
+    .notation-entry dt {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: baseline;
+      gap: 0.35rem 0.65rem;
+      font-weight: 600;
+    }
+
+    .notation-entry dd {
+      display: grid;
+      gap: 0.45rem;
+      color: var(--sl-color-gray-2);
+    }
+
+    .notation-symbol {
+      min-width: 2.25rem;
+      color: var(--sl-color-accent-high);
+    }
+
+    .notation-symbol-trigger {
+      border-radius: 0.16em;
+      cursor: help;
+    }
+
+    .notation-symbol-trigger:hover,
+    .notation-symbol-trigger.is-notation-active {
+      background: var(--sl-color-accent-low);
+      box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
+    }
+
+    @media (forced-colors: active) {
+      .notation-symbol-trigger:hover,
+      .notation-symbol-trigger.is-notation-active {
+        outline: 2px solid Highlight;
+        color: HighlightText;
+        background: Highlight;
+        box-shadow: none;
+      }
+    }
+
+    .notation-status {
+      padding: 0.08rem 0.35rem;
+      border: 1px solid var(--sl-color-gray-5);
+      border-radius: 999px;
+      color: var(--sl-color-gray-3);
+      font-size: var(--sl-text-xs);
+      font-weight: 500;
+    }
+
+    .notation-formula,
+    .notation-units {
+      font-size: var(--sl-text-sm);
+    }
+
+    .notation-formula {
+      overflow-x: auto;
+      padding-block: 0.15rem;
+      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);
+    }
+
+    /* The fixed-position shell is `HoverPanel`; these rules style only the
+       notation-owned fields slotted into it. */
+    .notation-panel-heading {
+      display: flex;
+      align-items: baseline;
+      gap: 0.7rem;
+    }
+
+    .notation-panel-heading h3,
+    .notation-panel-body p {
+      margin: 0;
+    }
+
+    .notation-panel-heading h3 {
+      font-size: var(--sl-text-base);
+    }
+
+    .notation-panel-body p {
+      margin-block: 0.65rem;
+      color: var(--sl-color-gray-2);
+      font-size: var(--sl-text-sm);
+      line-height: 1.5;
+    }
+
+    .notation-panel-body [data-panel-formula] {
+      overflow-x: auto;
+      margin-block: 0.65rem;
+      color: var(--sl-color-text);
+    }
+
+    .notation-panel-symbol {
+      color: var(--sl-color-accent-high);
+    }
+
+    .notation-layer :focus-visible {
+      outline: 3px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+  }
+
+  :global(.katex-html [data-notation-key]),
+  :global(.notation-term[data-notation-key]) {
+    border-radius: 0.16em;
+  }
+
+  /* KaTeX represents vertical-list depth with a guaranteed-empty second
+     table row. Because that row is painted last, it can otherwise intercept
+     pointer hits meant for visible notation in fractions and subscripts. */
+  :global(.katex-html .vlist-t2 > .vlist-r:nth-child(2)) {
+    pointer-events: none;
+  }
+
+  :global(.katex-html [data-notation-key]) {
+    cursor: help;
+  }
+
+  :global(.katex-html [data-notation-key]:hover),
+  :global([data-notation-key].is-notation-active) {
+    background: var(--sl-color-accent-low);
+    box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
+  }
+
+  @media (max-width: 40rem) {
+    .notation-entry {
+      grid-template-columns: 1fr;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :global(.katex-html [data-notation-key]:hover),
+    :global([data-notation-key].is-notation-active) {
+      outline: 2px solid Highlight;
+      color: HighlightText;
+      background: Highlight;
+      box-shadow: none;
+    }
+  }
+</style>

package/src/components/notation/NotationMath.astro

@@ -0,0 +1,24 @@
+---
+import { renderNotationMath } from './render-notation-math';
+import SafeMathNode from './SafeMathNode.astro';
+
+interface Props {
+  latex: string;
+  class?: string;
+}
+
+const { latex, class: className } = Astro.props;
+const nodes = renderNotationMath(latex);
+---
+
+<span class:list={['notation-math', className]} data-notation-math>
+  {nodes.map((node) => <SafeMathNode node={node} />)}
+</span>
+
+<style>
+  .notation-math :global(.katex) {
+    /* Compact labels inherit their surrounding text size. KaTeX's own sizing
+       classes retain the smaller scale for subscripts and superscripts. */
+    font-size: 1em;
+  }
+</style>

package/src/components/notation/SafeMathNode.astro

@@ -0,0 +1,23 @@
+---
+import type { SafeMathNode as Node } from './render-notation-math';
+import SafeMathNode from './SafeMathNode.astro';
+
+interface Props {
+  node: Node;
+}
+
+const { node } = Astro.props;
+const Element = node.type === 'element' ? node.tagName : undefined;
+---
+
+{
+  node.type === 'text'
+    ? node.value
+    : Element && (
+        <Element {...node.properties}>
+          {node.children.map((child) => (
+            <SafeMathNode node={child} />
+          ))}
+        </Element>
+      )
+}