@gramlot/gramlot-examples 0.2.14 → 0.2.16

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.16.
 
 [Documentation and learning sequence](https://gramlot-examples.readthedocs.io/en/latest/)
 include every lesson, its Python and JavaScript source, and the gallery guide.
@@ -24,6 +24,10 @@ The repositories of the family are described in
 [The Gramlot family](https://github.com/gramlot-org/gramlot/blob/main/docs/public/055-family.md)
 (GC-055).
 
+## Updating
+
+Choose [packaged or source-checkout updates](docs/010-gallery.md#ge-010-050). A Python gallery installed from source also needs its JavaScript bundles rebuilt; updating Python files alone does not update the footer inspector.
+
 ## Pages
 
 [`src/gramlot_examples/pages/`](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/README.md) holds three
@@ -32,10 +36,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.20 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.16",
   "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.20"
   },
   "devDependencies": {
     "@genrojs/bag": ">=0.11.0",

package/src/gramlot_examples/catalog.json

@@ -72,7 +72,7 @@
           "title": "Cards with icons",
           "folder": "10_cards_with_icons",
           "description": "HTML cards with SVG icons and live Source removal.",
-          "explanation": "Helpers and loops build the cards. Each \u00d7 button removes its labelled Source node through the browser Builder; Gramlot updates the DOM without reloading. Reload restores the initial cards. No Data binding or server synchronization is involved."
+          "explanation": "Helpers and loops build the cards. Each × button removes its labelled Source node through the browser Builder; Gramlot updates the DOM without reloading. Reload restores the initial cards. No Data binding or server synchronization is involved."
         },
         {
           "key": "e11",
@@ -304,13 +304,31 @@
           "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."
+        },
+        {
+          "key": "c22",
+          "title": "Pointer templates and expressions",
+          "folder": "22_pointer_transforms",
+          "description": "Core 0.2.20: revisit CSS lengths, boolean state and formatted text with attribute pointer transforms."
         }
       ]
     }

package/src/gramlot_examples/pages/binding/06_style_and_visibility.md

@@ -16,29 +16,94 @@ Controls change an element’s appearance and visibility. You learn how Data dri
 
 **Open and edit:** select **b06 · Style and visibility** in your environment’s gallery. For source changes, copy/edit the matching page in your own project using the [setup guide](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md); the gallery is a source viewer. Save, then reload/reopen as that guide explains. The snippets below are excerpts/edits within that Page, not standalone launch commands.
 
-## Read the page
+## From Python to Source to DOM
 
-The box binds class, style, color, background, size, radius and visibility to Data. Supported class/style values are strings or null. CSS shortcuts compose the style and take precedence over a duplicate property in `style`.
+The controls above change Data. The preview box reads that Data through its bindings.
+Follow three steps side by side; these are **excerpts of the existing page**, not
+additional declarations to paste into it. Source cells list attributes, not serialized
+Bags; DOM cells show only relevant CSS and omit other styles/classes. Browsers may
+normalize colors to `rgb(...)` and change declaration spacing/order.
 
-`visible=False` sets hidden visibility but retains space; native `hidden=True` removes the box from layout. Use CSS units such as `1.5rem` for font size.
+| Python declaration | Source attributes | DOM inline style at startup |
+| --- | --- | --- |
+| `color="^.color"` | `color: "^.color"` | `color: #ffffff` |
+| `background_color="^.background"` | `background_color: "^.background"` | `background-color: #456bc4` |
+| `font_size="^.size"` | `font_size: "^.size"` | `font-size: 1.5rem` |
+| `padding="1rem"` | `padding: "1rem"` | `padding: 1rem` |
+| `style="^.style"` | `style: "^.style"` | `border: 4px dashed #ffc400` |
 
-Python builds Source on the server; its JavaScript counterpart builds it on Node/Bun or in a standalone Worker. Bindings, actions and any Logic execute in the browser; Python strings containing JavaScript are not executed by Python.
+All these attributes belong to the **same** preview div. Its enclosing pane has
+`datapath="look"`, so `^.color` follows `look.color`. The renderer combines the
+resolved values into one HTML `style` attribute. It does not put a `color` HTML
+attribute on the div or replace the Source pointer with its current value.
 
