@gramlot/gramlot-examples 0.3.4 → 0.3.6

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.6.
 
 [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.6",
   "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"));
@@ -6838,33 +6879,160 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     element.innerHTML = purifier.sanitize(markdown.parse(element.textContent), { USE_PROFILES: { html: true } });
   }
 
+  // src/gramlot_examples/gallery/browser/gallery-content.js
+  var pending = /* @__PURE__ */ new WeakMap();
+  function mountGalleryContent(renderer, root) {
+    const document2 = renderer.destination.ownerDocument;
+    const byId = (id) => document2.getElementById(id);
+    const node = (element) => renderer.elements.get(element).node;
+    const entries2 = /* @__PURE__ */ new Map();
+    let disposed = false;
+    function format({ key, view }) {
+      if (view === "description") {
+        const readme = byId(`readme-${key}`);
+        readme.textContent = node(readme).value;
+        renderReadme(readme);
+        return;
+      }
+      const code = byId(`code-${key}`);
+      code.textContent = node(code).value;
+      highlightCode(code);
+      const logic = byId(`logic-${key}`);
+      if (logic) {
+        const source = logicSource(node(logic).value);
+        node(byId(`logic-panel-${key}`)).setAttr({ hidden: source === null });
+        logic.textContent = source ?? "";
+        if (source !== null) highlightCode(logic);
+      }
+    }
+    async function load(entry) {
+      if (entry.loading) return;
+      entry.loading = true;
+      const targetId = entry.view === "code" ? `code-tabs-${entry.key}` : entry.element.id;
+      const target = node(byId(targetId));
+      const current = () => {
+        const element = byId(targetId);
+        return element && renderer.elements.get(element)?.node === target ? element : null;
+      };
+      let request = pending.get(target);
+      if (!request) {
+        request = renderer.binding.gramlot.src.remoteSource(target, "lesson", { key: entry.key, view: entry.view });
+        pending.set(target, request);
+      }
+      try {
+        const mounted = await request;
+        if (disposed || !current() || !mounted) return;
+        format(entry);
+        observer.unobserve(entry.element);
+        entries2.delete(entry.element);
+      } catch {
+        if (disposed || !current()) return;
+        const status = current().querySelector('[role="status"]');
+        node(status).setValue("Could not load this content. Close and reopen the panel to retry.");
+      } finally {
+        if (pending.get(target) === request) pending.delete(target);
+        entry.loading = false;
+      }
+    }
+    const observer = new document2.defaultView.IntersectionObserver((records) => {
+      for (const record of records) {
+        const entry = entries2.get(record.target);
+        if (!entry) continue;
+        const visible = record.isIntersecting && record.intersectionRect.width > 0 && record.intersectionRect.height > 0;
+        if (visible && !entry.visible) void load(entry);
+        entry.visible = visible;
+      }
+    });
+    const dispose = () => {
+      disposed = true;
+      observer.disconnect();
+      entries2.clear();
+    };
+    renderer.onDispose(root, dispose);
+    return {
+      observe(key) {
+        for (const [view, id, loaded] of [
+          ["code", `codepane-${key}`, `code-${key}`],
+          ["description", `description-${key}`, `readme-${key}`]
+        ]) {
+          const element = byId(id);
+          const entry = { key, view, element, visible: false, loading: false };
+          if (byId(loaded)) format(entry);
+          else if (!entries2.has(element)) {
+            entries2.set(element, entry);
+            observer.observe(element);
+          }
+        }
+      },
+      dispose
+    };
+  }
+
   // src/gramlot_examples/gallery/browser/gallery.js
   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 content = mountGalleryContent(renderer, root);
     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);
-    }, (entry, { byId, node, set, listen }) => {
+      guide?.update(entries2, active);
+    }, (entry, { byId }) => {
       const { key } = entry;
-      renderReadme(byId(`readme-${key}`));
-      if (entry.panel.classList.contains("index-category")) return;
-      highlightCode(byId(`code-${key}`));
-      const logic = byId(`logic-${key}`);
-      if (logic) {
-        const source = logicSource(node(logic).value);
-        set(byId(`logic-panel-${key}`), { hidden: source === null });
-        logic.textContent = source ?? "";
-        if (source !== null) highlightCode(logic);
+      if (key === "l04" && !guide) guide = mountGuidedDemo(renderer, root);
+      if (entry.panel.classList.contains("index-category")) {
+        renderReadme(byId(`readme-${key}`));
+        return;
       }
-    }, { containerLayout: true, state });
+      content.observe(entry.key);
+    }, {
+      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").div({
+          id: `codepane-${entry.key}`,
+          class: "gallery-codepane",
+          hidden: true,
+          height: "100%"
+        });
+        if (code) code.tabContainer({
+          id: `code-tabs-${entry.key}`,
+          class: "gallery-source-tabs",
+          height: "100%",
+          tabMode: "underline"
+        }).contentPane({ title: "Code" }).p("Loading code\u2026", { role: "status" });
+        try {
+          const runtime = renderer.binding.gramlot;
+          const mounted = await runtime.src.remoteSource(node(`panel-${entry.key}`), "lesson", { key: entry.key });
+          if (!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();
+      content.dispose();
       settings.dispose();
       index.dispose();
       mobile.dispose();
@@ -7470,11 +7638,11 @@ Please report this to https://github.com/markedjs/marked.`, e) {
         this.error = error.message;
       }
       if (message.type === "result") {
-        const pending = this.#pending.get(message.id);
-        if (pending) {
+        const pending2 = this.#pending.get(message.id);
+        if (pending2) {
           this.#pending.delete(message.id);
-          if (message.ok && !this.error) pending.resolve(message);
-          else pending.reject(new Error(message.error || this.error));
+          if (message.ok && !this.error) pending2.resolve(message);
+          else pending2.reject(new Error(message.error || this.error));
         }
       }
       this.#notify();
@@ -7531,7 +7699,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       this.#port.removeEventListener("message", this.#receive);
       this.#port.close();
       this.state = "disposed";
-      for (const pending of this.#pending.values()) pending.reject(new Error("Inspected page disconnected"));
+      for (const pending2 of this.#pending.values()) pending2.reject(new Error("Inspected page disconnected"));
       this.#pending.clear();
       this.#notify();
     }
@@ -7610,9 +7778,9 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     _subscribe() {
       if (this._store) this._store.subscribe(this._subId, { any: () => {
         if (this._pendingRender) return;
-        const pending = this._pendingRender = {};
+        const pending2 = this._pendingRender = {};
         queueMicrotask(() => {
-          if (this._pendingRender === pending && this.isConnected) this._render();
+          if (this._pendingRender === pending2 && this.isConnected) this._render();
         });
       } });
     }

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,25 @@ 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 === 'description' && !item.examples) root.div(item.readme, {id: `readme-${key}`});
+        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);
@@ -116,13 +125,12 @@ export class GalleryPage extends IndexPage {
             guidedDemo(layout);
         }
         stage.iframe({title: `${example.title} preview`, name: `example-${key}`, id: `frame-${key}`});
-        preview.contentPane({title: 'Explanation', pageName: 'explanation', class: 'gallery-lesson', overflow: 'auto'})
-            .div(example.readme, {id: `readme-${key}`});
+        preview.contentPane({title: 'Explanation', pageName: 'explanation', class: 'gallery-lesson', overflow: 'auto', id: `description-${key}`})
+            .p('Loading explanation…', {role: 'status'});
     }
     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 +139,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'); },
                 })),
             };
         });