explico 0.7.0 → 0.11.0

package/src/components/starlight/section-summary.ts

@@ -0,0 +1,181 @@
+/**
+ * The "Hidden here: …" line a *closed* collapsible section shows under its
+ * title (see `CollapsibleSections.astro`), so a reader can tell there is
+ * content behind the title — and roughly how much — without opening it.
+ *
+ * A numbered float with a short caption is named, number first, before the
+ * counts of everything else: "Hidden here: **Figure 2.1.1** Projectile
+ * trajectory explorer, 2 paragraphs" (docs/plans/figures-and-short-captions.md,
+ * decision 9.2); a float without one stays in the counts ("1 table").
+ *
+ * Split in two so the wording is unit-testable without a DOM:
+ * `collectHiddenContent` walks a section body once (browser only), and
+ * `hiddenContentParts` / `describeHiddenContent` turn what it found into the
+ * reader-facing line.
+ */
+import { FLOAT_KIND_WORDS, floatOf, type NamedFloat } from '../float-name';
+
+export interface HiddenContentCounts {
+  readonly subsections: number;
+  readonly paragraphs: number;
+  readonly equations: number;
+  readonly figures: number;
+  readonly tables: number;
+  readonly diagrams: number;
+  readonly lists: number;
+  readonly codeBlocks: number;
+  readonly memos: number;
+  readonly examples: number;
+  readonly questions: number;
+}
+
+// Reading order of the summary line: structure first, then prose, then the
+// numbered floats, then everything else.
+const LABELS: readonly (readonly [keyof HiddenContentCounts, string, string])[] = [
+  ['subsections', 'subsection', 'subsections'],
+  ['paragraphs', 'paragraph', 'paragraphs'],
+  ['equations', 'equation', 'equations'],
+  ['figures', 'figure', 'figures'],
+  ['tables', 'table', 'tables'],
+  ['diagrams', 'diagram', 'diagrams'],
+  ['lists', 'list', 'lists'],
+  ['codeBlocks', 'code block', 'code blocks'],
+  ['memos', 'memo', 'memos'],
+  ['examples', 'worked example', 'worked examples'],
+  ['questions', 'question', 'questions'],
+];
+
+/** One item of the line: a named float — its number set in bold — or a count. */
+export type HiddenPart = string | { readonly number: string; readonly short: string };
+
+/**
+ * The line's items: every named float, in page order, then the counts; or
+ * `null` when nothing countable is inside (the caller then shows no line at
+ * all rather than a vague one). `named` holds only floats with a short
+ * caption, already left out of `counts`.
+ */
+export function hiddenContentParts(
+  counts: HiddenContentCounts,
+  named: readonly NamedFloat[] = [],
+): HiddenPart[] | null {
+  const parts: HiddenPart[] = [
+    ...named.flatMap((float) =>
+      float.short
+        ? [{ number: `${FLOAT_KIND_WORDS[float.kind]} ${float.number}`, short: float.short }]
+        : [],
+    ),
+    ...LABELS.filter(([key]) => counts[key] > 0).map(
+      ([key, singular, plural]) =>
+        `${counts[key]} ${counts[key] === 1 ? singular : plural}`,
+    ),
+  ];
+  return parts.length > 0 ? parts : null;
+}
+
+/**
+ * `"Hidden here: Figure 2.1.1 Projectile trajectory explorer, 2 paragraphs,
+ * 1 equation"` — the line as text — or `null` with nothing to say.
+ */
+export function describeHiddenContent(
+  counts: HiddenContentCounts,
+  named: readonly NamedFloat[] = [],
+): string | null {
+  const parts = hiddenContentParts(counts, named);
+  if (!parts) return null;
+  const text = parts.map((part) =>
+    typeof part === 'string' ? part : `${part.number} ${part.short}`,
+  );
+  return `Hidden here: ${text.join(', ')}`;
+}
+
+/**
+ * Components counted as one item each. Anything *inside* one of them (a
+ * figure's caption paragraph, a memo's equation, a question's option list,
+ * a worked example's working) belongs to that component and is not counted
+ * again on its own.
+ */
+const CONTAINERS =
+  '.keyed-figure, .keyed-table, .diagram, .memo-block, .compact-examples, .compact-example, .assessment-shell, .short-note';
+
+/** Whether any ancestor of `element` strictly between it and `root` matches `selector`. */
+function hasAncestorWithin(element: Element, root: Element, selector: string): boolean {
+  for (
+    let node = element.parentElement;
+    node && node !== root;
+    node = node.parentElement
+  ) {
+    if (node.matches(selector)) return true;
+  }
+  return false;
+}
+
+export interface HiddenContent {
+  readonly counts: HiddenContentCounts;
+  /** The numbered floats with a short caption, in page order; not in `counts`. */
+  readonly named: readonly NamedFloat[];
+}
+
+/**
+ * What a section body holds, at every depth — a nested subsection's content
+ * is hidden along with its parent's, so it counts too. `headings` is the
+ * heading selector (`HEADINGS` from `./section-parts`). With `nameFloats:
+ * false` — a `<Fold>` whose bar already names its floats — every float stays
+ * a count.
+ */
+export function collectHiddenContent(
+  body: Element,
+  headings: string,
+  { nameFloats = true }: { readonly nameFloats?: boolean } = {},
+): HiddenContent {
+  const outside = (selector: string, alsoExclude = '') =>
+    Array.from(body.querySelectorAll(selector)).filter(
+      (element) =>
+        !hasAncestorWithin(element, body, CONTAINERS) &&
+        !(alsoExclude && hasAncestorWithin(element, body, alsoExclude)),
+    );
+  const itemsIn = (container: string, item: string) =>
+    outside(container).reduce(
+      (total, element) => total + element.querySelectorAll(item).length,
+      0,
+    );
+  const named = nameFloats
+    ? outside('.keyed-figure, .keyed-table, .diagram').flatMap((element) => {
+        const float = floatOf(element);
+        return float?.short ? [float] : [];
+      })
+    : [];
+  const unnamed = (selector: string) =>
+    outside(selector).filter(
+      (element) => !named.some((float) => float.anchorId === element.id),
+    ).length;
+
+  const counts: HiddenContentCounts = {
+    // Only Markdown section headings — each sits in its own
+    // `.sl-heading-wrapper` — not a heading a component draws for itself
+    // (a lab's title, an assessment runner's, a `<Fold>`'s bar, which is out
+    // of the accessibility tree's headings with `role="none"`).
+    subsections: outside(headings).filter(
+      (heading) =>
+        hasAncestorWithin(heading, body, '.sl-heading-wrapper') &&
+        heading.getAttribute('role') !== 'none',
+    ).length,
+    // A loose list's `<li><p>` is part of the list, not a paragraph of its own.
+    paragraphs: outside('p', 'ul, ol').length,
+    equations: outside('.katex-display').length,
+    figures: unnamed('.keyed-figure'),
+    // Keyed tables, plus any raw Markdown table (warned about, but possible).
+    tables: unnamed('.keyed-table') + outside('table').length,
+    diagrams: unnamed('.diagram'),
+    lists: outside('ul, ol', 'ul, ol').length,
+    codeBlocks: outside('pre').length,
+    memos: outside('.memo-block').length,
+    // A set of worked examples counts its examples; folded itself (the set
+    // is a section of its own, `CompactExamples.astro`), its body holds them
+    // directly.
+    examples:
+      itemsIn('.compact-examples', '.compact-example') +
+      outside('.compact-example').length,
+    questions: itemsIn('.assessment-shell', '.assessment-item'),
+  };
+  return { counts, named };
+}

