explico 0.2.0 → 0.4.0

package/src/styles/global.css

@@ -448,6 +448,135 @@
     min-height: 100%;
   }
 
+  /* A compact chapter remains useful as a row of lesson icons. The
+     link text doubles as a pointer/keyboard tooltip; opening the chapter via
+     its summary restores Starlight's normal, fully labelled list. */
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.35rem;
+    margin: 0.2rem 0 0.35rem;
+    padding-inline-start: 0.5rem;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li {
+    position: relative;
+    margin-inline-start: 0;
+    border-inline-start: 0;
+    padding-inline-start: 0;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a {
+    display: grid;
+    position: relative;
+    place-items: center;
+    width: 1.75rem;
+    height: 1.75rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.4rem;
+    padding: 0;
+    color: var(--sl-color-gray-3);
+    background: var(--sl-color-bg-sidebar);
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a::before {
+    content: '';
+    width: 0.65rem;
+    height: 0.78rem;
+    border: 1.5px solid currentColor;
+    border-radius: 0.13rem;
+    box-shadow: 0.18rem 0.18rem 0 -0.1rem var(--sl-color-bg-sidebar),
+      0.18rem 0.18rem 0 0 currentColor;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a:hover,
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a:focus-visible {
+    border-color: var(--sl-color-accent);
+    color: var(--sl-color-text-accent);
+    background: var(--sl-color-accent-low);
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a[aria-current='page'] {
+    color: var(--sl-color-text-invert);
+    background: var(--sl-color-text-accent);
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a
+    > span {
+    position: absolute;
+    z-index: 2;
+    inset-block-start: 50%;
+    inset-inline-start: calc(100% + 0.45rem);
+    width: max-content;
+    max-width: 12rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.35rem;
+    padding: 0.3rem 0.5rem;
+    color: var(--sl-color-white);
+    background: var(--sl-color-bg-nav);
+    box-shadow: var(--sl-shadow-md);
+    font-size: var(--sl-text-xs);
+    font-weight: 500;
+    line-height: 1.3;
+    opacity: 0;
+    pointer-events: none;
+    transform: translateY(-50%) translateX(-0.2rem);
+    transition:
+      opacity 100ms ease,
+      transform 100ms ease;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a:is(:hover, :focus-visible)
+    > span {
+    opacity: 1;
+    transform: translateY(-50%) translateX(0);
+  }
+
+  .layout-compact-sidebar details[data-compact] > summary .caret {
+    transform: rotateZ(0);
+  }
+
+  [dir='rtl']
+    .layout-compact-sidebar
+    details[data-compact]
+    > summary
+    .caret {
+    transform: rotateZ(180deg);
+  }
+
   .layout-navigation-toggle {
     position: fixed;
     z-index: calc(var(--sl-z-index-menu) + 1);
@@ -668,7 +797,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,12 +819,11 @@
   font-size: var(--sl-text-sm);
   color: var(--sl-color-text-accent);
   text-decoration: none;
-  /* Hardly visible until you look for it (F3): transparent by default, so it
-     never competes with the equation, and — being `opacity:0`, not `hidden` —
-     still announced to assistive tech and revealed on hover/focus/deep-link.
-     A partial opacity would fail the WCAG contrast check, so it is all or
-     nothing, mirroring Starlight's own heading anchor links. */
-  opacity: 0;
+  /* 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;
 }
 
@@ -726,6 +854,41 @@
   }
 }
 
+/* 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;
@@ -785,12 +948,86 @@
     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

package/src/components/starlight/EquationEnhancer.astro

@@ -1,87 +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:
- *  - a smooth, header-aware scroll on an in-page jump;
- *  - re-triggering the highlight when the same `#eq-…` is activated again —
- *    the one case a plain anchor click does nothing for, since the browser
- *    won't navigate to a fragment that's already current;
- *  - moving keyboard focus onto the equation so screen-reader users land on it.
- *
- * It deliberately does *not* intercept an ordinary click that changes the
- * hash. `:target` is set only by a genuine same-document fragment
- * navigation — never by `history.pushState` (a common trap: pushState
- * updates the URL but leaves `:target`, and thus `eq-flash`, dark). Letting
- * the click through and reacting to the `hashchange` it produces is what
- * actually plays the highlight.
- *
- * 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;
-      // Only the already-on-this-anchor click needs handling here — the
-      // browser has nothing new to navigate to, so it won't fire `hashchange`
-      // and nothing else will re-trigger the flash. Every other click is left
-      // alone: its native navigation sets `:target` and fires `hashchange`,
-      // which the listener below turns into the same `activate()`.
-      if (location.hash === href) {
-        event.preventDefault();
-        activate(target, true);
-      }
-    });
-
-    window.addEventListener('hashchange', () => {
-      if (!location.hash.startsWith('#eq-')) return;
-      activate(document.getElementById(location.hash.slice(1)), true);
-    });
-
-    if (location.hash.startsWith('#eq-')) {
-      activate(document.getElementById(location.hash.slice(1)), true);
-    }
-  })();
-</script>