explico 0.4.0 → 0.5.0

package/src/components/diagram/Diagram.astro

@@ -26,6 +26,10 @@ import { renderNotationFormula } from '../notation/render-notation-math';
 import type { SafeMathNode as SafeMathNodeType } from '../notation/render-notation-math';
 import SafeMathNode from '../notation/SafeMathNode.astro';
 import type { GlyphScopeEntry } from '../../reference/gloss';
+import {
+  notationKeysInMathNodes,
+  registerPageNotationDependencies,
+} from '../../reference/page-notation';
 
 export interface DiagramNode {
   readonly id: string;
@@ -53,6 +57,19 @@ export interface Props {
   /** Glyph scope `formula` resolves against — omit if no node uses `formula`. */
   scope?: readonly GlyphScopeEntry[];
   direction?: 'TB' | 'LR';
+  /** Computed by `remark-notation.mjs` for a top-level lesson diagram. */
+  number?: string;
+  /** Computed by `remark-notation.mjs` for a top-level lesson diagram. */
+  anchorId?: string;
+  /** Author-chosen state for a reader with nothing saved yet. Default: `true`. */
+  defaultOpen?: boolean;
+  /** Persist the reader's open/closed choice across visits. Default: `true`. */
+  rememberState?: boolean;
+  /**
+   * Emit a build warning when the laid-out SVG is wider than this many pixels.
+   * Set `false` only when horizontal overflow is deliberate. Default: `800`.
+   */
+  warnAboveWidth?: number | false;
   /**
    * Prose text alternative for the SVG. When omitted, the fallback is
    * generated from the node labels and the edge chain — readable, but a
@@ -69,6 +86,11 @@ const {
   scope = [],
   direction = 'TB',
   description,
+  number,
+  anchorId,
+  defaultOpen = true,
+  rememberState = true,
+  warnAboveWidth = 800,
 } = Astro.props;
 
 const idPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
@@ -78,6 +100,17 @@ if (!idPattern.test(id)) {
 if (nodes.length === 0) {
   throw new Error(`Diagram "${id}" has no nodes.`);
 }
+if ((number && !anchorId) || (!number && anchorId)) {
+  throw new Error(
+    `Diagram "${id}" must receive both computed \`number\` and \`anchorId\`, or neither.`,
+  );
+}
+if (
+  warnAboveWidth !== false &&
+  (!Number.isFinite(warnAboveWidth) || warnAboveWidth <= 0)
+) {
+  throw new Error(`Diagram "${id}" requires a positive \`warnAboveWidth\`.`);
+}
 
 interface RenderedNode extends DiagramNode {
   readonly mathNodes?: readonly SafeMathNodeType[];
@@ -114,6 +147,15 @@ const rendered: RenderedNode[] = nodes.map((node) => {
   return { ...node, mathNodes };
 });
 
+for (const node of rendered) {
+  if (!node.mathNodes) continue;
+  registerPageNotationDependencies(
+    Astro.locals,
+    notationKeysInMathNodes(node.mathNodes),
+    `Diagram "${id}" node "${node.id}" formula "${node.formula}"`,
+  );
+}
+
 const sized = rendered.map((node) => ({
   node,
   box:
@@ -134,6 +176,19 @@ const layout = layoutDiagram(
 const nodeById = new Map(rendered.map((node) => [node.id, node]));
 const laidOutById = new Map(layout.nodes.map((node) => [node.id, node]));
 const markerId = `diagram-arrow-${id}`;
+const legacyAnchorId = `diagram-${id}`;
+const renderedAnchorId = anchorId ?? legacyAnchorId;
+const viewportId = `${legacyAnchorId}-viewport`;
+
+if (warnAboveWidth !== false && layout.width > warnAboveWidth) {
+  console.warn(
+    `[explico/Diagram] "${id}" lays out at ${layout.width}px wide, above the ` +
+      `${warnAboveWidth}px authoring threshold. It will scroll and can be expanded ` +
+      `by readers, but consider recreating the graph with direction="TB", shorter ` +
+      `labels, or explicit node sizes. Set warnAboveWidth={false} only when the ` +
+      `horizontal overflow is intentional.`,
+  );
+}
 
 /** A node's human label for the text fallback — never the internal id. */
 function fallbackLabel(nodeId: string): string {
@@ -148,100 +203,361 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
 }
 ---
 
-<figure class="diagram" id={`diagram-${id}`}>
-  <figcaption id={`${id}-caption`}>{label}</figcaption>
-  <div class="diagram-scroll" tabindex="0" role="group" aria-labelledby={`${id}-caption`}>
-  <svg
-    viewBox={`0 0 ${layout.width} ${layout.height}`}
-    width={layout.width}
-    height={layout.height}
-  >
-    <defs>
-      <marker
-        id={markerId}
-        viewBox="0 0 10 10"
-        refX="9"
-        refY="5"
-        markerWidth="7"
-        markerHeight="7"
-        orient="auto-start-reverse"
-      >
-        <path d="M 0 0 L 10 5 L 0 10 z" class="diagram-arrowhead" />
-      </marker>
-    </defs>
-
-    {
-      layout.edges.map((edge) => (
-        <path
-          d={pathFrom(edge.points)}
-          class="diagram-edge"
-          marker-end={`url(#${markerId})`}
-        />
-      ))
-    }
-
-    {
-      layout.nodes.map((position) => {
-        const node = nodeById.get(position.id)!;
-        return (
-          <g transform={`translate(${position.x}, ${position.y})`} class="diagram-node">
-            <rect width={position.width} height={position.height} rx="8" ry="8" />
-            <foreignObject width={position.width} height={position.height}>
-              <div xmlns="http://www.w3.org/1999/xhtml" class="diagram-node-content">
-                {node.text && <span class="diagram-node-text">{node.text}</span>}
-                {node.mathNodes && (
-                  <span class="diagram-node-formula notation-math">
-                    {node.mathNodes.map((mathNode) => (
-                      <SafeMathNode node={mathNode} />
+<figure
+  class="diagram"
+  id={renderedAnchorId}
+  aria-labelledby={`${id}-caption`}
+  data-dia-number={number}
+  data-dia-key={number ? id : undefined}
+  data-diagram-width={layout.width}
+  data-diagram-expandable
+>
+  <div class="diagram__titlebar">
+    <details
+      class="diagram__details"
+      data-diagram-details
+      data-remember-state={String(rememberState)}
+      data-state={defaultOpen ? 'open' : 'closed'}
+      open={defaultOpen}
+    >
+      <summary class="diagram__summary" id={`${id}-caption`}>
+        {number && <span class="diagram__number">Diagram {number}</span>}
+        <span class="diagram__caption-text">{label}</span>
+      </summary>
+      <div class="diagram__body" data-diagram-body>
+        <div
+          class="diagram-stage"
+          id={renderedAnchorId === legacyAnchorId ? undefined : legacyAnchorId}
+        >
+          <div
+            id={viewportId}
+            class="diagram-scroll"
+            tabindex="0"
+            role="group"
+            aria-labelledby={`${id}-caption`}
+          >
+            <div
+              class="diagram-canvas"
+              style={`--diagram-print-ratio: ${layout.width} / ${layout.height}; width: ${layout.width}px; height: ${layout.height}px;`}
+            >
+              <svg
+                viewBox={`0 0 ${layout.width} ${layout.height}`}
+                width="100%"
+                height="100%"
+              >
+                <defs>
+                  <marker
+                    id={markerId}
+                    viewBox="0 0 10 10"
+                    refX="9"
+                    refY="5"
+                    markerWidth="7"
+                    markerHeight="7"
+                    orient="auto-start-reverse"
+                  >
+                    <path
+                      d="M 0 0 L 10 5 L 0 10 z"
+                      class="diagram-arrowhead"
+                    />
+                  </marker>
+                </defs>
+
+                {
+                  layout.edges.map((edge) => (
+                    <path
+                      d={pathFrom(edge.points)}
+                      class="diagram-edge"
+                      marker-end={`url(#${markerId})`}
+                    />
+                  ))
+                }
+
+                {
+                  layout.nodes.map((position) => {
+                    const node = nodeById.get(position.id)!;
+                    return (
+                      <g
+                        transform={`translate(${position.x}, ${position.y})`}
+                        class="diagram-node"
+                      >
+                        <rect
+                          width={position.width}
+                          height={position.height}
+                          rx="8"
+                          ry="8"
+                        />
+                        <foreignObject
+                          width={position.width}
+                          height={position.height}
+                        >
+                          <div
+                            xmlns="http://www.w3.org/1999/xhtml"
+                            class="diagram-node-content"
+                          >
+                            {
+                              node.text && (
+                                <span class="diagram-node-text">{node.text}</span>
+                              )
+                            }
+                            {
+                              node.mathNodes && (
+                                <span class="diagram-node-formula notation-math">
+                                  {node.mathNodes.map((mathNode) => (
+                                    <SafeMathNode node={mathNode} />
+                                  ))}
+                                </span>
+                              )
+                            }
+                          </div>
+                        </foreignObject>
+                      </g>
+                    );
+                  })
+                }
+              </svg>
+            </div>
+          </div>
+        </div>
+
+        <details class="diagram-fallback">
+          <summary>Diagram description</summary>
+          {
+            description ? (
+              <p>{description}</p>
+            ) : (
+              <Fragment>
+                <ol>
+                  {rendered.map((node) => (
+                    <li>{fallbackLabel(node.id)}</li>
+                  ))}
+                </ol>
+                {edges.length > 0 && (
+                  <p class="diagram-fallback-flow">
+                    {edges.map((edge, index) => (
+                      <Fragment>
+                        {index > 0 && '; '}
+                        {fallbackLabel(edge.from)} → {fallbackLabel(edge.to)}
+                      </Fragment>
                     ))}
-                  </span>
+                  </p>
                 )}
-              </div>
-            </foreignObject>
-          </g>
-        );
-      })
-    }
-  </svg>
-  </div>
+              </Fragment>
+            )
+          }
+        </details>
+      </div>
+    </details>
 
-  <details class="diagram-fallback">
-    <summary>Diagram description</summary>
-    {
-      description ? (
-        <p>{description}</p>
-      ) : (
-        <Fragment>
-          <ol>
-            {rendered.map((node) => (
-              <li>{fallbackLabel(node.id)}</li>
-            ))}
-          </ol>
-          {edges.length > 0 && (
-            <p class="diagram-fallback-flow">
-              {edges.map((edge, index) => (
-                <Fragment>
-                  {index > 0 && '; '}
-                  {fallbackLabel(edge.from)} → {fallbackLabel(edge.to)}
-                </Fragment>
-              ))}
-            </p>
-          )}
-        </Fragment>
-      )
-    }
-  </details>
+    <a
+      class="diagram__title-anchor"
+      href={`#${renderedAnchorId}`}
+      aria-label={`${number ? `Diagram ${number}: ` : ''}${label}`}
+    >
+      <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 class="diagram-toolbar" data-diagram-toolbar hidden>
+      <button
+        type="button"
+        class="diagram-expand-button"
+        data-diagram-expand
+        aria-controls={viewportId}
+        aria-expanded="false"
+        title="Expand diagram horizontally"
+      >
+        <svg aria-hidden="true" viewBox="0 0 24 24">
+          <path class="diagram-expand-icon" d="M3 12h18M8 7l-5 5 5 5M16 7l5 5-5 5" />
+          <path
+            class="diagram-shrink-icon"
+            d="M3 12h7M7 9l3 3-3 3M21 12h-7M17 9l-3 3 3 3"
+          />
+        </svg>
+        <span class="sr-only">Expand {label}</span>
+      </button>
+    </div>
+  </div>
 </figure>
 
 <style>
   @layer starlight.components {
     .diagram {
+      position: relative;
       margin: 1.5rem 0;
+      max-width: 100%;
+      contain: inline-size;
+    }
+
+    .diagram__titlebar {
+      position: relative;
+    }
+
+    .diagram__details {
+      border-inline-start: 0;
+      padding-inline-start: 0;
     }
 
-    .diagram figcaption {
-      margin-block-end: 0.5rem;
+    .diagram__summary {
+      position: relative;
+      min-height: 1.75rem;
+      padding-inline-end: 4rem;
       font-weight: 600;
+      cursor: pointer;
+    }
+
+    .diagram__summary::before {
+      position: absolute;
+      top: 50%;
+      left: -1.35em;
+      margin: 0;
+      transform: translateY(-50%);
+      opacity: 0;
+      transition:
+        opacity 150ms ease 700ms,
+        transform 150ms ease;
+    }
+
+    .diagram__details[data-state='open'] > .diagram__summary::before {
+      transform: translateY(-50%) rotateZ(90deg);
+    }
+
+    .diagram__details[data-state='closed'] > .diagram__summary::before {
+      opacity: 1;
+      transition: none;
+    }
+
+    .diagram__summary:hover::before,
+    .diagram__summary:focus-visible::before {
+      opacity: 1;
+      transition: opacity 100ms ease;
+    }
+
+    .diagram__body {
+      overflow: hidden;
+      transition: max-height 220ms ease;
+    }
+
+    .diagram__number {
+      color: var(--sl-color-text-accent);
+    }
+
+    .diagram__caption-text::before {
+      content: ' — ';
+    }
+
+    .diagram__summary > .diagram__caption-text:first-child::before {
+      content: none;
+    }
+
+    .diagram__title-anchor {
+      position: absolute;
+      top: 0.1rem;
+      inset-inline-end: 0;
+      display: inline-flex;
+      width: 1.5rem;
+      height: 1.5rem;
+      align-items: center;
+      justify-content: center;
+      color: var(--sl-color-gray-3);
+      text-decoration: none;
+      opacity: 1;
+    }
+
+    .diagram[data-diagram-overflow='true'] .diagram__title-anchor {
+      inset-inline-end: 2rem;
+    }
+
+    .diagram__title-anchor svg {
+      width: 0.9rem;
+      height: 0.9rem;
+    }
+
+    .diagram__title-anchor:hover,
+    .diagram__title-anchor:focus-visible {
+      color: var(--sl-color-text-accent);
+    }
+
+    .diagram__title-anchor:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 0.1rem;
+    }
+
+    @media (hover: hover) {
+      .diagram__title-anchor {
+        opacity: 0;
+      }
+
+      .diagram__details:has(> .diagram__summary:hover) ~ .diagram__title-anchor,
+      .diagram__details:has(> .diagram__summary:focus-visible)
+        ~ .diagram__title-anchor,
+      .diagram__title-anchor:hover,
+      .diagram__title-anchor:focus-visible {
+        opacity: 1;
+      }
+    }
+
+    .diagram-stage {
+      min-width: 0;
+      max-width: 100%;
+      overflow: hidden;
+    }
+
+    .diagram-toolbar {
+      position: absolute;
+      z-index: 2;
+      top: -0.25rem;
+      inset-inline-end: 0;
+    }
+
+    .diagram-toolbar[hidden] {
+      display: none;
+    }
+
+    .diagram-expand-button {
+      display: inline-flex;
+      width: 1.75rem;
+      height: 1.75rem;
+      margin: 0;
+      align-items: center;
+      justify-content: center;
+      color: var(--sl-color-gray-2);
+      border: 0;
+      border-radius: 0.25rem;
+      background: transparent;
+      cursor: pointer;
+    }
+
+    .diagram-expand-button svg {
+      width: 1.1rem;
+      height: 1.1rem;
+      fill: none;
+      stroke: currentColor;
+      stroke-width: 1.8;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+
+    .diagram-expand-button[aria-expanded='false'] .diagram-shrink-icon,
+    .diagram-expand-button[aria-expanded='true'] .diagram-expand-icon {
+      display: none;
+    }
+
+    .diagram-expand-button:hover {
+      color: var(--sl-color-text);
+      background: var(--sl-color-accent-low);
+    }
+
+    .diagram-expand-button:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 1px;
     }
 
     /* A wide graph scrolls inside its own box rather than shrinking to
@@ -250,6 +566,10 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
        that: a scrollable region a keyboard user cannot reach is unreachable
        content, not just an awkward one. */
     .diagram-scroll {
+      width: 100%;
+      min-width: 0;
+      max-width: 100%;
+      flex: 1 1 auto;
       overflow-x: auto;
       padding-block: 0.15rem;
     }
@@ -259,11 +579,27 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
       outline-offset: 2px;
     }
 
-    .diagram svg {
+    .diagram-canvas > svg {
       display: block;
+      /* Starlight globally constrains SVGs to the content width. That is safe
+         for an all-SVG illustration, but this diagram embeds HTML/KaTeX in
+         `foreignObject` nodes. WebKit on iOS can scale the SVG geometry while
+         leaving that HTML at its unscaled size, which puts formulas outside
+         their boxes. Keep the build-time dimensions and let the keyboard-
+         reachable wrapper above provide the intended horizontal scroll. */
+      max-width: none;
       overflow: visible;
     }
 
+    .diagram-canvas {
+      flex: none;
+    }
+
+    .diagram.dia-ref-highlight {
+      outline: 3px solid var(--sl-color-accent);
+      outline-offset: 0.25rem;
+    }
+
     .diagram-node rect {
       fill: var(--sl-color-gray-7);
       stroke: var(--sl-color-gray-5);
@@ -313,5 +649,30 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
     .diagram-fallback ol {
       padding-inline-start: 1.25rem;
     }
+
+    @media print {
+      .diagram-toolbar,
+      .diagram__title-anchor,
+      .diagram__summary::before {
+        display: none;
+      }
+
+      .diagram__number {
+        color: inherit;
+      }
+
+      .diagram__body {
+        display: block !important;
+        max-height: none !important;
+        overflow: visible !important;
+      }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .diagram__summary::before,
+      .diagram__body {
+        transition: none;
+      }
+    }
   }
 </style>