@gramlot/gramlot-examples 0.2.12 → 0.2.15

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

@@ -25,11 +25,8 @@ export class GalleryPage extends IndexPage {
     footer(footer) {
         super.footer(footer);
         const inspector = footer.button({type: 'button', id: 'gallery-inspector', class: 'gallery-inspector',
-            title: 'Inspect the gallery or the visible example', aria_label: 'Inspector', aria_pressed: 'false', disabled: true});
-        const icon = inspector.svg({viewBox: '0 0 24 24', width: '18', height: '18', aria_hidden: 'true'});
-        icon.rect({x: '3', y: '3', width: '18', height: '18', rx: '2', fill: 'none', stroke: 'currentColor', stroke_width: '1.5'});
-        icon.path({d: 'M9 3v18M12 8h6M12 12h6M12 16h4', fill: 'none', stroke: 'currentColor', stroke_width: '1.5'});
-        inspector.span('Inspector');
+            title: 'Open inspector', aria_label: 'Inspector', aria_pressed: 'false', disabled: true});
+        inspector.span('🔍', {aria_hidden: 'true'});
 
     }
     behavior(shell) { shell.script({src: this.constructor.galleryScript}); }

package/src/gramlot_examples/gallery/gallery.css

@@ -33,6 +33,7 @@
 .gallery-source-tabs button:focus-visible { outline: 2px solid var(--gramlot-focus-ring); outline-offset: -2px; }
 .gallery-source-tabs button[hidden] { display: none; }
   .gallery-explanation { padding: .4rem; }
-.gallery-inspector { display: inline-flex; align-items: center; gap: .35rem; margin-inline-start: auto; padding: .15rem .5rem; min-block-size: 26px; font-size: inherit; }
-.gallery-inspector svg { flex: none; }
+.gallery-inspector { display: inline-flex; align-items: center; justify-content: center; flex: none; margin-inline-start: auto; padding: 0; inline-size: 28px; block-size: 28px; min-block-size: 28px; border: 0; background: transparent; box-shadow: none; font-size: 16px; line-height: 1; }
+.gallery-inspector:hover { background: var(--gramlot-surface); }
+.gallery-inspector:focus-visible { outline: 2px solid var(--gramlot-focus-ring); outline-offset: 2px; }
 .gallery-inspector[aria-pressed="true"] { background: var(--gramlot-action); color: var(--gramlot-navigation-text); }

package/src/gramlot_examples/pages/README.md

@@ -93,8 +93,9 @@ from [the gallery guide](https://github.com/gramlot-org/gramlot-examples/blob/ma
 c13/c14 separate the basic trial from advanced cache/error/lifetime exercises.
 In c13, “Mounted fragments” counts successful mounts; HTTP calls must be observed
 independently. c14 has an explicit read button to distinguish a stored snapshot
-from a later response. Neither page claims every environment has been qualified. The corrected cache behavior documented in
-the development core is not automatically present in published packages.
+from a later response. The corrected cache behavior is included from core 0.2.17. Update older
+installations before following the advanced trials; a startup check alone does
+not qualify every exercise in an environment.
 
 The common FileServer gallery has no named resource groups: css_requires,
 js_requires and named connect_on handlers need genro-kajenn's resource host.

package/src/gramlot_examples/pages/controllers/13_cached_remote.md

@@ -48,7 +48,7 @@ The corrected identity is the method name plus the **TYTX snapshot of parameters
 
 ## Advanced practice
 
-**Development distinction:** the corrected cache identity is locally implemented in the core stabilization work; it is not a new published release. Check the runtime you are using before interpreting these advanced trials. Installed released packages may retain the earlier defects.
+**Release history:** core 0.2.17 includes the corrected cache identity and cancellation behavior. Update an older runtime before trying these advanced cases.
 
 Run these separately after the basic trial, using that core cache correction. Reload between source edits so each trial has a known starting state.
 

package/src/gramlot_examples/pages/controllers/18_publish_subscribe.js

@@ -0,0 +1,36 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Publish and subscribe';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class: 'example-page stack', datapath: 'messages'});
+        pane.h1('The same action, two entry points');
+        pane.p('Compare the direct controller with a page topic. Both update the same summary.');
+        pane.dataSetter({destination_path: '.text', value: 'Hello'});
+        pane.html_label('Message', {for: 'message'});
+        pane.input({id: 'message', value: '^.text', live: true});
+        pane.button('Direct controller', {id: 'direct'}).dataController({func: 'save', text: '=.text'});
+        pane.button('Publish', {id: 'publish'}).dataController({func: 'publishMessage', text: '=.text'});
+        pane.dataController({func: 'save', subscribe_saved: true});
+        pane.p('^.summary', {id: 'summary'});
+        pane.button('Ask, then publish', {id: 'ask'}).dataController({func: 'publishMessage',
+            _ask: {title: 'Message', fields: [{name: 'text', lbl: 'Message', required: true}]}, text: '=.text'});
+        pane.h2('Two independent receivers');
+        for (const name of ['left', 'right']) {
+            const box = pane.section({class: 'card stack', datapath: `.${name}`});
+            box.h3(name[0].toUpperCase() + name.slice(1));
+            const target = box.dataController({func: 'receive', selfsubscribe_refresh: true});
+            box.button(`Send to ${name}`, {id: `send-${name}`}).dataController({func: 'sendToNode', target, text: '=.text'});
+            box.p('^.received', {id: `received-${name}`});
+            box.dataSetter({destination_path: '.text', value: `Hello ${name}`});
+        }
+    }
+}
+
+export class Logic {
+    save(node, {text, _reason}) { node.SET('.summary', `${text} (${_reason})`); }
+    publishMessage(node, {text}) { this.page.publish('saved', {text}); }
+    sendToNode(node, {target, text}) { target.publish('refresh', {text}); }
+    receive(node, {text}) { node.SET('.received', text); }
+}

