fb-slides 0.1.2

package/runtime/deck.js

@@ -0,0 +1,299 @@
+import RevealAnnotate from './annotate.js';
+import RevealSpotlight from './spotlight.js';
+import RevealOutline from './outline.js';
+
+// ---------------------------------------------------------------------------
+// The decks are the Markdown files. This file only assembles them into reveal.js
+// slides, so the .md stay the single source of truth and readable on their own.
+//
+// Nothing here is specific to a talk: what differs between projects arrives in
+// `window.__FB_SLIDES__`, written into index.html from slides.config.js.
+// ---------------------------------------------------------------------------
+
+const CFG = window.__FB_SLIDES__ ?? {};
+
+// The decks are whatever `.md` sits in decks/, in file-name order: adding or
+// deleting a file is the whole workflow, there is no list to keep in step.
+const DECKS_DIR = CFG.decks ?? 'decks/';
+
+// The dev server answers this from the folder as it is right now, and the build
+// writes it into dist/ — so the list is never stale and never hand-written.
+const MANIFEST = 'decks.json';
+
+// Last resort: a plain static server with no manifest but a directory listing
+// (`python3 -m http.server`, `npx serve`). The listing is HTML, so it gets parsed.
+const listFromDirectory = async () => {
+  const response = await fetch(DECKS_DIR, { cache: 'no-cache' });
+  if (!response.ok) throw new Error(`${DECKS_DIR} → ${response.status}`);
+
+  const listing = new DOMParser().parseFromString(await response.text(), 'text/html');
+  const names = [...listing.querySelectorAll('a[href]')]
+    .map((a) => decodeURIComponent(a.getAttribute('href').split('?')[0].split('/').pop()))
+    .filter((name) => name.endsWith('.md'));
+
+  // `numeric` so 10-… sorts after 09-… rather than after 01-….
+  return [...new Set(names)].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+};
+
+const listDecks = async () => {
+  const manifest = await fetch(MANIFEST, { cache: 'no-cache' }).catch(() => null);
+  if (manifest?.ok) {
+    const names = await manifest.json().catch(() => []);
+    if (names.length) return names;
+  }
+  try {
+    return await listFromDirectory();
+  } catch (error) {
+    console.warn(`[deck] no ${MANIFEST} and no directory listing (${error.message})`);
+    return [];
+  }
+};
+
+const DECKS = await listDecks();
+if (!DECKS.length) console.error(`[deck] no .md found in ${DECKS_DIR}`);
+
+// A slide whose source opens with `<!-- demo: cart -->` is replaced by that demo,
+// running in an iframe. The marker lives in the Markdown, so the position of a
+// demo is decided there — like any other slide. The value is a folder inside the
+// project's demos dir, a ./ or ../ path, or a full http(s) URL for anything external.
+const DEMO_MARKER = /^<!--\s*demo:\s*(\S+?)\s*-->/;
+const DEMOS_DIR = CFG.demos ?? 'demo/';
+
+// Bullet lists reveal themselves one item at a time. `?nofrag` turns it off for
+// one visit; `fragmentLists: false` in the config turns it off for the project.
+const AUTO_FRAGMENT = CFG.fragmentLists !== false && !new URLSearchParams(location.search).has('nofrag');
+
+const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+const stripFrontMatter = (md) => md.replace(FRONT_MATTER, '');
+
+// Enough YAML for `key: value` lines — which is all the front matter holds.
+const parseFrontMatter = (md) =>
+  Object.fromEntries(
+    (md.match(FRONT_MATTER)?.[1] ?? '')
+      .split(/\r?\n/)
+      .map((line) => line.match(/^([A-Za-z_][\w-]*):\s*(.+)$/))
+      .filter(Boolean)
+      .map(([, key, value]) => [key, value.trim().replace(/^['"]|['"]$/g, '')]),
+  );
+const splitSlides = (md) => md.split(/\r?\n---\r?\n/).map((s) => s.trim()).filter(Boolean);
+
+// ---------------------------------------------------------------------------
+// Build the DOM before Reveal.initialize(): the markdown plugin picks up every
+// `data-markdown` section at init time.
+// ---------------------------------------------------------------------------
+
+const slidesEl = document.querySelector('.slides');
+
+const markdownSection = (source, deck) => {
+  const section = document.createElement('section');
+  section.setAttribute('data-markdown', '');
+  section.dataset.deck = deck.label;
+  // A slide opening with an `# h1` is a deck divider, not content.
+  if (/^#\s/.test(source)) section.classList.add('deck-title');
+  const template = document.createElement('script');
+  template.type = 'text/template';
+  template.textContent = source;
+  section.append(template);
+  return section;
+};
+
+// The real page, running, inside the slide.
+const demoSection = (target, deck) => {
+  const isUrl = /^https?:\/\//.test(target);
+  const name = isUrl ? target : target.replace(/\/$/, '');
+  // Bare names are folders in the demos dir; a ./ or ../ path and a full URL are
+  // used as given.
+  const path = isUrl || /^[./]/.test(name) ? name : `${DEMOS_DIR}${name}/`;
+  // A whole URL in the header would drown the slide: show just the host.
+  const label = isUrl ? new URL(name).host : name;
+  const section = document.createElement('section');
+  section.className = 'demo-slide';
+  section.dataset.deck = deck.label;
+  section.innerHTML = `
+    <header>
+      <span class="tag">live</span>
+      <code>${label}</code>
+      <a href="${path}" target="_blank" rel="noreferrer">open in a tab ↗</a>
+    </header>
+    <iframe data-src="${path}" title="${name}" loading="lazy"></iframe>
+  `;
+  return section;
+};
+
+for (const file of DECKS) {
+  // `no-cache` revalidates on every load: editing a .md and hitting reload is the
+  // whole authoring loop, and fetch() ignores the browser's reload button.
+  const response = await fetch(DECKS_DIR + file, { cache: 'no-cache' });
+  if (!response.ok) {
+    console.error(`[deck] cannot load ${file}: ${response.status}`);
+    continue;
+  }
+  const markdown = await response.text();
+  const front = parseFrontMatter(markdown);
+  // `section:` names the deck; without one the file name has to do.
+  const deck = { file, label: front.section ?? file.replace(/^\d+-|\.md$/g, '') };
+
+  for (const source of splitSlides(stripFrontMatter(markdown))) {
+    const marker = source.match(DEMO_MARKER);
+    slidesEl.append(marker ? demoSection(marker[1], deck) : markdownSection(source, deck));
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+await Reveal.initialize({
+  width: 1280,
+  height: 720,
+  margin: 0.055,
+  minScale: 0.2,
+  maxScale: 1.8,
+  hash: true,
+  slideNumber: 'c/t',
+  transition: 'slide',
+  transitionSpeed: 'fast',
+  backgroundTransition: 'fade',
+  // `data-src` on the demo iframes: `false` loads one only once its slide is on
+  // screen, and unloads it on the way out. Loading early is worse than it sounds —
+  // an embed that measures its container at mount comes up blank when it mounts
+  // hidden, which is what you get when you deep-link straight to a demo slide.
+  // The trade-off is a fresh page on every visit, which is what you want on stage.
+  preloadIframes: false,
+  pdfSeparateFragments: false,
+  // Anything the project wants to change, from `reveal:` in slides.config.js.
+  ...(CFG.reveal ?? {}),
+  // Spotlight after Annotate: it hangs its button on the toolbar the pen builds.
+  plugins: [RevealMarkdown, RevealHighlight, RevealNotes, RevealAnnotate(), RevealSpotlight(), RevealOutline()],
+});
+
+// ---------------------------------------------------------------------------
+// Embedded apps that measure their container once, at mount, come up blank in a
+// deck: reveal scales slides with a CSS transform, which fires no resize inside
+// the frame. Changing the iframe's own width does fire one — so nudge it whenever
+// a demo slide is shown, and again when its page finishes loading.
+// ---------------------------------------------------------------------------
+
+const nudge = (slide) => {
+  const iframe = slide?.querySelector('iframe');
+  if (!iframe) return;
+
+  const kick = () => {
+    iframe.style.width = '99%';
+    setTimeout(() => { iframe.style.width = ''; }, 150);
+  };
+
+  iframe.addEventListener('load', kick, { once: true });
+  kick(); // already loaded: revisiting the slide
+};
+
+Reveal.on('ready', ({ currentSlide }) => nudge(currentSlide));
+Reveal.on('slidechanged', ({ currentSlide }) => nudge(currentSlide));
+
+// ---------------------------------------------------------------------------
+// Post-processing — everything below runs on markdown the plugin has rendered.
+// ---------------------------------------------------------------------------
+
+// ```mermaid fences become real diagrams. Rendering after highlight.js keeps the
+// original source intact in textContent.
+mermaid.initialize({
+  startOnLoad: false,
+  theme: 'base',
+  securityLevel: 'strict',
+  // Explicit width on the SVG: reveal hides off-screen slides with `display:none`,
+  // so a diagram sized against its container would come out zero-width.
+  // `htmlLabels: false` keeps mermaid measuring labels with the same metrics it
+  // draws them with — HTML labels get clipped at these font settings.
+  flowchart: { useMaxWidth: false, htmlLabels: false, curve: 'basis', padding: 18, nodeSpacing: 55, rankSpacing: 70 },
+  themeVariables: {
+    fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+    fontSize: '17px',
+    primaryColor: '#1a1f27',
+    primaryTextColor: '#e8ebf0',
+    primaryBorderColor: '#6ea8fe',
+    lineColor: '#97a1b0',
+    secondaryColor: '#12151b',
+    tertiaryColor: '#12151b',
+  },
+  // `mermaid:` in slides.config.js, for a deck on a light theme.
+  ...(CFG.mermaid ?? {}),
+});
+
+const diagrams = document.querySelectorAll('pre code.language-mermaid, pre code.mermaid');
+for (const [i, code] of [...diagrams].entries()) {
+  const holder = document.createElement('div');
+  holder.className = 'mermaid';
+  try {
+    // `render()` draws into its own detached sandbox and hands back markup, so it
+    // does not care that the slide it is going into is currently hidden.
+    const { svg } = await mermaid.render(`mermaid-${i}`, code.textContent.trim());
+    holder.innerHTML = svg;
+  } catch (error) {
+    console.error('[deck] mermaid failed', error);
+    continue;
+  }
+  code.closest('pre').replaceWith(holder);
+}
+
+// ---------------------------------------------------------------------------
+// highlight.js stops at the edge of a template literal's `${…}`: it tags the
+// interpolation but leaves most of its contents untokenised, so
+// `${addToCounter(amount)}` inherits the string colour and reads as static text.
+// The same expression on its own tokenises fine — so re-run the highlighter on
+// what sits inside each `${…}`, and tag the delimiters so the seam between
+// string and code is visible.
+// ---------------------------------------------------------------------------
+
+const { hljs } = RevealHighlight();
+
+const relightSubst = (subst) => {
+  const source = subst.textContent;
+  // `data-line-numbers` re-splits highlighted code row by row: a `${…}` broken
+  // across two lines arrives here in halves, and half an expression is not one.
+  if (!source.startsWith('${') || !source.endsWith('}')) return;
+
+  const code = hljs.highlight(source.slice(2, -1), { language: 'javascript', ignoreIllegals: true }).value;
+  subst.innerHTML = `<span class="hljs-subst-mark">\${</span>${code}<span class="hljs-subst-mark">}</span>`;
+  // A nested `${…}` comes back out of the highlighter as flat as its parent did.
+  subst.querySelectorAll('.hljs-subst').forEach(relightSubst);
+};
+
+// Outermost first: the nested ones are reached through the recursion above, and
+// filtering before the first rewrite keeps every node in the list still attached.
+[...document.querySelectorAll('.slides pre code .hljs-subst')]
+  .filter((subst) => !subst.parentElement.closest('.hljs-subst'))
+  .forEach(relightSubst);
+
+// Bullets appear one at a time; tables, code and short lists stay whole.
+if (AUTO_FRAGMENT) {
+  for (const section of document.querySelectorAll('.slides section:not(.deck-title)')) {
+    const lists = [...section.querySelectorAll(':scope > ul')].filter((ul) => ul.children.length > 2);
+    if (!lists.length) continue;
+    for (const list of lists) for (const li of list.children) li.classList.add('fragment');
+
+    // Reveal numbered the fragments the Markdown declared itself — an
+    // `<!-- .element: class="fragment" -->` — back at init, before these bullets
+    // existed, so they would keep those low indices and step first wherever they
+    // sit. Dropping the numbers lets the sync below order the slide by the DOM.
+    for (const numbered of section.querySelectorAll('.fragment[data-fragment-index]')) {
+      numbered.removeAttribute('data-fragment-index');
+    }
+  }
+}
+
+// Long code blocks scroll instead of overflowing the slide.
+for (const pre of document.querySelectorAll('.slides pre')) {
+  const lines = pre.textContent.trimEnd().split('\n').length;
+  if (lines > 14) pre.classList.add('pre--dense');
+}
+
+Reveal.sync();
+
+// Which deck are we in? Shown in the corner, hidden on dividers.
+const badge = document.querySelector('#deck-badge');
+const updateBadge = () => {
+  const current = Reveal.getCurrentSlide();
+  badge.textContent = current?.dataset.deck ?? '';
+  badge.hidden = !current || current.classList.contains('deck-title');
+};
+Reveal.on('slidechanged', updateBadge);
+Reveal.on('ready', updateBadge);
+updateBadge();

package/runtime/index.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="{{lang}}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+
+    <!-- reveal.js and mermaid are served from this project, not from a CDN:
+         a talk has to survive the conference wifi. -->
+    <link rel="stylesheet" href="vendor/reveal/dist/reveal.css" />
+    <link rel="stylesheet" href="vendor/reveal/plugin/highlight/monokai.css" />
+    <link rel="stylesheet" href="theme.base.css" />
+    {{head}}
+  </head>
+
+  <body>
+    <div class="reveal">
+      <div class="slides"><!-- built at runtime from the .md files --></div>
+    </div>
+
+    <div id="deck-badge" aria-hidden="true"></div>
+
+    {{signature}}
+
+    <script>
+      window.__FB_SLIDES__ = {{config}};
+    </script>
+
+    <script src="vendor/reveal/dist/reveal.js"></script>
+    <script src="vendor/reveal/plugin/markdown/markdown.js"></script>
+    <script src="vendor/reveal/plugin/highlight/highlight.js"></script>
+    <script src="vendor/reveal/plugin/notes/notes.js"></script>
+    <script src="vendor/mermaid/dist/mermaid.min.js"></script>
+
+    <script type="module" src="deck.js"></script>
+  </body>
+</html>