explico 0.8.0 → 0.11.1

package/src/components/HoverPanel.astro

@@ -1,29 +1,30 @@
 ---
 /**
- * Shared hover/pin panel shell for the notation and citation layers.
+ * The shell every explanation card is cloned from: notation, citation,
+ * abbreviation and reference cards alike (rule C6 of
+ * `docs/plans/hover-card-consistency.md`).
  *
- * This component contributes only the fixed-position `<aside>` container and
- * its base styling. The interaction engine — side selection, the sticky-header
- * and article-column clamps, pin, Escape, and outside-close — lives once in
- * `./hover-panel.ts` and is wired from each layer's island script. The panel's
- * inner fields are slotted by the layer that owns them.
+ * It renders a `<template>`, so nothing shows until a layer's script clones
+ * it with `cloneCardShell` (`./card-manager.ts`) — once per card, which is
+ * what lets a layer show several cards at once. A card is an `<aside>` with
+ * a header row — a grip, the layer's `heading` slot, then a Side toggle, a
+ * Pin toggle and a × — a note line under it, and the layer's own fields in
+ * the default slot. The card manager owns the buttons (`data-card-grip`,
+ * `data-card-side`, `data-card-pin`, `data-card-close`), the note
+ * (`data-card-note`), the mode (`data-card-mode`: hover, pinned, side or
+ * moved), the flash (`is-card-flashing`) and where the card goes
+ * (`./card-placement.ts`, `./card-side.ts`, `./card-drag.ts`).
  *
- * Extra attributes (e.g. `data-notation-panel`, `data-citation-panel`) are
- * forwarded to the `<aside>` so each layer keeps the hook its tests and pin
- * controls already reference.
+ * Extra attributes (`data-citation-panel`, `data-float-ref-panel`, …) go on
+ * every card, so each layer keeps the hook its styles and tests use.
  *
- * `tabindex="-1"`: never in the tab order, but a valid target for
- * `panel.focus()`. A layer that lets the reader click deeper into the panel's
- * own content (D15's in-panel navigation) needs somewhere stable to move
- * focus to before it replaces whatever the reader just clicked — otherwise
- * removing the focused node drops focus to nothing, and the shared
- * `focusout` handler in `./hover-panel.ts` reads that as "the reader left"
- * and closes the panel it was just asked to update.
+ * `tabindex="-1"`: never in the tab order, but focusable, so a click inside
+ * a card raises it and focus has somewhere stable to go.
  */
 export interface Props {
-  /** Element id — pin controls point `aria-controls` at it. */
+  /** The template's id. Each card cloned from it gets `‹id›-‹n›`. */
   id: string;
-  /** Accessible name for the region. */
+  /** Accessible name for each card, until the layer gives it a specific one. */
   label: string;
   class?: string;
 }