package/src/gramlot_examples/pages/controllers/18_publish_subscribe.md

@@ -0,0 +1,20 @@
+# 18 · Publish and subscribe
+
+Revisit **Button controller**: one button calls a controller directly, another publishes a message to the same behavior. Then address two independent receivers without looking up their IDs, and collect a message in a dialog.
+
+**Uses:** Source, Data, named Logic, page/self subscriptions, authored references and native `ask` — core 0.2.18. No endpoint calls. Earlier lessons remain the 0.2.0 stage.
+
+**Try it:** edit Message, press Direct controller, then Publish. The summary is the same except for the trigger reason. Send to left: only the left receiver changes. Ask, then publish lets you edit the outgoing message; Cancel leaves the summary unchanged.
+
+<details>
+<summary>More detail</summary>
+
+The direct controller keeps the c06 click mechanism. The publishing controller knows the topic `saved`; `subscribe_saved=True` connects the receiver. The publisher does not need a Data trigger path to activate that receiver. Repeating the same message still delivers it.
+
+Each receiver declares `selfsubscribe_refresh=True`. Python passes that controller as `target`; Gramlot resolves the authored reference in the browser. `target.publish('refresh', {text})` addresses only that node. The JavaScript Page makes the same declaration, and both use the shared Logic class.
+
+`_ask` adds native field collection to the existing controller. It runs the controller once after confirmation and never after cancellation. This example uses named methods throughout; it does not need inline JavaScript evaluation. For a conditional confirmation use a string `_ask` with `_ask_if`; those inline conditions need the corresponding CSP policy.
+
+**Exercise:** subscribe a second controller to `saved`, writing another Data path. Predict whether both run when Publish is pressed. **Answer:** both run, in registration order; each should write its own result. A self-subscription does not also subscribe to the plain page topic.
+
+</details>

package/src/gramlot_examples/pages/controllers/19_frame_messages.js

@@ -0,0 +1,39 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Parent and child messages';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class: 'example-page stack', datapath: 'frames'});
+        pane.h1('Parent and child messages');
+        pane.dataSetter({destination_path: '.child', value: false});
+        pane.dataSetter({destination_path: '.text', value: 'Hello'});
+        pane.html_label('Message', {for: 'message'});
+        pane.input({id: 'message', value: '^.text', live: true});
+        const parent = pane.section({hidden: '^.child'});
+        const frame = parent.iframe({id: 'detail', title: 'Child page', style: 'width:100%;height:260px;border:1px solid #aab4c2'});
+        parent.button('Send to child', {id: 'send-child'}).dataController({func: 'sendChild', target: frame, text: '=.text'});
+        pane.button('Reply to parent', {id: 'reply'}).dataController({func: 'reply', text: '=.text', child: '=.child'});
+        pane.p('^.received', {id: 'received'});
+        pane.dataController({func: 'receive', subscribe_message: true});
+        pane.dataController({func: 'setup', frame, _onStart: true});
+    }
+}
+
+export class Logic {
+    setup(node, {frame}) {
+        const url = new URL(this.page.dom.getDomNode(node.parentNode).ownerDocument.location.href);
+        const child = url.hash === '#child';
+        node.SET('.child', child);
+        if (!child) { url.hash = 'child'; frame.setAttr({src: url.href}); }
+    }
+    sendChild(node, {target, text}) {
+        try { this.page.publish({topic: 'message', iframe: target}, {text}); }
+        catch (error) { node.SET('.received', error.message); }
+    }
+    reply(node, {text, child}) {
+        if (child) this.page.publish({topic: 'message', parent: true}, {text});
+        else node.SET('.received', 'Use Reply inside the child page.');
+    }
+    receive(node, {text}) { node.SET('.received', text); }
+}

