explico 0.1.1 → 0.3.0

package/src/styles/global.css

@@ -668,7 +668,7 @@
    `.keyed-equation` with an `id="eq-<key>"`, a `data-eq-number`, and a
    focusable number link. Prose refers to it with `[[eq:key]]` →
    `a.equation-ref`. The deep-link highlight is a pure-CSS `:target` animation
-   with a reduced-motion fallback; `EquationEnhancer.astro` only re-triggers it
+   with a reduced-motion fallback; `KeyedFloatEnhancer.astro` only re-triggers it
    on a repeated activation and moves focus. */
 .sl-markdown-content .keyed-equation {
   position: relative;
@@ -690,13 +690,76 @@
   font-size: var(--sl-text-sm);
   color: var(--sl-color-text-accent);
   text-decoration: none;
+  /* Present but quiet by default (F4): partially visible so a reader
+     scanning the page can always find the number without hunting, but it
+     still doesn't compete with the equation itself. Hover, focus, and a
+     deep-link (`:target`) push it to full opacity, same as before. */
+  opacity: 0.45;
+  transition: opacity 120ms ease-out;
 }
 
-.sl-markdown-content a.keyed-equation__number:hover,
+@media (hover: none) {
+  /* No hover to reveal it on touch, so keep the number legible there. */
+  .sl-markdown-content a.keyed-equation__number {
+    opacity: 1;
+  }
+}
+
+.sl-markdown-content .keyed-equation:hover a.keyed-equation__number,
+.sl-markdown-content .keyed-equation:focus-within a.keyed-equation__number,
+.sl-markdown-content .keyed-equation:target a.keyed-equation__number,
 .sl-markdown-content a.keyed-equation__number:focus-visible {
+  opacity: 1;
   text-decoration: underline;
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .sl-markdown-content a.keyed-equation__number {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content a.keyed-equation__number {
+    opacity: 1;
+  }
+}
+
+/* Once a reader has actually arrived at (or clicked through to) an equation —
+   a deep-link on load, an in-page `[[eq:key]]` navigation, or pinning its
+   preview card (`FloatRefLayer.astro`) — its number stays fully visible
+   for the rest of the page's life, not just while `:target` or `:hover`
+   holds. `KeyedFloatEnhancer.astro` and `FloatRefLayer.astro` add this class
+   in JS; it is never present in the static markup. One extra class over the
+   base selector's specificity, so this always wins regardless of rule order. */
+.sl-markdown-content a.keyed-equation__number.eq-number-revealed {
+  opacity: 1;
+}
+
+/* A referencing `[[eq:key]]` link elsewhere in the prose was hovered/focused
+   and the equation it points to is already fully on screen: highlight it in
+   place instead of opening a preview card (`FloatRefLayer.astro` decides
+   which). Mirrors the reduced-motion `:target` treatment below — steady, no
+   keyframe — since this fires on every hover, not just a rare deep-link. */
+.sl-markdown-content .keyed-equation.eq-ref-highlight {
+  background: var(--sl-color-accent-low);
+  outline: 2px solid var(--sl-color-accent);
+  outline-offset: 0.2rem;
+  transition:
+    background 120ms ease-out,
+    outline-color 120ms ease-out;
+}
+
+.sl-markdown-content .keyed-equation.eq-ref-highlight a.keyed-equation__number {
+  opacity: 1;
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content .keyed-equation.eq-ref-highlight {
+    outline-color: Highlight;
+  }
+}
+
 .sl-markdown-content a.equation-ref {
   font-variant-numeric: tabular-nums;
   font-weight: 600;
@@ -725,7 +788,7 @@
 }
 
 .sl-markdown-content .keyed-equation:target {
-  animation: eq-flash 3s ease-out both;
+  animation: eq-flash 5s ease-out both;
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -756,8 +819,135 @@
     transform: none;
     text-align: end;
     color: inherit;
+    opacity: 1;
   }
   .sl-markdown-content .keyed-equation {
     padding-inline-end: 0;
   }
 }
