fb-slides 0.5.0 → 0.6.2

package/README.md

@@ -127,6 +127,63 @@ A `Note:` block at the end of a slide never shows on screen, only in the speaker
 Note: a bad description is the most common reason a tool never gets used.
 ```
 
+### Blocks
+
+Six classes cover the layouts a talk keeps needing, so a slide asks for one by name
+instead of carrying a paragraph of inline styles:
+
+| | |
+| --- | --- |
+| `.cols` / `.col` | two columns — with the `min-width: 0` a code block falls over without |
+| `.frame` | an embed that shares the slide instead of taking it whole |
+| `.caption` | a quiet line under a figure |
+| `.box` | a bordered block: the point the slide comes back to |
+| `.author-slide` | the speaker page — photos down the left edge, the bio on the right |
+| `<img>`, `<video>` | centred, unframed, and never wider than the slide |
+
+````markdown
+<div class="cols">
+<div class="col">
+
+**In the widget**
+
+```js
+app.openLink({ url: 'https://example.com/' });
+```
+
+</div>
+<div class="col">
+
+The blank lines matter: Markdown inside a block-level tag is only parsed
+when there is one on each side of it.
+
+</div>
+</div>
+````
+
+Each of them fixes its numbers in CSS variables — `--cols-gap`, `--frame-w`,
+`--frame-h`, `--author-photo`, `--author-hold` — so a project retunes one from its own
+`theme.css` without restating the rule.
+
+The speaker page is markup you write and the theme lays out. Give `.author-photo` as
+many `<img>` as you like: they cross-fade in the order they are written, on a loop that
+restarts every time the slide comes up.
+
+```markdown
+<!-- .slide: class="author-slide" -->
+
+<div class="author-photo">
+  <img src="assets/author/on-stage.jpg" alt="" />
+  <img src="assets/author/portrait.jpg" alt="" />
+</div>
+
+<div class="author-bio">
+  <h1>Your name</h1>
+  <ul><li>What you do</li></ul>
+  <p class="author-meta">The stack · you · work · with</p>
+</div>
+```
+
 ### Editing in the browser
 
 On the dev server, `T` (or the last button on the toolbar) opens the slide you
@@ -140,6 +197,22 @@ right after the current one and opens it; **Delete** removes the slide from its
 file, after asking. Clicking into the notes box trades the room with the slide
 box, so both are comfortable to write in.
 
+The `+` over the slide box — or `/` typed on an empty line — opens the block
+picker: the demo marker, a framed embed, a video with the attributes that make
+it behave, two columns, a fenced block, the speaker page. The block lands where
+the cursor was, with its first placeholder selected so it is ready to type over;
+text already selected takes that placeholder's place, so picking **Fragment**
+wraps the paragraph that was highlighted. A block that only works at the top of
+a slide, like the demo marker, goes there whatever the cursor was doing.
+
+`snippets:` in `slides.config.js` adds a project's own blocks to the list:
+
+```js
+snippets: [
+  { label: 'Pricing table', hint: 'the three tiers', body: '<div class="tiers">${…}</div>' },
+],
+```
+
 The drawer exists only under `fb-slides dev`: a built deck is static files and
 never shows the button.
 
@@ -194,6 +267,7 @@ export default {
   outDir: 'dist',
   exclude: ['dist'],             // extra path segments the build skips
   fragmentLists: true,           // bullet lists reveal one item at a time
+  snippets: [],                  // your own blocks in the edit drawer's picker
   reveal: { transition: 'fade' },// passed to Reveal.initialize()
   mermaid: {},                   // passed to mermaid.initialize()
 };

package/lib/config.mjs

@@ -80,6 +80,10 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
     reveal: user.reveal ?? {},
     // Bullet lists of 3+ items appear one item at a time.
     fragmentLists: user.fragmentLists ?? true,
+    // The project's own entries in the edit drawer's block picker, after the
+    // built-in ones: `{ label, hint, body, top }`, where `${…}` in the body
+    // marks what has to be typed over.
+    snippets: user.snippets ?? [],
     // The build output, at any depth: a framework demo's own dist/ is its dev
     // server's business, and the deck ships that demo as sources.
     exclude: [...ALWAYS_EXCLUDED, overrides.outDir ?? user.outDir ?? 'dist', ...(user.exclude ?? [])],

package/lib/render.mjs

@@ -46,6 +46,7 @@ export const renderIndex = async (config, runtimeDir) => {
     demos: config.urls.demos,
     reveal: config.reveal,
     fragmentLists: config.fragmentLists,
+    snippets: config.snippets,
   };
 
   // The chrome reads this to take its colours from the reveal theme instead of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fb-slides",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "type": "module",
   "description": "Markdown-driven reveal.js decks: live demo embeds, annotation, mermaid, and a zero-config dev server",
   "keywords": [

package/runtime/annotate.js

@@ -477,7 +477,17 @@ const RevealAnnotate = () => ({
       for (const [name, button] of Object.entries(toolButtons)) {
         button.setAttribute('aria-pressed', String(name === tool));
       }
-      toolbar.classList.toggle('is-armed', tool !== null);
+      // `is-armed` is shared with the other tool plugins, and the arming
+      // handshake fires mid-switch: the newcomer sets the class, then its
+      // event runs this module's stand-down — so a plain toggle with this
+      // module's own boolean would wipe it with a tool still armed. It is
+      // recomputed from the buttons instead, which every module keeps
+      // truthful. The edit chip stays out of it: its pressed state is the
+      // drawer, not an armed tool.
+      toolbar.classList.toggle(
+        'is-armed',
+        !!toolbar.querySelector('.deck-tool[aria-pressed="true"]:not(#tool-edit)'),
+      );
       // The colours are only worth showing while there is a tool to apply them
       // to, which makes arming one the gesture that opens them.
       swatches.hidden = tool === null;

package/runtime/deck.js

@@ -294,6 +294,58 @@ for (const pre of document.querySelectorAll('.slides pre')) {
   if (lines > 14) pre.classList.add('pre--dense');
 }
 
+// ---------------------------------------------------------------------------
+// The speaker page's photos cross-fade in DOM order (`.author-slide` in
+// theme.base.css). Where each fade lands depends on how many photos there are
+// and on the two timing tokens a project can retune — so the keyframes each
+// strip needs are written here, instead of shipping a set for every count the
+// theme might ever be handed.
+// ---------------------------------------------------------------------------
+
+const seconds = (value) => {
+  const time = Number.parseFloat(value);
+  if (!Number.isFinite(time)) return 0;
+  return value.trim().endsWith('ms') ? time / 1000 : time;
+};
+
+const strips = document.querySelectorAll('.slides .author-photo');
+if (strips.length) {
+  const sheet = document.createElement('style');
+  document.head.append(sheet);
+  const written = new Set();
+
+  for (const strip of strips) {
+    const photos = [...strip.querySelectorAll('img')];
+    photos.forEach((photo, i) => photo.style.setProperty('--i', i));
+    // One photo has nothing to fade to, and the CSS already leaves it showing.
+    if (photos.length < 2) continue;
+
+    const css = getComputedStyle(strip);
+    const hold = seconds(css.getPropertyValue('--author-hold'));
+    const fade = seconds(css.getPropertyValue('--author-fade'));
+    const slot = hold + fade;
+    if (!slot) continue;
+
+    const total = photos.length * slot;
+    const at = (time) => `${((time / total) * 100).toFixed(3)}%`;
+    // Named for what it draws: two strips of the same length and timing — the
+    // ordinary case, since both come from the same tokens — share one set.
+    const name = `author-fade-${photos.length}-${Math.round(hold * 1000)}-${Math.round(fade * 1000)}`;
+    if (!written.has(name)) {
+      written.add(name);
+      sheet.sheet.insertRule(
+        `@keyframes ${name} {` +
+          `0% { opacity: 0 }` +
+          `${at(fade)}, ${at(slot)} { opacity: 1 }` +
+          `${at(slot + fade)}, 100% { opacity: 0 }` +
+        `}`,
+      );
+    }
+    strip.style.setProperty('--author-n', photos.length);
+    strip.style.setProperty('--author-anim', name);
+  }
+}
+
 Reveal.sync();
 
 // Which deck are we in? Shown in the corner, hidden on dividers.

package/runtime/edit.js

@@ -13,8 +13,13 @@
 // slide's own range of the .md (the server owns that arithmetic) and reloads:
 // the URL hash puts the deck back on this slide, and the full pipeline —
 // mermaid, fragments, highlight steps — runs over the saved source.
+//
+// The `+` over the slide box — or `/` on an empty line — opens the block
+// picker, which writes the markup nobody should have to remember (snippets.js).
 // ---------------------------------------------------------------------------
 
+import { createSnippets, PLUS_ICON } from './snippets.js';
+
 // Where the slide came from, stamped on every section by deck.js: the .md file
 // and the slide's index within it, counted the way the server counts.
 const SRC = (slide) => {
@@ -116,19 +121,22 @@ const build = (deck) => {
   panel.id = 'deck-edit';
   panel.innerHTML = `
     <header>