package/src/gramlot_examples/pages/controllers/19_frame_messages.md

@@ -0,0 +1,20 @@
+# 19 · Parent and child messages
+
+Send a message to the embedded page, then reply from that page. The example reuses the page-topic receiver from **Publish and subscribe** and adds a destination to `publish`.
+
+**Uses:** Source, Data, named Logic, authored iframe references and direct parent/child `postMessage` — core 0.2.18. No endpoint calls or server messaging.
+
+**Try it:** wait for the child field to appear, edit the outer Message and press Send to child. Both summaries change: publication is local first, then reaches the selected child. Edit the child's Message and press its Reply to parent. The child publishes locally first and the parent receives the reply.
+
+<details>
+<summary>More detail</summary>
+
+The same page opens with `#child` inside the iframe. Its setup controller hides the parent section and does not load another iframe, so nesting stops after one child. The URL hash is only this example's mode selector; it is not a messaging address.
+
+Python passes the iframe Source as `target`. Logic uses `{topic: 'message', iframe: target}`. The child uses `{topic: 'message', parent: true}`. All cross-frame calls use postMessage, including same-origin pages; each receiving page activates its ordinary subscribe_message controller.
+
+The child must be connected and ready. An early click reports the readiness error; retry after the child appears. There is no automatic queue or broadcast. Source/DOM objects stay local: the iframe reference selects a local destination, while only the message data crosses the connection. Reloading the child establishes a new connection.
+
+**Exercise:** add another owned child and send only to its reference. **Answer:** local delivery still occurs, but only the selected child receives the remote copy. There is no recursive broadcast in this release.
+
+</details>

package/src/gramlot_examples/pages/controllers/20_actions_ask_references.js

@@ -0,0 +1,40 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Actions, confirmations and references';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class: 'example-page stack', datapath: 'buttons'});
+        pane.h1('One action, with or without a question');
+        pane.dataSetter({destination_path: '.name', value: 'Ada'});
+        pane.dataSetter({destination_path: '.confirm', value: true});
+        pane.dataSetter({destination_path: '.result', value: 'No action yet'});
+        pane.html_label('Ask before running', {for: 'confirm-needed'});
+        pane.input({id: 'confirm-needed', type: 'checkbox', value: '^.confirm'});
+        pane.button('Run action', {id: 'action', name: '=.name', action: "this.SET('.result', 'Hello ' + name)"});
+        pane.button('Ask for a name', {id: 'action-ask', name: '=.name', action: "this.SET('.result', 'Hello ' + name)",
+            ask: {title: 'Greeting', fields: [{name: 'name', lbl: 'Name', required: true}]}});
+        pane.button('Conditional action', {id: 'conditional-action', name: '=.name', confirm_needed: '=.confirm',
+            action: "this.SET('.result', 'Hello ' + name)", ask: 'Send this greeting?', _ask_if: 'confirm_needed'});
+        pane.button('Conditional controller', {id: 'conditional-controller'}).dataController({func: 'greet', name: '=.name',
+            confirm_needed: '=.confirm', _ask: 'Send this greeting?', _ask_if: 'confirm_needed'});
+        pane.button('Conditional fields', {id: 'conditional-fields', name: '=.name', confirm_needed: '=.confirm',
+            action: "this.SET('.result', 'Hello ' + name)",
+            ask: {title: 'Greeting', _if: 'confirm_needed', fields: [{name: 'name', lbl: 'Name'}]}});
+        pane.button('Legacy askIf', {id: 'legacy-askif', name: '=.name', action: "this.SET('.result', 'Hello ' + name)",
+            ask: {msg: 'askIf=false alone still asks in legacy semantics.', askIf: 'false'}});
+        pane.p('^.result', {id: 'result'});
+        pane.h2('Pass the element, without looking up an ID');
+        const target = pane.p('Original text', {id: 'reference-target'});
+        pane.button('Use Source reference', {id: 'source-reference'}).dataController({func: 'changeSource', target});
+        pane.button('Read DOM reference', {id: 'dom-reference'}).dataController({func: 'describeDom',
+            target: target.builder.reference(target, 'dom')});
+        pane.p('^.reference', {id: 'reference-result'});
+    }
+}
+
+export class Logic {
+    greet(node, {name}) { node.SET('.result', `Hello ${name}`); }
+    changeSource(node, {target}) { target.setValue('Changed through Source'); }
+    describeDom(node, {target}) { node.SET('.reference', `DOM element: ${target.tagName}`); }
+}

