explico 0.13.1 → 0.15.0

package/src/components/block-heading.ts

@@ -63,14 +63,23 @@ export async function titledBlocksOf(
  * The text a reader sees for each outline heading with inline math, by its
  * anchor (`manifest.lessons[].headings`, v30). Astro lists a heading by all
  * the text in it, and KaTeX writes a formula three ways — MathML, its LaTeX
- * annotation and its glyphs — so its own list reads `R\explain{k}{R}R`.
+ * annotation and its glyphs — so its own list reads `R\explain{k}{R}R`. A
+ * deck beside its chapter, or a part's, is no lesson: its page lists its
+ * frames by their titles as the reader sees them (`decks[].frames`).
  */
-export async function mathHeadingTextsOf(lessonId: string): Promise<ReadonlyMap<string, string>> {
-  const lesson = (await manifestOnce()).lessons.find((entry) => entry.id === lessonId);
+export async function mathHeadingTextsOf(pageId: string): Promise<ReadonlyMap<string, string>> {
+  const manifest = await manifestOnce();
+  const lesson = manifest.lessons.find((entry) => entry.id === pageId);
+  if (lesson) {
+    return new Map(
+      lesson.headings.filter((heading) => heading.math).map((heading) => [heading.slug, heading.text]),
+    );
+  }
+  const deck = (manifest.decks ?? []).find((entry) => entry.pageId === pageId);
   return new Map(
-    (lesson?.headings ?? [])
-      .filter((heading) => heading.math)
-      .map((heading) => [heading.slug, heading.text]),
+    (deck?.frames ?? []).flatMap((frame): [string, string][] =>
+      frame.slug === undefined ? [] : [[frame.slug, frame.title]],
+    ),
   );
 }
 

package/src/components/card-carry.ts

@@ -63,6 +63,7 @@ import {
   createBrowserPreferenceStore,
   createSessionPreferenceStore,
 } from '../session/PreferenceStore';
+import { rememberReading } from '../session/reading-memory';
 import { decodeCard, keyOf, type RememberedCard } from './card-memory';
 import type { HoldEdge } from './card-placement';
 
@@ -305,21 +306,23 @@ const setKey = (base: string) => `explico:cards:carried:${base}`;
 
 /**
  * K5, D9: this tab's own set; a tab with none takes the course's last set,
- * which is its own from then on.
+ * which is its own from then on. The course's last set is reading memory
+ * (`../session/reading-memory.ts`): it is read and kept only with the
+ * reader's yes, so without it a new tab starts with no cards.
  */
 export function readCarried(base: string): CarriedSet {
   const own = decodeCarried(tab.get(setKey(base)));
   if (own) return own;
-  const last = decodeCarried(preferences.get(setKey(base))) ?? EMPTY_SET;
+  const last = (rememberReading(base) ? decodeCarried(preferences.get(setKey(base))) : null) ?? EMPTY_SET;
   tab.set(setKey(base), encodeCarried(last));
   return last;
 }
 
-/** K5: this tab's set, written as the course's last set too. Returns what was stored. */
+/** K5: this tab's set, written as the course's last set too with the reader's yes. Returns what was stored. */
 export function writeCarried(base: string, set: CarriedSet): string {
   const text = encodeCarried(set);
   tab.set(setKey(base), text);
-  preferences.set(setKey(base), text);
+  if (rememberReading(base)) preferences.set(setKey(base), text);
   return text;
 }
 

package/src/components/card-manager.ts

@@ -75,6 +75,10 @@ import {
   type CarriedSet,
   type OpenedAt,
 } from './card-carry';
+import {
+  READING_MEMORY_EVENT,
+  type ReadingMemoryChange,
+} from '../session/reading-memory';
 import { isThisPage, pageTitleOf } from './card-fetch';
 import { wireJumpArrow } from './card-jump';
 import { readableText } from './readable-text';
@@ -2051,7 +2055,7 @@ function rememberCards(): void {
       width: card.width,
     });
   }