-      <span>edit</span>
+      <button type="button" class="deck-edit-wide" aria-pressed="false"></button>
       <code class="deck-edit-file"></code>
       <button type="button" class="deck-edit-nav" data-go="-1" title="Previous slide" aria-label="Previous slide">${PREV_ICON}</button>
       <button type="button" class="deck-edit-nav" data-go="1" title="Next slide" aria-label="Next slide">${NEXT_ICON}</button>
       <button type="button" class="deck-edit-close" aria-label="Close">${CLOSE_ICON}</button>
     </header>
-    <label class="deck-edit-label" for="deck-edit-source">slide</label>
+    <div class="deck-edit-row">
+      <label class="deck-edit-label" for="deck-edit-source">slide</label>
+      <button type="button" class="deck-edit-snip" title="Insert a block (/)" aria-label="Insert a block">${PLUS_ICON}</button>
+    </div>
     <textarea id="deck-edit-source" spellcheck="false"></textarea>
     <label class="deck-edit-label" for="deck-edit-notes">speaker notes</label>
     <textarea id="deck-edit-notes" spellcheck="false"></textarea>
     <footer>
-      <button type="button" class="deck-edit-add" title="Add a slide after this one">Add</button>
-      <button type="button" class="deck-edit-delete" title="Delete this slide">Delete</button>
+      <button type="button" class="deck-edit-add" title="Add a slide after this one">Add page</button>
+      <button type="button" class="deck-edit-delete" title="Delete this slide">Delete page</button>
       <span class="deck-edit-status" role="status"></span>
       <button type="button" class="deck-edit-save">Save</button>
     </footer>
