@gramlot/gramlot-examples 0.2.14 → 0.2.15

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.2.14.
+Current release: 0.2.15.
 
 [Documentation and learning sequence](https://gramlot-examples.readthedocs.io/en/latest/)
 include every lesson, its Python and JavaScript source, and the gallery guide.
@@ -32,10 +32,11 @@ same-name README:
 
 - `html_svg/`: thirteen HTML and SVG pages, without binding (`e01`–`e13`);
 - `binding/`: eleven pages whose DOM follows the Data (`b01`–`b11`);
-- `controllers/`: nineteen pages with formulas, controllers, named logic, events, the
+- `controllers/`: twenty-one pages with formulas, controllers, named logic, events, the
   end-to-end story, `dataRpc` calls to the endpoints of the page, `remote` fragments and
-  `dataRemote` values (`c01`–`c19`). The last two introduce: topics,
-  authored references, native ask and parent/child messages. They require core 0.2.18 or later.
+  `dataRemote` values (`c01`–`c21`). Later lessons introduce topics, authored references, native ask,
+  parent/child messages, plain HTML buttons and delayed Gramlot clicks. The package
+  requires core 0.2.19 or later; each lesson states which features it uses.
 
 Each `NN_name.js` exports `Page` and `Logic`; the Python page `NN_name.py` takes its
 `Logic` from the module beside it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramlot/gramlot-examples",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "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.2.18"
+    "@gramlot/gramlot": ">=0.2.19"
   },
   "devDependencies": {
     "@genrojs/bag": ">=0.11.0",

package/src/gramlot_examples/catalog.json

@@ -304,13 +304,25 @@
           "key": "c18",
           "title": "Publish and subscribe",
           "folder": "18_publish_subscribe",
-          "description": "Development core 0.2.18: revisit button actions with page topics, self receivers, references and native ask."
+          "description": "Core 0.2.18: revisit button actions with page topics, self receivers, references and native ask."
         },
         {
           "key": "c19",
           "title": "Parent and child messages",
           "folder": "19_frame_messages",
-          "description": "Development core 0.2.18: local-first publish and direct parent/child postMessage exchange."
+          "description": "Core 0.2.18: local-first publish and direct parent/child postMessage exchange."
+        },
+        {
+          "key": "c20",
+          "title": "Actions, confirmations and references",
+          "folder": "20_actions_ask_references",
+          "description": "Core 0.2.18: action, conditional ask and explicit Source/DOM references."
+        },
+        {
+          "key": "c21",
+          "title": "Plain and delayed buttons",
+          "folder": "21_plain_and_delayed_buttons",
+          "description": "Core 0.2.19: native html_button and grouped clicks with _delay."
         }
       ]
     }

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

@@ -65,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.