-  writeRememberedCards({
+  writeRememberedCards(base, {
     cards: saved,
     pointed: pointedKey !== null && keys.has(pointedKey) ? pointedKey : null,
   });
@@ -2599,11 +2603,19 @@ function install(): void {
   if (carry) {
     restoreCarriedSet(readCarried(base));
   } else {
-    const page = readRememberedCards();
+    const page = readRememberedCards(base);
     remembered = [...page.cards];
     rememberedPointed = page.pointed;
   }
   window.addEventListener('pagehide', leavePage);
+  // A yes to reading memory keeps what is open now beyond the tab; a no has
+  // already deleted the kept copies, and the tab's own go on.
+  window.addEventListener(READING_MEMORY_EVENT, (event) => {
+    const { answer } = (event as CustomEvent<ReadingMemoryChange>).detail;
+    if (answer !== 'yes') return;
+    lastStored = null;
+    leavePage();
+  });
   document.addEventListener('visibilitychange', () => {
     if (document.visibilityState === 'hidden') leavePage();
   });

package/src/components/card-memory.ts

@@ -2,7 +2,10 @@
  * Remembering a page's open explanation cards. A reader who leaves a lesson
  * with cards pinned, docked or moved finds them where they were on coming
  * back to it: through a link, Back or a reload, in another tab, or after the
- * browser restarts. Closing the last card forgets the page.
+ * browser restarts. Closing the last card forgets the page. This is reading
+ * memory (`../session/reading-memory.ts`): kept in the browser only with the
+ * reader's yes; without it, in the tab's session, so Back, a reload and a
+ * link still bring the cards back until the tab is closed.
  *
  * The card manager (`./card-manager.ts`) saves the kept cards as the page is
  * left (`pagehide`) and restores them as each layer registers. A card is
@@ -17,7 +20,7 @@
  * `decodeCards` and `restorable` are pure, so `tests/unit/card-memory.test.ts`
  * checks them in Node.
  */
-import { createBrowserPreferenceStore } from '../session/PreferenceStore';
+import { readingMemoryStore } from '../session/reading-memory';
 import type { MovedSpot } from './card-drag';
 import type { CardAnchor } from './card-placement';
 
@@ -159,21 +162,22 @@ export function restorable(
 // ---------------------------------------------------------------------------
 
 // The one seam for browser storage; this module never touches it itself.
-// Local storage, so the cards outlive the tab and a browser restart; tabs
-// open on the same page share one entry, and the last one left wins.
-const store = createBrowserPreferenceStore();
-
+// With the reader's yes, local storage, so the cards outlive the tab and a
+// browser restart (tabs open on the same page share one entry, and the last
+// one left wins); without it, the tab's session storage.
 /**
  * One entry per page, kept only while the page has cards to bring back. The
  * path includes a course's base, so courses on one origin never share one.
  */
 const storageKey = () => `explico:cards:${window.location.pathname}`;
 
-/** The cards this page had open when the reader last left it. */
-export const readRememberedCards = (): RememberedPage => decodeCards(store.get(storageKey()));
+/** The cards this page had open when the reader last left it, in the course at `base`. */
+export const readRememberedCards = (base: string): RememberedPage =>
+  decodeCards(readingMemoryStore(base).get(storageKey()));
 
 /** Remember this page's cards; with none, the page is forgotten. */
-export function writeRememberedCards(page: RememberedPage): void {
+export function writeRememberedCards(base: string, page: RememberedPage): void {
+  const store = readingMemoryStore(base);
   const key = storageKey();
   if (page.cards.length > 0) store.set(key, encodeCards(page));
   else if (store.remove) store.remove(key);

package/src/components/deck/DeckEnhancer.astro

@@ -0,0 +1,13 @@
+---
+/**
+ * A deck page's behaviour in the browser: the scaled frames, Present mode,
+ * the presenter window and the steps' effects (`deck-controller.ts`).
+ * `LessonFooter.astro` includes it on a deck's page only.
+ */
+---
+
+<script>
+  import { installDecks } from './deck-controller';
+
+  installDecks();
+</script>

package/src/components/deck/deck-context.ts

@@ -0,0 +1,104 @@
+/**
+ * What a component on a deck page (`<lesson>.deck.mdx`, `<part>/index.deck.mdx`,
+ * docs/authoring/deck.md) needs to know about it, read from the one manifest:
+ * a float on a deck carries no number of its own, and one the deck recalls
+ * from a chapter keeps the chapter's number, which links to the chapter. A
+ * course's own wrapper around `<Figure>`, `<Table>` or `<Diagram>` forwards
+ * `number` and `anchorId` as it always did, and nothing more.
+ */
+import { loadManifest, type Manifest } from '../../compiler/manifest';
+import type { ManifestDeck } from '../../compiler/manifest';
+import { routeIdFromLocals } from '../../reference/page-notation';
+
+/** The manifest's deck the page renders, if the page is one. */
+export function deckOfRoute(manifest: Pick<Manifest, 'decks'>, routeId: string | undefined): ManifestDeck | undefined {
+  if (routeId === undefined) return undefined;
+  return (manifest.decks ?? []).find((deck) => deck.slug === routeId);
+}
+
+/** A part's deck, by the part's directory. */
+export function partDeckOf(manifest: Pick<Manifest, 'decks'>, dir: string): ManifestDeck | undefined {
+  return (manifest.decks ?? []).find((deck) => deck.part === dir);
+}
+
+/**
+ * Where a chapter's page sends a reader for its slides ("Slides for this
+ * chapter", and the sidebar's icon): its own deck, or else the section of
+ * its part's deck that covers it, at the section's divider (`#slide-N`). A
+ * lesson's own deck wins. `path` is below the site's base: `motion/x/slides/`.
+ */
+export function chapterSlides(
+  manifest: Pick<Manifest, 'decks'>,
+  chapterSlug: string,
+): { readonly deck: ManifestDeck; readonly path: string } | undefined {
+  const decks = manifest.decks ?? [];
+  const own = decks.find((deck) => deck.chapter === chapterSlug);
+  if (own) return { deck: own, path: `${own.slug}/` };
+  for (const deck of decks) {
+    const cover = deck.part === undefined ? undefined : deck.covers.find((entry) => entry.chapter === chapterSlug);
+    if (cover) return { deck, path: `${deck.slug}/#slide-${cover.frame}` };
+  }
+  return undefined;
+}
+
+/** A sidebar link as Starlight hands it to the footer's pagination. */
+export interface PaginationLink {
+  readonly type: string;
+  readonly label?: string;
+  readonly href?: string;
+  readonly attrs?: Readonly<Record<string, unknown>>;
+  readonly isCurrent?: boolean;
+}
+
+/**
+ * Next and Previous on a deck's page: the decks before and after it in the
+ * sidebar's order — a lesson's deck, a slides-first lesson, a part's deck —
+ * each named "Slides: *title*". `links` is the sidebar flattened, `current`
+ * the deck's own place in it; `titleOf` gives a deck's title by its link.
+ */
+export function deckNeighbours<T extends PaginationLink>(
+  links: readonly T[],
+  current: number,
+  titleOf: (link: T) => string | undefined,
+): { readonly prev?: T; readonly next?: T } {
+  const isDeck = (link: T | undefined) => link?.attrs?.['data-edition'] === 'slides';
+  const named = (link: T): T => {
+    const title = titleOf(link);
+    return title === undefined ? link : { ...link, label: `Slides: ${title}` };
+  };
+  const step = (direction: 1 | -1): T | undefined => {
+    for (let index = current + direction; index >= 0 && index < links.length; index += direction) {
+      if (isDeck(links[index])) return named(links[index]!);
+    }
+    return undefined;
+  };
+  const prev = step(-1);
+  const next = step(1);
+  return { ...(prev === undefined ? {} : { prev }), ...(next === undefined ? {} : { next }) };
+}
+
+export interface DeckFloat {
+  /** The float is on a deck page, where a float of the deck's own has no number. */
+  readonly onDeck: boolean;
+  /** Where a recalled float's number links: the float on its chapter's page. */
+  readonly numberHref?: string;
+}
+
+/**
+ * A float on the page `locals` renders, anchored at `anchorId`. A recalled
+ * one links to its chapter: a lesson's deck's, or on a part's deck the
+ * chapter the recall named (`recalledFrom`).
+ */
+export async function deckFloat(locals: object, anchorId: string | undefined, base: string): Promise<DeckFloat> {
+  const deck = deckOfRoute(await loadManifest(), routeIdFromLocals(locals));
+  if (!deck) return { onDeck: false };
+  const chapter = anchorId === undefined ? undefined : (deck.recalledFrom?.[anchorId] ?? deck.chapter);
+  const recalled =
+    anchorId !== undefined &&
+    chapter !== undefined &&
+    deck.frames.some((frame) => frame.recalls?.includes(anchorId));
+  return {
+    onDeck: true,
+    ...(recalled ? { numberHref: `${base.replace(/\/$/, '')}/${chapter}/#${anchorId}` } : {}),
+  };
+}