+
+/* `<Table>`/`<Figure>` keyed floats (F-tables-figures) — the same deep-link
+   and hover-highlight treatment as equations above, via `KeyedFloatEnhancer`
+   and `FloatRefLayer.astro`. Unlike an equation's number (quiet until
+   hovered, F4), a table/figure number lives in its always-visible caption,
+   so there is no opacity dance to mirror here — only the `:target` flash
+   (reusing the `eq-flash` keyframe above) and the ref-highlight. */
+.sl-markdown-content a.table-ref,
+.sl-markdown-content a.figure-ref {
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+  padding-inline: 0.1em;
+  border-radius: 0.2em;
+  color: var(--sl-color-text-accent);
+  white-space: nowrap;
+}
+
+.sl-markdown-content a.table-ref:hover,
+.sl-markdown-content a.table-ref:focus-visible,
+.sl-markdown-content a.figure-ref:hover,
+.sl-markdown-content a.figure-ref:focus-visible {
+  background: var(--sl-color-accent-low);
+}
+
+.sl-markdown-content .keyed-table:target,
+.sl-markdown-content .keyed-figure:target {
+  animation: eq-flash 5s ease-out both;
+  border-radius: 0.3rem;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sl-markdown-content .keyed-table:target,
+  .sl-markdown-content .keyed-figure:target {
+    animation: none;
+    background: var(--sl-color-accent-low);
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.2rem;
+  }
+}
+
+/* A referencing `[[tab-key]]`/`[[fig-key]]` link elsewhere in the prose was
+   hovered/focused and the float it points to is already fully on screen:
+   highlight it in place instead of opening a preview card
+   (`FloatRefLayer.astro` decides which) — mirrors `.eq-ref-highlight`. */
+.sl-markdown-content .keyed-table.tab-ref-highlight,
+.sl-markdown-content .keyed-figure.fig-ref-highlight {
+  background: var(--sl-color-accent-low);
+  outline: 2px solid var(--sl-color-accent);
+  outline-offset: 0.2rem;
+  border-radius: 0.3rem;
+  transition:
+    background 120ms ease-out,
+    outline-color 120ms ease-out;
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content .keyed-table:target,
+  .sl-markdown-content .keyed-figure:target,
+  .sl-markdown-content .keyed-table.tab-ref-highlight,
+  .sl-markdown-content .keyed-figure.fig-ref-highlight {
+    animation: none;
+    outline: 2px solid Highlight;
+    outline-offset: 0.2rem;
+  }
+  .sl-markdown-content a.table-ref:hover,
+  .sl-markdown-content a.table-ref:focus-visible,
+  .sl-markdown-content a.figure-ref:hover,
+  .sl-markdown-content a.figure-ref:focus-visible {
+    outline: 2px solid Highlight;
+  }
+}
+
+/* Deep-linkable content headings (F3). The wrapper + anchor-link markup and its
+   hover/focus reveal come from Starlight's bundled `anchor-links.css`; these
+   rules add the sticky-header scroll offset and the `:target` flash, mirroring
+   the keyed-equation deep-link treatment. `HeadingAnchorEnhancer.astro` adds
+   the JS-only niceties (smooth scroll, repeat-activation re-trigger, and a
+   brief highlight of the section body). */
+.sl-markdown-content :is(h1, h2, h3, h4, h5, h6),
+.sl-markdown-content .sl-heading-wrapper {
+  scroll-margin-block-start: 5rem;
+}
+
+@keyframes heading-flash {
+  from {
+    background: var(--sl-color-accent-low);
+    box-shadow: 0 0 0 0.3rem var(--sl-color-accent-low);
+  }
+  to {
+    background: transparent;
+    box-shadow: 0 0 0 0.3rem transparent;
+  }
+}
+
+.sl-markdown-content :is(h1, h2, h3, h4, h5, h6):target,
+.sl-markdown-content .sl-heading-wrapper:has(> :target),
+.sl-markdown-content .deep-link-section-flash {
+  border-radius: 0.3rem;
+  /* `HeadingAnchorEnhancer.astro`'s `FLASH_MS` cleanup timeout must stay
+     comfortably longer than this so it never clips the fade-out. */
+  animation: heading-flash 5s ease-out both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sl-markdown-content :is(h1, h2, h3, h4, h5, h6):target,
+  .sl-markdown-content .sl-heading-wrapper:has(> :target) {
+    animation: none;
+    background: var(--sl-color-accent-low);
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.2rem;
+  }
+  .sl-markdown-content .deep-link-section-flash {
+    animation: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .sl-markdown-content :is(h1, h2, h3, h4, h5, h6):target,
+  .sl-markdown-content .sl-heading-wrapper:has(> :target) {
+    animation: none;
+    outline: 2px solid Highlight;
+    outline-offset: 0.2rem;
+  }
+}

package/src/components/starlight/EquationEnhancer.astro

@@ -1,72 +0,0 @@
----
-/**
- * Progressive enhancement for keyed equations (Step D7).
- *
- * The no-JS baseline is complete: `remark-notation` emits a real `id="eq-<key>"`
- * container, a focusable number `<a>`, and `[[eq:key]]` renders a plain anchor;
- * `global.css` does the `:target` deep-link highlight (with a
- * `prefers-reduced-motion` fallback) and the sticky-header scroll offset via
- * `scroll-margin`.
- *
- * This script only adds what CSS and anchors cannot:
- *  - re-triggering the highlight when the same `#eq-…` is activated again;
- *  - a smooth, header-aware scroll on an in-page jump;
- *  - moving keyboard focus onto the equation so screen-reader users land on it.
- *
- * Everything here is gated on `prefers-reduced-motion` and degrades to the
- * native anchor behaviour if it throws.
- */
----
-
-<script>
-  (() => {
-    const root = document.querySelector('.sl-markdown-content');
-    if (!root) return;
-
-    const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
-
-    const activate = (target: HTMLElement | null, doScroll: boolean) => {
-      if (!target) return;
-      if (!reduce.matches) {
-        // Restart the CSS `:target` animation even when the hash is unchanged.
-        target.style.animation = 'none';
-        void target.offsetWidth;
-        target.style.removeProperty('animation');
-      }
-      if (doScroll) {
-        target.scrollIntoView({
-          behavior: reduce.matches ? 'auto' : 'smooth',
-          block: 'start',
-        });
-      }
-      target.setAttribute('tabindex', '-1');
-      try {
-        target.focus({ preventScroll: true });
-      } catch {
-        target.focus();
-      }
-    };
-
-    root.addEventListener('click', (event) => {
-      const origin = event.target instanceof Element ? event.target : null;
-      const link = origin?.closest('a.equation-ref, a.keyed-equation__number');
-      if (!link) return;
-      const href = link.getAttribute('href') || '';
-      if (!href.startsWith('#eq-')) return; // cross-page: let the browser navigate
-      const target = document.getElementById(href.slice(1));
-      if (!target) return;
-      event.preventDefault();
-      if (location.hash !== href) history.pushState(null, '', href);
-      activate(target, true);
-    });
-
-    window.addEventListener('hashchange', () => {
-      if (!location.hash.startsWith('#eq-')) return;
-      activate(document.getElementById(location.hash.slice(1)), false);
-    });
-
-    if (location.hash.startsWith('#eq-')) {
-      activate(document.getElementById(location.hash.slice(1)), true);
-    }
-  })();
-</script>