package/src/gramlot_examples/pages/controllers/20_actions_ask_references.md

@@ -0,0 +1,20 @@
+# 20 · Actions, confirmations and references
+
+The same greeting runs immediately, after a question, or after collecting a name. Switch **Ask before running** off and on to see when the question appears. Then pass a paragraph to a controller as a Source reference or as a DOM reference.
+
+**Uses:** Source, Data, buttons, inline actions, named controllers, native ask and local references — core 0.2.18. No endpoints or cross-frame references. This revisits the earlier button lesson with the 0.2.18 additions.
+
+**Try it:** choose **Ask for a name**, enter Grace and confirm. The result becomes Hello Grace; Cancel keeps the old result. Turn the checkbox off: both conditional buttons run immediately. Turn it on: they wait for confirmation. **Conditional fields** applies the same choice to a dialog with a field.
+
+<details>
+<summary>More detail</summary>
+
+`action` is a small JavaScript expression on the button. `ask` belongs to that action; `_ask` belongs to its nested controller. The string forms use `_ask_if`. The dictionary form uses `_if` to skip the dialog when false. These inline conditions/actions require the gallery's permissive CSP; named controller methods remain the usual choice for reusable behavior.
+
+Legacy `askIf` is not the skip condition: `askIf="false"` alone still asks. The dedicated button demonstrates this difference. Modifier-based `askOn`/`skipOn` are not supported. Use `_ask_if`, or dictionary `_if`, when a false condition must run without asking.
+
+Python passes `target=target` to obtain the live Source node. Its controller changes the paragraph through Source. `target.builder.reference(target, kind="dom")` explicitly requests the rendered element; the second controller reads its tag name. JavaScript spells this `reference(target, 'dom')`. Neither requires an application ID lookup. These references remain local to the page and cannot be sent as RPC or interframe payloads.
+
+**Exercise:** change the initial name to Linus and turn the checkbox off. **Result:** the conditional controls use Linus without opening a dialog; no field collection has taken place.
+
+</details>

package/src/gramlot_examples/pages/controllers/21_plain_and_delayed_buttons.js

@@ -0,0 +1,36 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Plain and delayed buttons';
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class: 'example-page stack', datapath: 'clicks'});
+        pane.h1('Native HTML, then Gramlot behavior');
+        const form = pane.form({class: 'card stack'});
+        form.html_label('Native value', {for: 'native-value'});
+        form.input({id: 'native-value', value: 'Original'});
+        form.html_button('Native reset', {type: 'reset', id: 'native-reset'});
+        pane.p('Edit the field and Reset: the browser restores its initial value, without a Data controller.');
+        pane.dataSetter({destination_path: '.count', value: 0});
+        pane.dataSetter({destination_path: '.runs', value: 0});
+        pane.button('Immediate action', {id: 'immediate',
+            action: "this.SET('.count', _counter); this.SET('.runs', this.GET('.runs') + 1)"});
+        pane.button('Delayed action', {id: 'delayed', _delay: 600,
+            action: "this.SET('.count', _counter); this.SET('.runs', this.GET('.runs') + 1)"});
+        pane.button('Delayed controller', {id: 'delayed-controller', _delay: 600}).dataController({func: 'countBurst'});
+        pane.button('Delayed confirmation', {id: 'delayed-ask', _delay: 600,
+            action: "this.SET('.count', _counter); this.SET('.runs', this.GET('.runs') + 1)", ask: 'Run this group of clicks?'});
+        pane.p('Click a delayed button several times quickly. Wait: one execution reports the number of clicks in that group.');
+        pane.html_label('Clicks', {for: 'count'});
+        pane.output('^.count', {id: 'count'});
+        pane.html_label('Executions', {for: 'runs'});
+        pane.output('^.runs', {id: 'runs'});
+    }
+}
+
+export class Logic {
+    countBurst(node, {button_counter}) {
+        node.SET('.count', button_counter);
+        node.SET('.runs', node.GET('.runs') + 1);
+    }
+}

