explico 0.13.0 → 0.14.0

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}` } : {}),
+  };
+}