package/src/components/table/Table.astro

@@ -13,23 +13,40 @@
  * `[[tab-<id>]]` (same page) or `[[lesson-slug#tab-<id>]]` (cross page); a
  * table without `id` is still numbered and deep-linkable, just not
  * referenceable by name — the same rule an unkeyed equation follows.
+ *
+ * Named by the caption pair every float takes
+ * (docs/plans/titles-and-containers.md Part 3): the long `caption`, in the
+ * shared caption line (`global.css` `.float-caption`) above the table, and an
+ * optional `short` caption that heads the `[[tab-…]]` preview card. Minimized,
+ * a table keeps that caption line and its header row (decision Q6).
  */
+import { courseDisclosure } from '../disclosure/course-disclosure';
+import { captionTitle } from '../float-name';
+
 export interface Props {
   /** Stable key, e.g. `id="kinematics-summary"`. Omit for a positional-only table. */
   id?: string;
-  /** Visible caption, shown above the table (the LaTeX convention — the reverse of a figure caption, which goes below) and in the hover-preview card. */
+  /** The long caption, shown above the table (the LaTeX convention — the reverse of a figure caption, which goes below) and in the hover-preview card. */
   caption: string;
+  /** Optional short caption: heads the `[[tab-…]]` preview card; rule S1 measures it. */
+  short?: string;
   /** Computed by `remark-notation.mjs` — never author this directly. */
   number?: string;
   /** Computed by `remark-notation.mjs` — never author this directly. */
   anchorId?: string;
 }
 
