explico 0.4.0 → 0.6.0

package/src/components/memo/Memo.astro

@@ -0,0 +1,453 @@
+---
+/**
+ * A collapsible side-note authored inline and moved between the surrounding
+ * paragraphs by `remark-memo.mjs`. The remark adapter owns `number` and
+ * `anchorId`; this component owns the block, persistence, hover preview, and
+ * click/deep-link behavior.
+ *
+ * The numbered permalink and chain-icon permalink are siblings of `<details>`,
+ * positioned into its title row. They cannot be children of `<summary>`:
+ * nesting a focusable link inside that disclosure control is invalid and trips
+ * axe's `nested-interactive` rule.
+ */
+export interface Props {
+  /** Stable lowercase/hyphenated key used by the marker and persistence. */
+  id: string;
+  /** Short summary shown on the disclosure itself. */
+  title: string;
+  /** Required context shown before the body in the marker's hover preview. */
+  description: string;
+  /** Optional prose label for the marker; omission gives the numbered `[n]` form. */
+  label?: string;
+  /** Persist the reader's open/closed choice across visits, per page. Default: `true`. */
+  rememberState?: boolean;
+  /** Computed by `remark-memo.mjs` — never author this directly. */
+  number?: string;
+  /** Computed by `remark-memo.mjs` — never author this directly. */
+  anchorId?: string;
+}
+
+const {
+  id,
+  title,
+  description,
+  rememberState = true,
+  number,
+  anchorId,
+} = Astro.props;
+
+if (typeof id !== 'string' || !id.trim()) {
+  throw new Error('Memo requires a non-empty `id` prop.');
+}
+if (typeof title !== 'string' || !title.trim()) {
+  throw new Error('Memo requires a non-empty `title` prop.');
+}
+if (typeof description !== 'string' || !description.trim()) {
+  throw new Error('Memo requires a non-empty `description` prop.');
+}
+if (!number || !anchorId) {
+  throw new Error(
+    'Memo is missing its computed `number`/`anchorId` — register remark-memo after remark-mdx in the Markdown remark pipeline.',
+  );
+}
+---
+
+<div class="memo-block-frame">
+  <a
+    class="memo-block__anchor"
+    href={`#${anchorId}`}
+    aria-label={`Link to memo ${number}: ${title}`}
+    data-memo-self-link
+  >[{number}]</a>
+  <details
+    class="memo-block"
+    id={anchorId}
+    data-memo-key={id}
+    data-memo-number={number}
+    data-memo-description={description}
+    data-remember-state={String(rememberState)}
+  >
+    <summary class="memo-block__summary">{title}</summary>
+    <div class="memo-block__body">
+      <slot />
+    </div>
+  </details>
+  <a
+    class="memo-block__title-anchor"
+    href={`#${anchorId}`}
+    aria-label={`Link to memo ${number} titled “${title}”`}
+    data-memo-anchor-link
+  >
+    <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>
+
+<style>
+  .memo-block-frame {
+    position: relative;
+    margin-block: 1rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-inline-start: 4px solid var(--sl-color-accent);
+    border-radius: 0.35rem;
+    background: color-mix(in srgb, var(--sl-color-bg) 95%, var(--sl-color-accent) 5%);
+  }
+
+  .memo-block {
+    margin: 0;
+    padding: 0;
+    scroll-margin-block-start: 5rem;
+  }
+
+  .memo-block__summary {
+    padding: 0.7rem 2.75rem 0.7rem 3.25rem;
+    color: var(--sl-color-white);
+    font-weight: 600;
+  }
+
+  .memo-block__anchor {
+    position: absolute;
+    z-index: 1;
+    inset-block-start: 0.7rem;
+    inset-inline-start: 0.9rem;
+    color: var(--sl-color-text-accent);
+    font-weight: 600;
+    text-decoration: none;
+  }
+
+  .memo-block__anchor:hover,
+  .memo-block__anchor:focus-visible {
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+
+  .memo-block__title-anchor {
+    position: absolute;
+    z-index: 1;
+    inset-block-start: 0.55rem;
+    inset-inline-end: 0.65rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.75rem;
+    height: 1.75rem;
+    color: var(--sl-color-gray-3);
+    text-decoration: none;
+    -webkit-user-select: none;
+    user-select: none;
+  }
+
+  .memo-block__title-anchor svg {
+    width: 1rem;
+    height: 1rem;
+  }
+
+  .memo-block__title-anchor:hover,
+  .memo-block__title-anchor:focus-visible {
+    color: var(--sl-color-text-accent);
+  }
+
+  .memo-block__title-anchor:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.1rem;
+  }
+
+  @media (hover: hover) {
+    .memo-block__title-anchor {
+      opacity: 0;
+    }
+
+    .memo-block__title-anchor:focus-visible,
+    .memo-block-frame:hover .memo-block__title-anchor {
+      opacity: 1;
+    }
+  }
+
+  .memo-block__body {
+    padding: 0 0.9rem 0.9rem;
+  }
+
+  .memo-block__body > :first-child {
+    margin-block-start: 0;
+  }
+
+  :global(.sl-markdown-content .memo-marker) {
+    border-radius: 0.2em;
+    color: var(--sl-color-text-accent);
+    font-weight: 600;
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+
+  :global(.sl-markdown-content .memo-marker:hover),
+  :global(.sl-markdown-content .memo-marker:focus-visible) {
+    background: var(--sl-color-accent-low);
+  }
+
+  :global(.sl-markdown-content .memo-marker:focus-visible) {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.15rem;
+  }
+
+  :global(.sl-markdown-content .memo-marker-wrap) {
+    line-height: 0;
+    vertical-align: super;
+  }
+
+  :global(.memo-preview__description) {
+    margin: 0 0 0.65rem;
+    color: var(--sl-color-gray-2);
+  }
+
+  :global(.memo-preview__body) {
+    max-height: 20em;
+    overflow: hidden;
+    border-block-start: 1px solid var(--sl-color-gray-5);
+    padding-block-start: 0.65rem;
+  }
+
+  @media print {
+    .memo-block-frame {
+      border-color: currentColor;
+      background: transparent;
+    }
+
+    .memo-block__summary::before {
+      display: none !important;
+    }
+
+    .memo-block__title-anchor {
+      display: none;
+    }
+
+    /* The script opens the native disclosure while print media is active.
+       Keep the body explicit in case author CSS would otherwise hide it. */
+    .memo-block__body {
+      display: block !important;
+    }
+  }
+</style>
+
+<script>
+  import { attachHoverPeek, closeHoverPeek } from '../disclosure/hover-preview';
+  import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
+
+  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+  let memoPreviewSerial = 0;
+
+  function cloneMemoBody(body: HTMLElement): HTMLElement {
+    const clone = document.importNode(body, true);
+    clone.classList.add('memo-preview__body');
+
+    // The shared panel temporarily joins the live document. Isolate every
+    // cloned id and rewrite both SVG fragment URLs and HTML/ARIA IDREFs. Merely
+    // deleting ids would break arrow markers, masks, labels, and controls in a
+    // nested Diagram/Figure preview.
+    const prefix = `memo-preview-${++memoPreviewSerial}-`;
+    const ids = new Map<string, string>();
+    for (const element of clone.querySelectorAll<Element>('[id]')) {
+      const oldId = element.getAttribute('id');
+      if (!oldId) continue;
+      const nextId = `${prefix}${oldId}`;
+      ids.set(oldId, nextId);
+      element.setAttribute('id', nextId);
+    }
+    const fragmentUrlAttributes = [
+      'marker-start',
+      'marker-mid',
+      'marker-end',
+      'clip-path',
+      'mask',
+      'filter',
+      'fill',
+      'stroke',
+      'style',
+    ];
+    const idrefAttributes = [
+      'aria-activedescendant',
+      'aria-controls',
+      'aria-describedby',
+      'aria-details',
+      'aria-errormessage',
+      'aria-flowto',
+      'aria-labelledby',
+      'aria-owns',
+      'for',
+      'form',
+      'headers',
+      'list',
+    ];
+    for (const element of clone.querySelectorAll<Element>('*')) {
+      for (const name of fragmentUrlAttributes) {
+        const value = element.getAttribute(name);
+        if (!value) continue;
+        const rewritten = value.replace(
+          /url\(\s*(['"]?)#([^)'"\s]+)\1\s*\)/g,
+          (match, quote: string, oldId: string) => {
+            const nextId = ids.get(oldId);
+            return nextId ? `url(${quote}#${nextId}${quote})` : match;
+          },
+        );
+        if (rewritten !== value) element.setAttribute(name, rewritten);
+      }
+      for (const name of ['href', 'xlink:href']) {
+        const value = element.getAttribute(name);
+        if (!value?.startsWith('#')) continue;
+        const nextId = ids.get(value.slice(1));
+        if (nextId) element.setAttribute(name, `#${nextId}`);
+      }
+      for (const name of idrefAttributes) {
+        const value = element.getAttribute(name);
+        if (!value) continue;
+        const rewritten = value
+          .split(/\s+/)
+          .map((id) => ids.get(id) ?? id)
+          .join(' ');
+        if (rewritten !== value) element.setAttribute(name, rewritten);
+      }
+    }
+    return clone;
+  }
+
+  function targetInside(details: HTMLDetailsElement): boolean {
+    if (!location.hash) return false;
+    let id = location.hash.slice(1);
+    try {
+      id = decodeURIComponent(id);
+    } catch {
+      /* keep the raw fragment */
+    }
+    const target = document.getElementById(id);
+    return target === details || (!!target && details.contains(target));
+  }
+
+  document
+    .querySelectorAll<HTMLDetailsElement>('.memo-block:not([data-memo-wired])')
+    .forEach((details) => {
+      details.dataset.memoWired = 'true';
+      const key = details.dataset.memoKey;
+      const number = details.dataset.memoNumber;
+      const body = details.querySelector<HTMLElement>(':scope > .memo-block__body');
+      const summary = details.querySelector<HTMLElement>(
+        ':scope > .memo-block__summary',
+      );
+      const selfLinks = Array.from(
+        details.parentElement?.querySelectorAll<HTMLAnchorElement>(
+          ':scope > [data-memo-self-link], :scope > [data-memo-anchor-link]',
+        ) ?? [],
+      );
+      if (!key || !number || !body || !summary || selfLinks.length === 0) return;
+
+      if (details.dataset.rememberState === 'true') {
+        wirePersistedDetails(details, `memo:${key}`, false);
+      } else {
+        details.open = false;
+      }
+
+      const markers = Array.from(
+        document.querySelectorAll<HTMLAnchorElement>(
+          `.memo-marker[data-memo-key="${key}"]`,
+        ),
+      ).filter(
+        (marker) => marker.getAttribute('aria-controls') === details.id,
+      );
+
+      const syncMarkers = () => {
+        for (const marker of markers) {
+          marker.setAttribute('aria-expanded', String(details.open));
+          if (details.open) closeHoverPeek(marker);
+        }
+      };
+      details.addEventListener('toggle', syncMarkers);
+      syncMarkers();
+
+      const revealForHash = () => {
+        if (targetInside(details)) details.open = true;
+      };
+      revealForHash();
+      window.addEventListener('hashchange', revealForHash);
+
+      for (const selfLink of selfLinks) {
+        selfLink.addEventListener('click', (event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          details.open = true;
+          if (location.hash !== `#${details.id}`) {
+            history.pushState(null, '', `#${details.id}`);
+          }
+        });
+      }
+
+      // A closed native <details> suppresses its body at the UA rendering
+      // layer, beyond what an author stylesheet can reliably override. Open it
+      // while print media is active, then put the reader's exact screen state
+      // back when the print dialog/export ends (the same approach used by
+      // CollapsibleSections for its native disclosures).
+      const printMedia = window.matchMedia('print');
+      let screenOpen: boolean | null = null;
+      const syncPrintState = () => {
+        if (document.querySelector('[data-explico-print-controller]')) return;
+        if (printMedia.matches) {
+          if (screenOpen === null) screenOpen = details.open;
+          details.open = true;
+        } else if (screenOpen !== null) {
+          details.open = screenOpen;
+          screenOpen = null;
+        }
+      };
+      printMedia.addEventListener('change', syncPrintState);
+      window.addEventListener('beforeprint', syncPrintState);
+      window.addEventListener('afterprint', syncPrintState);
+      syncPrintState();
+
+      for (const marker of markers) {
+        const suppressWhenOpen = (event: Event) => {
+          if (details.open) event.stopImmediatePropagation();
+        };
+        marker.addEventListener('pointerenter', suppressWhenOpen);
+        marker.addEventListener('focus', suppressWhenOpen);
+
+        attachHoverPeek(marker, {
+          label: `Memo ${number} preview`,
+          // Keep the description visible above up to 20em of body content.
+          maxHeightEm: 24,
+          getContent: () => {
+            const wrap = document.createElement('div');
+            const heading = document.createElement('strong');
+            heading.textContent = summary.textContent?.trim() || `Memo ${number}`;
+            const description = document.createElement('p');
+            description.className = 'memo-preview__description';
+            description.textContent = details.dataset.memoDescription ?? '';
+            wrap.append(heading, description, cloneMemoBody(body));
+            return wrap;
+          },
+        });
+
+        marker.addEventListener('click', (event) => {
+          event.preventDefault();
+          const opening = !details.open;
+          details.open = opening;
+          if (!opening) return;
+
+          closeHoverPeek(marker);
+          if (location.hash !== `#${details.id}`) {
+            history.pushState(null, '', `#${details.id}`);
+          }
+          requestAnimationFrame(() => {
+            details.scrollIntoView({
+              behavior: reduceMotion.matches ? 'auto' : 'smooth',
+              block: 'start',
+            });
+          });
+        });
+      }
+    });
+</script>

package/src/components/memo/ShortNote.astro

@@ -0,0 +1,223 @@
+---
+/** A reveal-in-place note whose collapsed trigger remains part of its sentence. */
+export interface Props {
+  /** Stable lowercase/hyphenated key used by the trigger and URL fragment. */
+  id: string;
+  /** Exact inline text shown while the note is collapsed. */
+  title: string;
+  /** Accessible explanation of what expanding the note will reveal. */
+  description: string;
+  /** Computed by `remark-short-note.mjs` — never author this directly. */
+  anchorId?: string;
+}
+
+const { id, title, description, anchorId } = Astro.props;
+
+if (typeof id !== 'string' || !id.trim()) {
+  throw new Error('ShortNote requires a non-empty `id` prop.');
+}
+if (typeof title !== 'string' || !title.trim()) {
+  throw new Error('ShortNote requires a non-empty `title` prop.');
+}
+if (typeof description !== 'string' || !description.trim()) {
+  throw new Error('ShortNote requires a non-empty `description` prop.');
+}
+if (!anchorId) {
+  throw new Error(
+    'ShortNote is missing its computed `anchorId` — register remark-short-note before remark-memo in the Markdown remark pipeline.',
+  );
+}
+---
+
+<aside
+  class="short-note"
+  id={anchorId}
+  data-short-note-key={id}
+  aria-label={description}
+  hidden
+>
+  <div class="short-note__body">
+    <slot />
+  </div>
+  <button class="short-note__collapse" type="button">Show less</button>
+</aside>
+
+<style>
+  .short-note {
+    margin-block: 0.65rem;
+    padding-inline-start: 0.9rem;
+    scroll-margin-block-start: 5rem;
+    border-inline-start: 2px solid var(--sl-color-accent);
+  }
+
+  .short-note[hidden] {
+    display: none !important;
+  }
+
+  /* A fragment link still reveals the note when client JavaScript is absent. */
+  .short-note:target {
+    display: block !important;
+  }
+
+  .short-note__body > :first-child {
+    margin-block-start: 0;
+  }
+
+  .short-note__body > :last-child {
+    margin-block-end: 0;
+  }
+
+  .short-note__collapse {
+    margin-block-start: 0.45rem;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: var(--sl-color-text-accent);
+    font: inherit;
+    font-size: var(--sl-text-sm);
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+    cursor: pointer;
+  }
+
+  :global(.sl-markdown-content .short-note-marker) {
+    border-radius: 0.2em;
+    color: var(--sl-color-text-accent);
+    font-weight: 600;
+    text-decoration-line: underline;
+    text-decoration-style: dashed;
+    text-underline-offset: 0.18em;
+  }
+
+  :global(.sl-markdown-content .short-note-marker:hover),
+  :global(.sl-markdown-content .short-note-marker:focus-visible) {
+    background: var(--sl-color-accent-low);
+  }
+
+  :global(.sl-markdown-content .short-note-marker:focus-visible),
+  .short-note__collapse:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.15rem;
+  }
+
+  :global(.short-note__continuation) {
+    margin-block-start: 0;
+  }
+
+  @media print {
+    .short-note[hidden] {
+      display: block !important;
+    }
+
+    .short-note__collapse {
+      display: none;
+    }
+  }
+</style>
+
+<script>
+  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+  document
+    .querySelectorAll<HTMLElement>('.short-note:not([data-short-note-wired])')
+    .forEach((note) => {
+      note.dataset.shortNoteWired = 'true';
+      const key = note.dataset.shortNoteKey;
+      const collapseButton = note.querySelector<HTMLButtonElement>(
+        ':scope > .short-note__collapse',
+      );
+      if (!key || !collapseButton) return;
+
+      const markers = Array.from(
+        document.querySelectorAll<HTMLAnchorElement>(
+          `.short-note-marker[data-short-note-key="${key}"]`,
+        ),
+      ).filter((marker) => marker.getAttribute('aria-controls') === note.id);
+      if (markers.length === 0) return;
+
+      const storage = document.createComment(`short-note:${key}`);
+      note.before(storage);
+      let activeMarker: HTMLAnchorElement | null = null;
+      let paragraph: HTMLParagraphElement | null = null;
+      let continuation: HTMLParagraphElement | null = null;
+
+      const setExpanded = (expanded: boolean) => {
+        for (const marker of markers) {
+          marker.setAttribute('aria-expanded', String(expanded));
+          marker.hidden = expanded && marker === activeMarker;
+        }
+      };
+
+      const collapse = (restoreFocus: boolean) => {
+        if (note.hidden) return;
+        note.hidden = true;
+        if (paragraph && continuation) {
+          while (continuation.firstChild) paragraph.append(continuation.firstChild);
+          continuation.remove();
+        }
+        storage.after(note);
+        const marker = activeMarker;
+        activeMarker = null;
+        paragraph = null;
+        continuation = null;
+        setExpanded(false);
+        if (location.hash === `#${note.id}`) {
+          history.replaceState(null, '', `${location.pathname}${location.search}`);
+        }
+        if (restoreFocus) marker?.focus();
+      };
+
+      const expand = (marker: HTMLAnchorElement, updateUrl = true) => {
+        window.dispatchEvent(
+          new CustomEvent('explico:short-note-open', { detail: note }),
+        );
+        activeMarker = marker;
+        paragraph = marker.closest('p');
+        continuation = document.createElement('p');
+        continuation.className = 'short-note__continuation';
+        while (marker.nextSibling) continuation.append(marker.nextSibling);
+
+        note.hidden = false;
+        paragraph?.after(note);
+        if (continuation.hasChildNodes()) note.after(continuation);
+        setExpanded(true);
+        if (updateUrl && location.hash !== `#${note.id}`) {
+          history.pushState(null, '', `#${note.id}`);
+        }
+        requestAnimationFrame(() => {
+          note.scrollIntoView({
+            behavior: reduceMotion.matches ? 'auto' : 'smooth',
+            block: 'nearest',
+          });
+        });
+      };
+
+      window.addEventListener('explico:short-note-open', (event) => {
+        if ((event as CustomEvent).detail !== note) collapse(false);
+      });
+      collapseButton.addEventListener('click', () => collapse(true));
+      for (const marker of markers) {
+        marker.addEventListener('click', (event) => {
+          event.preventDefault();
+          if (!note.hidden) collapse(false);
+          expand(marker);
+        });
+      }
+
+      const revealForHash = () => {
+        if (!location.hash || !note.hidden) return;
+        let id = location.hash.slice(1);
+        try {
+          id = decodeURIComponent(id);
+        } catch {
+          /* keep the raw fragment */
+        }
+        const target = document.getElementById(id);
+        if (target === note || (!!target && note.contains(target))) {
+          expand(markers[0], false);
+        }
+      };
+      window.addEventListener('hashchange', revealForHash);
+      revealForHash();
+    });
+</script>