fb-slides 0.1.2

package/runtime/outline.js

@@ -0,0 +1,354 @@
+// ---------------------------------------------------------------------------
+// RevealOutline — the deck as a list, down the left edge.
+//
+// Reveal's own overview (`O`) lays the slides out as a grid of thumbnails: good
+// for "where am I", useless for "jump to the bit about X" once a talk is fifty
+// slides long. This is the other view — every slide by its title, in a column
+// you can read and scroll, with the structure of the decks still visible.
+//
+// It pushes the deck aside rather than covering it: the slide stays readable
+// while you look for the next one, which is the whole point on stage.
+//
+// A reveal.js plugin: `init()` gets the deck instance, so this file owns the
+// feature end to end — its chrome, its list and its key binding. The look lives
+// in theme.base.css with the rest of the chrome, so a project can reskin it.
+// ---------------------------------------------------------------------------
+
+import { listShortcutAfter } from './shortcuts.js';
+
+const MENU_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"
+  stroke-linecap="round" aria-hidden="true">
+  <path d="M4 7h16" /><path d="M4 12h16" /><path d="M4 17h16" />
+</svg>`;
+
+const CLOSE_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"
+  stroke-linecap="round" aria-hidden="true">
+  <path d="M6 6l12 12" /><path d="M18 6L6 18" />
+</svg>`;
+
+// The view toggle wears the mode it would switch to, not the one it is in:
+// reading titles, you see the image; browsing previews, you see the list.
+const IMAGE_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"
+  stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="4" y="5" width="16" height="14" rx="2" />
+  <circle cx="9.2" cy="10.2" r="1.5" />
+  <path d="M4 16.8l4.6-4.6 3.4 3.4 3.2-3.2 4.8 4.8" />
+</svg>`;
+
+const LIST_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"
+  stroke-linecap="round" aria-hidden="true">
+  <path d="M9 6.5h11" /><path d="M9 12h11" /><path d="M9 17.5h11" />
+  <path d="M4.5 6.5h.01" /><path d="M4.5 12h.01" /><path d="M4.5 17.5h.01" />
+</svg>`;
+
+// Which face of the panel you last used — titles or previews — is a durable
+// preference, not per-deck state, so it survives the tab.
+const VIEW_KEY = 'fb-slides.outline-view';
+
+// Long enough to read as a movement, short enough not to be waited on. The
+// panel's slide-in and the deck's reflow share it — see theme.base.css.
+const SLIDE_MS = 260;
+
+// The key the panel answers to, how the help overlay spells it, and what it
+// calls it there — one row below reveal's own overview, which is what this is
+// the vertical answer to.
+//
+// `V` is one of reveal's three black-screen keys, and a plugin binding wins over
+// it — which is the point: the navigator is reached for far more often, and `B`
+// and `.` still black the screen. Reveal's help row for pause reads `B  ,  .`
+// and never listed `V`, so nothing there needs correcting.
+const KEY_CODE = 86;
+const HELP_ROW = { key: 'V', action: 'Vertical Slide Overview', after: /overview/i };
+
+// What to call a slide in the list. The rendered heading is the title the
+// audience saw; a demo slide has no heading, so its header names the demo.
+const titleOf = (slide) => {
+  if (slide.classList.contains('demo-slide')) {
+    return slide.querySelector('header code')?.textContent.trim() ?? 'demo';
+  }
+  const heading = slide.querySelector(':scope > h1, :scope > h2, :scope > h3');
+  if (heading) return heading.textContent.trim();
+  // No heading at all — a slide that is one image, one quote, one line of code.
+  // Its own first words are still a better handle than "slide 14".
+  const text = slide.textContent.replace(/\s+/g, ' ').trim();
+  return text ? text.slice(0, 70) : `slide ${slide.dataset.outlineNumber ?? ''}`.trim();
+};
+
+// The list, in reading order: one row per deck as it starts, one per slide.
+//
+// Depth is the talk's own structure, not a tree someone has to maintain. A
+// slide opening with an `# h1` is a deck divider, so the slides that follow it
+// are what it introduces and sit one step in. A deck that has no divider has
+// nothing to hang off, and stays flush. Reveal's vertical slides — should a
+// deck use them — indent once more under the slide they hang off.
+const rowsFor = (deck) => {
+  const rows = [];
+  let section = null;
+  let dividerSeen = false;
+
+  for (const [index, slide] of deck.getSlides().entries()) {
+    const stack = slide.parentElement.matches('section') ? slide.parentElement : null;
+    const owner = stack ?? slide;
+    const label = owner.dataset.deck ?? '';
+
+    if (label !== section) {
+      section = label;
+      dividerSeen = false;
+      if (label) rows.push({ kind: 'section', label });
+    }
+
+    const divider = owner.classList.contains('deck-title');
+    if (divider) dividerSeen = true;
+    const base = divider || !dividerSeen ? 0 : 1;
+    // A vertical slide is not just one deeper — the preview view insets it from
+    // both sides, so it reads as stacked under its slide, not as a new section.
+    const vertical = Boolean(stack) && slide !== stack.firstElementChild;
+    const depth = vertical ? base + 1 : base;
+
+    slide.dataset.outlineNumber = index + 1;
+    rows.push({ kind: 'slide', slide, depth, number: index + 1, divider, vertical });
+  }
+  return rows;
+};
+
+const RevealOutline = () => ({
+  id: 'outline',
+
+  init(deck) {
+    const button = document.createElement('button');
+    button.id = 'deck-menu';
+    button.type = 'button';
+    button.title = 'Slides (V)';
+    button.setAttribute('aria-label', 'Slides');
+    button.innerHTML = MENU_ICON;
+
+    const panel = document.createElement('aside');
+    panel.id = 'deck-outline';
+    panel.innerHTML = `
+      <header>
+        <span>slides</span>
+        <button type="button" class="deck-outline-view"></button>
+        <button type="button" class="deck-outline-close" aria-label="Close">${CLOSE_ICON}</button>
+      </header>
+      <nav class="deck-outline-list"></nav>
+    `;
+
+    document.body.append(button, panel);
+    const list = panel.querySelector('.deck-outline-list');
+    const viewButton = panel.querySelector('.deck-outline-view');
+
+    // ---------------------------------------------------------------------
+    // Open and close. The deck itself is narrowed by CSS, and reveal only
+    // rescales a slide when it is told to — so drive `layout()` for as long as
+    // the width is moving, or the slide would snap to its new size at the end.
+    // ---------------------------------------------------------------------
+
+    let open = false;
+
+    const reflow = () => {
+      const until = performance.now() + SLIDE_MS;
+      const step = () => {
+        deck.layout();
+        if (performance.now() < until) requestAnimationFrame(step);
+      };
+      requestAnimationFrame(step);
+    };
+
+    const setOpen = (next) => {
+      if (next === open) return;
+      open = next;
+      document.body.classList.toggle('outline-open', open);
+      button.setAttribute('aria-expanded', String(open));
+      // Closed, it is still on the page for the transition — but out of reach
+      // of the pointer and of Tab.
+      panel.inert = !open;
+      if (open) scrollToCurrent();
+      reflow();
+    };
+
+    // ---------------------------------------------------------------------
+    // Two faces of the same list: every slide by its title, or every slide as
+    // itself — a live clone on a deck-sized stage, scaled to the row.
+    // ---------------------------------------------------------------------
+
+    let view = 'list';
+    try {
+      if (localStorage.getItem(VIEW_KEY) === 'preview') view = 'preview';
+    } catch {
+      /* storage can be walled off (file://, private mode); the default stands */
+    }
+
+    // The stage is deck-sized so the theme lays the clone out exactly as it did
+    // the slide, then one transform shrinks it to the row. The scale is the
+    // measured row width over the deck width — set on the list, not per thumb,
+    // since every row is as wide as the panel.
+    const config = deck.getConfig();
+    list.style.setProperty('--deck-w', `${config.width}px`);
+    list.style.setProperty('--deck-h', `${config.height}px`);
+    list.style.setProperty('--deck-ratio', `${config.width} / ${config.height}`);
+
+    // Per stage, not once on the list: indented rows (a divider's slides, a
+    // vertical stack) have narrower thumbs, so each gets its own scale.
+    const syncThumbScale = () => {
+      for (const thumb of list.querySelectorAll('.deck-outline-thumb')) {
+        thumb.style.setProperty('--thumb-scale', thumb.clientWidth / config.width);
+      }
+    };
+
+    const thumbFor = (slide) => {
+      const clone = slide.cloneNode(true);
+      // Undo what reveal did to keep the original off-screen. Inline styles go
+      // wholesale: layout inside the stage is the stylesheet's job.
+      clone.removeAttribute('style');
+      clone.removeAttribute('hidden');
+      clone.removeAttribute('aria-hidden');
+      clone.classList.remove('past', 'present', 'future', 'stack');
+      // A demo slide would put a live page — server round-trips and all — in
+      // every row. A framed blank stands in; the header still names the demo.
+      for (const frame of clone.querySelectorAll('iframe')) {
+        const shell = document.createElement('div');
+        shell.className = 'deck-outline-thumb-frame';
+        frame.replaceWith(shell);
+      }
+      // Cloned ids (headings, mermaid SVGs) would duplicate the document's.
+      for (const el of clone.querySelectorAll('[id]')) el.removeAttribute('id');
+      clone.removeAttribute('id');
+      const stage = document.createElement('span');
+      stage.className = 'deck-outline-thumb reveal';
+      stage.setAttribute('aria-hidden', 'true');
+      const slides = document.createElement('span');
+      slides.className = 'slides';
+      slides.append(clone);
+      stage.append(slides);
+      return stage;
+    };
+
+    let rows = [];
+
+    const render = () => {
+      rows = rowsFor(deck);
+      list.replaceChildren(
+        ...rows.map((row, index) => {
+          if (row.kind === 'section') {
+            const header = document.createElement('h2');
+            header.textContent = row.label;
+            return header;
+          }
+          const item = document.createElement('button');
+          item.type = 'button';
+          item.className = 'deck-outline-item';
+          item.dataset.row = index;
+          item.dataset.depth = Math.min(row.depth, 2);
+          if (row.divider) item.classList.add('is-divider');
+          if (row.vertical) item.classList.add('is-vertical');
+          if (view === 'preview') {
+            item.innerHTML = `<span class="deck-outline-n">${row.number}</span>`;
+            item.prepend(thumbFor(row.slide));
+            // No room for the title in the row; it moves to the tooltip.
+            item.title = titleOf(row.slide);
+          } else {
+            item.innerHTML = `<span class="deck-outline-title"></span><span class="deck-outline-n">${row.number}</span>`;
+            item.querySelector('.deck-outline-title').textContent = titleOf(row.slide);
+          }
+          return item;
+        }),
+      );
+      syncThumbScale();
+    };
+
+    const applyView = () => {
+      panel.dataset.view = view;
+      const toList = view === 'preview';
+      viewButton.innerHTML = toList ? LIST_ICON : IMAGE_ICON;
+      viewButton.title = toList ? 'Title list' : 'Slide previews';
+      viewButton.setAttribute('aria-label', toList ? 'Show title list' : 'Show slide previews');
+    };
+    applyView();
+
+    const setView = (next) => {
+      if (next === view) return;
+      view = next;
+      applyView();
+      render();
+      markCurrent();
+      scrollToCurrent();
+      try {
+        localStorage.setItem(VIEW_KEY, view);
+      } catch {
+        /* not persisted, still switched */
+      }
+    };
+
+    viewButton.addEventListener('click', () => setView(view === 'list' ? 'preview' : 'list'));
+    window.addEventListener('resize', syncThumbScale);
+
+    const currentItem = () => {
+      const current = deck.getCurrentSlide();
+      return [...list.querySelectorAll('.deck-outline-item')].find(
+        (item) => rows[item.dataset.row].slide === current,
+      );
+    };
+
+    const scrollToCurrent = () => currentItem()?.scrollIntoView({ block: 'nearest' });
+
+    const markCurrent = () => {
+      const item = currentItem();
+      for (const other of list.querySelectorAll('.is-current')) other.classList.remove('is-current');
+      if (!item) return;
+      item.classList.add('is-current');
+      if (open) item.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    };
+
+    list.addEventListener('click', (event) => {
+      const item = event.target.closest('.deck-outline-item');
+      if (!item) return;
+      const { h, v } = deck.getIndices(rows[item.dataset.row].slide);
+      deck.slide(h, v);
+      // Clicked with the mouse, the button would keep the focus and swallow the
+      // next Space as a re-click. Activated from the keyboard (`detail === 0`)
+      // the focus is the only place the caller has, so it stays.
+      if (event.detail) item.blur();
+    });
+
+    button.addEventListener('click', () => setOpen(!open));
+    panel.querySelector('.deck-outline-close').addEventListener('click', () => setOpen(false));
+
+    // The bare form binds the key without listing it: a descriptor here would
+    // put the row in the plugin table at the foot of the help overlay, and it
+    // belongs with the built-ins — see the `ready` handler below.
+    // Blacked out, the key would toggle a panel nobody can see — and `V` is one
+    // of the keys reveal lets through while paused, so it gets here. Leave the
+    // screen black: `B` and `.` are what brings it back.
+    deck.addKeyBinding(KEY_CODE, () => {
+      if (!deck.isPaused()) setOpen(!open);
+    });
+    // Escape is reveal's own overview toggle, and it binds before a plugin can.
+    // Capture phase gets there first — but only to take Escape back while the
+    // panel is open, so the key still opens the overview the rest of the time.
+    document.addEventListener(
+      'keydown',
+      (event) => {
+        if (event.key !== 'Escape' || !open) return;
+        setOpen(false);
+        event.stopPropagation();
+        event.preventDefault();
+      },
+      true,
+    );
+
+    // Titles are read off the rendered slides, so the list can only be built
+    // once the markdown plugin has run — which `ready` is the signal for.
+    deck.on('ready', () => {
+      render();
+      markCurrent();
+      // Not before: the built-in shortcuts are only in the map once reveal has
+      // configured itself, and there would be no overview row to sit under.
+      listShortcutAfter(deck, HELP_ROW);
+    });
+    deck.on('slidechanged', markCurrent);
+
+    panel.inert = true;
+  },
+});
+
+export default RevealOutline;

