contour-deck 0.3.0 → 0.3.2

package/README.md

@@ -13,7 +13,7 @@ Outline-first slide decks on real DOM.
 A deck is blocks, slides, and pages: it opens on an outline of every block, a block opens into a left-right track of slides, and each slide scrolls down one page at a time.
 The core is plain TypeScript with no runtime dependency (7 KB of JavaScript and 3 KB of CSS, gzipped); the phone remote is a separate module that loads on first use.
 
-Status: 0.3.0 on npm. It holds the deck (M1), the M2 client (phone remote, laser pointer, drawing, tilt pointing, and a presenter window, see [Remote](#remote); the relay it talks to is a separate small service, [docs/PROTOCOL.md](docs/PROTOCOL.md)), and, new in 0.3.0, an opt-in structure for the Markdown plugins that reads blocks, slides, and pages from headings ([docs/PLUGINS.md](docs/PLUGINS.md#headings-mode)). Live demo: https://wayne930242.github.io/contour-deck/
+Status: 0.3.1 on npm. It holds the deck (M1), the M2 client (phone remote, laser pointer, drawing, tilt pointing, and a presenter window, see [Remote](#remote); the relay it talks to is a separate small service, [docs/PROTOCOL.md](docs/PROTOCOL.md)), and, since 0.3.0, an opt-in structure for the Markdown plugins that reads blocks, slides, and pages from headings ([docs/PLUGINS.md](docs/PLUGINS.md#headings-mode)); 0.3.1 lets HTML comments stand anywhere in it and titles a heading-less block by its first slide. Live demo: https://wayne930242.github.io/contour-deck/
 The design is in [docs/DESIGN.md](docs/DESIGN.md) (Traditional Chinese); the HTML the core reads is in [docs/CONTRACT.md](docs/CONTRACT.md).
 
 ## 看看它怎麼動
@@ -116,7 +116,7 @@ deck.prev();
 deck.open("4.2");       // put a block on the stage
 deck.go("4.4.2");       // or deck.go("slide-id")
 deck.overview();        // back to the outline
-deck.slideBy(1);        // the next slide, as the right arrow key; -1 for the one before
+deck.slideBy(1);        // the next slide, as the right arrow key once the page's steps are shown; -1 for the one before
 deck.pageBy(1);         // one stop down inside the slide, as the down arrow key
 deck.state;             // { mode, block, slide, page, step }; ordinals are 1-based
 deck.on("change", ({ mode, at, step }) => {});
@@ -201,7 +201,7 @@ The phone must be able to open the page's URL, so a deck on `localhost` needs a
 | --- | --- | --- |
 | `Space`, `Enter`, `PageDown` | advance one step | open the current slide |
 | `Shift+Space`, `PageUp`, `Backspace` | back one step | |
-| `←` `→` | previous, next slide | move between thumbnails |
+| `←` `→` | hide or show the current page's steps first, then the previous or next slide | move between thumbnails |
 | `↑` `↓` | previous, next stop | move between thumbnails |
 | `Home`, `End` | first, last slide of the block | |
 | `N` | notes panel | |

package/dist/core/deck.js

@@ -302,6 +302,15 @@ export function createDeck(root, options = {}) {
             slide.el.scrollBy({ top: below + 32, behavior: smooth() });
         render();
     }
+    /** The arrow keys: reveal or hide the current page's steps first, then move to the next or previous slide. */
+    function stepOrSlide(direction) {
+        readScroll();
+        const steps = pageAt().steps;
+        const pending = direction > 0 ? steps.some(item => !item.hasAttribute(ON)) : steps.some(item => item.hasAttribute(ON));
+        if (pending)
+            return direction > 0 ? next() : prev();
+        slideBy(direction);
+    }
     function prev() {
         if (busy || mode !== "stage")
             return;
@@ -509,8 +518,8 @@ export function createDeck(root, options = {}) {
                 PageDown: next,
                 PageUp: prev,
                 Backspace: prev,
-                ArrowRight: () => slideBy(1),
-                ArrowLeft: () => slideBy(-1),
+                ArrowRight: () => stepOrSlide(1),
+                ArrowLeft: () => stepOrSlide(-1),
                 ArrowDown: () => stepV(1),
                 ArrowUp: () => stepV(-1),
                 Escape: toOverview,

package/dist/rehype/headings.d.ts

@@ -3,7 +3,8 @@ import { type Group } from "./draft.js";
 import { type HastNode } from "./hast.js";
 /**
  * Reads the blocks out of the flow. A block with a title of its own (`::block` title, else its
- * heading) derives its label and the 附錄 kind from it unless `::block` gives them; a block
- * without one takes the deck's title and derives nothing.
+ * heading) derives its label and the 附錄 kind from it unless `::block` gives them. A block
+ * without one derives nothing: in a deck of several blocks it takes its first slide's title, and
+ * the only block takes the deck's title, else the deck's first `h1`, else its first slide's title.
  */
 export declare function readHeadings(flow: HastNode[], deckTitle: string | undefined, file: DeckFile): Group[];

package/dist/rehype/headings.js

@@ -3,10 +3,11 @@
  *
  * - A top-level `---` starts a block.
  * - A top-level `##` starts a slide. What stands before a block's first `##` is the block's first
- *   slide (a title, a `# 拆解` divider), unless it is nothing but a `####` kicker, notes, and
- *   directives: those open the first `##` slide.
+ *   slide (a title, a `# 拆解` divider), unless it is nothing but a `####` kicker, notes,
+ *   `::block`/`::slide`, and HTML comments: those open the first `##` slide.
  * - A top-level `###` starts a further page of the slide, unless it stands right under the `##`
- *   with no content between them: then both head the first page.
+ *   with no content between them (notes, `::block`/`::slide`, and HTML comments are not content):
+ *   then both head the first page.
  * - A block is titled by the first `#` or `####` before its first `##` or `###`; the heading stays
  *   where it is. `::block{…}` anywhere at the block's top level overrides what it names.
  * - Headings inside other elements, `####` and deeper, and a `#` after the first `##` are content.
@@ -15,7 +16,11 @@ import { MARK_BLOCK, MARK_SLIDE, MARK_VERTICAL, NOTES } from "../shared/markers.
 import { NO_VERTICAL } from "../shared/structure.js";
 import { blockMarkOf, isRule, leadTitle, ORIGIN, splitAt } from "./draft.js";
 import { isBlank, isElement, markOf, plainText } from "./hast.js";
-import { kindOf, shortOf } from "./titles.js";
+import { kindOf, shortOf, slideTitle } from "./titles.js";
+/** An HTML comment: a `comment` node (after rehype-raw), or a `raw` node of nothing but comments. */
+const isComment = (node) => node.type === "comment" || (node.type === "raw" && /^\s*(<!--(?:(?!-->)[\s\S])*-->\s*)+$/.test(node.value ?? ""));
+/** A slide's pages without their speaker notes, which never reach the audience. */
+const visibleOf = (slide) => slide.pages.map(page => page.filter(node => !(isElement(node) && NOTES in node.properties)));
 function readBlock(nodes, file) {
     let slide = { pages: [[]] };
     const slides = [slide];
@@ -32,7 +37,9 @@ function readBlock(nodes, file) {
     let trailing;
     for (const node of nodes) {
         if (!isElement(node)) {
-            if (!isBlank(node)) {
+            if (isComment(node))
+                slide.pages[slide.pages.length - 1].push(node);
+            else if (!isBlank(node)) {
                 slide.pages[slide.pages.length - 1].push(node);
                 bare = trailing = undefined;
                 body = true;
@@ -94,7 +101,7 @@ function readBlock(nodes, file) {
         trailing = undefined;
     }
     // Only the opening can be left empty: every other slide starts with its `##`.
-    if (!slides[0].pages[0].length) {
+    if (!slides[0].pages[0].some(node => !isComment(node))) {
         const marker = idMarkers.get(slides[0]);
         if (marker)
             file.fail("::slide without any content in its slide", marker, ORIGIN);
@@ -109,8 +116,9 @@ function readBlock(nodes, file) {
 }
 /**
  * Reads the blocks out of the flow. A block with a title of its own (`::block` title, else its
- * heading) derives its label and the 附錄 kind from it unless `::block` gives them; a block
- * without one takes the deck's title and derives nothing.
+ * heading) derives its label and the 附錄 kind from it unless `::block` gives them. A block
+ * without one derives nothing: in a deck of several blocks it takes its first slide's title, and
+ * the only block takes the deck's title, else the deck's first `h1`, else its first slide's title.
  */
 export function readHeadings(flow, deckTitle, file) {
     const blocks = splitAt(flow, isRule, () => true)
@@ -121,7 +129,10 @@ export function readHeadings(flow, deckTitle, file) {
         const own = mark.title ?? heading;
         const spec = own
             ? { ...mark, title: own, short: mark.short ?? shortOf(own), kind: mark.kind ?? kindOf(own) }
-            : { ...mark, title: leadTitle(deckTitle, drafts, slides[0]) };
+            : {
+                ...mark,
+                title: (blocks.length > 1 && slideTitle(visibleOf(slides[0]), "")) || leadTitle(deckTitle, drafts, slides[0]),
+            };
         return { spec, slides };
     });
 }

package/dist/rehype/index.js

@@ -17,7 +17,7 @@
  * Run it after `contour-deck/remark`, which writes the markers this plugin reads.
  */
 import { MARK_BLOCK, MARK_SLIDE, MARK_VERTICAL } from "../shared/markers.js";
-import { structureOf } from "../shared/structure.js";
+import { checkStructure, structureOf } from "../shared/structure.js";
 import { blockMarkOf, hasContent, isRule, leadTitle, ORIGIN, splitAt, } from "./draft.js";
 import { element, isElement, markOf, plainText, walkElements } from "./hast.js";
 import { readHeadings } from "./headings.js";
@@ -200,7 +200,9 @@ export function rehypeDeck(options = {}) {
             else
                 flow.push(node);
         }
-        const groups = structureOf(options.structure, file, ORIGIN) === "headings"
+        const structure = structureOf(options.structure, file, ORIGIN);
+        checkStructure(file, structure, ORIGIN);
+        const groups = structure === "headings"
             ? readHeadings(flow, deckTitle, file)
             : groupBlocks(readSlides(flow, file), deckTitle);
         rejectNestedMarkers(groups.flatMap(group => group.slides), file);

package/dist/remark/index.js

@@ -17,7 +17,7 @@
  * and `::block` needs no `title`: the block has its heading.
  */
 import { MARK, MARK_BLOCK, MARK_BUILD, MARK_SLIDE, MARK_VERTICAL, NOTES } from "../shared/markers.js";
-import { NO_VERTICAL, structureOf } from "../shared/structure.js";
+import { NO_VERTICAL, recordStructure, structureOf } from "../shared/structure.js";
 const ORIGIN = "contour-deck:remark";
 const DIRECTIVES = {
     summary: {
@@ -127,6 +127,8 @@ export function remarkDeck(options = {}) {
     return (tree, file) => {
         if (options.match && !options.match(file))
             return;
-        visit(tree, file, structureOf(options.structure, file, ORIGIN));
+        const structure = structureOf(options.structure, file, ORIGIN);
+        recordStructure(file, structure);
+        visit(tree, file, structure);
     };
 }

package/dist/remote/presenter.js

@@ -24,6 +24,16 @@ const KEYS = {
     Escape: "overview",
     o: "overview",
 };
+/** The arrow keys reveal or hide the current page's steps before they move to another slide, as on the deck. */
+function arrowStep(key, state) {
+    if (!state || state.mode !== "stage")
+        return undefined;
+    if (key === "ArrowRight" && state.step < state.steps)
+        return "next";
+    if (key === "ArrowLeft" && state.step > 0)
+        return "prev";
+    return undefined;
+}
 export function presenterView(root, options = {}) {
     injectStyle(options.nonce);
     const labels = { ...defaultRemoteLabels, ...options.labels };
@@ -94,7 +104,7 @@ export function presenterView(root, options = {}) {
         const onButton = !!event.target.closest?.("button,a");
         if (onButton && (key === " " || key === "Enter"))
             return;
-        const command = key === " " && event.shiftKey ? "prev" : KEYS[key];
+        const command = key === " " && event.shiftKey ? "prev" : arrowStep(key, guest.state) ?? KEYS[key];
         if (!command)
             return;
         event.preventDefault();

package/dist/shared/structure.d.ts

@@ -21,3 +21,6 @@ export declare const NO_VERTICAL = "::vertical has no meaning with structure: \"
  * names is an error here, not a silent fallback to the default.
  */
 export declare function structureOf(option: StructureOption | undefined, file: DeckFile, origin: string): Structure;
+export declare function recordStructure(file: DeckFile, structure: Structure): void;
+/** Fails when `remarkDeck` read the file by another structure than `rehypeDeck` is about to. */
+export declare function checkStructure(file: DeckFile, structure: Structure, origin: string): void;

package/dist/shared/structure.js

@@ -20,3 +20,18 @@ export function structureOf(option, file, origin) {
         return value;
     return file.fail(`structure must be "slides" or "headings", got ${JSON.stringify(value)}`, undefined, origin);
 }
+/** Where `remarkDeck` leaves the structure it read a file by, for `rehypeDeck` to compare. */
+const RECORD = "contourDeckStructure";
+export function recordStructure(file, structure) {
+    file.data[RECORD] = structure;
+}
+/** Fails when `remarkDeck` read the file by another structure than `rehypeDeck` is about to. */
+export function checkStructure(file, structure, origin) {
+    const data = file.data;
+    const recorded = data[RECORD];
+    // Read once: a later pass on the same file without remarkDeck must not see a stale record.
+    delete data[RECORD];
+    if (recorded !== undefined && recorded !== structure) {
+        file.fail(`remarkDeck ran with structure "${String(recorded)}" and rehypeDeck with "${structure}": give both the same structure option`, undefined, origin);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contour-deck",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Outline-first slide decks on real DOM: blocks, slides, pages.",
   "keywords": [
     "slides",