-## Try it and predict the result
+For comparison, a literal declaration has no Data dependency:
 
-1. Expect a blue box, white text, dashed border, 1.5rem font and rounded corners.
-2. Replace the style field with `color: red` and leave it: the color shortcut still makes the text white; replacing the style string also removes its old border declaration.
-3. Uncheck visible: the space remains. Then check hidden: the space collapses.
+| Python | Source attributes | DOM |
+| --- | --- | --- |
+| `pane.div("Hello", color="red", font_size="18px")` | `color: "red"`, `font_size: "18px"` | `<div style="color: red; font-size: 18px;">Hello</div>` |
 
-## Change it and check yourself
+This comparison uses the literal styling foundation; the controls in this lesson
+add the core 0.2.0 Data binding layer. No later controller or component feature is needed.
 
-Restore visible, clear hidden and choose 2rem with 24px corners.
+## Try the binding
 
-**Answer:** the same box changes appearance from Data; its text and Source structure are unchanged. A null shortcut removes its own property, not every other style declaration.
+1. Choose a new **Text color**, for example `#ff0000`.
+2. The color input writes its value to `look.color`.
+3. The preview's `color="^.color"` reads that value and becomes red.
+4. Inspect its Source: `color` still contains `^.color`. Inspect the preview element
+   in browser DevTools: the inline style now has the resolved red color.
+
+The input writes Data; the div displays it. This is not the div's CSS writing back
+to Data. Python built the Source; these edits and projections execute in the browser.
+
+## Which style wins?
+
+Restore **Text color** to white, then replace the **style** field with
+`color: red; border: 4px dashed #ffc400` and leave the field to commit the edit.
+
+| Declaration retained in Source | Current Data | Resulting inline style (excerpt) |
+| --- | --- | --- |
+| `style="^.style"`, `color="^.color"` | `look.style = "color: red; border: 4px dashed #ffc400"`; `look.color = "#ffffff"` | `color: #ffffff; border: 4px dashed #ffc400` |
+
+**The text stays white:** the explicit `color` shortcut wins over the same property
+inside `style`. The border survives because it has no conflicting shortcut. Now
+replace the style field with only `color: red`: the border disappears, while text
+stays white. Replacing the style string removes its old declarations; other shortcut
+properties still compose into the result.
+
+This is Gramlot's composition of inline style. The browser then applies the CSS
+cascade: an applicable `!important` stylesheet rule can change the computed result.
+A resolved null shortcut removes its property; it does not restore an overwritten
+property from the style string. Class/style values accept strings or null, not objects.
+
+## What about the reverse direction?
+
+As a temporary debugging exercise, select the preview's `#box` element in browser
+DevTools and change its inline `color` to green. Source still has `^.color`, and
+Data still has the selected color: **editing CSS does not update either one**.
+Choose another Text color in the page: the Data-driven projection takes over again.
+Reloading also rebuilds the page from its declarations.
+
+Editing a literal Source attribute through the Gramlot inspector does project it to
+the DOM, but does not save it to the Python/JS source file. The inspector's **Styles**
+tab previews theme variables, not reverse conversion of element CSS into Source;
+use **Download CSS** there to export applied theme overrides. Computed CSS may come
+from classes, inheritance or variables, so there is no single reverse mapping.
+
+## Visibility and a small exercise
+
+Uncheck **visible**: the box keeps its space. Restore it and check **hidden**: the
+space collapses. Restore visible and clear hidden, then choose **2rem** font size
+and **24px** corners. The same box changes appearance; its Source structure stays
+unchanged. Use explicit CSS units for sizes.
+
+For the broader theme and cascade explanation, see
+[Python styles and a reactive example](https://github.com/gramlot-org/gramlot/blob/main/docs/public/096-themes-and-css.md#gc-096-040).
 
 ## Limits and next step
 
-Stay with the agreed string/null contract. The development review has a pending renderer-parity correction for rejection of unsupported class/style types; this lesson does not teach object coercions or rely on them.
+Stay with the agreed string/null contract. This lesson does not teach object coercions or rely on them.
 
 Continue with [b07 · Bound SVG](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/07_bound_svg.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
 

package/src/gramlot_examples/pages/controllers/02_controller.js

@@ -47,7 +47,7 @@ export class Page extends BasePage {
         }
         for (const [key, path, exact] of [['name_exact', '.filter.name', true], ['name_all', '.filter.name', false],
             ['address_exact', '.filter.address', true], ['address_all', '.filter.address', false]]) {
-            filtered.p(`^.${key}`, {mask: `${key}: %s`, id: key});
+            filtered.p(`^.${key}`, {mask: `${key}: {}`, id: key});
             filtered.dataController({func: 'countPath', watched: `^${path}`, counter: `.${key}`, _userChanges: exact});
             pane.dataSetter({destination_path: `.${key}`, value: 0});
         }

package/src/gramlot_examples/pages/controllers/16_attribute_projection.js

@@ -9,7 +9,7 @@ export class Page extends BasePage {
         pane.h2('0.2.0: one value, several projections');
         pane.html_label('Name', {for: 'name'});
         pane.input({value: '^.name', live: true, id: 'name'});
-        pane.p('^.name', {mask: 'Hello, %s', id: 'greeting'});
+        pane.p('^.name', {mask: 'Hello, {}', id: 'greeting'});
         pane.div('Hover to read the title', {customer: '^.name', title: 'Customer: ${customer}', id: 'card'});
         pane.p('The template consumes customer; it is not a DOM attribute.');
         pane.h2('0.2.3: a separate HTML preview');

package/src/gramlot_examples/pages/controllers/16_attribute_projection.md

@@ -23,10 +23,10 @@ A template reads another attribute of its own Source node **after pointer resolu
 ```python
 pane.div("Hover to read the title", customer="^.name",
          title="Customer: ${customer}")
-pane.p("^.name", mask="Hello, %s")
+pane.p("^.name", mask="Hello, {}")
 ```
 
-`${customer}` is Gramlot syntax, not Python interpolation. `customer` supplies the template and is consumed instead of becoming a DOM attribute. `mask` formats the projected text; it does not enable HTML.
+`${customer}` is Gramlot syntax, not Python interpolation. `customer` supplies the template and is consumed instead of becoming a DOM attribute. `mask` formats the projected text; it does not enable HTML. The maintained syntax uses `{}`; older releases used `%s`.
 
 The later section uses `pane.iframe(srcdoc="^.html", ...)`. Data-provided HTML gets `sandbox=""`: it is an isolated document, with scripts/forms/popups blocked by default. Ordinary `pane.p("^.html")` would show literal markup instead.
 
@@ -39,7 +39,7 @@ The later section uses `pane.iframe(srcdoc="^.html", ...)`. Data-provided HTML g
 
 ## Change it and check yourself
 
-Change the mask to `Welcome, %s` and the title to `Guest: ${customer}`. Leave the Data pointer alone.
+Change the mask to `Welcome, {}` and the title to `Guest: ${customer}`. Leave the Data pointer alone.
 
 **Answer:** one Name edit still updates both destinations with different formatting; no extra provider or shared formatted Data value is needed.
 

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/22_pointer_transforms.js

@@ -0,0 +1,39 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Pointer templates and expressions';
+    static css = ['/themes/gramlot-base/theme.css'];
+    static locale = 'it-IT';
+    static timeZone = 'Europe/Rome';
+
+    main(root) {
+        const pane = root.main({class: 'example-page stack', datapath: 'transforms'});
+        for (const [path, value] of [['width', 38], ['draft', false], ['name', 'Ada'], ['amount', 1234.5]]) {
+            pane.dataSetter({destination_path: `.${path}`, value});
+        }
+        pane.h1('Same Data, different presentation');
+        const sizes = pane.section({class: 'card stack'});
+        sizes.h2('1. A number becomes a CSS length');
+        sizes.html_label('Width in pixels', {for: 'width-input'});
+        sizes.input({id: 'width-input', type: 'number', value: '^.width', live: true});
+        sizes.div('Width', {id: 'width-preview', width: '^.width:{}px', background_color: '#456bc4', color: 'white'});
+        sizes.p('Edit the number: only its presentation gains px. Clear it: the explicit width disappears.');
+        const state = pane.section({class: 'card stack'});
+        state.h2('2. A boolean becomes another boolean');
+        state.html_label('Draft: allow editing', {for: 'draft-input'});
+        state.input({id: 'draft-input', type: 'checkbox', value: '^.draft'});
+        state.html_label('Name', {for: 'name-input'});
+        state.input({id: 'name-input', value: '^.name', readonly: '^.draft:=!{}'});
+        const display = pane.section({class: 'card stack'});
+        display.h2('3. Format a number, then wrap the text');
+        display.html_label('Amount', {for: 'amount-input'});
+        display.input({id: 'amount-input', type: 'number', value: '^.amount', live: true});
+        display.p('^.amount', {id: 'amount-display', format: '0.00', mask: 'Total: {} €'});
+        display.p('Hover to read the same amount in the title.', {id: 'amount-title',
+            title: "^.amount:=_F({}, {pattern: '0.00', mask: '{} €'})"});
+        display.p('This page uses Italian formatting. The amount in Data remains a number.');
+    }
+}
+
+/** The page logic: this page names no methods. */
+export class Logic {}

package/src/gramlot_examples/pages/controllers/22_pointer_transforms.md

@@ -0,0 +1,64 @@
+# 22 · Pointer templates and expressions
+
+Resize a bar, enable a field and display an amount. The same typed Data drives all three: you learn when to produce text and when to keep a boolean or number.
+
+**Uses:** Source, Data, attribute pointers and the page formatter — core 0.2.20. No Web Components or endpoint calls. Earlier lessons retain their release scope.
+
+**Try it:** enter 80 in Width, then clear it. Turn Draft on to edit Name. Change Amount and compare the displayed text with the title shown on hover.
+
+<details>
+<summary>More detail</summary>
+
+## One value, one template
+
+Earlier lessons needed a supporting attribute to turn a number into CSS text:
+
+```python
+pane.div(width="${pixels}px", pixels="^.width")
+```
+
+The suffix expresses that same operation directly:
+
+```python
+pane.div(width="^.width:{}px")
+```
+
+Read `.width`, then replace `{}` in the text after `:`. A Data number 38 becomes the CSS string `38px`; Data still contains 38. The old multi-attribute template remains supported.
+
+## An expression keeps its result type
+
+```python
+pane.input(value="^.name", readonly="^.draft:=!{}")
+```
+
+After `:=` comes a JavaScript expression. If Draft is false, `!{}` is true: Name is read-only. With Draft true it becomes editable. `:!{}` would create text instead, which is not the intended boolean result.
+
+Keep `value` as a plain pointer: suffix transformations are not allowed on the widget value. They do not define how to convert edited text back into Data.
+
+## Format first, mask second
+
+For the content of a paragraph, ordinary attributes are the clearest choice:
+
+```python
+pane.p("^.amount", format="0.00", mask="Total: {} €")
+```
+
+`format` produces the number text using the page locale; `mask` wraps that text. This page declares `locale = "it-IT"`, so 1234.5 displays as `Total: 1234,50 €`.
+
+For an attribute such as a tooltip, use the same formatter inside an expression:
+
+```python
+pane.p("Hover here", title="^.amount:=_F({}, {pattern: '0.00', mask: '{} €'})")
+```
+
+The first `{}` passes the typed amount. The quoted `'{} €'` is the mask passed to `_F`; it is not another pointer placeholder. `_F` calls this page's `gramlot.format` and does not create a global function.
+
+## Empty values
+
+An ordinary template slot requires a nonempty value. Null or an empty string makes the whole template null; the destination applies its usual null behavior. `0` and `False` are valid values. Use `{?}` to allow an empty string explicitly, for example `title="^.name:Customer: {?}"`. It still does not admit null.
+
+Expressions receive typed values, including null. The standalone `mask` wraps formatted text; `gramlot.format(None)` returns empty text without applying the mask.
+
+**Exercise:** change only `readonly="^.draft:=!{}"` to `readonly="^.draft"`. **Result:** the checkbox now has the opposite effect; the name binding does not change.
+
+</details>

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

@@ -65,3 +65,12 @@ 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.
+
+**c22 · Pointer templates and expressions** follows c21 in core 0.2.20: repeat the CSS-width exercise with a shorter pointer, invert a boolean
+and reuse the page formatter for text and attributes. It does not use Web Components.