explico 0.8.0 → 0.11.1

package/src/components/diagram/Diagram.astro

@@ -20,11 +20,23 @@
  * Box sizes are a generous estimate (`reference/diagram-layout.ts`) unless a
  * node gives an explicit `width`/`height` — there is no DOM at build time to
  * measure a real render against.
+ *
+ * Named like every float (docs/plans/titles-and-containers.md Part 3): the
+ * long `caption` sits below the graph with its number, in the same caption
+ * line a `<Figure>` has (`../figure/FloatCaption.astro`), and an optional
+ * `short` caption heads the `[[dia-…]]` preview card. A diagram is always
+ * its graph and then that line (docs/plans/figures-and-short-captions.md,
+ * decision 1); the line ends with the widen button ↔, shown while the graph
+ * overflows its column (`../starlight/DiagramEnhancer.astro`). To let a
+ * reader fold a diagram away, wrap it in a `<Fold>` or put it in a
+ * collapsible section.
  */
 import { estimateBoxSize, layoutDiagram } from '../../reference/diagram-layout';
 import { renderNotationFormula } from '../notation/render-notation-math';
 import type { SafeMathNode as SafeMathNodeType } from '../notation/render-notation-math';
 import SafeMathNode from '../notation/SafeMathNode.astro';
+import FloatCaption from '../figure/FloatCaption.astro';
+import { DIAGRAM_NO_LONGER_FOLDS } from '../../reference/diagrams-validate';
 import type { GlyphScopeEntry } from '../../reference/gloss';
 import {
   notationKeysInMathNodes,
@@ -50,8 +62,10 @@ export interface DiagramEdge {
 export interface Props {
   /** Unique on the page — namespaces the arrowhead marker id. */
   id: string;
-  /** Visible caption; also the diagram's accessible name. */
-  label: string;
+  /** The long caption, shown below the diagram with its number; also its accessible name. */
+  caption: string;
+  /** Optional short caption: heads the `[[dia-…]]` preview card; rule S1 measures it. */
+  short?: string;
   nodes: readonly DiagramNode[];
   edges: readonly DiagramEdge[];
   /** Glyph scope `formula` resolves against — omit if no node uses `formula`. */
@@ -61,10 +75,6 @@ export interface Props {
   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`.
@@ -74,15 +84,14 @@ export interface Props {
 
 const {
   id,
-  label,
+  caption,
+  short,
   nodes,
   edges,
   scope = [],
   direction = 'TB',
   number,
   anchorId,
-  defaultOpen = true,
-  rememberState = true,
   warnAboveWidth = 800,
 } = Astro.props;
 
@@ -90,6 +99,26 @@ const idPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
 if (!idPattern.test(id)) {
   throw new Error(`Unsafe Diagram id: ${id}`);
 }
+for (const removed of ['label', 'title'] as const) {
+  if (removed in Astro.props) {
+    throw new Error(
+      `<Diagram id="${id}"> has no \`${removed}\` prop: a diagram is named by its \`caption\` (shown below it with its number) and an optional \`short\` caption.`,
+    );
+  }
+}
+// Also caught in the MDX by `dia-removed-prop`; this catches a diagram a
+// wrapper component renders, whose props the MDX scan never sees.
+for (const removed of ['defaultOpen', 'rememberState'] as const) {
+  if (removed in Astro.props) {
+    throw new Error(`<Diagram id="${id}"> has no \`${removed}\` prop: ${DIAGRAM_NO_LONGER_FOLDS}`);
+  }
+}
+if (typeof caption !== 'string' || !caption.trim()) {
+  throw new Error(`Diagram "${id}" requires a non-empty \`caption\` prop.`);
+}
+if (short !== undefined && (typeof short !== 'string' || !short.trim())) {
+  throw new Error(`Diagram "${id}" \`short\` must be a non-empty string when given.`);
+}
 if (nodes.length === 0) {
   throw new Error(`Diagram "${id}" has no nodes.`);
 }
@@ -172,6 +201,7 @@ const markerId = `diagram-arrow-${id}`;
 const legacyAnchorId = `diagram-${id}`;
 const renderedAnchorId = anchorId ?? legacyAnchorId;
 const viewportId = `${legacyAnchorId}-viewport`;
+const captionTextId = `${legacyAnchorId}-caption`;
 
 if (warnAboveWidth !== false && layout.width > warnAboveWidth) {
   console.warn(
@@ -193,158 +223,140 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
 <figure
   class="diagram"
   id={renderedAnchorId}
-  aria-labelledby={`${id}-caption`}
   data-dia-number={number}
   data-dia-key={number ? id : undefined}
+  data-dia-short={short}
   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}
+  <div class="diagram__body">
+    <div
+      class="diagram-stage"
+      id={renderedAnchorId === legacyAnchorId ? undefined : legacyAnchorId}
     >
-      <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
+        id={viewportId}
+        class="diagram-scroll"
+        tabindex="0"
+        role="group"
+        aria-labelledby={captionTextId}
+      >
         <div
-          class="diagram-stage"
-          id={renderedAnchorId === legacyAnchorId ? undefined : legacyAnchorId}
+          class="diagram-canvas"
+          style={`--diagram-print-ratio: ${layout.width} / ${layout.height}; --diagram-width: ${layout.width}; --diagram-height: ${layout.height}; width: ${layout.width}px; height: ${layout.height}px;`}
         >
-          <div
-            id={viewportId}
-            class="diagram-scroll"
-            tabindex="0"
-            role="group"
-            aria-labelledby={`${id}-caption`}
+          <svg
+            viewBox={`0 0 ${layout.width} ${layout.height}`}
+            width="100%"
+            height="100%"
           >
-            <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"
               >
-                <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})`}
+                <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)!;
+                // Position each node with x/y attributes, never a
+                // `transform` on the group: WebKit (every iOS browser)
+                // paints a `foreignObject` descendant that gets its own
+                // render layer — every KaTeX `position: relative` span —
+                // without the ancestor transform, so formulas pile up at
+                // the SVG origin while their boxes stay put.
+                return (
+                  <g class="diagram-node">
+                    <rect
+                      x={position.x}
+                      y={position.y}
+                      width={position.width}
+                      height={position.height}
+                      rx="8"
+                      ry="8"
                     />
-                  ))
-                }
-
-                {
-                  layout.nodes.map((position) => {
-                    const node = nodeById.get(position.id)!;
-                    return (
-                      <g
-                        transform={`translate(${position.x}, ${position.y})`}
-                        class="diagram-node"
+                    <foreignObject
+                      x={position.x}
+                      y={position.y}
+                      width={position.width}
+                      height={position.height}
+                    >
+                      <div
+                        xmlns="http://www.w3.org/1999/xhtml"
+                        class="diagram-node-content"
                       >
-                        <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>
+                        {
+                          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>
-    </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>
+
+  <FloatCaption
+    kind="Diagram"
+    prefix="diagram"
+    caption={caption}
+    short={short}
+    anchorId={renderedAnchorId}
+    number={number}
+    textId={captionTextId}
+  >
+    <button
+      type="button"
+      class="float-tool diagram__widen"
+      data-diagram-expand
+      aria-controls={viewportId}
+      aria-expanded="false"
+      aria-label={`Expand ${number ? `Diagram ${number}` : 'this diagram'} horizontally`}
+      title="Expand diagram horizontally"
+      hidden
+    >
+      <svg aria-hidden="true" viewBox="0 0 24 24">
+        <path class="float-tool__widen" d="M3 12h18M8 7l-5 5 5 5M16 7l5 5-5 5" />
+        <path class="float-tool__narrow" d="M3 12h7M7 9l3 3-3 3M21 12h-7M17 9l-3 3 3 3" />
+      </svg>
+    </button>
+  </FloatCaption>
 </figure>
 
 <style>
@@ -356,112 +368,10 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
       contain: inline-size;
     }
 
-    .diagram__titlebar {
-      position: relative;
-    }
-
-    .diagram__details {
-      border-inline-start: 0;
-      padding-inline-start: 0;
-    }
-
-    .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;
-    }
-
+    /* The caption line, its links and its widen button are styled once for
+       every float, in `global.css` (`.float-caption`, `.float-tool`). */
     .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 {
@@ -470,56 +380,6 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
       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
        illegibility — the same tradeoff `.notation-formula-math` makes for a
        wide equation. `tabindex` on the scroller is the accessibility half of
@@ -595,29 +455,14 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
       fill: var(--sl-color-gray-4);
     }
 
+    /* A diagram prints its whole graph (`global.css` resets the scroll box
+       for print). */
     @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>

package/src/components/disclosure/course-disclosure.ts

@@ -0,0 +1,24 @@
+/**
+ * The course's collapse defaults at build time — `manifest.disclosure`, the
+ * `disclosure` block of the course settings with the engine defaults applied
+ * (`normalizeDisclosure` in `../../compiler/course-config`). A component
+ * reads its kind's first-visit state here instead of hardcoding one, and a
+ * per-instance prop (`defaultOpen`) still overrides it.
+ *
+ * Read once per build: every float on every page asks, and the manifest does
+ * not change under a running build (a content edit in dev restarts Astro).
+ */
+import {
+  DISCLOSURE_DEFAULTS,
+  type NormalizedDisclosure,
+} from '../../compiler/course-config';
+import { loadManifest } from '../../compiler/manifest';
+
+let cached: Promise<NormalizedDisclosure> | undefined;
+
+export function courseDisclosure(): Promise<NormalizedDisclosure> {
+  cached ??= loadManifest().then(
+    (manifest) => manifest.disclosure ?? DISCLOSURE_DEFAULTS,
+  );
+  return cached;
+}