@@ -144,6 +152,7 @@ const build = (deck) => {
   panel.inert = true;
 
   const fileLabel = panel.querySelector('.deck-edit-file');
+  const wideButton = panel.querySelector('.deck-edit-wide');
   const sourceArea = panel.querySelector('#deck-edit-source');
   const notesArea = panel.querySelector('#deck-edit-notes');
   const status = panel.querySelector('.deck-edit-status');
@@ -190,6 +199,13 @@ const build = (deck) => {
     frame ||= requestAnimationFrame(paint);
   };
 
+  // ---- the block picker ---------------------------------------------------
+  // Over the drawer, like the delete question: the deck keeps the stage, and
+  // what the picker writes goes through the same preview typing does.
+
+  const snippets = createSnippets({ area: sourceArea, paint: schedulePaint });
+  panel.append(snippets.element);
+
   // ---- open and close ---------------------------------------------------
   // The deck is narrowed by CSS while the drawer is out (see theme.base.css);
   // reveal only rescales when told to, so layout() is driven for as long as
@@ -204,6 +220,29 @@ const build = (deck) => {
     requestAnimationFrame(step);
   };
 
+  // Half the page for a slide that is mostly markup, the narrow drawer for one
+  // that is mostly words. The width is a token, so saying it on the body is
+  // enough — the deck, the badge, the signature and the toolbar all step aside
+  // through the same `calc()` they already use. It survives the reload a save
+  // ends in, which is the only way it could be worth setting at all.
+  const WIDE_KEY = 'fb-slides.edit-wide';
+
+  const setWide = (wide) => {
+    document.body.classList.toggle('edit-wide', wide);
+    wideButton.setAttribute('aria-pressed', String(wide));
+    wideButton.innerHTML = wide ? NEXT_ICON : PREV_ICON;
+    const label = wide ? 'Narrow the drawer' : 'Widen the drawer to half the page';
+    wideButton.title = label;
+    wideButton.setAttribute('aria-label', label);
+    try {
+      if (wide) sessionStorage.setItem(WIDE_KEY, '1');
+      else sessionStorage.removeItem(WIDE_KEY);
+    } catch {
+      /* walled-off storage only costs the width after a reload */
+    }
+    reflow();
+  };
+
   const setOpen = (open) => {
     document.body.classList.toggle('edit-open', open);
     button.setAttribute('aria-pressed', String(open));
@@ -216,6 +255,7 @@ const build = (deck) => {
   const discard = () => {
     cancelAnimationFrame(frame);
     frame = 0;
+    snippets.close({ restore: false });
     confirmBox.hidden = true;
     editing.slide.innerHTML = editing.html;
     // The original fragments are back; reveal counts them again.
@@ -230,7 +270,10 @@ const build = (deck) => {
     deck.layout();
   };
 
-  const open = async () => {
+  // `focus` names the box that gets the room and the cursor — navigation and
+  // save-reloads pass the one the drawer already had, so following the deck
+  // never folds the notes away under a writing hand.
+  const open = async (focus = 'source') => {
     const slide = deck.getCurrentSlide();
     const src = SRC(slide);
     if (!src) return;
@@ -266,15 +309,16 @@ const build = (deck) => {
     fileLabel.textContent = src.file;
     sourceArea.value = content;
     notesArea.value = notes;
+    snippets.reset();
     status.textContent = '';
     saveButton.disabled = false;
-    panel.dataset.focus = 'source';
+    panel.dataset.focus = focus;
 
     // One pointer, one tool: the pen, spotlight and pointer stand down — and
     // stand this drawer down in turn when one of them arms (see below).
     document.dispatchEvent(new CustomEvent('deck:tool-armed', { detail: 'edit' }));
     setOpen(true);
-    sourceArea.focus();
+    (focus === 'notes' ? notesArea : sourceArea).focus();
   };
 
   const toggle = () => (editing ? close() : open());
@@ -287,9 +331,11 @@ const build = (deck) => {
 
   const REOPEN_KEY = 'fb-slides.edit-reopen';
 
+  // The flag's value is the box that was open, so the reload hands the room
+  // (and the cursor) back to it.
   const reloadEditing = () => {
     try {
-      sessionStorage.setItem(REOPEN_KEY, '1');
+      sessionStorage.setItem(REOPEN_KEY, panel.dataset.focus === 'notes' ? 'notes' : 'source');
     } catch {
       /* walled-off storage only costs the reopen */
     }
@@ -348,6 +394,10 @@ const build = (deck) => {
 
   button.addEventListener('click', toggle);
   panel.querySelector('.deck-edit-close').addEventListener('click', close);
+  wideButton.addEventListener('click', () =>
+    setWide(!document.body.classList.contains('edit-wide')),
+  );
+  panel.querySelector('.deck-edit-snip').addEventListener('click', () => snippets.open());
   saveButton.addEventListener('click', save);
   sourceArea.addEventListener('input', schedulePaint);
 
@@ -400,8 +450,10 @@ const build = (deck) => {
     'keydown',
     (event) => {
       if (event.key !== 'Escape' || !editing) return;
-      // One layer at a time: a pending delete question goes first.
-      if (confirmBox.hidden) close();
+      // One layer at a time, innermost first: the picker, then a pending
+      // delete question, then the drawer itself.
+      if (snippets.isOpen()) snippets.close();
+      else if (confirmBox.hidden) close();
       else confirmBox.hidden = true;
       event.stopPropagation();
       event.preventDefault();
@@ -416,13 +468,22 @@ const build = (deck) => {
     if (event.detail !== 'edit') close();
   });
 
+  let wideAtStart = false;
+  try {
+    wideAtStart = Boolean(sessionStorage.getItem(WIDE_KEY));
+  } catch {
+    /* walled-off storage: the drawer opens at its usual width */
+  }
+  setWide(wideAtStart);
+
   // A write reloaded the page with the drawer out: pick the editing back up
   // on whatever slide the hash landed on.
   try {
-    if (sessionStorage.getItem(REOPEN_KEY)) {
+    const reopen = sessionStorage.getItem(REOPEN_KEY);
+    if (reopen) {
       sessionStorage.removeItem(REOPEN_KEY);
-      if (deck.isReady?.()) open();
-      else deck.on('ready', open);
+      if (deck.isReady?.()) open(reopen);
+      else deck.on('ready', () => open(reopen));
     }
   } catch {
     /* walled-off storage: the drawer just stays closed */
@@ -433,8 +494,9 @@ const build = (deck) => {
   // overview is a different surface altogether, so there it does close.
   deck.on('slidechanged', async () => {
     if (!editing) return;
+    const focus = panel.dataset.focus;
     discard();
-    await open();
+    await open(focus);
     // The new slide would not load — a drawer left standing would lie about
     // what it edits.
     if (!editing) setOpen(false);

package/runtime/pointer.js

@@ -198,7 +198,15 @@ const RevealPointer = () => ({
     const setPointer = (on) => {
       armed = on;
       button.setAttribute('aria-pressed', String(on));
-      toolbar.classList.toggle('is-armed', on);
+      // Recomputed from every module's button, not toggled with this one's
+      // boolean: the arming handshake runs the loser's stand-down after the
+      // winner set the class, and the last writer would close the bar with a
+      // tool still armed. The edit chip's pressed state is the drawer, so it
+      // does not count.
+      toolbar.classList.toggle(
+        'is-armed',
+        !!toolbar.querySelector('.deck-tool[aria-pressed="true"]:not(#tool-edit)'),
+      );
       picker.hidden = !on;
       applyCursor();
       if (on) document.dispatchEvent(new CustomEvent('deck:tool-armed', { detail: 'pointer' }));