@@ -31,52 +32,100 @@ export interface Props {
 const { id, label, class: className, ...rest } = Astro.props;
 ---
 
-<aside
-  class:list={['hover-panel', className]}
-  id={id}
-  role="region"
-  aria-label={label}
-  aria-live="polite"
-  aria-atomic="true"
-  hidden
-  tabindex="-1"
-  {...rest}
->
-  <button
-    class="hover-panel-close"
-    type="button"
-    data-hover-panel-close
-    aria-label="Close"
+<template id={id} data-card-template>
+  <aside
+    class:list={['hover-panel', className]}
+    role="region"
+    aria-label={label}
+    tabindex="-1"
+    {...rest}
   >
-    <span aria-hidden="true">&times;</span>
-  </button>
-  <div class="hover-panel-scroll">
-    <slot />
-  </div>
-</aside>
+    <div class="hover-panel-header">
+      <button
+        class="hover-panel-grip"
+        type="button"
+        data-card-grip
+        aria-label="Move card"
+        title="Drag to move this card. Arrow keys move it; Home puts it back."
+      >
+        <svg viewBox="0 0 10 16" width="10" height="16" aria-hidden="true">
+          <circle cx="3" cy="4" r="1.15"></circle>
+          <circle cx="7" cy="4" r="1.15"></circle>
+          <circle cx="3" cy="8" r="1.15"></circle>
+          <circle cx="7" cy="8" r="1.15"></circle>
+          <circle cx="3" cy="12" r="1.15"></circle>
+          <circle cx="7" cy="12" r="1.15"></circle>
+        </svg>
+      </button>
+      <div class="hover-panel-heading"><slot name="heading" /></div>
+      <div class="hover-panel-tools">
+        <button
+          class="hover-panel-side"
+          type="button"
+          data-card-side
+          aria-pressed="false"
+          aria-label="Side"
+          title="Keep this card beside the article"
+        >
+          <svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true">
+            <rect x="1.75" y="2.75" width="12.5" height="10.5" rx="1.5"></rect>
+            <path class="hover-panel-side-column" d="M10.25 2.75v10.5"></path>
+            <path class="hover-panel-side-fill" d="M10.25 3.5h3.25v9h-3.25z"></path>
+          </svg>
+        </button>
+        <button
+          class="hover-panel-pin"
+          type="button"
+          data-card-pin
+          aria-pressed="false"
+          aria-label="Pin"
+          title="Keep this card open"
+        >
+          <svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true">
+            <path
+              class="hover-panel-pin-head"
+              d="M6 1.75h4v4.25l2.25 2.75h-8.5L6 6z"
+            ></path>
+            <path d="M8 8.75V14.5"></path>
+          </svg>
+        </button>
+        <button
+          class="hover-panel-close"
+          type="button"
+          data-hover-panel-close
+          data-card-close
+          aria-label="Close"
+        >
+          <span aria-hidden="true">&times;</span>
+        </button>
+      </div>
+    </div>
+    <p class="hover-panel-note" data-card-note role="status" hidden></p>
+    <div class="hover-panel-scroll">
+      <slot />
+    </div>
+  </aside>
+</template>
 
 <style>
   @layer starlight.components {
     .hover-panel {
-      position: fixed;
-      z-index: 100;
-      /* The panel is an <aside> in the content flow; a stray cascade margin
-         would offset a position:fixed box from its computed `top`, so the
-         JS placement (which clears display equations) must start from zero. */
+      /* In the card layer, whose origin is the document's: `left`/`top` are
+         page coordinates, so the card scrolls with the page (P1). */
+      position: absolute;
       margin: 0;
-      width: min(23rem, calc(100vw - 1.5rem));
+      width: min(var(--explico-card-width, 23rem), calc(100vw - 1.5rem));
       display: flex;
       flex-direction: column;
-      /* The scrolling lives on `.hover-panel-scroll` below, not here — the
-         close button is an absolutely-positioned sibling of that scroller,
-         so it stays put when the content scrolls instead of scrolling away
-         with it (which is what happens to an absolutely-positioned child of
-         the scroll container itself). `hidden` also keeps the rounded
-         corners clean around the inner scroller. */
+      /* The scrolling lives on `.hover-panel-scroll` below, so the header
+         row stays put while a long card scrolls; `hidden` also keeps the
+         rounded corners clean around that scroller. */
       overflow: hidden;
-      border: 1px solid var(--sl-color-gray-5);
-      border-top: 0.25rem solid var(--sl-color-accent);
-      border-radius: 0.65rem;
+      /* No accent top rule: the system has none (`surfaces.css`). A floating
+         card keeps its overlay shadow — that is what lifts it off the page —
+         which is not the accent tier's in-flow `raised` depth. */
+      border: var(--ex-edge-border);
+      border-radius: var(--ex-radius-meta);
       color: var(--sl-color-text);
       background: var(--sl-color-bg);
       box-shadow: var(--sl-shadow-lg);
@@ -85,41 +134,135 @@ const { id, label, class: className, ...rest } = Astro.props;
 
     /* `.hover-panel { display: flex }` above has the same specificity as the
        UA stylesheet's `[hidden] { display: none }` and comes later in the
-       cascade, so it would otherwise win and defeat the `hidden` attribute
-       that every layer's JS relies on to actually hide the panel. */
+       cascade, so it would otherwise win and defeat the `hidden` attribute. */
     .hover-panel[hidden] {
       display: none;
     }
 
-    /* The equation/table/figure preview card (`FloatRefLayer.astro`) is the
-       one panel whose content size varies wildly — a short reference vs. a
-       wide equation — so it grows to fit instead of staying pinned at the
-       default width. `--float-ref-max-width` is computed in JS from the live
-       layout (the room between the left sidebar and the viewport edge); the
-       notation and citation panels never set it and keep the fixed default. */
+    /* C6: a kept card shows it, on its border as well as its Pin or Side
+       button. */
+    .hover-panel:is([data-card-mode='pinned'], [data-card-mode='side'], [data-card-mode='moved']) {
+      border-color: var(--sl-color-accent);
+      box-shadow:
+        var(--sl-shadow-lg),
+        0 0 0 1px var(--sl-color-accent);
+    }
+
+    /* C8: pointing at another occurrence of a kept card's item. */
+    .hover-panel.is-card-flashing {
+      outline: 3px solid transparent;
+      outline-offset: 2px;
+      animation: explico-card-flash var(--explico-card-flash, 500ms) ease-out;
+    }
+
+    @keyframes explico-card-flash {
+      from {
+        outline-color: var(--sl-color-accent);
+      }
+      to {
+        outline-color: transparent;
+      }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .hover-panel.is-card-flashing {
+        animation: none;
+        outline-color: var(--sl-color-accent);
+      }
+    }
+
+    /* P5: a reference card fits its content, a short reference or a wide
+       equation, up to the cap; wider content scrolls inside it. */
     .hover-panel[data-float-ref-panel] {
       width: fit-content;
-      min-width: min(23rem, var(--float-ref-max-width, 100vw));
-      max-width: var(--float-ref-max-width, min(23rem, calc(100vw - 1.5rem)));
+      min-width: min(var(--explico-card-width, 23rem), calc(100vw - 1.5rem));
+      max-width: min(
+        var(--explico-card-reference-max-width, 80ch),
+        calc(100vw - 1.5rem)
+      );
     }
 
-    .hover-panel-scroll {
-      overflow: auto;
-      /* Without these, this flex item's default `auto` minimum size is its
-         *content's* size, not the panel's — content wider or taller than the
-         panel would inflate the panel itself outward instead of scrolling
-         inside it (the same flexbox trap `.float-ref-panel-content` guards
-         against with its own `min-width: 0`). */
+    /* S1, S8: a docked card takes the side column's width, whatever its
+       layer: a wide reference wraps or scrolls inside rather than reaching
+       onto the rail. The manager caps its height. */
+    .hover-panel[data-card-mode='side'] {
+      width: var(--explico-card-side-width, var(--explico-card-width, 23rem));
       min-width: 0;
-      min-height: 0;
-      padding: 1rem;
-      padding-inline-end: 2.4rem;
+      max-width: none;
     }
 
-    .hover-panel-close {
+    /* S6: a docked card keeps × and its Side toggle; Side brings it back. A
+       moved card is kept too: Home, or a drop near its old spot, brings it
+       back (D5, D6). */
+    .hover-panel:is([data-card-mode='side'], [data-card-mode='moved']) .hover-panel-pin {
+      display: none;
+    }
+
+    .hover-panel-header {
+      position: relative;
+      display: flex;
+      align-items: flex-start;
+      gap: 0.5rem;
+      /* Logical, so the grip's margin is at the start in either direction. */
+      padding-block: 0.5rem 0;
+      padding-inline: 1.75rem 0.5rem;
+    }
+
+    /* D1: the grip, in the header's start margin. The only drag handle: the
+       rest of the card stays selectable, and only the grip turns off touch
+       panning. */
+    .hover-panel-grip {
       position: absolute;
-      top: 0.5rem;
-      right: 0.5rem;
+      inset-block-start: 0.5rem;
+      inset-inline-start: 0.35rem;
+      width: 1.1rem;
+      height: 1.6rem;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 0;
+      border: 0;
+      border-radius: 0.35rem;
+      color: var(--sl-color-gray-3);
+      background: transparent;
+      cursor: grab;
+      touch-action: none;
+      user-select: none;
+      -webkit-user-select: none;
+    }
+
+    .hover-panel-grip svg {
+      fill: currentColor;
+    }
+
+    .hover-panel-grip:hover,
+    .hover-panel[data-card-dragged] .hover-panel-grip {
+      color: var(--sl-color-text);
+      background: var(--sl-color-gray-6);
+    }
+
+    .hover-panel[data-card-dragged] {
+      box-shadow:
+        var(--sl-shadow-lg),
+        0 0 0 1px var(--sl-color-accent);
+    }
+
+    .hover-panel-heading {
+      flex: 1;
+      min-width: 0;
+      padding-block-start: 0.2rem;
+    }
+
+    .hover-panel-tools {
+      flex: none;
+      display: flex;
+      align-items: center;
+      gap: 0.15rem;
+    }
+
+    .hover-panel-side,
+    .hover-panel-pin,
+    .hover-panel-close {
       width: 1.6rem;
       height: 1.6rem;
       display: flex;
@@ -130,21 +273,230 @@ const { id, label, class: className, ...rest } = Astro.props;
       border-radius: 0.35rem;
       color: var(--sl-color-gray-3);
       background: transparent;
+      cursor: pointer;
+    }
+
+    .hover-panel-close {
       font-size: 1.15rem;
       line-height: 1;
-      cursor: pointer;
     }
 
+    .hover-panel-side:hover,
+    .hover-panel-pin:hover,
     .hover-panel-close:hover {
       color: var(--sl-color-text);
       background: var(--sl-color-gray-6);
     }
 
+    .hover-panel-side svg,
+    .hover-panel-pin svg {
+      fill: none;
+      stroke: currentColor;
+      stroke-width: 1.4;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+
+    .hover-panel-side[aria-pressed='true'],
+    .hover-panel-pin[aria-pressed='true'] {
+      color: var(--sl-color-text-accent);
+      background: var(--sl-color-accent-low);
+    }
+
+    .hover-panel-pin[aria-pressed='true'] .hover-panel-pin-head {
+      fill: currentColor;
+    }
+
+    .hover-panel-side-fill {
+      stroke: none;
+    }
+
+    .hover-panel-side[aria-pressed='true'] .hover-panel-side-fill {
+      fill: currentColor;
+    }
+
+    /* S7: below 72rem there is never a side column, so no Side button. The
+       side column is laid out left to right only. */
+    @media not all and (min-width: 72rem) {
+      .hover-panel-side {
+        display: none;
+      }
+    }
+
+    :global([dir='rtl']) .hover-panel-side {
+      display: none;
+    }
+
+    /* S7: "Collapse a side panel to make room", under the header row. */
+    .hover-panel-note {
+      margin: 0.35rem 1rem 0;
+      padding: 0.25rem 0.5rem;
+      border-radius: 0.35rem;
+      font-size: var(--sl-text-xs);
+      color: var(--sl-color-text);
+      background: var(--sl-color-gray-6);
+    }
+
+    .hover-panel-note[hidden] {
+      display: none;
+    }
+
+    .hover-panel-scroll {
+      overflow: auto;
+      /* Without these, this flex item's default `auto` minimum size is its
+         *content's* size, not the panel's — content wider or taller than the
+         panel would inflate the panel itself outward instead of scrolling
+         inside it (the same flexbox trap `.float-ref-panel-content` guards
+         against with its own `min-width: 0`). */
+      min-width: 0;
+      min-height: 0;
+      padding: 0.35rem 1rem 1rem;
+    }
+
     /* Slotted fields carry the owning layer's scope, not this component's, so
        the descendant match must be global. */
     .hover-panel :global(:focus-visible) {
       outline: 3px solid var(--sl-color-accent);
       outline-offset: 2px;
     }
+
+    @media (forced-colors: active) {
+      .hover-panel:is([data-card-mode='pinned'], [data-card-mode='side'], [data-card-mode='moved']) {
+        border-color: Highlight;
+      }
+    }
+  }
+
+  /* D1: while a card is dragged, nothing on the page is selected and the
+     pointer shows the grab everywhere. */
+  :global(html[data-card-dragging]),
+  :global(html[data-card-dragging] *) {
+    cursor: grabbing !important;
+    user-select: none !important;
+    -webkit-user-select: none !important;
+  }
+
+  /* D3: the docking area's tint from a drag's first movement; once the card
+     snaps, a dashed line on the article's edge, the dashed outline of where
+     it lands, and a label (`../card-drag.ts`). Fixed to the window at the
+     bottom of the card layer: over the article, under every card. */
+  :global(.explico-card-dock) {
+    position: fixed;
+    inset: 0;
+    z-index: 0;
+    pointer-events: none;
+  }
+
+  :global(.explico-card-dock [hidden]) {
+    display: none;
+  }
+
+  :global(.explico-card-dock-area) {
+    position: fixed;
+    bottom: 0;
+    background: color-mix(in srgb, var(--sl-color-accent) 6%, transparent);
+  }
+
+  :global(.explico-card-dock-edge) {
+    position: fixed;
+    bottom: 0;
+    width: 0;
+    border-inline-start: 2px dashed var(--sl-color-accent);
+    transform: translateX(-1px);
+  }
+
+  :global(.explico-card-dock-outline) {
+    position: fixed;
+    box-sizing: border-box;
+    border: 2px dashed var(--sl-color-accent);
+    border-radius: var(--ex-radius-meta);
+    background: color-mix(in srgb, var(--sl-color-accent) 10%, transparent);
+  }
+
+  :global(.explico-card-dock-label) {
+    position: fixed;
+    transform: translateX(-50%);
+    padding: 0.2rem 0.75rem;
+    border: 1px solid var(--sl-color-accent);
+    border-radius: 999px;
+    font-size: var(--sl-text-xs);
+    line-height: 1.4;
+    white-space: nowrap;
+    color: var(--sl-color-text-accent);
+    background: var(--sl-color-bg);
+    box-shadow: var(--sl-shadow-sm);
+  }
+
+  @media (forced-colors: active) {
+    :global(.explico-card-dock-area),
+    :global(.explico-card-dock-outline) {
+      background: transparent;
+    }
+
+    :global(.explico-card-dock-edge),
+    :global(.explico-card-dock-outline),
+    :global(.explico-card-dock-label) {
+      border-color: Highlight;
+    }
+  }
+
+  @media print {
+    :global(.explico-card-dock) {
+      display: none;
+    }
+  }
+
+  /* S5: the arrow from a kept card to an occurrence of its item
+     (`../card-arrow.ts`), at the bottom of the card layer. */
+  :global(.explico-card-arrow) {
+    transition: opacity var(--explico-card-motion, 100ms) ease-out;
+  }
+
+  :global(.explico-card-arrow.is-fading) {
+    opacity: 0;
+  }
+
+  :global(.explico-card-arrow-line) {
+    fill: none;
+    stroke: var(--sl-color-accent);
+    stroke-width: 1.75;
+    stroke-linecap: round;
+  }
+
+  :global(.explico-card-arrow-head) {
+    fill: var(--sl-color-accent);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :global(.explico-card-arrow) {
+      transition: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :global(.explico-card-arrow-line) {
+      stroke: Highlight;
+    }
+
+    :global(.explico-card-arrow-head) {
+      fill: Highlight;
+    }
+  }
+
+  @media print {
+    :global(.explico-card-arrow) {
+      display: none;
+    }
+  }
+
+  /* The open mobile menu covers the page; the cards above it would float
+     over the menu. */
+  :global(body[data-mobile-menu-expanded] .explico-card-layer) {
+    display: none;
+  }
+
+  /* Escape can hand focus back to the article (C10); it needs no ring. */
+  :global(main[data-card-focus-return]:focus) {
+    outline: none;
   }
 </style>

package/src/components/PartBridge.astro

@@ -0,0 +1,27 @@
+---
+/**
+ * The paragraph on a part's overview page that says how the earlier parts
+ * lead into this one — which results it reuses, and what they now make
+ * possible. Rule S2 requires one on every part after the first, placed before
+ * `<PartScope>`; `gate-part-pages.ts` checks that it holds one paragraph within
+ * the course's `partPages.bridge` word range.
+ *
+ * Usage, in `content/docs/<part>/index.mdx`:
+ *
+ * ```mdx
+ * import PartBridge from 'explico/components/PartBridge.astro';
+ *
+ * <PartBridge>
+ *
+ * Part 1 gave the position of a point and, for a constant acceleration, its
+ * velocity and position at any later time. …
+ *
+ * </PartBridge>
+ * ```
+ *
+ * Keep a blank line inside each tag, so the paragraph is parsed as Markdown
+ * and its math and `[[key]]` references render.
+ */
+---
+
+<div class="part-intro part-bridge" data-part-intro="bridge"><slot /></div>