@gramlot/gramlot-examples 0.3.4 → 0.3.5

package/README.md

@@ -12,7 +12,7 @@ npm install @gramlot/gramlot-examples
 [![PyPI](https://img.shields.io/pypi/v/gramlot-examples)](https://pypi.org/project/gramlot-examples/)
 [![npm](https://img.shields.io/npm/v/@gramlot/gramlot-examples)](https://www.npmjs.com/package/@gramlot/gramlot-examples)
 
-Current release: 0.3.4.
+Current release: 0.3.5.
 
 [Documentation and learning sequence](https://gramlot-examples.readthedocs.io/en/latest/)
 include every lesson, its Python and JavaScript source, and the gallery guide.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramlot/gramlot-examples",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Gramlot example pages, the gallery page and its catalogue.",
   "license": "Apache-2.0",
   "repository": {
@@ -14,7 +14,7 @@
     "prepack": "node scripts/build-browser.mjs"
   },
   "dependencies": {
-    "@gramlot/gramlot": ">=0.3.2"
+    "@gramlot/gramlot": ">=0.3.3"
   },
   "devDependencies": {
     "@genrojs/bag": ">=0.11.0",

package/src/gramlot_examples/gallery/dist/gallery.js

@@ -1920,7 +1920,9 @@
   // node_modules/@gramlot/gramlot/src/index-page-runtime.js
   function mountIndexPage(renderer, root, onSelection = () => {
   }, prepareEntry = () => {
-  }, { containerLayout = false, state: suppliedState = null } = {}) {
+  }, { containerLayout = false, state: suppliedState = null, createEntry = null, onLoad = () => {
+  } } = {}) {
+    if (createEntry && !containerLayout) throw new TypeError("Deferred index entries require containerLayout");
     const shell = renderer.records.get(root).element;
     const document2 = shell.ownerDocument;
     const window2 = document2.defaultView;
@@ -2028,17 +2030,53 @@
         set(shell, { data_code_visible: String(visible) });
       }
     };
+    const prepare = (entry) => {
+      entry.panel = byId(`panel-${entry.key}`);
+      entry.tab = containerLayout ? entry.panel : byId(`tab-${entry.key}`);
+      entry.code = byId(`codepane-${entry.key}`);
+      if (entry.key === "intro") return;
+      prepareEntry(entry, { byId, node, set, listen });
+      entry.frame = byId(`frame-${entry.key}`);
+      if (entry.frame) listen(entry.frame, "load", () => send(entry.frame));
+    };
+    const openEntry = (entry) => {
+      if (opened.getItem(entry.key)) return;
+      opened.setItem(entry.key, true);
+      set(containerLayout ? entry.panel : entry.tab, { hidden: false });
+      if (entry.frame) set(entry.frame, { src: entry.open.getAttribute("href") });
+    };
     let selecting = false;
     function select(key) {
-      if (selecting) return;
+      if (selecting || disposed) return;
+      const requested = entries2.get(key);
+      if (!requested) return;
+      state.setItem("requested", key);
+      if (!requested.panel) {
+        onLoad(key, "loading");
+        if (!requested.loading) {
+          requested.loading = Promise.resolve().then(() => {
+            if (!disposed) return createEntry(requested);
+          }).then(() => {
+            if (disposed) return;
+            prepare(requested);
+            openEntry(requested);
+            if (state.getItem("requested") === key) {
+              onLoad(key, "ready");
+              select(key);
+            }
+          }).catch((error) => {
+            if (!disposed && state.getItem("requested") === key) onLoad(key, "error", error);
+          }).finally(() => {
+            requested.loading = null;
+          });
+        }
+        return;
+      }
+      onLoad(key, "ready");
       selecting = true;
       try {
         const entry = entries2.get(key);
-        if (!opened.getItem(key)) {
-          opened.setItem(key, true);
-          set(containerLayout ? entry.panel : entry.tab, { hidden: false });
-          if (entry.frame) set(entry.frame, { src: entry.open.getAttribute("href") });
-        }
+        openEntry(entry);
         if (entry.family) set(entry.family, { open: true });
         for (const [current, item] of entries2) {
           const active = current === key;
@@ -2202,9 +2240,9 @@
         });
         listen(window2, "resize", () => setSidebarWidth(state.getItem("preferredSidebarWidth")));
       }
-      const choices = containerLayout ? byId("index-pages").children : shell.querySelectorAll(".index-tabs button");
+      const choices = createEntry ? [byId("panel-intro"), ...shell.querySelectorAll('.index-sidebar a[id^="open-"]')] : containerLayout ? byId("index-pages").children : shell.querySelectorAll(".index-tabs button");
       for (const tab of choices) {
-        const key = tab.id.slice(containerLayout ? "panel-".length : "tab-".length);
+        const key = tab.id.slice(createEntry && tab.id.startsWith("open-") ? "open-".length : containerLayout ? "panel-".length : "tab-".length);
         const entry = {
           key,
           tab,
@@ -2213,7 +2251,7 @@
           open: key === "intro" ? null : byId(`open-${key}`)
         };
         entries2.set(key, entry);
-        if (containerLayout ? node(tab).getAttr("hidden") !== true : !tab.hidden) opened.setItem(key, true);
+        if (entry.panel && (containerLayout ? node(entry.panel).getAttr("hidden") !== true : !tab.hidden)) opened.setItem(key, true);
         if (!containerLayout && tab.getAttribute("aria-selected") === "true") state.setItem("active", key);
         if (!containerLayout) listen(tab, "click", () => select(key));
         if (entry.open) listen(entry.open, "click", (event) => {
@@ -2231,12 +2269,15 @@
         });
         if (key === "intro") continue;
         entry.family = entry.open.closest("details");
-        prepareEntry(entry, { byId, node, set, listen });
-        if (entry.panel.classList.contains("index-category")) continue;
-        entry.frame = byId(`frame-${key}`);
-        listen(entry.frame, "load", () => send(entry.frame));
+        if (entry.panel) prepare(entry);
       }
       if (containerLayout) {
+        const pages = byId("index-pages");
+        listen(pages, "click", (event) => {
+          if (event.target === pages && event.composedPath().some((element) => element instanceof window2.Element && element.getAttribute("role") === "tab")) {
+            select(state.getItem("active"));
+          }
+        });
         const subscription = `${shell.id}-selection`;
         state.subscribe(subscription, { any: (event) => {
           if (event.node === state.getNode("active")) select(state.getItem("active"));
@@ -6842,16 +6883,17 @@ Please report this to https://github.com/markedjs/marked.`, e) {
   function mountGallery(renderer, root, inspector) {
     const state = root.builder.data.getItem("galleryIndex");
     const settings = mountGallerySettings(renderer, root, state);
-    const guide = mountGuidedDemo(renderer, root);
+    let guide = null;
     const mobile = mountGalleryMobile(renderer, root, inspector, state, (visible) => {
-      if (!visible) guide.pause();
+      if (!visible) guide?.pause();
     });
     const index = mountIndexPage(renderer, root, (entries2, active) => {
       inspector.update(entries2, active);
       mobile.update(entries2, active);
-      guide.update(entries2, active);
+      guide?.update(entries2, active);
     }, (entry, { byId, node, set, listen }) => {
       const { key } = entry;
+      if (key === "l04" && !guide) guide = mountGuidedDemo(renderer, root);
       renderReadme(byId(`readme-${key}`));
       if (entry.panel.classList.contains("index-category")) return;
       highlightCode(byId(`code-${key}`));
@@ -6862,9 +6904,47 @@ Please report this to https://github.com/markedjs/marked.`, e) {
         logic.textContent = source ?? "";
         if (source !== null) highlightCode(logic);
       }
-    }, { containerLayout: true, state });
+    }, {
+      containerLayout: true,
+      state,
+      async createEntry(entry) {
+        const document2 = renderer.destination.ownerDocument;
+        const node = (id) => renderer.elements.get(document2.getElementById(id)).node;
+        const source = (id) => root.builder.wrapSource(node(id));
+        const category = entry.open.classList.contains("index-family");
+        const pane = source("index-pages").contentPane({
+          id: `panel-${entry.key}`,
+          title: entry.open.textContent,
+          pageName: entry.key,
+          hidden: true,
+          class: category ? "index-category" : "gallery-panel"
+        });
+        const code = category ? null : source("gallery-code-pages").tabContainer({
+          id: `codepane-${entry.key}`,
+          class: "gallery-codepane gallery-source-tabs",
+          hidden: true,
+          height: "100%",
+          tabMode: "underline"
+        });
+        try {
+          const runtime = renderer.binding.gramlot;
+          const results = await Promise.all([
+            runtime.src.remoteSource(node(`panel-${entry.key}`), "lesson", { key: entry.key }),
+            ...code ? [runtime.src.remoteSource(node(`codepane-${entry.key}`), "lesson", { key: entry.key, view: "code" })] : []
+          ]);
+          if (results.some((mounted) => !mounted)) throw new Error("Lesson loading was cancelled");
+        } catch (error) {
+          for (const target of [pane, code]) if (target?.parentBag) target.parentBag.popNode(target.label);
+          throw error;
+        }
+      },
+      onLoad(key, status) {
+        const element = renderer.destination.ownerDocument.getElementById("gallery-load-status");
+        renderer.elements.get(element).node.setValue(status === "loading" ? "Loading lesson\u2026" : status === "error" ? "Could not load this lesson. Select it again to retry." : "");
+      }
+    });
     return { dispose() {
-      guide.dispose();
+      guide?.dispose();
       settings.dispose();
       index.dispose();
       mobile.dispose();

package/src/gramlot_examples/gallery/gallery-page.js

@@ -10,8 +10,8 @@ export class GalleryPage extends IndexPage {
     static galleryScript = '/gallery/dist/gallery.js';
     static css = [...IndexPage.css, '/gallery/gallery.css'];
     static get navigation() {
-        return this.families.map(group => ({...group,
-            children: group.examples.map(item => ({...item, url: item.frameUrl}))}));
+        return this.families.map(group => ({key: group.key, title: group.title,
+            children: group.examples.map(item => ({key: item.key, title: item.title, url: item.frameUrl}))}));
     }
     main(root) {
         const families = this.constructor.navigation;
@@ -38,17 +38,10 @@ export class GalleryPage extends IndexPage {
         const panels = center.tabContainer({id: 'index-pages', class: 'index-main', height: '100%',
             selectedPage: '^galleryIndex.active', tabMode: 'tabs'});
         this.introduction(panels.contentPane({id: 'panel-intro', title: 'Introduction', pageName: 'intro', class: 'index-intro'}));
-        for (const family of families) {
-            this.groupPanel(panels.contentPane({id: `panel-${family.key}`, title: family.title,
-                pageName: family.key, class: 'index-category', hidden: true}), family);
-            for (const example of family.children) this.panel(panels, example);
-        }
         const code = regions.contentPane({region: 'right', width: '420px', minSize: 220, maxSize: 900,
             splitter: true, drawer: true, drawer_icon: '⌘', drawer_label: 'Code', drawer_minimize: true,
             node_id: 'galleryCode', id: 'index-code', aria_label: 'Example source code', hidden: true});
-        for (const family of families) {
-            for (const example of family.children) this.codePanel(code, example);
-        }
+        code.div({id: 'gallery-code-pages', height: '100%'});
         this.footer(shell.footer({class: 'index-footer'}));
         this.behavior(shell);
     }
@@ -84,6 +77,7 @@ export class GalleryPage extends IndexPage {
         header.html_button('☰', {type: 'button', id: 'gallery-mobile-menu', class: 'gallery-mobile-only',
             aria_label: 'Navigation', aria_controls: 'index-sidebar', aria_expanded: 'false'});
         header.h1(this.constructor.title);
+        header.span('', {id: 'gallery-load-status', role: 'status', aria_live: 'polite'});
         header.html_button('Code ⟨/⟩', {type: 'button', id: 'index-code-toggle',
             aria_controls: 'index-code', aria_expanded: 'false', disabled: true});
         const views = header.div({class: 'gallery-mobile-views gallery-mobile-only', role: 'group', aria_label: 'Gallery view'});
@@ -98,10 +92,24 @@ export class GalleryPage extends IndexPage {
         shell.script({src: this.constructor.galleryScript});
     }
 
+    galleryItem(key) {
+        for (const family of this.constructor.families) {
+            if (family.key === key) return family;
+            for (const example of family.examples) if (example.key === key) return example;
+        }
+        throw new Error(`Unknown gallery entry: ${key}`);
+    }
+    lesson(root, {key, view = 'example'}) {
+        const item = this.galleryItem(key);
+        if (view === 'code' && !item.examples) this.codePanel(root, item);
+        else if (view === 'example') {
+            if (item.examples) this.groupPanel(root, item);
+            else this.panel(root, item);
+        } else throw new Error(`Unknown gallery view: ${key}/${view}`);
+    }
     panel(parent, example) {
         const key = example.key;
-        const panel = parent.contentPane({id: `panel-${key}`, title: example.title, pageName: key,
-            class: 'gallery-panel', hidden: true}).div({class: 'gallery-panel-layout'});
+        const panel = parent.div({class: 'gallery-panel-layout'});
         const header = panel.header({class: 'gallery-explanation'});
         header.h2(example.title);
         header.p('In this example: ' + example.description);
@@ -121,8 +129,7 @@ export class GalleryPage extends IndexPage {
     }
     codePanel(parent, example) {
         const key = example.key;
-        const codepane = parent.tabContainer({class: 'gallery-codepane gallery-source-tabs', id: `codepane-${key}`,
-            hidden: true, height: '100%', tabMode: 'underline'});
+        const codepane = parent;
         codepane.contentPane({title: 'JavaScript', pageName: 'javascript', id: `code-panel-${key}`})
             .pre({tabindex: 0}).code(example.source, {class: 'language-javascript', id: `code-${key}`});
         if (example.logic != null) {
@@ -131,3 +138,5 @@ export class GalleryPage extends IndexPage {
         }
     }
 }
+
+GalleryPage.registerSource('lesson');

package/src/gramlot_examples/gallery/page.js

@@ -14,14 +14,14 @@ export class Page extends GalleryPage {
         return families.map(({key, title, path, examples}) => {
             const read = name => readFileSync(join(path, name), 'utf8');
             return {
-                key, title, readme: read('README.md'),
+                key, title, get readme() { return read('README.md'); },
                 examples: examples.map(example => ({
                     key: example.key, title: example.title, description: example.description, folder: example.folder, frameUrl: example.key,
-                    readme: read(`${example.folder}.md`),
-                    source: read(`${example.folder}.js`),
+                    get readme() { return read(`${example.folder}.md`); },
+                    get source() { return read(`${example.folder}.js`); },
                     // The page module shows its own Logic; only a companion NN_name_aux.js is shown apart.
-                    logic: routes[example.key].logic === routes[example.key].page
-                        ? null : readFileSync(routes[example.key].logic, 'utf8'),
+                    get logic() { return routes[example.key].logic === routes[example.key].page
+                        ? null : readFileSync(routes[example.key].logic, 'utf8'); },
                 })),
             };
         });