@gramlot/gramlot-examples 0.3.5 → 0.3.7

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.5.
+Current release: 0.3.7.
 
 [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.5",
+  "version": "0.3.7",
   "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.3"
+    "@gramlot/gramlot": ">=0.3.4"
   },
   "devDependencies": {
     "@genrojs/bag": ">=0.11.0",

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

@@ -6879,11 +6879,101 @@ 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);
     let guide = null;
+    const content = mountGalleryContent(renderer, root);
     const mobile = mountGalleryMobile(renderer, root, inspector, state, (visible) => {
       if (!visible) guide?.pause();
     });
@@ -6891,19 +6981,14 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       inspector.update(entries2, active);
       mobile.update(entries2, active);
       guide?.update(entries2, active);
-    }, (entry, { byId, node, set, listen }) => {
+    }, (entry, { byId }) => {
       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}`));
-      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 (entry.panel.classList.contains("index-category")) {
+        renderReadme(byId(`readme-${key}`));
+        return;
       }
+      content.observe(entry.key);
     }, {
       containerLayout: true,
       state,
@@ -6919,20 +7004,22 @@ Please report this to https://github.com/markedjs/marked.`, e) {
           hidden: true,
           class: category ? "index-category" : "gallery-panel"
         });
-        const code = category ? null : source("gallery-code-pages").tabContainer({
+        const code = category ? null : source("gallery-code-pages").div({
           id: `codepane-${entry.key}`,
-          class: "gallery-codepane gallery-source-tabs",
+          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 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");
+          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;
@@ -6945,6 +7032,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     });
     return { dispose() {
       guide?.dispose();
+      content.dispose();
       settings.dispose();
       index.dispose();
       mobile.dispose();
@@ -7550,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();
@@ -7611,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();
     }
@@ -7690,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/dist/layout.js

@@ -253,7 +253,7 @@ var SIDES = ["top", "bottom", "left", "right"];
 var REGIONS = [...SIDES, "center"];
 var borderRegions = /* @__PURE__ */ new WeakMap();
 var horizontal = (side) => side === "top" || side === "bottom";
-function projectBorderChild(element, attrs, { adapt, invoke, publish, publishParent }) {
+function projectBorderChild(element, attrs, { adapt, invoke, publish, publishParent, writeParameter }) {
   const rest = { ...attrs }, splitter = {}, drawer = {};
   for (const [name, value] of Object.entries(rest)) {
     for (const [prefix, group] of [["splitter_", splitter], ["drawer_", drawer]]) {
@@ -272,7 +272,15 @@ function projectBorderChild(element, attrs, { adapt, invoke, publish, publishPar
   if (![void 0, null, false, true, "close"].includes(rest.drawer)) throw new TypeError("drawer must be true, false or close");
   const probe = element.ownerDocument.createElement("div");
   probe.style.cssText = rest.style ?? "";
-  const size = probe.style[horizontal(region) ? "height" : "width"];
+  const dimension = horizontal(region) ? "height" : "width";
+  const numeric = typeof rest[dimension] === "number";
+  if (numeric) {
+    if (!Number.isFinite(rest[dimension]) || rest[dimension] < 0) throw new TypeError("Border numeric dimensions must be finite nonnegative pixels");
+    probe.style[dimension] = `${rest[dimension]}px`;
+  }
+  const size = probe.style[dimension];
+  delete rest.width;
+  delete rest.height;
   probe.style.width = "100%";
   probe.style.height = "100%";
   rest.style = probe.style.cssText;
@@ -297,6 +305,9 @@ function projectBorderChild(element, attrs, { adapt, invoke, publish, publishPar
     label,
     icon,
     minimize,
+    writeParameter: (size2) => {
+      if (numeric) writeParameter(dimension, size2);
+    },
     notifications: {
       closableChange: (payload) => publish("closable_change", payload),
       splitterResize: (payload) => publishParent("splitter_resize", payload)
@@ -334,7 +345,7 @@ var BorderContainer = defineComponent({
   tag: "gramlot-border-container",
   base: Container,
   subTags: "*",
-  childParameters: { region: { required: true, enum: REGIONS, unique: true }, drawer_onclick: { inline: ["evt", "show"] } },
+  childParameters: { region: { required: true, enum: REGIONS, unique: true }, width: {}, height: {}, drawer_onclick: { inline: ["evt", "show"] } },
   parameters: {
     design: { dtype: "T", default: "headline", binding: "read", enum: ["headline", "sidebar"] },
     persist: { dtype: "B", default: false, binding: "read" }
@@ -636,6 +647,7 @@ var BorderContainer = defineComponent({
       const size = Math.max(Math.min(c.min, available), Math.min(desired, c.max, available));
       state.size = `${size}px`;
       this.#render(side);
+      c.writeParameter(size);
     }
     #keyResize(side, evt) {
       const state = this.#regions.get(side);

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

@@ -102,6 +102,7 @@ export class GalleryPage extends IndexPage {
     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);
@@ -124,8 +125,8 @@ 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;

package/src/gramlot_examples/pages/layout/05_nested_lab.js

@@ -82,7 +82,7 @@ export class Page extends BasePage {
         });
         const header = outer.contentPane({
             region: 'top',
-            height: '^regions.outer.top:{}px',
+            height: '^regions.outer.top',
             minSize: 40,
             maxSize: 110,
             drawer_label: 'Header',
@@ -94,7 +94,7 @@ export class Page extends BasePage {
         header.span('^customer');
         const footer = outer.contentPane({
             region: 'bottom',
-            height: '^regions.outer.bottom:{}px',
+            height: '^regions.outer.bottom',
             minSize: 35,
             maxSize: 130,
             drawer_label: 'Status',
@@ -107,7 +107,7 @@ export class Page extends BasePage {
         const nav = outer.borderContainer({
             id: 'lab-navigation',
             region: 'left',
-            width: '^regions.outer.left:{}px',
+            width: '^regions.outer.left',
             minSize: 90,
             maxSize: 240,
             drawer_label: 'Navigation',
@@ -129,7 +129,7 @@ export class Page extends BasePage {
         const details = outer.borderContainer({
             id: 'lab-details',
             region: 'right',
-            width: '^regions.outer.right:{}px',
+            width: '^regions.outer.right',
             minSize: 90,
             maxSize: 240,
             drawer_label: 'Details',
@@ -159,7 +159,7 @@ export class Page extends BasePage {
         });
         const tools = work.contentPane({
             region: 'left',
-            width: '^regions.workspace.left:{}px',
+            width: '^regions.workspace.left',
             minSize: 70,
             maxSize: 200,
             drawer_label: 'Tools',
@@ -172,7 +172,7 @@ export class Page extends BasePage {
         tools.checkbox({ value: '^readonly', lbl: 'Editor', label: 'Read only' });
         const preview = work.contentPane({
             region: 'bottom',
-            height: '^regions.workspace.bottom:{}px',
+            height: '^regions.workspace.bottom',
             minSize: 50,
             maxSize: 180,
             drawer_label: 'Preview',
@@ -213,7 +213,7 @@ export class Page extends BasePage {
         fields.numberTextBox({ id: 'lab-quantity', value: '^quantity', lbl: 'Quantity', width: '100%' });
         const notes = editor.contentPane({
             region: 'bottom',
-            height: '^regions.editor.bottom:{}px',
+            height: '^regions.editor.bottom',
             minSize: 60,
             maxSize: 180,
             drawer_label: 'Notes',

package/src/gramlot_examples/pages/layout/05_nested_lab.md

@@ -8,6 +8,8 @@ If the page looks complicated at first, start with just one slider. You do not n
 
 Move one region-size slider a little, then back again. Follow the boundary that moves. Does it belong to the outer workspace, or to a layout inside it? Repeat with a slider for a different level.
 
+Next, drag the same separator. Its slider moves immediately: both controls update the same number. Open the Inspector on Data to follow `regions.outer.left` while moving either the Navigation width slider or its separator. Try a nested region too.
+
 Now enter a customer name and a note. Change a date or delivery option too. Look for the places where those values are repeated. They are views of shared Data, not separate copies of the customer.
 
 Move the sliders again. The regions become wider, narrower, taller or shorter while your edits remain. Close one drawer, rearrange another area, and reopen it. Hiding a panel has not discarded its contents.
@@ -16,7 +18,15 @@ Finally, try the design and corner-radius controls. These change presentation wh
 
 ## How a number becomes a size
 
-A slider produces a number. A region width needs a size such as 180px. The example connects them with a pointer template: it reads the slider's Data value and adds the unit. You can find these declarations by looking for the region-size paths in **Code**.
+The slider and the region both use a plain pointer to the same number. Numeric region widths and heights are pixels; the borderContainer converts them to CSS internally. Dragging the splitter writes back the constrained number through the binding, so the slider follows immediately.
+
+```python
+sliders.horizontalSlider(value="^regions.outer.left", min=90, max=240, live=True)
+nav = outer.borderContainer(region="left", width="^regions.outer.left",
+                            splitter=True, minSize=90, maxSize=240)
+```
+
+There is no formatting suffix or synchronization controller. `regions` is just the Data branch chosen by this example; it is not a special container parameter. You can find all seven shared size bindings in **Code**.
 
 The nested containers still have a simple responsibility: each lays out its own immediate children. The outer container does not calculate the positions of every field inside the editor.