package/src/gramlot_examples/pages/controllers/21_plain_and_delayed_buttons.md

@@ -0,0 +1,20 @@
+# 21 · Plain and delayed buttons
+
+Reset an ordinary HTML form, then compare the same Gramlot action with and without a delay. Several quick clicks become one execution, with the size of the group displayed below.
+
+**Uses:** Source, Data and button actions/controllers; core 0.2.19 additions: `html_button` and button `_delay`. No Web Components or endpoint calls. Earlier lessons keep their original release scope.
+
+**Try it:** edit Native value and press Native reset. Click Immediate action twice: Executions increases twice. Click Delayed action three times quickly: after 600 ms from the last click, Executions increases once and Clicks shows 3. A new group starts again from 1. Delayed controller does the same with a named method. Delayed confirmation opens one question after the group; Cancel does not run the action.
+
+<details>
+<summary>More detail</summary>
+
+`html_button` renders a native `<button>` with no implicit type or Gramlot click mechanism. Here `type="reset"` lets the browser reset an unbound field. Use `type="button"` for a plain button that must not submit a form; explicit events use `connect_onclick`. `action`, `ask`, `fire` and `_delay` belong to `button`, not `html_button`.
+
+Both immediate and delayed buttons render as `<button>`. The delayed example adds only `_delay=600`; the action stays the same. Every click restarts the timer. The last event supplies modifiers, and the delayed action reads its arguments when it runs. `_counter` is the group count; a nested controller receives it as `button_counter`. Without delay, the existing counter counts the button's whole lifetime.
+
+A container can supply inherited `_delay`; an explicit zero on a button makes it immediate. Button delay precedes action, ask, fire and the nested provider. A controller's own `_delay` separately delays its Data/subscription triggers. Explicit native event listeners still run on each click. Removing the button or closing its page cancels pending work. The old legacy 200 ms disabled guard for immediate clicks is not introduced.
+
+**Exercise:** change only `_delay` from 600 to 1200. **Result:** the last click postpones the same action for 1.2 seconds; the action and its count logic do not change.
+
+</details>

package/src/gramlot_examples/pages/controllers/README.md

@@ -9,6 +9,8 @@ Add calculations and actions to bound pages, then calls to their host. Each stag
 - **0.2.15:** the later part of **Call on click** adds Source authorization.
 - **0.2.16:** **Remote**, **Cached remote** and **Data remote** add Source fragments and values loaded on demand.
 
+- **0.2.18:** revisit **Button controller** in **Publish and subscribe**, then use **Parent and child messages** for direct iframe exchange. These pages require core 0.2.18 or later.
+
 The host is Python, Node/Bun or a standalone browser Worker. Local Logic runs in the browser. Stable example numbers identify pages; the menu follows release order.
 
 <details>
@@ -33,8 +35,8 @@ c12 teaches Source replacement in the later 0.2.16 stage.
 The Page/Logic module arrangement is a 0.2.5 addition to the named-logic lesson. c08's first pass combines local binding/lifecycle. Return after c09/c11 for its
 0.2.14 quote/result/error section; it does not run automatically or add remote/lazy Data. After b02 and c12, use c13
 for a first cache trial; c14 needs the endpoint concepts of c09/c10. Advanced
-cache/lifecycle exercises are separate in c13/c14; development-only cache
-corrections and pending environment-wide qualification are explicitly labelled. See the [release-by-release route](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md#gc-025-015). Prerequisites support the
+cache/lifecycle exercises are separate in c13/c14; their corrected cache behavior
+is available from core 0.2.17. See the [release-by-release route](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md#gc-025-015). Prerequisites support the
 chronological sequence; they do not replace it. The maintained files may use
 later APIs, so they are not snapshots of the earliest release.
 
@@ -63,3 +65,9 @@ The date initialization issue in c17 and named-resource-host prerequisites remai
 explicit gaps; the local file lesson does not imply HTTP service or mail delivery.
 
 </details>
+
+
+After the messaging lessons, **c20 · Actions, confirmations and references**
+completes the 0.2.18 button examples. **c21 · Plain and delayed buttons** then
+shows the 0.2.19 additions, comparing the same action before
+and after adding `_delay`. It needs core 0.2.19 or later.