package/runtime/shortcuts.js

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// The help overlay's table (`?`), edited.
+//
+// Reveal keeps its own shortcuts in one insertion-ordered map and renders the
+// plugins' key bindings as a second, separate table under it. That is the right
+// default — but not for a key that belongs beside a built-in rather than under
+// a heading of its own, and not for a key a plugin takes over from reveal,
+// which would leave the built-in row promising something it no longer does.
+//
+// Both cases are the same edit: the map has to be rebuilt, because emptying and
+// refilling it is the only way to choose where a row lands. It lives here so
+// that neither plugin has to carry the trick.
+//
+// Nothing in it is load-bearing: a reveal that stopped handing the map out
+// leaves the overlay as reveal wrote it, and every key still works.
+// ---------------------------------------------------------------------------
+
+const mapOf = (deck) => deck.keyboard?.getShortcuts?.() ?? null;
+
+// The map is live, so this reorders the real thing rather than a copy of it.
+const rewrite = (shortcuts, rows) => {
+  for (const key of Object.keys(shortcuts)) delete shortcuts[key];
+  Object.assign(shortcuts, Object.fromEntries(rows));
+};
+
+// Reveal writes a row's keys as one string: `P  ,  Shift SPACE`.
+const SEPARATOR = '  ,  ';
+
+// One row for `key`, in the place right below the first row whose action `after`
+// matches — or at the end, if the deck is configured without that one.
+export const listShortcutAfter = (deck, { key, action, after }) => {
+  const shortcuts = mapOf(deck);
+  if (!shortcuts) return;
+  const rows = Object.entries(shortcuts).filter(([keys]) => keys !== key);
+  const at = rows.findIndex(([, text]) => after.test(text));
+  rows.splice(at < 0 ? rows.length : at + 1, 0, [key, action]);
+  rewrite(shortcuts, rows);
+};
+
+// Take `key` out of the built-in row `from` matches, leaving the other keys in
+// it. A row that had no other key goes with it.
+export const unlistShortcut = (deck, { key, from }) => {
+  const shortcuts = mapOf(deck);
+  if (!shortcuts) return;
+  const rows = Object.entries(shortcuts)
+    .map(([keys, text]) => {
+      if (!from.test(text)) return [keys, text];
+      const kept = keys.split(',').map((one) => one.trim()).filter((one) => one !== key);
+      return [kept.join(SEPARATOR), text];
+    })
+    .filter(([keys]) => keys);
+  rewrite(shortcuts, rows);
+};