contour-deck 0.3.0 → 0.3.1

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).
 
 ## 看看它怎麼動

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/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.1",
   "description": "Outline-first slide decks on real DOM: blocks, slides, pages.",
   "keywords": [
     "slides",