-const { id, caption, number, anchorId } = Astro.props;
+const { id, caption, short, number, anchorId } = Astro.props;
+// A table longer than this starts truncated (the course's
+// `disclosure.tables.truncateAfter`, default 6).
+const { truncateAfter } = (await courseDisclosure()).tables;
 
 if (typeof caption !== 'string' || !caption.trim()) {
   throw new Error('Table requires a non-empty `caption` prop.');
 }
+if (short !== undefined && (typeof short !== 'string' || !short.trim())) {
+  throw new Error('Table `short` must be a non-empty string when given.');
+}
 if (!number || !anchorId) {
   throw new Error(
     'Table is missing its computed `number`/`anchorId` — this page must run remark-notation with a `tables` cross-page table configured (see astro.config.mjs).',
@@ -42,14 +59,31 @@ if (!number || !anchorId) {
   id={anchorId}
   data-tab-number={number}
   data-tab-key={id}
+  data-tab-short={short}
+  data-truncate-after={truncateAfter}
 >
-  <figcaption class="keyed-table__caption">
+  <figcaption class="keyed-table__caption float-caption">
     <a
-      class="keyed-table__number"
+      class="keyed-table__number float-caption__number"
       href={`#${anchorId}`}
       aria-label={`Table ${number}`}>Table {number}</a
     >
-    <span class="keyed-table__caption-text">{caption}</span>
+    <a
+      class="float-caption__anchor"
+      href={`#${anchorId}`}
+      aria-label={`Copy the link to Table ${number}`}
+      title="Copy link"
+      data-copy-link={`Table ${number}`}
+    >
+      <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>
+    {short && <b class="float-caption__title">{captionTitle(short)}</b>}{short && ' '}<span
+      class="keyed-table__caption-text float-caption__text">{caption}</span
+    >
   </figcaption>
   <div class="keyed-table__body">
     <slot />
@@ -76,45 +110,33 @@ if (!number || !anchorId) {
     margin-inline: auto;
   }
 
-  .keyed-table__caption {
-    position: relative;
-    margin-block-end: 0.5rem;
-    font-size: var(--sl-text-base);
-    color: var(--sl-color-gray-3);
-  }
-
-  /* Added by the row-pagination script below for every table (it always
-     gets a minimize-to-header-row toggle, regardless of row count) —
-     reserves room so caption text never runs under the absolutely-positioned
-     toggle button in the corner. */
-  .keyed-table__caption--paginated {
-    padding-inline-end: 1.75em;
-  }
-
-  /* The toggle button and everything else this rule block styles are
-     created at runtime (see the `<script>` below), so they never carry this
-     component's `data-astro-cid-*` scoping attribute — `:global()` is
-     required for the same reason `.keyed-table__body :global(table)` above
-     needs it. Reuses `.table-overflow-expand-btn` from
-     `TableOverflowExpander.astro` (Part 4) for its base look
-     (border/hover/focus/print-hidden), just repositioned into the caption's
-     top-right corner instead of a flex-row side column. */
-  :global(.keyed-table__pagination-toggle) {
-    position: absolute;
-    top: 0;
-    inset-inline-end: 0;
-    border: 1px solid var(--sl-color-gray-5);
-    border-radius: 0.3rem;
-  }
-
+  /* Everything this rule block styles is created at runtime (see the
+     `<script>` below), so it never carries this component's
+     `data-astro-cid-*` scoping attribute — `:global()` is required for the
+     same reason `.keyed-table__body :global(table)` above needs it. The fold
+     toggle is a `.float-tool` in the caption's button row (`global.css`). */
   :global(.keyed-table__more-row td) {
     padding-block: 0.4rem;
+    padding-inline: 0;
     color: var(--sl-color-gray-3);
     font-size: var(--sl-text-sm);
     font-style: italic;
     text-align: center;
   }
 
+  /* Centred on the part of the table on screen: the cell spans every column,
+     so a wide table scrolled or clipped sideways would otherwise centre the
+     label on columns the reader cannot see. The label sticks to the scroll
+     clip's start edge and is as wide as the clip (`100cqi`, the clip being a
+     size container), or as the row when the whole table fits. */
+  :global(.keyed-table__more-label) {
+    position: sticky;
+    inset-inline-start: 0;
+    display: block;
+    width: 100cqi;
+    max-width: 100%;
+  }
+
   /* Only the live table's own more-row gets this class — a hover-card
      preview clone (`FloatRefLayer.astro`) strips it so the same row reads
      as an inert truncation marker there instead of a dead-looking link. */
@@ -163,32 +185,7 @@ if (!number || !anchorId) {
     margin-inline-start: 1.25rem;
   }
 
-  .keyed-table__number {
-    font-weight: 600;
-    font-variant-numeric: tabular-nums;
-    color: var(--sl-color-text-accent);
-    text-decoration: none;
-  }
-
-  .keyed-table__number:hover,
-  .keyed-table__number:focus-visible {
-    text-decoration: underline;
-  }
-
-  .keyed-table__number:focus-visible {
-    outline: 2px solid var(--sl-color-accent);
-    outline-offset: 0.15rem;
-  }
-
-  .keyed-table__caption-text::before {
-    content: ' — ';
-  }
-
   @media print {
-    .keyed-table__number {
-      color: inherit;
-    }
-
     :global(.keyed-table__pagination-links),
     :global(.keyed-table__more-row) {
       display: none !important;
@@ -211,7 +208,7 @@ if (!number || !anchorId) {
    * `truncated` (first/last few rows, the default once a table is long
    * enough to bother) -> `expanded` (every row). Every table gets the
    * minimize-to-header-row toggle in its caption, regardless of row count —
-   * a short table (`totalRows <= PAGINATE_ABOVE_ROWS`) just never grows the
+   * a short table (`totalRows <= truncateAfter`) just never grows the
    * "… N more rows …" truncation row or the "Show less"/"Minimize" links
    * below it, so it only ever has two reachable states, `minimized` and
    * `expanded`. No persisted state here, same as `TableOverflowExpander.astro`'s
@@ -231,8 +228,6 @@ if (!number || !anchorId) {
 
   type PaginationState = 'minimized' | 'truncated' | 'expanded';
 
-  const KEEP_EACH_END = 3;
-  const PAGINATE_ABOVE_ROWS = 6;
 
   // Mirrors `TableOverflowExpander.astro`'s own `captionFor` exactly, for
   // the same aria-label wording across both tables' controls.
@@ -245,6 +240,25 @@ if (!number || !anchorId) {
     return text || 'this table';
   }
 
+  // The fold toggle's chevron: ⌃ folds the rows away, ⌄ brings them back.
+  const FOLD_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 15l6-6 6 6"/></svg>';
+  const UNFOLD_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 9l6 6 6-6"/></svg>';
+
+  /**
+   * The caption's button row (`global.css` `.float-tools`), shared with
+   * `TableOverflowExpander.astro`'s widen button: whichever script runs
+   * first makes it. The widen button goes first, the fold toggle last.
+   */
+  function floatTools(caption: HTMLElement): HTMLElement {
+    let tools = caption.querySelector<HTMLElement>(':scope > .float-tools');
+    if (!tools) {
+      tools = document.createElement('span');
+      tools.className = 'float-tools';
+      caption.append(tools);
+    }
+    return tools;
+  }
+
   function wireTable(figure: HTMLElement) {
     figure.dataset.paginationWired = 'true';
 
@@ -260,18 +274,20 @@ if (!number || !anchorId) {
     if (totalRows === 0) return;
 
     // Long enough to also need truncation, on top of the minimize toggle
-    // every table gets below.
-    const paginated = totalRows > PAGINATE_ABOVE_ROWS;
+    // every table gets below: more rows than the course's
+    // `disclosure.tables.truncateAfter`. A truncated table shows up to that
+    // many rows, half from each end.
+    const truncateAfter = Number(figure.dataset.truncateAfter) || 6;
+    const keepEachEnd = Math.floor(truncateAfter / 2);
+    const paginated = totalRows > truncateAfter;
 
     const caption = figure.querySelector<HTMLElement>(
       ':scope > .keyed-table__caption',
     );
-    caption?.classList.add('keyed-table__caption--paginated');
     const toggle = document.createElement('button');
     toggle.type = 'button';
-    toggle.className =
-      'table-overflow-expand-btn keyed-table__pagination-toggle';
-    caption?.append(toggle);
+    toggle.className = 'float-tool keyed-table__pagination-toggle';
+    if (caption) floatTools(caption).append(toggle);
 
     let moreRow: HTMLTableRowElement | null = null;
     let links: HTMLElement | null = null;
@@ -279,7 +295,7 @@ if (!number || !anchorId) {
     let minimizeAll: HTMLButtonElement | null = null;
 
     if (paginated) {
-      const hiddenCount = totalRows - KEEP_EACH_END * 2;
+      const hiddenCount = totalRows - keepEachEnd * 2;
       const headerCells = table.tHead?.rows[0]?.cells ?? rows[0].cells;
       const colCount =
         Array.from(headerCells).reduce(
@@ -302,10 +318,13 @@ if (!number || !anchorId) {
       moreRow.setAttribute('aria-label', `Show all ${totalRows} rows`);
       const moreCell = document.createElement('td');
       moreCell.colSpan = colCount;
-      moreCell.textContent =
+      const moreLabel = document.createElement('span');
+      moreLabel.className = 'keyed-table__more-label';
+      moreLabel.textContent =
         hiddenCount === 1 ? '… 1 more row …' : `… ${hiddenCount} more rows …`;
+      moreCell.append(moreLabel);
       moreRow.append(moreCell);
-      tbody.insertBefore(moreRow, rows[KEEP_EACH_END]);
+      tbody.insertBefore(moreRow, rows[keepEachEnd]);
 
       // Centered below the table body, and only ever shown once every row is
       // — "Show less" un-truncates back down, "Minimize to header row"
@@ -336,13 +355,13 @@ if (!number || !anchorId) {
       rows.forEach((row, index) => {
         const inMiddle =
           paginated &&
-          index >= KEEP_EACH_END &&
-          index < totalRows - KEEP_EACH_END;
+          index >= keepEachEnd &&
+          index < totalRows - keepEachEnd;
         row.hidden = minimized || (inMiddle && !expanded);
       });
       if (moreRow) moreRow.hidden = minimized || expanded;
 
-      toggle.textContent = minimized ? '▾' : '▴';
+      toggle.innerHTML = minimized ? UNFOLD_ICON : FOLD_ICON;
       toggle.setAttribute('aria-expanded', String(!minimized));
       toggle.setAttribute(
         'aria-label',

package/src/components/table/TableOverflowExpander.astro

@@ -95,15 +95,11 @@
  * (`visibility: hidden`) outright — there is no reason to keep any part of
  * it rendered once the reader has scrolled past it.
  *
- * Only one table is ever expanded at a time, and expanding one closes
- * whichever other overlay — a hover-preview card, a notation popup — was
- * open, via the same `claimActiveSurface`/`releaseActiveSurface` arbiter
- * `FloatRefLayer.astro` and the citation/notation layers already share. That
- * claim is released again immediately rather than held, though: unlike
- * those layers, the table doesn't stay registered as the arbiter's active
- * surface while expanded, so a hover card opening *afterward* — over an
- * explainable quantity inside the table itself, say — can't turn around and
- * force the table closed the way claiming the arbiter normally would. The
+ * Only one table is ever expanded at a time, and expanding one closes the
+ * explanation cards only the pointer was keeping open
+ * (`closeTransientCards`, `../card-manager.ts`); pinned cards stay. A card
+ * opening *afterward* — over an explainable quantity inside the table
+ * itself, say — simply floats above the still-open table. The
  * table closes only through its own explicit gestures — the collapse
  * buttons or Escape — and deliberately *not* an outside click: a reader
  * following a link in the "On this page" rail, or clicking anywhere else to
@@ -112,13 +108,18 @@
  *
  * No persisted state here (unlike Parts 1/3): expand/collapse is transient
  * per-view UI, not a reader preference worth remembering across visits.
+ *
+ * **Caption button**: a keyed table also gets a widen button ↔ in its
+ * caption's button row at the top right (`global.css` `.float-tools`), next
+ * to the fold toggle — the same action as the right-edge column, found
+ * where a reader looks for a table's controls. It shows whenever that
+ * column does, and turns into →← while the table is widened.
  */
 ---
 
 <script>
-  import { claimActiveSurface, releaseActiveSurface } from "../hover-panel";
+  import { closeTransientCards } from "../card-manager";
 
-  const GROUP = "table-overflow";
   const EDGE_PX = 16; // ~1em at the default root font size
   const WIDTH_BUFFER_PX = 2; // rounding slack so the minimal width never re-triggers a scrollbar
   const SIDE_COLUMN_PX = 24; // must match `.table-overflow-expand-btn`'s `width: 1.5rem`
@@ -136,6 +137,28 @@
 
   let active: Expansion | null = null;
 
+  /** Each keyed table's caption widen button, by its body (the container). */
+  const captionButtons = new WeakMap<HTMLElement, HTMLButtonElement>();
+
+  const WIDEN_ICON =
+    '<svg viewBox="0 0 24 24" aria-hidden="true">' +
+    '<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>';
+
+  /**
+   * The caption's button row, shared with `Table.astro`'s fold toggle
+   * (which has the same helper): whichever script runs first makes it.
+   */
+  function floatTools(caption: HTMLElement): HTMLElement {
+    let tools = caption.querySelector<HTMLElement>(":scope > .float-tools");
+    if (!tools) {
+      tools = document.createElement("span");
+      tools.className = "float-tools";
+      caption.append(tools);
+    }
+    return tools;
+  }
+
   function sidebarLeftBound(): number {
     const sidebar = document.querySelector<HTMLElement>(".sidebar-pane");
     const visible =
@@ -187,6 +210,12 @@
     );
     button.title = expanded ? "Collapse" : "Expand to full width";
     button.setAttribute("aria-expanded", String(expanded));
+    const captionButton = captionButtons.get(container);
+    if (captionButton) {
+      captionButton.setAttribute("aria-label", button.getAttribute("aria-label") ?? "");
+      captionButton.title = button.title;
+      captionButton.setAttribute("aria-expanded", String(expanded));
+    }
   }
 
   // A scrollable region must itself be reachable by keyboard (WCAG 2.1.1 —
@@ -216,6 +245,8 @@
   ) {
     if (active?.scroll === scroll) return; // never hide the one currently expanded
     button.hidden = scroll.scrollWidth <= scroll.clientWidth + 1;
+    const captionButton = captionButtons.get(container);
+    if (captionButton) captionButton.hidden = button.hidden;
     updateScrollFocusability(scroll, container);
   }
 
@@ -250,20 +281,11 @@
   ) {
     if (active) collapse();
 
-    // Close whatever other overlay (a hover-preview card, a notation popup)
-    // was open, via the same shared arbiter every layer uses — but
-    // immediately release the claim rather than leaving the table
-    // registered as the arbiter's active surface. If it stayed registered,
-    // a hover card opening *afterward* over the table's own content (an
-    // explainable quantity inside it, say) would claim the arbiter in turn
-    // and force this table closed the same way a genuinely different
-    // overlay replacing it would — which is exactly backwards: the card
-    // should simply float above the still-open table (it already
-    // out-ranks it on z-index), and the table should close only through
-    // its own explicit gestures (the collapse buttons, an outside click, or
-    // Escape — all wired below, independent of this arbiter).
-    claimActiveSurface(GROUP, () => {});
-    releaseActiveSurface(GROUP);
+    // A hovered card would linger over the expanded table; pinned ones stay.
+    // A card opened afterward over the table's own content floats above it
+    // (the card layer out-ranks it on z-index), and the table closes only
+    // through its own gestures (the collapse buttons or Escape, wired below).
+    closeTransientCards();
 
     // Measured *before* anything moves: `scrollWidth` reports the table's
     // full, unclipped content width regardless of how narrow this wrapper
@@ -438,13 +460,28 @@
     button.type = "button";
     button.className = "table-overflow-expand-btn";
     button.hidden = true;
-    updateButtonLabel(container, button, false);
     container.append(button);
 
-    button.addEventListener("click", () => {
+    const caption = container
+      .closest<HTMLElement>(".keyed-table")
+      ?.querySelector<HTMLElement>(":scope > .keyed-table__caption");
+    if (caption) {
+      const captionButton = document.createElement("button");
+      captionButton.type = "button";
+      captionButton.className = "float-tool keyed-table__widen-toggle";
+      captionButton.hidden = true;
+      captionButton.innerHTML = WIDEN_ICON;
+      floatTools(caption).prepend(captionButton);
+      captionButtons.set(container, captionButton);
+    }
+    updateButtonLabel(container, button, false);
+
+    const toggle = () => {
       if (active?.container === container) collapse();
       else expand(container, button, scroll);
-    });
+    };
+    button.addEventListener("click", toggle);
+    captionButtons.get(container)?.addEventListener("click", toggle);
 
     evaluateOverflow(scroll, button, container);